项目简介

Hypermodel 文档 MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的后端服务，专门为大型语言模型（LLM）驱动的编码代理提供高质量、实时的文档上下文。它允许代理自动搜索、索引和管理来自公共 URL 的文档，并提供用户/团队范围的访问控制，确保代理始终能获取到准确且相关的文档信息。

主要功能点

文档链接与范围管理: 支持将会话关联到特定用户或团队，以管理文档访问权限和范围。
文档搜索: 允许通过语义查询在已索引的文档中进行高效搜索，返回相关的 URL、标题和内容片段。
文档列表: 列出当前用户或团队可访问的所有文档索引。
文档索引: 支持从公开 URL 爬取网站内容并将其索引到向量数据库中，支持后台处理和进度跟踪。
索引状态与任务列表: 查看特定文档索引任务的详细状态和进度，或列出当前范围内的所有近期索引任务。
用户与团队管理: 集成了 WorkOS webhook，支持用户创建、更新、删除，并为用户自动创建团队，实现团队协作功能。
认证与授权: 提供基于 OAuth 2.0 的 Bearer Token 认证，确保对 MCP 端点的安全访问。

安装步骤

环境准备:
- 确保已安装 Node.js (v16 或更高版本)。
- 需要一个 PostgreSQL 数据库实例，并安装 'pgvector' 扩展。
- 需要一个 OpenAI API 密钥用于生成文档嵌入。
- 推荐使用 Temporal Cloud 或自部署 Temporal 集群用于文档索引的后台工作流。
- 如果需要用户/团队管理和 OAuth 认证，需要 WorkOS 账号并配置相应的环境变量。
克隆仓库: 'git clone https://github.com/hypermodel-labs/docs.git'
安装依赖: 进入仓库目录，运行 'npm install'。

配置环境变量: 创建 '.env' 文件，并根据需要配置以下变量：

# 数据库连接字符串 (必须)
POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database"
# OpenAI API 密钥 (必须)
OPENAI_API_KEY="your_openai_api_key"
# Temporal 服务地址 (必须，用于文档索引工作流)
TEMPORAL_ADDRESS="your_temporal_cloud_address:port"
# Temporal 命名空间 (可选，默认为 default)
TEMPORAL_NAMESPACE="your_temporal_namespace"
# Temporal TLS 证书和密钥 (如果使用 Temporal Cloud 或生产环境)
# TEMPORAL_TLS_CERT="base64_encoded_cert"
# TEMPORAL_TLS_KEY="base64_encoded_key"
# WorkOS 相关配置 (如果需要用户/团队管理和 OAuth)
# WORKOS_CLIENT_ID="your_workos_client_id"
# WORKOS_CLIENT_SECRET="your_workos_client_secret"
# WORKOS_WEBHOOK_SECRET="your_workos_webhook_secret"
# 文档爬取配置 (可选，高级设置)
# DOCS_MAX_PAGES=10000
# DOCS_CONCURRENCY=4
# DOCS_TIMEOUT_MS=25000
# DOCS_USER_AGENT="YourCustomUserAgent"
# DOCS_INCLUDE_REGEX=".*your_pattern.*"
# DOCS_EXCLUDE_REGEX=".*another_pattern.*"

构建项目: 'npm run build'
启动 Temporal Worker: 在一个新的终端中，运行 'npm run start:worker'。这是处理文档索引任务的后台进程。
启动 MCP 服务器: 运行 'npm start' 或 'npm run dev' (开发模式)。服务器默认运行在 3001 端口。

服务器配置

{
  "name": "@hypermodel-labs/docs-mcp",
  "command": "node",
  "args": ["./dist/index.js"],
  "description": "Hypermodel 文档 MCP 服务器，提供文档搜索和索引服务。",
  "transport": {
    "type": "http",
    "url": "http://localhost:3001/mcp"
  },
  "authentication": {
    "type": "oauth2",
    "authorization_url": "http://localhost:3001/authorize",
    "token_url": "http://localhost:3001/token",
    "resource": "http://localhost:3001/mcp",
    "scopes": ["openid", "profile", "email"],
    "client_id": "your_client_id",
    "redirect_uri": "your_redirect_uri"
  }
}

name: MCP 服务器的唯一标识符。
command: 启动 MCP 服务器的主命令。
args: 传递给启动命令的参数。
description: 对服务器功能的简要描述。
transport:
- type: 连接协议类型，此处为 'http'。
- url: MCP 服务器的 HTTP 端点 URL。
authentication:
- type: 认证类型，此处为 'oauth2'。
- authorization_url: OAuth 授权码流程的授权端点。
- token_url: OAuth 授权码流程的令牌端点。
- resource: OAuth 保护的资源 URL，即 MCP 服务器端点。
- scopes: 请求的 OAuth 范围。
- client_id: 您的 OAuth 客户端 ID，通常需要通过 MCP 服务器的 '/register' 端点进行注册以获取，或由服务提供商分配。
- redirect_uri: OAuth 认证完成后重定向回的 URI，需要与注册的 'client_id' 关联的重定向 URI 保持一致。

基本使用方法

链接会话: 在 AI 代理中调用 'link' 工具，将当前会话与用户或团队关联，例如：'link user_id="your_user_id" scope="user"'。
列出文档索引: 调用 'list-docs' 工具查看当前会话可访问的文档索引，例如：'list-docs'。
索引新文档: 调用 'index' 工具从 URL 爬取并索引文档，例如：'index url="https://supabase.com/docs"'。您也可以选择 'shareWith' 其他用户或团队。
查询文档: 调用 'search-docs' 工具，指定索引名称和查询语句进行搜索，例如：'search-docs index="supabase-com" query="how to use functions"'。
检查索引状态: 调用 'index-status' 工具并提供工作流 ID，查看索引任务的详细进度，例如：'index-status workflowId="index-supabase-com-123456789"'。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息