UnifAPI 如何从几十个端点发展到由三个 MCP 目录工具承载的大规模公开数据操作集，以及 Skills 为何能隐藏这种复杂度。

一句话总结：这篇工程笔记解释了为什么 UnifAPI 通过三个 MCP 工具来暴露一个庞大的操作目录，以及为什么 Skills 是位于那个目录之上、面向用户的那一层。

UnifAPI 最初的 MCP 目录暴露了 73 个端点。当前的目录则通过三个 MCP 工具——list_operations、get_operation 和 call_api——跨各实时公开数据 API 暴露了一个庞大的操作集。要把这件事做好，比看上去要难：模型仍然得发现正确的操作、检视 schema，并发起一次干净的调用。下面是我们关于命名、描述、参数 schema，以及那些直到你有几十个操作上线后才会冒出来的故障模式所学到的东西。

为什么一个庞大的操作集会改变产品

在 5-10 个操作时，MCP「直接就能用」——模型搜索目录、挑出一个、调用它。到 20-30 个时，操作命名开始变得重要；你会看到模型偶尔挑到那条「相近但不对」的路径。到 50 个以上时，目录本身就成了承重结构。

数量还会继续增长，但产品上的教训已经很清楚：随着操作数量上升，Skills 变得更重要，因为它们把目录导航藏到了一个任务结果背后。

操作命名：可被 Agent 读懂，而非可被人类读懂

我们的操作标签遵循一个模式：平台、动词、名词。TikTok search videos、Reddit get post、LinkedIn search people。啰嗦，但毫不含糊。模型之所以能挑对操作，是因为名字读起来像一个句子片段，而不是一个代码标识符。

我们早期试过更短的约定——tiktok.search、reddit.post——结果看到模型在相近的成对操作上挑错（用户说「search」时，TikTok 上的「search」和 Reddit 上的「search」就分不清了）。而操作标题里的平台前缀，无需模型去推理就消除了歧义。

描述就是提示词

每个操作描述只有一两句话。模型在发现和检视阶段会看到它们。有两种模式对得起它们消耗的 token：在头 12 个词里用「动词-宾语」的概要打头，并以一个「何时使用」的提示收尾。

好的写法："Search TikTok for videos matching a keyword or hashtag. Use when the user wants short-video discovery on a topic." 差的写法："This endpoint allows you to query the TikTok platform and retrieve a paginated list of videos that match a search term, optionally filtered by various parameters including ..." 第二种从技术上讲更完整，但在一个庞大的目录里是错误的取舍。

参数 schema：保持扁平

call_api 接受一个扁平对象：path、method、query 和 body。必填字段在前，可选字段在后。原因很简单：嵌套的 JSON schema 会把模型的工具调用生成器搞糊涂。我们见过 Claude 正确理解了一个参数，却因为 schema 看起来像有分支，而把它输出在了错误的嵌套层级上。

当一个操作确实需要多态输入时（按关键词或按话题标签搜索），get_operation 就需要给出一个具体的调用示例。每一次，一个具体示例都胜过一个带分支的 schema。

我们做错了什么

有三个值得点名的错误。第一，我们让 Twitter 和 Reddit 各自的搜索操作有了几乎相同的描述，结果在用户明确要求其中一个时，模型却开始挑另一个。修复办法是让每条描述在第一句里就明确点出自己的平台。

第二，有一阵子我们把数据源的错误消息原样透传了出去。其中一些引用了模型并不理解的平台专有概念，于是 Agent 会陷入循环，试图去修一个本被我们的封装藏起来的问题。修复办法是把错误归一化为一套封闭词汇，比如 unauthorized、validation_error、invalid_id、not_found、rate_limited 和 upstream_unavailable。

第三，我们在几个操作上对分页的文档写得不够，于是模型每一轮都从游标 0 重新调用，而不是往前推进。修复办法是把分页契约明明白白地写进被检视的操作数据本身，而不只是写在规范里。

尚未有定论的问题

我们到什么时候才该给目录分区？如今一个庞大的操作集还能装在一个 MCP 服务器背后，但目录最终也许会需要品类过滤器或品类专属的服务器，好让模型只加载它需要的东西。

我们还不知道正确答案。如果你今天正在交付大量消费 UnifAPI 操作的 Agent，我们很想听听在你那边操作挑选的延迟看起来如何——给我们写封信吧：hello@unifapi.com。

MCP 目录工具设计：从几十个端点到一个庞大的操作集