给 Claude Code 造个趁手的 MCP Tool Server，聊聊我踩的那些坑

搞前端工具链搞了好几年，组件库、设计稿、代码模板这些东西散落在各个系统里。每次新需求来了，得先翻组件库找有没有现成的，再去 Figma 看设计稿，最后手动糊代码。这套流程重复了几百次之后，终于忍不了了——能不能让 AI 帮我把这几步串起来？

这块我花的时间最多，也是最想吐槽的部分。

MCP 的 Tool 定义看起来跟写个 JSON Schema 一样——给工具起个名字，声明入参类型，完事。但实际跑起来你就会发现，Schema 写得好不好，直接决定了 LLM 能不能正确调用你的工具。这不是”能用就行”的问题，是”差一点就完全不可用”的问题。

参数命名比你想的重要十倍

先说个真实场景。我做了个组件检索工具，第一版 Schema 长这样：

跑了几次发现 Claude 经常不传 参数，或者把 理解错。改成下面这样之后命中率直接从六成拉到九成以上：

区别在哪？三个地方：工具名自带语义（ → ），参数名是人话（ → ），description 里给了具体例子。

这不是什么高深的道理，但你不踩一遍坑真的意识不到——LLM 理解你工具的唯一信息源就是 Schema 里的文本。你偷懒少写一个 description，它就得靠猜，猜错的概率远比你想的高。

嵌套参数的深度控制

还有个坑是参数结构太深。一开始我想着n8n 工作流 教程把过滤条件做得灵活一点：

三层嵌套，参数十几个。结果 LLM 基本上构造不出正确的调用——它倒是能理解每个字段的意思，但组装成完整的嵌套 JSON 时总会漏字段或者层级搞错。

后来拍扁成一层：

经验就一句话：Schema 嵌套不超过一层，参数不超过 6-7 个。超了就拆成多个工具。你可能觉得”一个工具能干的事为什么要拆成三个”，但对 LLM 来说，三个简单工具比一个复杂工具好使得多。

多工具协作时的命名空间问题

项目里最终搞了七八个工具：搜组件、查设计稿、生成代码、查 API 文档……工具一多，命名冲突和语义模糊的问题就来了。

比如 和 都有个 参数，但前者期望的是组件名，后者期望的是 API 名。LLM 有时候会搞混到底该调哪个。

招很粗暴——给工具名加前缀：、、、。

这块我还没想透的是，当工具数量超过 15 个以后，LLM 的工具选择准确率是不是会断崖式下降。目前我控制在 10 个以内没出过问题，但如果以后要接更多系统进来，可能得做工具的动态加载——根据当前对话上下文只暴露相关的工具子集。先放着，等真到那一步再说。

配置 MCP Server 接入 Claude Code 这步反而没什么好说的，比想象中顺滑。

在项目根目录的 里声明一下就行：

Server 端用 起一个 stdio 类型的服务就行。真正要注意的只有一件事：错误处理必须返回结构化信息，不能直接 throw。

组件检索看着是最简单的功能——不就是个搜索嘛。但要做到 LLM 能真正用起来，返回的数据格式得反复调。

关键发现：返回给 LLM 的组件信息，多了不行少了也不行。

一开始我把组件的完整源码都返回了，结果 context 直接爆掉。后来只返回组件名和一句话描述，又太少了，LLM 没法判断这个组件到底能不能用。

最后稳定下来的格式大概是这样——组件名、Props 类型定义（只保留 public 的）、一个最简使用示例、适用场景的一句话说明。差不多 30-50 行的信息量，刚好够 LLM 判断要不要用、怎么用。

最后说说怎么把组件检索、设计稿解析、代码生成串成一条工作流。

一个典型场景：产品丢过来一个 Figma 链接，说”照这个做”。理想的流程是——解析设计稿拿到结构 → 匹配已有组件 → 生成代码。听着挺丝滑，但实际编排的时候有个根本性的取舍要做。

自动编排 vs 人工确认

第一种思路是全自动：在 MCP Server 内部把三步串起来，对外只暴露一个 工具，一步到位。

第二种思路是拆开：暴露 、、 三个独立工具，让 Claude 自己决定调用顺序，每一步人都能看到中间结果。

我最开始选了第一种，因为显然更”优雅”。跑了一周之后切回了第二种。

原因很现实——全自动流程一旦中间某步出错（比如设计稿里有个自定义图标组件库里没有），整条链路就废了，返回一个笼统的错误信息，你还得去翻日志看是哪步挂的。拆开之后，Claude 调完 会先把结构展示出来，你扫一眼说”这几个组件用现有的，那个图标先跳过”，它再去调 ，灵活得多。

这个取舍背后的道理其实很通用：

返回值设计影响下一步决策

还有个容易忽略的细节——上一个工具的返回值格式，直接影响 LLM 下一步能不能做出正确决策。

返回的设计稿结构里，我专门加了一个 字段：

这个 不是 Figma 原生的，是我在解析层做的一层映射——根据图层命名和结构特征猜一个可能的组件名。猜对了 LLM 直接拿去搜，猜错了也没关系，LLM 会根据搜索结果自行调整。

但如果不加这个字段，LLM 就得自己从图层名”顶部导航”推断出应该搜”NavBar”，这步推断的准确率大概七成，加了字段之后变成九成。一个小字段，效果差很多。

这让我意识到一件事：设计 MCP 工具的时候，不能只想”这个工具给人用该返回什么”，得想”给 LLM 用该返回什么“。有时候需要多返回一些冗余信息，专门用来降低 LLM 的推理难度。这跟传统 API 设计的”返回最少够用的信息”正好相反。

说到底，MCP Tool Server 就是给 AI 用的 API。但”给 AI 用”和”给人用”的设计直觉差异比想象中大——Schema 要更语义化，参数要更扁平，返回值要更冗余，错误信息要更具体。把这几条刻进脑子里，剩下的都是体力活。