用途
GroundTruth-MCP 是一个自托管的 MCP 服务器和命令行工具，用于在编码智能体提出请求时提供所使用库的当前官方文档。它针对模型凭训练数据写代码导致过时用法的问题：例如 React 19 后仍用 forwardRef 包裹组件、Next.js 将 cookies() 改为异步后仍同步调用、Tailwind v4 已用 @import "tailwindcss" 取代 @tailwind 指令。GroundTruth 在请求时读取库自身的文档（llms.txt、文档站 markdown 或 GitHub 仓库），对相关章节排序，并在返回前检查回答是否覆盖该主题。它还可以用 107 种以上模式审计源代码，并把每个发现链接到当前修复方法。它在本机运行，无账号、无 API 密钥、无自带速率限制。
主要能力
- 文档检索：将库名先匹配精选注册表，再匹配 npm、PyPI、crates.io 和 Go modules；来源按顺序尝试，第一个有用来源胜出：llms.txt / llms-full.txt、通过 Accept: text/markdown 获取的文档页 markdown、转换为 markdown 的 HTML 页面、GitHub README/文档文件/发布说明，Jina reader 作为兜底。
- 排序与检查：用 BM25 对每个章节按主题评分，填充 token 预算；证据门统计主题词出现数量、频率以及是否出现在标题或代码块中，链接目标和 URL 查询串不计入。弱覆盖会触发第二次针对主题的抓取，零覆盖返回明确未命中并附检查过的来源、这些页面覆盖的大纲及下一步建议。每个成功回答以 ## Evidence 页脚结束，含来源 URL、抓取日期和主题覆盖数字；检查对同义词敏感。
- 代码审计：gt_audit 遍历项目，运行 18 个类别的 107+ 模式，按 file:line 报告每个问题，然后从权威来源获取修复方法。
- 依赖感知最佳实践：gt_practices 读取清单与锁文件，确定所用库及版本，按使用次数排序返回最佳实践，默认输出约 15K 字符。支持 package.json、deno.json、requirements.txt、pyproject.toml、Cargo.toml、go.mod、pom.xml、build.gradle、build.gradle.kts、composer.json、Gemfile 和 pubspec.yaml。
- 工具集：14 个工具，每个既可作 MCP 工具也可作 CLI 命令；另暴露 2 个 MCP 资源（library-registry、library-docs）和 8 个提示（audit-my-project、upgrade-check、best-practices-scan、compare-libraries、security-check、migration-guide、find-examples、dependency-audit）。可用自然语言提问，也可直接调用工具，例如 gt-mcp <command>。
- 库覆盖：793 个精选库覆盖 21 个语言生态，注册表外自动回退到 npm、PyPI、crates.io 和 Go modules。8.0.0 新增 195 个库，覆盖 Python、数据与 AI 工具、Java、Kotlin 与 Spring、.NET、Go、Rust、Ruby、PHP、Swift、Dart 与 Flutter、Elixir、C 与 C++、基础设施、数据库、可观测性等；对全部 598 个已有条目做了在线探测：修复 35 个失效文档根、更新 115 个迁移的文档站、约 190 个已验证的 llms.txt 索引，并重新检查了精选 URL 表（2,638 个 URL）。完整列表见注册表源码 src/sources/registry.ts。
- 性能与缓存：二进制是小引导程序，惰性加载服务器并使用 Node 编译缓存；文档页以 markdown 请求；阅读服务仅作兜底；缓存页采用 stale-while-revalidate，最长 7 天的页面立即返回并在后台刷新。抓取层保持连接 60 秒、相同调用者共享在途请求、尊重每次调用取消和 GT_TOOL_TIMEOUT_MS 截止时间、缓存 404 和超大响应体避免重试、主机反复失败后暂时跳过。
使用方式
要求 Node.js 24 或更新版本。
在 Cursor、Claude Desktop、Windsurf 等使用 mcpServers 块的客户端（.cursor/mcp.json、claude_desktop_config.json、~/.codeium/windsurf/mcp_config.json）中配置；VS Code 使用 .vscode/mcp.json。其他 MCP 客户端运行 npx -y @groundtruth-mcp/gt-mcp@latest 作为 stdio 服务器。命令行（同样工具，无需 MCP 客户端）：gt-mcp <command> 在进程内运行同样的 14 个工具并打印答案；无参数时 gt-mcp 就是 stdio MCP 服务器。退出码：0 正常，1 工具错误，2 用法错误。日志默认在 stderr 保持安静（GT_LOG_LEVEL 默认 warn）。服务器标志仍可用：--version、--health、--routing-table、--help。@latest 让 npx 在下次会话启动时获取新版本；新版本存在时，工具响应携带一行通知（GT_NO_UPDATE_CHECK=1 可关闭检查）。
可选 GitHub token：GroundTruth 从 GitHub 读取 README、发布说明、迁移指南和代码示例。无 token 时 GitHub 允许每小时 60 次请求；无额外作用域的 token 可提高到 5,000 次，并在 gt_examples 中启用代码搜索。JSON 配置中在 args 旁加 "env": { "GT_GITHUB_TOKEN": "ghp_yourtoken" }。
HTTP 和 Docker：设置 GT_HTTP_PORT 后 GroundTruth 提供 Streamable HTTP 而非 stdio。它遵循 MCP 规范 2026-07-28，并仍服务 2025 时代的客户端。本地回环模式绑定 127.0.0.1；无 GT_AUTH_TOKEN 时对本地调用者开放并记录警告，有 token 时每个路径（包括 /health 和 /metrics）都需要 Authorization: Bearer <token>。Docker 镜像 277 MB，以非特权 gt 用户运行，容器内绑定 0.0.0.0，因此在没有 GT_AUTH_TOKEN 时拒绝启动；其健康检查会发送 token；-p 127.0.0.1: 前缀让端口留在宿主机回环，去掉则可服务其他机器。反向代理后：服务器说普通 HTTP，在代理终止 TLS 并将公共主机名加入 GT_HTTP_ALLOWED_HOSTS，否则携带该主机名的请求得到 403；非回环绑定下没有 GT_AUTH_TOKEN 服务器不会启动。会话默认无状态，GT_HTTP_STATEFUL=1 为每个 2025 时代客户端提供独立会话，30 分钟无请求后关闭。已认证调用者可以让服务器抓取公共 URL，并在进程可读的任何目录运行 gt_audit 和 gt_auto_scan，因此不要将不希望被读取的内容挂载进容器。所有配置均可选，无效数值或枚举值在启动时失败而非静默回退。gt-mcp --help 打印同样的列表。
适用场景
- 编码智能体需要目标库当前官方文档时。
- 对项目做 107+ 模式审计并把每个发现定位到 file:line 和当前修复。
- 根据锁文件识别的库与版本获取依赖感知的最佳实践。
- 比较库、检查升级、生成迁移指南、安全检查、查找示例和依赖审计等提示场景。
限制与说明
- 需要 Node.js 24 或更新版本。
- 抓取的是不可信网络内容并交给模型；提示注入清理器是尽力而为的模式脱敏，应把抓取到的文档视为不可信输入。
- 审计模式已做 ReDoS 安全处理，最坏输入从 9.5 秒降到 1 毫秒。
- GT_GITHUB_TOKEN 和 GT_JINA_API_KEY 永不转发到其他源，包括重定向。
- 磁盘缓存只保存以哈希为键的抓取文档，不保存提示或工具输入。
- 8.0.0 有四项破坏性变更；在 Node 24 或更新版本上读取文本内容的 stdio 用户不受影响。
- 安全漏洞请通过 GitHub Security Advisories 私下报告，范围与威胁模型见 SECURITY.md。
- 许可证为 Elastic License 2.0：可免费使用、自托管和在其上构建，唯一不能做的是将其作为托管服务提供。
- 与 Context7 的区别：Context7 将文档索引到向量数据库，速度快但落后于新发布；GroundTruth 在查询时从源抓取，并在主题无内容时告知模型。
- 添加库是对 src/sources/registry.ts 的拉取请求，需提供 id、name、docsUrl，以及项目发布 llmsTxtUrl 时的该字段。
- CI 在 Node 24 和 26 上运行测试套件。
