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 CodeClaude桌面应用的原生终端 这是最直接的方式通过Claude自带的MCP管理命令完成。claude mcp add gt -- npx -y groundtruth-mcp/gt-mcplatest执行后Claude Code会自动将其添加到配置中并立即生效。对于 Cursor / Claude Desktop / VS Code 你需要手动编辑对应的MCP配置文件。这些编辑器通常将配置放在以下位置Cursor:~/.cursor/mcp.jsonClaude 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-mcplatest] } } }关键细节这里使用了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 TokenPAT可以轻松解决。创建Token访问GitHub Settings - Developer settings - Personal access tokens - Tokens (classic)。生成一个新token不需要勾选任何scope权限。一个无scope的token足以将API速率限制从60/小时提升到5000/小时且非常安全。集成TokenClaude Code:claude mcp add gt -e GT_GITHUB_TOKENghp_yourtoken -- npx -y groundtruth-mcp/gt-mcplatest配置文件在MCP服务器配置中添加env字段。{ mcpServers: { gt: { command: npx, args: [-y, groundtruth-mcp/gt-mcplatest], env: { GT_GITHUB_TOKEN: ghp_yourtoken } } } }2. 自定义缓存目录可选GroundTruth会缓存抓取到的文档以减少重复请求。默认缓存位置是~/.gt-mcp-cache。你可以通过环境变量GT_CACHE_DIR将其更改到其他路径例如一个更快的SSD盘或一个共享的网络位置。{ mcpServers: { gt: { command: npx, args: [-y, groundtruth-mcp/gt-mcplatest], 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:28src/legacy/auth.js:15scripts/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:12src/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**建议在生产环境中设置连接池参数并警告N1查询问题附上使用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. **重视代码安全和质量**需要自动化审计。br2. **依赖链更新频繁**需要获取即时的迁移指南和变更日志。br3. **开发环境受限或对数据隐私敏感**需要完全本地化的解决方案。br4. **需要进行技术选型对比**gt_compare或检查浏览器兼容性gt_compat。 | 1. **查询模式更自由、更口语化**喜欢用自然语言提问而非精确的工具调用。br2. **查询的库非常小众或冷门**可能不在GroundTruth的精选列表内。br3. **可以接受云端服务**且月度查询量在免费额度内。 | **我的选择与理由** 在我的日常全栈开发中我主要使用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时代的关键补充。