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 扩展）的集成变得容易。

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Docs MCP 服务器：

npx -y @smithery/cli install @buger/docs-mcp --client claude

与 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 工具的描述（默认值："使用探针搜索引擎搜索文档。"）。
• 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）。

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

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

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

1. 分叉/克隆此仓库：从该项目的代码开始。
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服务器通过Model Context Protocol向连接的AI助手暴露了一个搜索工具。该工具的名称和描述是可配置的（请参阅配置部分）。它会在当前激活的data目录内搜索内容（由构建设置、配置文件、CLI参数或环境变量确定）。

工具参数：

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

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

{
  "tool_name": "search_tyk_docs",
  "arguments": {
    "query": "gateway rate limiting",
    "page": 1 // Requesting the first page
  }
}

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

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

{
  "tool_name": "search_tyk_official_docs",
  "arguments": {
    "query": "dashboard api access",
    "page": 2 // Requesting the second page
  }
}

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

许可证

MIT