AI导哈

文档搜索服务

一个基于GitHub的文档搜索服务，提供文档资源暴露和搜索工具，适用于LLM集成和开发环境。

  • by homebase-id
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 homebase-id/mcp-docs

使用说明

MCP文档服务器

一个模型上下文协议（MCP）服务器，它将GitHub上的文档作为资源公开，并提供搜索工具。

特性

  • 资源：将文档文件作为MCP资源公开，以便LLM读取
  • 工具：提供 search_docs 和 list_docs 查找信息的工具
  • GitHub集成：直接从GitHub存储库获取文档
  • 缓存：内存内缓存（5分钟TTL）以减少API调用
  • 基于Node.js：适用于标准Node.js运行时

安装

为了发展

克隆存储库并安装依赖项：

git clone https://github.com/homebase-id/mcp-docs.git
cd mcp-docs
npm install

来自GitHub软件包

要从GitHub软件包安装，首先配置npm使用GitHub注册表 @homebase-id 范围：

echo "@homebase-id:registry=https://npm.pkg.github.com" >> ~/.npmrc

然后进行身份验证（需要GitHub个人访问令牌 read:packages 范围）：

npm login --scope=@homebase-id --registry=https://npm.pkg.github.com

安装软件包：

npm install -g @homebase-id/mcp-docs-server

用法

在克劳德桌面

添加到您的 claude_desktop_config.json （位置因操作系统而异）：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-docs/src/index.js"],
      "env": {
        "GITHUB_OWNER": "homebase-id",
        "GITHUB_REPO": "odin-js",
        "GITHUB_BRANCH": "main"
      }
    }
  }
}

添加后，重新启动Claude Desktop。您将在中看到文档服务器🔌 偶像。

使用GitHub Copilot编写VS代码

添加到您的VS代码设置(settings.json):

  1. 打开命令选项板(Cmd+Shift+P / Ctrl+Shift+P)
  2. 搜索“首选项：打开用户设置（JSON）”
  3. 添加MCP服务器配置：
{
  "github.copilot.chat.mcp.servers": {
    "docs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-docs/src/index.js"],
      "env": {
        "GITHUB_OWNER": "homebase-id",
        "GITHUB_REPO": "odin-js",
        "GITHUB_BRANCH": "main"
      }
    }
  }
}

备注：替换 /absolute/path/to/mcp-docs 安装的实际路径。

添加后重新加载VS代码。MCP服务器将在Copilot聊天中可用。

In Cline（VS代码扩展）

添加到Cline的MCP设置中：

  1. 在VS Code中打开临床设置
  2. 导航到MCP服务器部分
  3. 添加服务器配置：
{
  "mcpServers": {
    "docs": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-docs/src/index.js"],
      "env": {
        "GITHUB_OWNER": "homebase-id",
        "GITHUB_REPO": "odin-js",
        "GITHUB_BRANCH": "main"
      }
    }
  }
}

独立运行

npm start

服务器使用stdio传输并通过JSON-RPC进行通信。

配置

设置要自定义的环境变量：

  • GITHUB_OWNER -存储库所有者（默认值： homebase-id)
  • GITHUB_REPO -存储库名称（默认值： odin-js)
  • GITHUB_BRANCH -分支名称（默认值： main)

可用资源

服务器将文档文件作为MCP资源公开，其URI如下：

github://homebase-id/odin-js/main/docs/llm/WORKSPACE_INSTRUCTIONS.md
github://homebase-id/odin-js/main/docs/llm/ARCHITECTURE.md
github://homebase-id/odin-js/main/docs/llm/modules/CORE_MODULE.md

LLM可以直接读取这些资源，而无需调用工具。这提供了对文档上下文的即时访问。

可用工具

list_docs

列出所有可用的文档文件及其URI。

search_docs

在所有文档中搜索特定术语或主题。

参数：

  • query （string）：要查找的搜索词

例子：

{
  "name": "search_docs",
  "arguments": {
    "query": "authentication"
  }
}

运作原理

  1. 资源：LLM可以将文档文件作为MCP资源列出并读取，以用于即时上下文
  2. 工具：LLM可以使用 search_docs 查找具体信息或 list_docs 查看所有可用文档
  3. 缓存：内容缓存在内存中5分钟，以最小化GitHub API调用并提高性能
  4. GitHub集成：从GitHub原始URL按需获取内容（适用于公共存储库）

故障排除

服务器未显示

  • 克劳德桌面：检查🔌 右下角的图标。如果不可见，请检查配置文件路径是否正确。
  • VS代码副本：重新加载VS代码窗口(Cmd+Shift+P → “开发人员：重新加载窗口”）
  • 验证Node.js：运行 node --version 确保Node.js已安装并位于PATH中

“找不到文档”错误

  • 确保文件存在于指定分支的GitHub存储库中
  • 检查一下 GITHUB_OWNER, GITHUB_REPO，以及 GITHUB_BRANCH 设置正确
  • 验证存储库是否公开（或您是否有访问权限）
  • 文件必须位于 docs/llm/ 存储库目录

权限错误

  • 确保脚本可执行： chmod +x /path/to/mcp-docs/src/index.js
  • 在配置文件中使用绝对路径
  • 检查Node.js是否已安装并可从终端访问

发展

在开发模式下运行：

node src/index.js

服务器会记录到stderr（console.error），这样它就不会干扰stdio传输。

出版

此包已发布到GitHub Packages。工作流会自动执行以下操作：

  1. 更改时碰撞版本 src/ 或 package.json
  2. 发布到 @homebase-id/mcp-docs-server
  3. 创建带有版本凹凸的PR

许可证

麻省理工学院

相关 MCP