Docs MCP 服务器

本项目提供了一个灵活的模型上下文协议 (MCP) 服务器，由 Probe 提供支持，旨在使 AI 助手可以搜索文档或代码库。

您可以通过指向 git 仓库或文件夹，与代码或文档进行聊天。

npx -y @buger/docs-mcp@latest --gitUrl https://github.com/buger/probe

使用场景：

• 与任何 GitHub 仓库聊天： 将服务器指向公共或私有 Git 仓库，以启用关于其内容的自然语言查询。
• 搜索您的文档： 集成您项目的文档（来自本地目录或 Git），以便轻松搜索。
• 构建自定义 MCP 服务器： 使用本项目作为模板，创建您自己的官方 MCP 服务器，专门针对特定的文档集甚至代码库。

内容源（文档或代码）可以在 npm run build 步骤中预构建到包中，也可以在运行时使用本地目录或 Git 仓库动态配置。 默认情况下，当使用 gitUrl 且未启用自动更新时，服务器会下载 .tar.gz 存档以加快启动速度。 仅当 autoUpdateInterval 大于 0 时才使用完整的 Git 克隆。

特性

• 由 Probe 提供支持： 利用 Probe 搜索引擎获得高效且相关的结果。
• 灵活的内容源： 包括特定的本地目录或克隆 Git 仓库。
• 预构建内容： 可选择将文档/代码内容直接捆绑到包中。
• 动态配置： 通过配置文件、CLI 参数或环境变量配置内容源、Git 设置和 MCP 工具详细信息。
• 自动 Git 更新： 通过以可配置的时间间隔自动从 Git 仓库拉取更改，保持内容最新。
• 可自定义的 MCP 工具： 定义暴露给 AI 助手的搜索工具的名称和描述。
• AI 集成： 与支持模型上下文协议 (MCP) 的 AI 助手无缝集成。

用法

使用此服务器的主要方式是通过 npx，它会下载并运行该包，而无需本地安装。 这使得它很容易与 AI 助手和 MCP 客户端（如 IDE 扩展）集成。

与 MCP 客户端集成（例如，IDE）

您可以配置您的 MCP 客户端以使用 npx 启动此服务器。 以下是如何配置客户端的示例（语法可能因特定客户端而异）：

示例 1：动态搜索 Git 仓库（Tyk 文档）

此配置告诉客户端使用 npx 运行最新的 @buger/docs-mcp 包，并将其动态指向 Tyk 文档仓库。 -y 参数自动确认 npx 安装提示。 --toolName 和 --toolDescription 参数自定义搜索工具在 AI 助手中的显示方式。

{
  "mcpServers": {
    "tyk-docs-search": {
      "command": "npx",
      "args": [
        "-y",
        "@buger/docs-mcp@latest",
        "--gitUrl",
        "https://github.com/TykTechnologies/tyk-docs",
        "--toolName",
        "search_tyk_docs",
        "--toolDescription",
        "Search Tyk API Management Documentation"
      ],
      "enabled": true
    }
  }
}

或者，某些客户端可能允许直接指定完整命令。 您可以使用以下方法实现与示例 1 相同的结果：

npx -y @buger/docs-mcp@latest --gitUrl https://github.com/TykTechnologies/tyk-docs --toolName search_tyk_docs --toolDescription "Search Tyk API Management Documentation"

示例 2：使用预构建的品牌 MCP 服务器（例如，Tyk 包）

如果团队发布了一个包含特定文档的预构建包（如 @tyk-technologies/docs-mcp），则配置会变得更简单，因为内容源和工具详细信息已烘焙到该包中。 仍然建议为 npx 使用 -y 参数。

{
  "mcpServers": {
    "tyk-official-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/docs-mcp@latest"
      ],
      "enabled": true
    }
  }
}

这种方法非常适合为官方文档或代码库分发标准化搜索体验。 请参阅下面的“创建您自己的预构建 MCP 服务器”部分。

这是一个 Tyk 团队如何构建自己的文档 MCP 服务器的示例：https://github.com/TykTechnologies/docs-mcp。

配置

在根目录中创建一个 docs-mcp.config.json 文件，以定义在构建期间和运行时使用的默认内容源和 MCP 工具详细信息（除非被 CLI 参数或环境变量覆盖）。

示例 1：使用本地目录

{
  "includeDir": "/Users/username/projects/my-project/docs",
  "toolName": "search_my_project_docs",
  "toolDescription": "Search the documentation for My Project.",
  "ignorePatterns": [
    "node_modules",
    ".git",
    "build",
    "*.log"
  ]
}

示例 2：使用 Git 仓库

{
  "gitUrl": "https://github.com/your-org/your-codebase.git",
  "gitRef": "develop",
  "autoUpdateInterval": 15,
  "toolName": "search_codebase",
  "toolDescription": "Search the main company codebase.",
  "ignorePatterns": [
    "*.test.js",
    "dist/",
    "__snapshots__"
  ]
}

配置选项

• includeDir：(构建/运行时) 本地目录的绝对路径，其内容将在构建期间复制到 data 目录，或者如果未指定 dataDir，则在运行时直接使用。 使用此选项或 gitUrl。
• gitUrl：(构建/运行时) Git 仓库的 URL。 使用此选项或 includeDir。
  • 如果 autoUpdateInterval 为 0（默认），则服务器尝试直接下载 .tar.gz 存档（当前假定 GitHub URL 结构：https://github.com/{owner}/{repo}/archive/{ref}.tar.gz）。 这更快，但不支持更新。
  • 如果 autoUpdateInterval > 0，则服务器执行 git clone 并启用定期更新。
• gitRef：(构建/运行时) 要从 gitUrl 使用的分支、标签或提交哈希（默认值：main）。 用于 tarball 下载和 Git 克隆/拉取。
• autoUpdateInterval：(运行时) 自动检查 Git 更新的间隔（以分钟为单位）（默认值：0，表示禁用）。 将此值设置为 > 0 会启用 Git 克隆和定期 git pull 操作。 需要 git 命令在系统路径中可用。
• dataDir：(运行时) 包含要在运行时搜索的内容的目录的路径。 覆盖从配置文件中的 includeDir 或 gitUrl 获取的内容，或构建到包中的内容。 用于将服务器指向实时数据而无需重建。
• toolName：(构建/运行时) 服务器公开的 MCP 工具的名称（默认值：search_docs）。 选择与内容相关的描述性名称。
• toolDescription：(构建/运行时) 向 AI 助手显示的 MCP 工具的描述（默认值：“使用 probe 搜索引擎搜索文档。”）。
• ignorePatterns：(构建/运行时) glob 模式数组。
• enableBuildCleanup：(构建) 如果为 true（默认），则在构建步骤后从 data 目录中删除常见的二进制/媒体文件（图像、视频、存档等）和大于 100KB 的文件。 设置为 false 以禁用此清理。
  • 如果在构建期间使用 includeDir：将内容复制到 data 时，将排除与这些模式匹配的文件。 还会遵守 .gitignore 规则。
  • 如果在运行时使用 gitUrl 或 dataDir：搜索索引器会忽略 data 目录中与这些模式匹配的文件。

优先级：

1. 运行时配置（最高）： CLI 参数（--dataDir、--gitUrl 等）和环境变量（DATA_DIR、GIT_URL 等）会覆盖所有其他设置。 CLI 参数优先于环境变量。
2. 构建时配置： docs-mcp.config.json 中的设置（includeDir、gitUrl、toolName 等）定义了在 npm run build 期间使用的默认值，并且如果未被覆盖，也充当运行时默认值。
3. 默认值（最低）： 如果未提供任何配置，则使用内部默认值（例如，toolName: 'search_docs'，autoUpdateInterval: 5）。

注意：如果在同一配置源中同时提供了 includeDir 和 gitUrl（例如，都在配置文件中，或者都作为 CLI 参数），则 gitUrl 优先。

创建您自己的预构建 MCP 服务器

您可以使用本项目作为模板来创建和发布您自己的 npm 包，其中预先构建了文档或代码。 这为用户提供了零配置体验（如上面的示例 2）。

1. Fork/克隆此仓库： 从本项目的代码开始。
2. 配置 docs-mcp.config.json： 定义指向您的内容源的 includeDir 或 gitUrl。 设置默认的 toolName 和 toolDescription。
3. 更新 package.json： 更改 name（例如，@my-org/my-docs-mcp）、version、description 等。
4. 构建： 运行 npm run build。 这会将您的内容克隆/复制到 data 目录中，并使该包准备就绪。
5. 发布： 运行 npm publish（您需要配置 npm 身份验证）。

现在，用户可以轻松运行您的特定文档服务器：npx @my-org/my-docs-mcp@latest。

（之前的“运行”、“运行时动态配置”和“环境变量”部分已被删除，因为客户端配置中使用带参数的 npx 现在是主要记录的方法。）

与 AI 助手一起使用

此 MCP 服务器通过模型上下文协议向连接的 AI 助手公开搜索工具。 该工具的名称和描述是可配置的（请参阅配置部分）。 它搜索当前活动的 data 目录中的内容（由构建设置、配置文件、CLI 参数或环境变量确定）。

工具参数：

• query：描述要搜索内容的自然语言查询或关键字（例如，“如何配置网关”、“数据库连接示例”、“用户身份验证”）。 服务器使用 Probe 的搜索功能来查找相关内容。（必需）
• page：处理多个匹配项时，结果的页码。 如果省略，则默认为 1。（可选）

示例工具调用（使用用法示例 1 中的 search_tyk_docs）：

{
  "tool_name": "search_tyk_docs",
  "arguments": {
    "query": "gateway rate limiting",
    "page": 1 // 请求第一页
  }
}

示例工具调用（使用来自 @tyk/docs-mcp 包的工具）：

假设预构建的包 @tyk/docs-mcp 将其工具名称定义为 search_tyk_official_docs：

{
  "tool_name": "search_tyk_official_docs",
  "arguments": {
    "query": "dashboard api access",
    "page": 2 // 请求第二页
  }
}

（之前的“发布为 npm 包”部分已被上面的“创建您自己的预构建 MCP 服务器”部分替换。）

许可证

MIT