上个月我们做了一个实验：把一个 180K 行的 Spring Boot 单体代码库接入 Claude Code，让它做一次全量架构分析。

结果 Claude 给出了一份比我们技术 lead 更细的依赖关系图，还发现了三处我们自己没注意到的循环依赖。

听起来很美好。但在那之前，我们踩了整整 6 周的坑。

其中最阴险的一个：我们搭的 MCP Server 暴露了 60 个工具，Claude Code 在某些 session 里会静默丢失其中一部分，没有任何报错，你根本不知道它已经"瞎了"。

这篇文章是那 6 周的踩坑记录。不是 tips 清单，是架构设计层面的复盘——哪里设计错了、为什么错、改成什么样才对。

先说说我们为什么要搭 MCP 检索层

大多数工程师用 Claude Code 的方式是：遇到问题，让它读几个文件，回答完事。

这在小项目里够用。但我们的代码库是 47 个开发维护了 4 年的 Spring Boot 单体，180K 行，模块间依赖错综复杂，一个业务改动往往牵扯 5 到 8 个 service。

用"喂文件"的方式让 Claude 分析，有两个死穴：

第一，Claude 的上下文窗口是 200K tokens，但一次深度分析很容易把它耗光。 按每个 Java 文件 300 行、每行 10 token 粗估，200K tokens 大约能装 600 个文件。听起来不少，但 Claude 读依赖时是递归的——你问一个 OrderService，它会连带读 PaymentService、InventoryService、UserService……读完一轮，上下文已经满了一半。

第二，全量读代码效率极低，Claude 的注意力被稀释了。 60 个文件里，真正和问题相关的可能只有 5 个。让 Claude 全量读完再找答案，相当于让一个工程师把整个代码库背一遍再回答你的问题。

MCP Server 的思路是反过来：不是给 Claude 代码，是给 Claude 查代码的能力。

就像给一个新工程师 IDE 的搜索功能，而不是印一本代码全集塞给他。

图：传统全量读取消耗 150K tokens，MCP 检索层每次查询约 2500 tokens，降幅 83%

工具数量超限会静默失效——这是最坑的地方

我们搭的第一版 MCP Server 暴露了 60 个工具：按模块细分的依赖查询、按服务维度的接口列表、历史 PR 摘要、配置项检索……

跑了两周，Claude 的表现时好时坏。有时候问它 OrderService 的依赖关系，它能给出很准确的结果；有时候问同样的问题，它说"我没有查询依赖关系的工具"。

一开始以为是 prompt 的问题，后来在 Claude Code 的 GitHub issue 里找到了答案。

MCP Server 注册的工具数量过多时，服务器可能在启动时静默失败。 没有报错，没有警告，就是工具消失了。受影响最大的是工具数量较多的服务——community 反馈里，10 个工具的 server 几乎从不出问题，50 个工具的 server 偶发失败，169 个工具的 server 是高频失败。

这里有个额外的维度：工具描述消耗 context 的量超乎想象。 一个实测数据是，开启所有 MCP server 的情况下，工具描述就消耗了整个上下文窗口的 41%（约 82000 tokens）——在任何对话开始之前。

这有双重危害：一方面减少了真正用来推理的上下文空间，另一方面，研究数据显示 LLM 在工具数量超过 10-20 个时会出现"认知过载"，开始混淆工具或者选错工具。

我们的解法分两步：

第一步：把 60 个工具合并成 12 个，用参数区分意图而非用独立工具区分。

// 改之前：4 个独立工具
search_order_service_deps()
search_payment_service_deps()
search_inventory_service_deps()
search_user_service_deps()

// 改之后：1 个工具，service_name 参数区分
search_service_dependencies(service_name: string)

// 同理，5 种 Firecrawl 模式 → 1 个工具 + mode 参数
query_codebase(query: string, scope: "service" | "api" | "config" | "pr_history" | "metrics")

这一步让工具数量从 60 降到 12，context 消耗从原来的 40000+ tokens 降到约 8000 tokens，减少了 80%。

第二步：把工具描述缩减到极致。

工具描述越长，占用的 context 越多，且不影响 Claude 的实际理解。我们把所有工具描述从平均 87 token 压到平均 20 token。

// 改之前（87 tokens）
description: "This tool allows you to search for dependencies between microservices 
in our Spring Boot monolithic architecture. Provide a service name to get a 
complete list of all services that depend on it and all services it depends on, 
including transitive dependencies..."

// 改之后（15 tokens）
description: "Query service dependency graph. service_name: target service."

原则是：描述只告诉 Claude「这个工具做什么」，不要教 Claude「怎么用这个工具」——那是参数 schema 的工作。

结构化代码检索的正确设计

第一版我们设计 MCP Server 的时候走了一个弯路：把整个 service 的代码文本直接塞进工具返回值。

// 错误做法：返回原始代码文本
tool: get_service_code
return: "public class OrderService { \n  @Autowired\n  PaymentService paymentService..." 
// 一个大 service 返回 5000+ tokens

这等于把全量读文件的问题移到了工具调用层面，治标不治本。

正确的做法是：工具只返回结构化的元信息，原始代码文本按需提供。

我们重新设计了三层检索接口：

第一层：意图识别层，返回高度摘要的信息，帮 Claude 判断"值不值得深挖"

// 示例：查询服务依赖关系
tool: query_service_graph
input: { service: "OrderService", depth: 1 }
output: {
  direct_dependencies: ["PaymentService", "InventoryService"],
  depended_by: ["ApiGateway", "BatchProcessor"],
  last_modified: "2026-04-12",
  complexity_score: 7.2  // 1-10，越高越复杂
}
// 返回约 200 tokens，而非原始代码的 5000 tokens

第二层：符号级查询层，精确到函数/接口级别

// 查询某个接口的所有实现
tool: find_implementations
input: { interface: "PaymentGateway" }
output: {
  implementations: [
    { class: "AlipayGateway", file: "src/payment/AlipayGateway.java", line: 23 },
    { class: "WechatPayGateway", file: "src/payment/WechatPayGateway.java", line: 18 }
  ]
}
// 精确定位，Claude 知道去哪里读源码

第三层：原文获取层，只在前两层锁定目标后才调用

// Claude 确认要读之后，按需获取原始代码
tool: read_source_fragment
input: { file: "src/payment/AlipayGateway.java", start_line: 23, end_line: 80 }
output: { code: "..." }  // 57 行，约 600 tokens

三层下来，平均每个问题的 context 消耗从 15000 tokens 降到了 2500 tokens 左右。同时，Claude 的回答质量反而更好——因为它拿到的是精准信息，不是噪音。

这个设计有一个副作用我没预料到：它迫使我们把代码库的结构化信息维护成一个独立的 index。 这个 index 本身就成了团队新人快速理解系统的文档——比任何手写的架构文档都准确，因为它是从代码自动生成的。

图：三层检索架构，三层合计约 950 tokens，比直接读文件降幅 94%

LSP 集成：给 Claude 装上 IDE 的眼睛

到这里，Claude 能查依赖、能查接口实现了。但有一类问题它还是答不好：跨文件的符号引用。

"这个 processPayment 方法在哪些地方被调用？" 用文本搜索找，会把注释、变量名、字符串里的 processPayment 全搜出来；真正的代码调用，得用 AST 级别的语义分析才能准确。

这就是 LSP（Language Server Protocol）的价值所在。

IDE 里的"Go to Definition"和"Find All References"背后就是 LSP——它建立了代码的语义索引，能准确区分"这个 processPayment 是调用"和"这个 processPayment 是字符串"。

把 LSP 能力通过 MCP 暴露给 Claude，它就拥有了和 IDE 完全等价的代码导航能力。

我们用的是 cclsp（640 stars），它把 LSP 封装成 6 个 MCP 工具：

find_definition(symbol: "PaymentGateway")
find_references(symbol: "processPayment")
rename_symbol(symbol: "processPayment", new_name: "executePayment")
get_diagnostics(file: "src/payment/AlipayGateway.java")

一个实测数据：用 find_references 定位一个函数的所有调用点，cclsp 大约耗时 50ms；用纯文本 grep 搜相同的结果，加上人工过滤误报，约需 45 秒。

但有个地方需要注意：cclsp 需要本地有对应语言的 Language Server 安装。 Java 的话需要 eclipse.jdt.ls，Go 需要 gopls，TypeScript 需要 typescript-language-server。在 Plugin 打包时（后面会说）要把这个前置依赖说清楚，否则新工程师装完什么都用不了。

图：cclsp 640 stars，支持 11 种语言，find_references 50ms 对比 grep 45 秒

Plugin 打包：让新工程师 day 1 即有满配 context

把这套东西搭好之后，我们遇到了一个工程化问题：怎么让 47 个工程师都用上同一套配置？

手动文档的方式不现实——"记得在 ~/.claude/mcp.json 里加这个，然后装这个 npm 包，再配置这个环境变量……" 两周后一半人配错，另一半人没配。

Claude Code 的 Plugin 系统是解法。

Plugin 是一个可分发的目录包，包含 Skills、Hooks、MCP 配置三件套：

codebase-intelligence-plugin/
├── .claude-plugin/
│   └── plugin.json        ← 插件元信息
├── skills/
│   ├── code-review/
│   │   └── SKILL.md       ← 代码审查工作流
│   └── arch-query/
│       └── SKILL.md       ← 架构查询工作流
├── hooks/
│   └── hooks.json         ← PostToolUse: 写完文件自动跑 lint
└── .mcp.json              ← MCP Server 配置（含 cclsp + 自建 codebase-server）

plugin.json 示例：

{
  "name": "codebase-intelligence",
  "description": "团队代码库智能检索：MCP 代码查询 + LSP 符号导航 + 自动 lint",
  "version": "1.2.0"
}

.mcp.json 里统一配置好两个 server：

{
  "mcpServers": {
    "codebase-server": {
      "command": "node",
      "args": ["./bin/codebase-server.js"],
      "env": {
        "CODEBASE_INDEX_PATH": "${PROJECT_ROOT}/.codebase-index"
      }
    },
    "cclsp": {
      "command": "npx",
      "args": ["-y", "cclsp"],
      "env": {
        "CCLSP_CONFIG": "${PROJECT_ROOT}/.cclsp.json"
      }
    }
  }
}

新工程师 day 1 的操作是：

claude --plugin-dir ./codebase-intelligence-plugin
# 或者从团队私有 marketplace 安装
claude plugin install @team/codebase-intelligence

装完即用，Skills、MCP、Hooks 全部到位。

我们团队用这套配置之后，新工程师的上手时间从以前的 6 周（真实数字，因为代码库实在太复杂）降到了大约 10 天。不是说 Claude 替代了学习，而是 Claude 接管了"用哪里的代码库 API 实现这个功能"这类机械性问题，让人可以把时间花在理解业务逻辑上。

图：Plugin 目录结构 + 新工程师 day 1 一键安装流程，上手时间从 6 周降到 10 天

常见问题

Q：我的代码库才 1 万行，值得搭这套吗？

说实话，不值得。这套东西的收益随代码库规模指数级放大，1 万行以下用 CLAUDE.md 把关键路径说清楚就够了，全量读也没多大代价。我建议的阈值是：代码库超过 3 万行、模块间耦合严重、或者团队 5 人以上，才考虑上 MCP 检索层。

Q：MCP Server 的工具数量上限到底是多少？

官方没有明文规定，社区实测是：约 50 个工具以内基本稳定，超过 100 个开始高频出现静默失效。我们的建议是控制在 20 个以内——不是怕失效，而是工具太多 Claude 的工具选择质量会变差，20 个以内是它能精准匹配工具的舒适区。

Q：代码库 index 怎么保持更新？

我们的方案是：MCP Server 启动时做增量 diff，只重建有变化的模块。完整重建一次（180K 行）约需 8 分钟，增量更新通常在 30 秒以内。工程师 push 代码后，CI pipeline 会触发一次 index 更新，保证 Claude 看到的是最新状态。有一个原则要记住：宁愿用轻微过期的 index，也不要在工具调用时实时扫描整个代码库——那会让每次工具调用耗时 10 秒以上，用户体验很差。

Q：Plugin 里的 MCP 配置和项目根目录的 .mcp.json 冲突怎么办？

Plugin 的配置会和项目本身的配置合并，同名 server 以项目根目录的优先。实践中建议 Plugin 里的 server 名字加上团队前缀（比如 team-codebase-server），避免和社区 Plugin 冲突。

Q：Claude Code 有时候"忘记"用工具，直接凭记忆回答，怎么破？

这个问题挺常见的，两个解法：一是在 CLAUDE.md 里明确写 "IMPORTANT: When answering questions about code architecture, always call the MCP tools to verify"；二是在 Skill 里把工具调用做成 workflow，不给 Claude"跳过工具"的机会。

参考资料

• Claude Code 官方最佳实践 — Plugin、MCP、CLAUDE.md 配置体系完整文档
• MCP Server 多工具静默失效 GitHub Issue — 真实踩坑记录，含社区 workaround
• cclsp: LSP × MCP 集成项目 — 640 stars，支持 11 种语言的 LSP-MCP 桥接
• Claude Code Plugin 创建文档 — 官方 Plugin 打包和分发指南
• 优化 MCP Server Context 使用量 — 工具合并实测：从 20 个工具合并到 8 个，context 减少 60%
  

说到底，给 Claude Code 配一套 MCP 检索层，本质上是在做「代码库可观测性」的工程——把一个只有老工程师才懂的隐式知识图谱，变成任何人（包括 AI）都能查询的显式结构。这件事做完，受益的不只是 Claude，是整个团队。工具数量超限的坑算是意外收获：它逼着我们把 API 设计从"把所有功能塞进去"改成"每个工具只做一件事"，这反而让代码库 index 本身变得更清晰了。如果你们团队也在做类似的事情，下篇我打算聊聊 index 的增量更新策略——关注一下，发了第一时间推给你。身边有人在做大代码库 AI 接入，这篇可以直接甩给他，省他重踩一遍。