Local Markdown document search MCP server
npm install doc-hub-mcp> 提供离线、本地的 Markdown 文档检索能力，可直接接入支持 Model Context Protocol (MCP) 的 IDE、Agent 或调试工具。目前支持企业微信和飞书，文档更新时间：2025-10-12
1. 项目简介
2. 功能特性
3. 系统要求
4. 快速开始
- 安装依赖
- 启动服务
- 本地自检（可选）
5. 配置说明
- 环境变量
- IDE / AI 编程助手集成示例
6. 使用方法
7. 故障排查
本项目基于 @modelcontextprotocol/sdk 构建 STDIO 传输模式的 MCP 服务。通过本地存储的 Markdown 文档向客户端提供检索工具与资源读取能力，适用于离线知识库、企业内部文档、私有 API 文档等场景。
主要聚合了企业微信和飞书开放平台的完整开发者文档，方便在 AI 编程助手中快速检索和查阅接口文档。
> 特别说明
> 1. 本 MCP 包含约 100 MB 以上的内容，首次接入（无缓存）需等待数分钟完成安装与加载。
> 2. 当前文档抓取覆盖至 2025-10-12，如需更细粒度更新时间，请自行运行最新的抓取脚本。
- 关键字检索：doc-hub 工具支持按关键词匹配标题与正文，返回排序后的候选列表。
- 全文获取：默认使用 doc://local-docs/{+path} 资源，可通过 resources/read 获取 Markdown 原文。
- 可配置命名空间：通过环境变量可自定义资源命名空间与服务名称，利于多知识库并行。
- 自定义文档根目录：默认依次查找运行目录与包内的 docs/、wecom/、feishu/，也可通过 DOC_ROOT 指定任意路径。
- 标准 MCP 兼容：可在 Cursor、Claude Code、Codex、MCP Inspector 等支持 MCP 的客户端中直接使用。
- Node.js ≥ 20.18（满足 cheerio@1.1.2 的引擎要求）
- 本地 Markdown 文档目录；若文档放在默认的 docs/、wecom/ 或 feishu/（无论位于项目根目录还是包内），无需额外配置
- 支持 MCP 协议的 AI 编程助手（见下方列表）
本 MCP 服务兼容所有支持 Model Context Protocol 的工具，包括但不限于：
- ✅ Cursor - AI-first 代码编辑器
- ✅ Claude Code - Anthropic 官方 CLI 工具
- ✅ Codex - AI 编程助手
- ✅ MCP Inspector - MCP 协议调试工具
- ✅ 其他支持 MCP 协议的工具
配置方式基本相同，只需在对应工具的 MCP 配置文件中添加服务配置即可。
``bash`
npm install
首次克隆仓库后执行一次即可，后续依赖更新时再重新安装。
`bash`
npm run mcp:server --silent
- --silent 用于屏蔽 npm 输出，避免干扰 STDIO 通信。
- 如果文档位于默认目录之外（或需覆盖包内文档），可在命令前添加环境变量：
`bash`
DOC_ROOT=/path/to/docs DOC_NAMESPACE=my-docs npm run mcp:server --silent
进程将常驻前台并接管 STDIO，直到客户端结束连接。
`bash`
npx @modelcontextprotocol/inspector -s "npm run mcp:server --silent"
若在 MCP Inspector 中能看到 doc-hub 工具和 doc://local-docs/...（或自定义命名空间）资源，即表示服务工作正常。
发布或打包后，终端可以直接拉取 npm 包运行，无需手动克隆仓库：
`bash`
npx -y doc-hub-mcp
常见场景：
- 私有部署：通过 npm publish --access restricted 发布到私有 registry，使用时将 npm 配置指向该 registry。 npm pack
- 本地分发：运行 生成 doc-hub-mcp-1.0.1.tgz，在目标机器执行 npx --yes --package ./doc-hub-mcp-1.0.1.tgz doc-hub-mcp
。
执行命令时若需自定义目录或命名空间，可以追加环境变量，例如：
`bash`
DOC_ROOT=/data/docs DOC_NAMESPACE=internal-docs npx -y doc-hub-mcp
| 变量名 | 说明 | 默认值 |
| ------------------ | ----------------------------------------------- | ------------------------------- |
| DOC_ROOT | 指定 Markdown 文档根目录的绝对路径 | 依次搜索运行目录与包内的 docs/、wecom/、feishu/ |DOC_NAMESPACE
| | 资源命名空间名称，对应 doc:// | local-docs |MCP_SERVER_NAME
| | MCP 服务在客户端中显示的名称 | doc-hub |
#### Cursor 配置
在 ~/.cursor/mcp.json 中添加（或更新）如下配置：
`json`
{
"mcpServers": {
"doc-hub": {
"command": "npx",
"args": ["-y", "doc-hub-mcp@latest"]
}
}
}
保存配置后，打开 Cursor 的 MCP 面板重新连接，若状态指示灯由红变绿即表示加载成功。
#### Claude Code 配置
在 ~/.config/claude-code/mcp.json (Linux/macOS) 或 %APPDATA%\claude-code\mcp.json (Windows) 中添加：
`json`
{
"mcpServers": {
"doc-hub": {
"command": "npx",
"args": ["-y", "doc-hub-mcp@latest"]
}
}
}
#### Codex 配置
配置方式与 Cursor、Claude Code 相同，在对应的 MCP 配置文件中添加上述配置即可。
#### 自定义环境变量
若需切换自定义目录或命名空间，可在配置中添加 env 字段：
`json`
{
"mcpServers": {
"doc-hub": {
"command": "npx",
"args": ["-y", "doc-hub-mcp@latest"]
}
}
}
配置完成后，在支持 MCP 的 AI 编程助手中，可以通过以下方式使用：
1. 直接对话查询：直接询问相关问题，AI 助手会自动调用 doc-hub 工具进行检索。例如：
- "企业微信如何获取外部联系人列表？"
- "飞书如何发送消息？"
2. 手动调用工具（如在 MCP Inspector 中）：
`json`
{
"query": "外部联系人 同步",
"limit": 5,
"source": "wecom"
}
参数说明：
- query：必填，搜索关键词limit
- ：可选，返回结果数量（默认 8，最多 20）source
- ：可选，指定文档来源（wecom 或 feishu）
3. 检索结果会返回 resourceUri（形如 doc://local-docs/wecom/...），AI 助手会自动读取完整文档内容并提供答案。
- 企业微信文档：
`bash`
npm run scrape:wecom -- --limit 20 # 仅抓取 20 篇做快速验证
npm run scrape:wecom # 全量抓取
- 飞书开放平台文档：
`bash`
npm run scrape:feishu -- --limit 20 # 仅抓取 20 篇做快速验证
npm run scrape:feishu # 全量抓取
> 使用 --limit 可以控制抓取数量，便于先做增量验证。去掉该参数即执行全量抓取。
- 依赖缺失：确认已执行 npm install 且无报错。docs/
- 文档目录不存在：服务会依次尝试运行目录与包内的 、wecom/、feishu/；若需其他目录，设置 DOC_ROOT 并确保路径可访问。Proxy Server PORT IS IN USE at port 6277
- 端口冲突：使用 MCP Inspector 时若提示 ，需关闭已有 Inspector 实例或修改其代理端口。npx
- 客户端不显示工具：
- 确认配置文件格式正确，JSON 无语法错误
- 检查客户端（Cursor、Claude Code 等）是否允许执行
- 必要时可改为使用本地脚本绝对路径或显式安装 npm 包
- 重启 IDE 或重新加载 MCP 连接
- 首次加载缓慢：首次通过