AI导哈

本地文档检索服务

ContextQMD是一款本地优先的文档管理工具，支持通过AI编码助手安装、搜索和检索库文档，适用于开发者快速获取技术文档。

  • by darkamenosa
  • TypeScript
  • 本地部署
  • 11 星标
  • 更新于
在 GitHub 查看 darkamenosa/contextqmd-mcp

使用说明

contextqmd-mcp

MCP服务器，用于本地优先、版本感知的库文档。直接从您的AI编码助手安装、搜索和检索任何库的文档。

它做什么

ContextQMD是context7的替代品，它使文档保持在本地。它从下载doc包 ContextQMD注册表，使用QMD（BM25+向量+LLM重新排序）对它们进行索引，并通过模型上下文协议提供结果。

安装流程先捆绑：

  1. 搜索库目录并选择库/版本
  2. 获取清单
  3. 下载a tar.gz 文档包（如果可用）
  4. 验证SHA256校验和并解包到本地缓存中
  5. QMD索引
  6. 本地搜索

如果缺少兼容的捆绑包，服务器将回退到 page-index 加上每页提取。安装是原子性的，失败时会回滚。

安装

npm install -g contextqmd-mcp

或者直接使用npx运行：

npx contextqmd-mcp

MCP配置

添加到您的MCP客户端配置中（例如，Claude Desktop、Cursor等）：

{
  "mcpServers": {
    "contextqmd": {
      "command": "npx",
      "args": ["-y", "contextqmd-mcp"]
    }
  }
}

或者，如果全局安装：

{
  "mcpServers": {
    "contextqmd": {
      "command": "contextqmd-mcp"
    }
  }
}

CLI选项

--transport <type>  Transport type: stdio (default) or http
--port <number>     HTTP port (default: 3001)
--registry <url>    Registry URL override
--token <token>     API token
--cache-dir <path>  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 允许有界膨胀：

  1. 发现候选库： search_libraries({ query: "react refs" })
  2. 安装精确的文档包： install_docs({ library: "react", version: "19.2.0" })
  3. 搜索本地索引： search_docs({ query: "how can i optimize refs", library: "react", version: "19.2.0" })
  4. 阅读最佳结果的有界摘录： 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

许可证

麻省理工学院

相关 MCP