1. 项目概述：当AI助手自信地写出过时代码时
你的AI助手刚刚又“自信满满”地给你生成了一堆过时的代码。它告诉你React 19里forwardRef用得没问题，Next.js 15的cookies()还是同步函数，或者用字符串模板拼接SQL查询“既简洁又高效”。更糟的是，你可能因为生成的代码格式漂亮、注释清晰，没细看就合并进了主分支。等到运行时诡异报错，或者安全扫描亮起红灯，你才追悔莫及——AI并不知道它不知道什么。
这就是GroundTruth-MCP要解决的问题。它不是一个简单的文档查询工具，而是一个运行在你本地的、持续更新的“代码事实核查员”。作为一个自托管的MCP服务器，它内置了超过422个主流库的“知识快照”和107种代码审计模式，能直接从源码（如项目的llms.txt文件、GitHub、官方文档）实时获取最新信息，告诉你“现在什么是对的”。没有API调用限制，无需密钥，通过简单的npx命令即可集成到Claude Code、Cursor、VS Code等任何支持MCP协议的IDE中。它的核心价值在于：在AI生成代码的“自信”与代码库的“真实”之间，建立一道可靠的防火墙。
2. 核心设计思路：实时、精准、可操作的真相源
市面上的AI编码助手，其知识截止日期是硬伤。即便联网搜索，返回的也可能是过时的博客或未经验证的答案。GroundTruth的设计哲学围绕三个核心原则展开，旨在从根本上解决信息滞后和噪音问题。
2.1 优先级明确的实时抓取策略
GroundTruth不相信单一的、静态的知识库。它的文档获取遵循一个精心设计的优先级链条，确保信息尽可能来自最权威、最即时的源头。
- 首选
llms.txt/llms-full.txt：这是最革命性的一步。越来越多的开源项目（如Next.js、Tailwind CSS）开始发布专为LLM优化的上下文文件。这些文件去除了网页导航、广告等噪音，只包含核心API、迁移指南和最佳实践，格式纯净。GroundTruth会优先寻找并抓取这些文件，这是获取“设计意图”最直接的途径。 - 降级至 Jina Reader：对于没有
llms.txt的项目，GroundTruth使用Jina Reader这类工具来抓取官方文档页。Jina Reader能处理JavaScript渲染的现代网站，将复杂的网页转化为干净的Markdown，比普通爬虫更可靠。 - 回退到 GitHub 元数据：如果上述方法失败，它会抓取GitHub仓库的README文件和最新的Release Notes。这里通常包含了最关键的安装、配置和变更信息。
- 兜底至包管理器：最后，对于任何在npm、PyPI、crates.io或pkg.go.dev上公开的包，GroundTruth都能将其作为基本信息源进行解析，确保“万物皆可查”。
这个链条的关键在于“实时”。它不是在启动时下载一个巨大的、很快就会过时的快照，而是在你每次查询时，按这个顺序去尝试获取最新内容。配合智能缓存（默认在~/.gt-mcp-cache），它在速度与新鲜度之间取得了平衡。
2.2 从“文档查询”到“代码诊断”的范式转变
大多数类似工具止步于“回答问题”。GroundTruth通过gt_audit工具，将能力延伸到了“主动发现问题”。这不仅仅是静态代码分析（SAST），更是结合了实时知识库的动态模式匹配。
其审计引擎会遍历你的项目文件，应用超过107种针对不同场景的审计模式。这些模式不是简单的正则匹配，而是能理解上下文。例如：
- 安全：它能识别出
db.query(SELECT * FROM users WHERE id = ${userId})这种典型的SQL注入模式，而不仅仅是寻找${。 - 框架过时用法：它能知道在React 19中，
React.forwardRef的用法已变更，并定位到文件中的具体行号。 - 可访问性：它能揪出
<div onClick={...}>（应使用<button>）或缺少alt属性的<img>标签。
更重要的是，当它发现一个问题时，不会只抛出一个模糊的警告。它会立即调用gt_get_docs或gt_search，从OWASP、MDN等权威来源获取当前推荐的修复方案，并直接附在审计结果后面。这使得修复建议不再是泛泛而谈，而是具体、可立即执行的代码片段。
2.3 一体化工具集设计：覆盖开发全链路
GroundTruth没有做一个“万能”工具，而是拆解成12个功能单一、职责明确的工具。这种设计让AI助手能更精确地调用，也让你在直接使用时有清晰的预期。
| 工具 | 核心用途与场景 | 典型查询示例 |
|---|---|---|
gt_resolve_library | 库识别：确认库名，获取基础信息，支持包管理器回退。 | “nestjs的最新稳定版是什么？” |
gt_get_docs | 精准文档：获取某个库特定主题（如“中间件”、“缓存”）的详细文档。 | “给我看nextjs中关于cookies()用法的文档。” |
gt_best_practices | 最佳实践：获取针对某个库的配置指南、模式与反模式。 | “prisma在生产环境的最佳实践有哪些？” |
gt_auto_scan | 栈级扫描：读取项目package.json等文件，自动分析所有依赖并汇总最佳实践。 | “扫描我当前项目，告诉我所有依赖的注意事项。” |
gt_search | 自由搜索：在OWASP、MDN、AI提供商文档等非特定库的广泛知识库中搜索。 | “如何防范SSRF攻击？” “Claude Tool Use的最佳实践？” |
gt_audit | 代码审计（核心）：扫描源代码，定位安全问题、过时API等，并附上实时修复指南。 | “审计我的src/目录下的安全和React问题。” |
gt_changelog | 变更日志：查看特定版本库的发布说明，评估升级影响。 | “tailwindcss从v3到v4有哪些破坏性变更？” |
gt_compat | 兼容性查询：通过MDN和caniuse数据查询浏览器或运行时API兼容性。 | “CSS Container Queries在Safari 16上的支持情况？” |
gt_compare | 技术选型：并排比较2-3个相似库在特定维度（如性能、TS支持）上的差异。 | “比较drizzle-orm和prisma的TypeScript支持。” |
gt_examples | 实例参考：从GitHub等源获取某个库的真实世界用法示例。 | “找几个hono框架使用中间件的例子。” |
gt_migration | 迁移指南：获取库版本升级的详细迁移指南。 | “如何从Next.js 14迁移到15？” |
gt_batch_resolve | 批量解析：一次性解析最多20个库，提高效率。 | “同时解析react,zustand,vite这三个库。” |
这套工具集形成了一个从技术选型、日常开发、代码审查到升级维护的完整支持闭环。
3. 安装与配置：五分钟内投入实战
GroundTruth的安装力求极简，核心思想是“零配置运行，按需优化”。你不需要克隆仓库、构建项目或编写复杂的配置文件。
3.1 基础安装：一行命令集成
根据你使用的IDE或AI助手，选择对应的安装方式。所有方式都指向同一个npm包@groundtruth-mcp/gt-mcp。
对于 Claude Code（Claude桌面应用的原生终端）： 这是最直接的方式，通过Claude自带的MCP管理命令完成。
claude mcp add gt -- npx -y @groundtruth-mcp/gt-mcp@latest执行后，Claude Code会自动将其添加到配置中，并立即生效。
对于 Cursor / Claude Desktop / VS Code： 你需要手动编辑对应的MCP配置文件。这些编辑器通常将配置放在以下位置：
- Cursor:
~/.cursor/mcp.json - Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 或%APPDATA%\Claude\claude_desktop_config.json(Windows) - VS Code: 项目根目录或用户全局设置的
.vscode/mcp.json
在配置文件的mcpServers对象中添加如下条目：
{ "mcpServers": { "gt": { "command": "npx", "args": ["-y", "@groundtruth-mcp/gt-mcp@latest"] } } }关键细节：这里使用了@latest标签。这意味着每次启动MCP服务器（通常是当你启动IDE或新建会话时），npx都会去拉取最新的版本。你无需手动更新，就能自动获得新增的审计规则、库支持和新功能。这是保持“事实”新鲜度的基础。
注意：确保你的Node.js版本在24或以上。这是运行GroundTruth的唯一硬性要求。你可以通过
node -v检查。如果版本过低，建议使用nvm或fnm等工具进行管理。
3.2 进阶配置：解锁更高性能
虽然零配置即可运行，但两个简单的配置能显著提升体验。
1. 配置GitHub Token（强烈推荐）GroundTruth会频繁地从GitHub获取README、发行说明和代码示例。未经认证的GitHub API请求每小时限制60次，很容易在密集使用时耗尽。申请一个GitHub Personal Access Token（PAT）可以轻松解决。
- 创建Token：访问GitHub Settings -> Developer settings -> Personal access tokens -> Tokens (classic)。生成一个新token，不需要勾选任何scope（权限）。一个无scope的token足以将API速率限制从60/小时提升到5000/小时，且非常安全。
- 集成Token：
- Claude Code:
claude mcp add gt -e GT_GITHUB_TOKEN=ghp_yourtoken -- npx -y @groundtruth-mcp/gt-mcp@latest - 配置文件：在MCP服务器配置中添加
env字段。
{ "mcpServers": { "gt": { "command": "npx", "args": ["-y", "@groundtruth-mcp/gt-mcp@latest"], "env": { "GT_GITHUB_TOKEN": "ghp_yourtoken" } } } } - Claude Code:
2. 自定义缓存目录（可选）GroundTruth会缓存抓取到的文档以减少重复请求。默认缓存位置是~/.gt-mcp-cache。你可以通过环境变量GT_CACHE_DIR将其更改到其他路径，例如一个更快的SSD盘或一个共享的网络位置。
{ "mcpServers": { "gt": { "command": "npx", "args": ["-y", "@groundtruth-mcp/gt-mcp@latest"], "env": { "GT_GITHUB_TOKEN": "ghp_yourtoken", "GT_CACHE_DIR": "/path/to/your/cache" } } } }完成上述步骤后，重启你的IDE或AI助手会话，GroundTruth就应该已经就绪。你可以直接在聊天窗口中尝试：“用gt查一下Next.js 15里cookies的用法”。
4. 核心工具实战详解
理解了设计思路和安装方法后，我们来深入看看几个核心工具在实际开发中如何发挥作用。我将结合具体场景，展示从发现问题到解决问题的完整工作流。
4.1gt_audit：你的自动化代码审查伙伴
假设你接手了一个略显陈旧的React项目，想要快速评估其代码健康度和安全风险。你可以在AI助手中输入：“gt_audit一下我的项目，重点看安全和React相关的问题。”
GroundTruth会开始遍历你的源代码目录。我们来看一个它可能生成的报告片段：
## [高危] 通过模板字符串构建SQL查询 分类: security | 严重性: critical | 出现次数: 3 **问题代码示例 (src/api/userService.js:28):** ```javascript const query = `SELECT * FROM users WHERE email = '${email}' AND status = 'active'`; const result = await db.query(query);实时修复指南 (来自OWASP SQL注入防护备忘单):永远不要使用用户输入直接拼接SQL语句。应使用参数化查询或预处理语句。
- Node.js (pg):
await db.query('SELECT * FROM users WHERE email = $1 AND status = $2', [email, 'active']) - Python (psycopg2):
cursor.execute("SELECT * FROM users WHERE email = %s AND status = %s", (email, 'active')) - PHP (PDO):
$stmt = $pdo->prepare("SELECT * FROM users WHERE email = ? AND status = ?"); $stmt->execute([$email, 'active']);
涉及文件:
- src/api/userService.js:28
- src/legacy/auth.js:15
- scripts/backup.js:7
[警告] 使用已弃用的React.forwardRef API
分类: react | 严重性: warning | 出现次数: 5
问题代码示例 (src/components/MyInput.jsx:12):
const MyInput = React.forwardRef((props, ref) => { return <input {...props} ref={ref} />; });实时修复指南 (来自React 19 llms.txt):自React 19起，forwardRef已被弃用。现在，函数组件默认可以接收ref作为第二个参数。新写法:
function MyInput(props, ref) { return <input {...props} ref={ref} />; } // 无需再调用 forwardRef涉及文件:
- src/components/MyInput.jsx:12
- src/ui/Modal.jsx:5 ...
这份报告的价值在于： 1. **精准定位**：不只是告诉你“有SQL注入风险”，而是精确到`src/api/userService.js`的第28行。 2. **上下文感知**：它能区分不同语言、不同数据库驱动下的正确写法。 3. **知识即时**：修复建议不是来自一个陈旧的规则集，而是实时从OWASP、React官方`llms.txt`等权威源获取的“当前最佳实践”。 4. **严重性分级**：帮助你优先处理`critical`（高危）问题。 你可以进一步缩小审计范围，例如只检查TypeScript和性能问题：`gt_audit({ categories: ["typescript", "performance"] })`。支持的18个审计类别就像一个精细的筛选器，让你能按需进行专项检查。 ### 4.2 `gt_auto_scan`：一键掌握项目技术栈的“脾气” 当你刚克隆一个新项目，或者想系统性地梳理现有项目的依赖时，`gt_auto_scan`是你的最佳起点。它不需要你指定库名，而是智能地读取项目根目录下的各种依赖声明文件。 执行`gt_auto_scan({ projectPath: "." })`后，它会： 1. **识别清单**：依次查找`package.json`、`requirements.txt`、`pyproject.toml`、`Cargo.toml`、`go.mod`等文件。 2. **解析依赖**：提取出所有声明的生产依赖和开发依赖。 3. **批量获取最佳实践**：并发调用`gt_best_practices`（默认并发数6，可通过`GT_CONCURRENCY`调整），为每一个识别到的库获取最新的配置建议、常见陷阱和性能优化点。 最终，它会生成一份汇总报告。例如，对于一个使用Next.js 14、Tailwind CSS和Prisma的项目，报告可能包括： * **Next.js 14**：提醒你`generateStaticParams`的用法变化，以及App Router下数据获取的最佳模式。 * **Tailwind CSS**：如果检测到版本是v3，会警告`@tailwind base;`等指令在v4中已废弃，并给出升级指南链接。 * **Prisma**：建议在生产环境中设置连接池参数，并警告N+1查询问题，附上使用`include`或批量查询的优化示例。 这个工具相当于为你项目的整个技术栈做了一次快速的“入职培训”，让你在写第一行代码前，就避开那些常见的坑。 ### 4.3 `gt_search`与`gt_get_docs`：精准获取知识的两种路径 虽然都是获取信息，但这两个工具的使用场景有微妙区别。 **`gt_search`：面向开放领域的问题** 当你有一个不特定于某个库的通用性问题时，使用`gt_search`。它的知识库来自MDN、OWASP、web.dev、W3C、各大AI提供商官方文档等。 * **场景**：“如何优化 Largest Contentful Paint (LCP)？”、“WCAG 2.2 对焦点指示器有什么新要求？”、“使用Google Gemini API进行函数调用的正确姿势是什么？” * **背后逻辑**：GroundTruth会将你的查询发送到这些权威站点的搜索接口或抓取其相关页面，然后通过Jina Reader清理格式，返回最相关的内容摘要和链接。 **`gt_get_docs`：面向特定库的特定主题** 当你明确知道是哪个库，并且想了解其某个具体功能时，使用`gt_get_docs`。你需要先通过`gt_resolve_library`或直接使用已知的`libraryId`（如`vercel/next.js`）。 * **场景**：“获取`express`中关于`error-handling middleware`的文档”、“查看`pydantic`的`Field`函数所有可用参数”。 * **背后逻辑**：工具会使用为该库预定义的URL模式（例如，`https://expressjs.com/en/guide/error-handling.html`），或结合库的官方文档基础URL和主题关键词，去构造并抓取最可能相关的页面。 **实操心得**：在向AI助手提问时，可以训练自己使用更清晰的指令。例如，不要说“怎么处理错误？”，而是说“用`gt_search`查一下Node.js异步错误处理的最佳实践”或“用`gt_get_docs`看看`fastapi`的`Depends`怎么用”。这能引导助手调用最合适的工具，得到更精准的答案。 ## 5. 与Context7的深度对比及选型思考 Context7是MCP生态中另一个知名的文档工具。选择哪一个，取决于你的具体工作流和需求。以下是我在实际使用两者后的对比分析。 | 维度 | GroundTruth | Context7 | | :--- | :--- | :--- | | **架构与部署** | **自托管/本地优先**。核心是一个你通过npx运行的Node.js进程（stdio模式），也可配置为HTTP服务器。所有抓取、分析、审计逻辑都在本地运行。 | **云端索引+本地客户端**。它有一个专有的云端爬虫和向量数据库，负责索引文档。本地MCP客户端主要是一个查询接口。 | | **信息新鲜度** | **查询时实时抓取**。优先从`llms.txt`、项目官网等源头获取**当前**最新内容。理论上，一个库发布新文档几分钟后，你就能查到。 | **依赖索引周期**。文档需要被其云端爬虫抓取、处理、嵌入向量数据库后才能被查询。对于刚发布的新版本，可能存在几小时到几天的延迟。 | | **核心能力** | **代码审计**是其杀手锏。`gt_audit`能主动扫描代码并给出基于最新知识的修复建议。**工具集丰富**，覆盖兼容性查询、对比分析等场景。 | **专注于文档检索**。其核心优势在于利用向量搜索进行语义查询，即使问题描述不精确，也能找到相关文档。 | | **覆盖范围** | **422+核心库深度覆盖 + 全生态回退**。对主流库有精心维护的元数据（文档URL模式、最佳实践路径）。对于任何在npm/PyPI等上的公开包，都能通过回退机制解析。 | **声称覆盖数千个库**，但具体列表不公开。其向量化方法使其在覆盖广度上可能有优势，但对特定库的深度和模式化支持不如GroundTruth明确。 | | **成本与限制** | **完全免费，无速率限制**。唯一的潜在瓶颈是GitHub API的未认证限制（60次/小时），可通过免费Token轻松提升至5000次/小时。 | **免费版有月度查询限制**（最初1000次/月），超出需付费。这对于重度用户或团队协作可能产生成本。 | | **适用场景** | 1. **重视代码安全和质量**，需要自动化审计。<br>2. **依赖链更新频繁**，需要获取即时的迁移指南和变更日志。<br>3. **开发环境受限或对数据隐私敏感**，需要完全本地化的解决方案。<br>4. **需要进行技术选型对比**（`gt_compare`）或检查浏览器兼容性（`gt_compat`）。 | 1. **查询模式更自由、更口语化**，喜欢用自然语言提问而非精确的工具调用。<br>2. **查询的库非常小众或冷门**，可能不在GroundTruth的精选列表内。<br>3. **可以接受云端服务**，且月度查询量在免费额度内。 | **我的选择与理由**： 在我的日常全栈开发中，我主要使用GroundTruth。原因如下： 1. **主动性**：`gt_audit`提供的主动代码审查能力是无可替代的。它能在代码被提交前就发现问题，这是纯粹的文档查询工具做不到的。 2. **确定性**：我知道`gt_get_docs`会尝试从`llms.txt`或官网获取信息，这比从可能混杂了社区博客内容的向量库中搜索更让我放心。 3. **零成本与可控性**：自托管意味着没有用量焦虑，也符合公司对开发工具可控性的要求。 4. **场景契合**：我经常需要对比相似技术（如Drizzle vs Prisma），或者快速查看某个CSS特性兼容性，GroundTruth的内置工具完美匹配。 当然，两者并非完全互斥。在一些需要“大海捞针”式模糊搜索的场景，我偶尔也会启用Context7作为补充。但对于构建一个可靠、自动化的代码质量防线，GroundTruth是我的基石工具。 ## 6. 高级技巧与实战避坑指南 经过一段时间的深度使用，我总结出一些能极大提升GroundTruth效能的技巧，以及几个常见的“坑”和解决方法。 ### 6.1 高效使用：让AI助手成为“GroundTruth专家” GroundTruth的强大在于与AI助手的无缝结合。你需要做的不是记忆12个工具名，而是学会用自然语言驱动它。 * **场景化指令**：不要只说“查文档”。把你的需求场景描述清楚。 * **低效**：“关于Next.js的文档。” * **高效**：“我准备升级到Next.js 15，用`gt`帮我看看`cookies()`、`headers()`这些API有什么变化，还有没有其他破坏性更新？”（这会触发`gt_get_docs`和`gt_changelog`的链式调用） * **高效**：“我刚写了一个用户登录API，用`gt`帮我审计一下有没有安全漏洞。”（这会触发`gt_audit`对相关文件的安全扫描） * **利用`gt_auto_scan`进行项目交接**：当你接手一个新项目，在第一次团队会议或深入代码前，先让助手运行`gt_auto_scan`。生成的报告能让你快速了解技术栈的“雷区”和最佳实践，在讨论中提出更有针对性的问题，显得非常专业。 * **将审计集成到工作流**：可以在提交代码前，习惯性地对改动文件运行一次快速审计。例如：“`gt audit`一下我刚改的`src/components/`和`src/api/`这两个目录。”这能有效防止低级错误进入代码库。 ### 6.2 性能调优与问题排查 虽然开箱即用，但稍作调整能获得更流畅的体验。 1. **GitHub Token是必选项**：如前所述，没有Token时60次/小时的限制在开发中很容易触发。你会看到请求失败或延迟。**务必申请一个无scope的Token并配置上**，这是提升稳定性的最重要一步。 2. **理解缓存行为**：GroundTruth的磁盘缓存能有效加速重复查询。但如果你怀疑获取的信息过时（例如，你知道某个库刚发布了重大更新），可以手动清空缓存目录（默认`~/.gt-mcp-cache`）来强制刷新。缓存是按库和查询主题进行哈希存储的，所以清空是全局性的。 3. **处理“未找到库”的情况**：当你查询一个非常小众的库时，可能遇到解析失败。此时，GroundTruth会尝试回退到npm等包管理器，返回基础信息（如最新版本号、描述）。虽然可能没有详细的最佳实践，但至少确认了库的存在和基本信息。你可以考虑向项目提Issue，请求将该库加入精选注册表。 4. **审计结果太多怎么办**：首次对整个大型项目运行`gt_audit({ categories: ["all"] })`可能会返回大量问题。不要被吓到。建议： * **分而治之**：按类别分批审计，先解决`critical`（高危）的`security`（安全）问题。 * **指定路径**：只审计你正在活跃开发的目录，如`gt_audit({ projectPath: "./src/modules/user" })`。 * **作为持续改进清单**：将报告导出，把问题录入团队的任务跟踪系统，按优先级逐步修复。 ### 6.3 常见问题与解决方案 * **Q: 安装后，在IDE里调用工具没反应或报错。** * **A1**: 首先确认Node版本>=24。运行`node -v`检查。 * **A2**: 检查MCP配置文件格式是否正确，特别是JSON的括号和逗号。可以使用在线JSON校验器。 * **A3**: 查看IDE的控制台或日志输出。通常会有更详细的错误信息，例如权限问题或网络连接失败。 * **Q: `gt_audit`扫描速度很慢。** * **A**: 这是正常的，尤其是首次扫描大型项目。因为它需要读取所有文件并进行模式匹配。后续扫描由于有缓存会快很多。你可以通过设置`categories`参数只扫描关心的类别来提速。 * **Q: 审计报告中的某个修复建议我觉得不对，或者不适用于我的场景。** * **A**: GroundTruth提供的修复建议是基于权威来源的“通用最佳实践”。它是一份极有价值的参考，但并非绝对真理。你需要结合自己项目的具体架构、业务逻辑和团队规范进行判断。工具的目的是“提示风险”和“提供方向”，最终的决策权在开发者手中。 * **Q: 如何为某个特定的内部公司库添加支持？** * **A**: GroundTruth的精选注册表（`src/sources/registry.ts`）是开源的。理论上，你可以fork项目，按照相同格式为你公司的内部库添加条目（指定`name`、`docsUrl`等），然后自行构建和运行这个修改后的版本。但这需要一定的开发投入。对于绝大多数公共库，现有的回退机制已经足够。 GroundTruth-MCP代表了一种新的AI辅助编程范式：AI不再是黑盒式的代码生成器，而是一个配备了实时、可验证事实核查能力的协作伙伴。它把开发者从“猜测AI生成的代码是否过时”的焦虑中解放出来，将精力重新聚焦于逻辑构建和业务创新。通过将本地运行、实时抓取、主动审计这些特性结合起来，它为自己在开发者工具链中找到了一个独特而稳固的位置——不是替代品，而是现有工具（如IDE Linter、SAST）在AI时代的关键补充。
