contextqmd-mcp
MCP服务器，用于本地优先、版本感知的库文档。直接从您的AI编码助手安装、搜索和检索任何库的文档。
它做什么
ContextQMD是context7的替代品，它使文档保持在本地。它从下载doc包 ContextQMD注册表，使用QMD（BM25+向量+LLM重新排序）对它们进行索引，并通过模型上下文协议提供结果。
安装流程先捆绑：
- 搜索库目录并选择库/版本
- 获取清单
- 下载a
tar.gz文档包（如果可用） - 验证SHA256校验和并解包到本地缓存中
- QMD索引
- 本地搜索
如果缺少兼容的捆绑包，服务器将回退到 page-index 加上每页提取。安装是原子性的，失败时会回滚。
安装
npm install -g contextqmd-mcp或者直接使用npx运行：
npx contextqmd-mcpMCP配置
添加到您的MCP客户端配置中（例如，Claude Desktop、Cursor等）：
{
"mcpServers": {
"contextqmd": {
"command": "npx",
"args": ["-y", "contextqmd-mcp"]
}
}
}或者，如果全局安装：
{
"mcpServers": {
"contextqmd": {
"command": "contextqmd-mcp"
}
}
}CLI选项
--transport Transport type: stdio (default) or http
--port HTTP port (default: 3001)
--registry Registry URL override
--token API token
--cache-dir
Cache directory override可用工具
| 工具 | 说明 |
|---|---|
search_libraries | 搜索远程库目录。返回带有版本、别名、源元数据和本地安装状态的候选项。 |
install_docs | 安装文档包。先捆绑SHA256验证；返回到API页。带有回滚功能的原子。Idempotent--如果已经安装了相同的清单校验和，则跳过。 |
update_docs | 将已安装的文档更新到最新版本，或在清单校验和更改时刷新。失败后回滚。 |
search_docs | 在本地搜索已安装的文档。返回包含代码段、行锚点和分数的页面级结果。支持自动/fts/矢量/混合模式。 |
get_doc | 通过以下方式从本地安装的页面读取有界切片 doc_path 或 page_uid.支持顺序读取(from_line/max_lines)和上下文窗口(around_line/before/after). |
list_installed_docs | 列出所有本地安装的文档包及其元数据。 |
remove_docs | 删除已安装的文档版本或库的所有版本。清理缓存和搜索索引。 |
搜索模式
search_docs 通过支持四种模式 mode 参数：
- 自动 （默认）--基于查询分类的智能路由：短关键字查询使用FTS，概念/操作问题使用向量，复杂的多方面查询使用混合。
- fts --BM25全文搜索（快速、基于关键字）。最适合API名称、函数查找和代码模式。
- 向量 --语义向量搜索。最适合概念性问题。超时时回退到FTS。
- 混合 --将BM25+矢量与LLM重新排序相结合（质量最佳，速度较慢）。超时时回退到FTS。
无论模式如何，跨库搜索始终使用FTS。
渐进式检索
服务器使用渐进式检索模型——搜索返回带有行锚点的小片段，然后 get_doc 允许有界膨胀：
- 发现候选库：
search_libraries({ query: "react refs" })
- 安装精确的文档包：
install_docs({ library: "react", version: "19.2.0" })
- 搜索本地索引：
search_docs({ query: "how can i optimize refs", library: "react", version: "19.2.0" })
- 阅读最佳结果的有界摘录：
get_doc({ library: "react", version: "19.2.0", doc_path: "reference/react/useRef.md", from_line: 40, max_lines: 30 })
search_docs结果
每个结果包括： doc_path, page_uid, title, content_md, score, snippet, line_start, line_end, search_mode，以及 url.
search_docs 仅限于本地。如果未安装库，则返回 NOT_INSTALLED 错误，而不是从网络中静默获取。
get_doc读取模式
- 顺序的:
from_line+max_lines（默认：第1行，60行） - 上下文窗口:
around_line+before/after（默认值：30之前，60之后） - 行号：set
line_numbers: true获取带有行号前缀的输出
升级说明
较旧的已安装库可能仍有遗留问题 page_uid.md 本地QMD索引中的路径。服务器在首次搜索时缓慢地重建这些索引。如果重建中断，请重新运行 update_docs 或重新安装受影响的库版本。
配置
配置文件位置： ~/.config/contextqmd/config.json
{
"registry_url": "https://contextqmd.com",
"local_cache_dir": "~/.cache/contextqmd",
"default_install_mode": "slim",
"preferred_search_mode": "auto"
}环境变量：
CONTEXTQMD_API_TOKEN-通过身份验证的终结点的API令牌
建筑
src/
index.ts # CLI entry point, MCP server, 7 tool handlers
lib/
types.ts # TypeScript interfaces for the API contract
config.ts # Config loader (~/.config/contextqmd/config.json)
registry-client.ts # HTTP client for the ContextQMD registry API
local-cache.ts # Local filesystem cache manager (atomic installs, page layout)
doc-indexer.ts # QMD-backed search indexer (FTS, vector, hybrid, query classifier)关键设计模式：
- 本地优先：所有搜索仅限于本地。
search_docs永远不要接触网络。 - 捆绑首次安装：首选
tar.gz捆；返回到逐页API获取。 - 原子安装：具有备份/还原功能的分阶段临时目录，用于安全升级。
- 临时行动:
install_docs当已安装相同的版本/校验和时，这是一个禁止操作。 - 安全：捆绑包提取针对路径遍历、符号链接和不支持的条目类型进行验证。
发展
npm install # install dependencies
npm run build # compile TypeScript to dist/
npm run dev # watch mode
npm run check # type-check without emitting
npm test # run tests (vitest)
npm run test:watch # watch mode tests集 SKIP_INTEGRATION=1 跳过需要在localhost:3000上运行注册表的集成测试。
需求
- Node.js>=22.0.0
许可证
麻省理工学院