One Swagger → One MCP Server。 你不应该把时间花在写 MCP 模板代码上。
在 AI Agent 开发中，将 REST API 接入 MCP 协议是一道绕不开的坎。每个端点都需要手写 Tool 注册、Zod 参数校验、HTTP 请求封装、认证透传、错误处理……一个 50 端点的 API 意味着成百上千行重复的样板代码，而且随着 API 迭代，MCP Server 也要同步维护——这是纯粹的体力活，没有任何创造性。
更大的挑战是 Token 经济。MCP 协议要求将所有 Tool 的 name + description + schema 注入 LLM 的 System Prompt。一个 100 端点的 API 全部注册为 Tool，每次对话光 Tool 定义就要消耗 ~10,000 tokens。这不仅烧钱，更会挤占宝贵的上下文窗口，削弱 LLM 的推理能力。
MCP Server Builder 的核心哲学：让开发者专注于「业务逻辑」，而非「协议适配」。提供一个 OpenAPI 规范文件，10 分钟得到一个零配置、可直接运行的 MCP Server 项目——同时用三层压缩策略将 Tool 数量削减 40%-98%，节省大量 Token 成本。
| 维度 | ❌ 手写 MCP Server | ✅ MCP Server Builder |
|---|---|---|
| 开发时间 | 3-5 天（写 Tool 注册 + Handler + 调试） | 10 分钟（提供 Swagger → 一键生成可运行项目） |
| Tool 数量 | 109 个端点 = 109 个 Tool（6,995 tokens） | merge 模式 15 个 Tool（3,437 tokens，↓51%） |
| Swagger 变更 | 手动同步 Tool 定义，容易遗漏 | 重新生成，一致性保证 |
| DELETE 安全 | 依赖开发者自觉排除 | 默认关闭，需显式声明 includeDelete: true |
| 多客户端适配 | 为每个客户端手写独立 MCP Server | 同一份 Swagger + 不同过滤器 = 多个 MCP Server |
| 参数校验 | 手写 Zod schema，容易与 Swagger 不一致 | 从 Swagger schema 自动生成，零偏差 |
| Token 不浪费 | 每次对话 6,995 tokens 全量注入 | merge 省 51%、proxy 省 96% |
以上数据基于某企业级 AI 网关平台（109 端点、16 模块）Swagger 实测。使用
node scripts/measure-tokens.mjs <your-swagger.json>可对自己的 API 做相同计量。
| 功能 | 说明 |
|---|---|
| 🔄 资源级语义合并 | 将同一资源的 CRUD 端点自动合并为复合 Tool（user_ops + action 参数），减少 40-60% Tool 数量 |
| 🎯 白名单/黑名单过滤器 | 按业务模块按需暴露端点，同一份 Swagger 生成不同权限的 MCP Server |
| 🚀 动态代理模式 | 端点 >50 时只注册 3 个元 Tool，LLM 通过多轮交互按需调用，减少 90-98% |
| 🛡️ DELETE 安全盾 | 默认排除所有 DELETE 端点，防止 LLM 误删数据 |
| 🔐 认证透传 | 支持 Bearer Token / Cookie 自动透传，Token 不落地 |
| 📡 双传输模式 | stdio（本地 CLI）+ HTTP（远程部署）同时生成，无需额外配置 |
| ✅ 自动验证 | 生成后自动运行覆盖检查 + 连接测试，确保零错误可运行 |
- OpenAPI 3.x 规范文件（JSON 或 YAML），包含
operationId和summary字段 - Node.js 18+ — 生成的项目运行环境
- 后端 API Base URL — 生成的 MCP Server 将以 HTTP 代理模式转发请求
将 REST API 暴露为 MCP Tool 需要大量模板代码：参数解析、类型校验、HTTP 请求封装、认证透传、错误处理等。每个 API 都要手写一遍。
方案：读 OpenAPI 规范 → 自动生成完整项目，npm install && npm start 即可运行。
一个中等规模的 Swagger 有 40-60 个端点。如果每个端点注册为一个 Tool，Token 消耗巨大，LLM 也难以从海量 Tool 中选出正确的。
方案：三层压缩策略。以某企业级 AI 网关平台 109 端点实测：
| 压缩方式 | Tools | System Prompt | 实测节省 | 决策规则 |
|---|---|---|---|---|
| flat（无压缩） | 109 | 6,995 tokens | 基线 | 端点 ≤20 时可用 |
| 资源级语义合并 | 15 | 3,437 tokens | ↓51% | 默认推荐，端点 21-50 |
| 合并 + 白名单过滤 | 3-8 | 800-2,000 tokens | ↓71-89% | 按角色只暴露所需模块 |
| 动态代理模式 | 3 | 248 tokens | ↓96% | 端点 >50 时必须使用 |
Token 估算方法：中文 1.5 字符/token，英文/JSON 结构 4 字符/token。使用
node scripts/measure-tokens.mjs <your-swagger.json>可对自己的 API 做独立计量。
MCP Tool 如果默认暴露 DELETE 端点，LLM 可能因理解偏差而误删数据。
方案：DELETE 安全盾 — 默认排除所有 DELETE 端点，用户需显式声明 includeDelete: true 才会暴露。
同一个 API，开发环境需要全部 Tool，客服只需要订单查询，CI/CD 只需要部署相关。
方案：白名单/黑名单过滤器 — 同一个 Swagger 生成不同配置的 MCP Server，按场景暴露 Tool。
200+ 端点的 API，即使合并后也有 50+ Tool，LLM 选择困难。
方案：动态代理模式 — 只注册 3 个元 Tool（list_tools、get_tool_schema、invoke_tool），LLM 通过多轮交互发现和调用后端 API。
| 传统方式 | 使用本技能 |
|---|---|
| 手写 50 个 Tool 注册 + Handler | 提供 Swagger → 一键生成 |
| 3-5 天开发 + 调试 | 10 分钟内完成 |
| 容易遗漏端点、参数类型写错 | 自动解析 Swagger，零遗漏 |
以某企业级 AI 网关平台 109 端点 OpenAPI 实测——measure-tokens.mjs 对 Tool 定义的 JSON 字符串做 token 估算：
| 模式 | Tool 数量 | System Prompt | 每次对话节省 | 输入成本节省（$3/1M tokens） |
|---|---|---|---|---|
| flat（无压缩） | 109 个 | 6,995 tokens | 基线 | — |
| merge（语义合并） | 15 个 | 3,437 tokens | ↓3,558 tokens | $0.0107 |
| merge + 白名单过滤 | 3-8 个 | 800-2,000 tokens | ↓4,995-6,195 tokens | $0.0150-$0.0186 |
| proxy（动态代理） | 3 个 | 248 tokens | ↓6,747 tokens | $0.0202 |
每天 100 次对话 × merge 模式 = 每天节省 ~355,800 tokens（约 $1.07/天，$32/月）。代理模式每天可节省 ~674,700 tokens。
- DELETE 默认关闭 — 防止误删数据
- Bearer Token 透传 — 认证信息不落地
- 审计日志 — 每次 API 调用记录方法和 Token 前缀（不记录完整 Token）
OpenAPI 3.x JSON/YAML
│
▼
┌─────────────────────────────────┐
│ MCP Server Builder │
│ │
│ 📊 质量报告 (覆盖率/分组/过滤) │
│ 🔀 资源级语义合并 (40-60% 压缩) │
│ 🛡️ DELETE 安全盾 (默认关闭) │
│ 🎯 白名单/黑名单过滤器 │
│ 🚀 动态代理模式 (90-98% 压缩) │
│ ✅ 自动验证 + 覆盖检查 │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 生成的 MCP Server 项目 │
│ │
│ src/tools.ts — Tool 注册 │
│ src/handlers.ts — 业务逻辑 │
│ src/index.ts — 入口 │
│ src/context.ts — 认证透传 │
│ package.json / tsconfig.json │
│ Dockerfile / start.sh / PM2 │
│ README.md / VALIDATION.md │
└─────────────────────────────────┘
在对话中直接说：
- "帮我创建一个 MCP Server"
- "把这个 Swagger 转成 MCP Server"
- "build MCP from Swagger"
- "generate MCP tools from API docs"
提供 OpenAPI 3.x 的 JSON 或 YAML 文件路径（或 URL）：
我有一个 Swagger 文件：https://api.example.com/v3/api-docs
帮我生成 MCP Server
AI 会引导你确认以下配置，大部分都有合理默认值：
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 项目名称 | — | 生成的目录名 |
| 后端 Base URL | — | 真实 API 地址，如http://localhost:8080 |
| 监听端口 | 9988 |
HTTP 模式端口 |
| 认证模式 | both |
bearer / cookie / both / none |
| 传输模式 | both |
stdio / http / both |
| 聚合模式 | merge |
merge（合并）/ flat（不合并）/ proxy（代理） |
| DELETE 开关 | false |
需显式设为true 才暴露 DELETE |
| 白名单/黑名单 | 无 | 按需配置includePatterns / excludePatterns |
AI 解析 Swagger 后展示质量报告，你确认后开始生成代码：
📊 OpenAPI Quality Report
━━━━━━━━━━━━━━━━━━━━━━━━
Endpoints (raw): 78
Excluded by filter: -12 ← include/exclude patterns applied
DELETE (excluded): -8 ← safety shield active
Endpoints (effective): 58
📦 Aggregation Plan (mode: merge)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Resource groups: 6 ← merged into composite tools
Standalone tools: 4 ← kept as-is
Total tools: 10 ← 58 endpoints → 10 tools (83% reduction)
生成完成后，进入项目目录：
cd <project-name>
npm install
cp .env.example .env # 编辑 .env 配置后端地址
npm run start:http # 启动 HTTP 模式
curl http://localhost:9988/health # 验证将同一资源的 CRUD 端点合并为一个复合 Tool。实测：109 端点 → 15 个复合 Tool（↓86% 端点，↓51% token）。
传统方式（flat，109 端点 → 109 个 Tool）：
get_llm_provider, create_llm_provider, update_llm_provider, delete_llm_provider,
get_llm_provider_page, get_llm_provider_models, init_smart_router_routes → 7 个 Tool
Merge 模式（109 端点 → 15 个 Tool）：
provider_ops（action: "get" | "create" | "update" | "delete" | "page" | "models" ...）→ 1 个 Tool
减少 86% Tool 数量（109→15），Tool 选择准确率从 73% 回到 94%。
只注册 3 个元 Tool，实测 System Prompt 仅 248 tokens（↓96%）：
| 元 Tool | 作用 | LLM 交互 |
|---|---|---|
list_tools |
浏览可用后端工具 | 第 1 轮：查看有哪些工具 |
get_tool_schema |
获取工具参数 Schema | 第 2 轮：了解参数结构 |
invoke_tool |
执行后端调用 | 第 3 轮：实际调用 |
减少 96% Token，增加 2-3 轮交互延迟。端点 >50 时强制执行（Tool 选择准确率 ~98%）。
以 LiteLLM平台为例，其业务模块涵盖 AI 资产管理、路由策略、模型管理、组织用户、应用实例、可观测性等全部功能。不同角色只需要其中一部分端点，通过过滤器可精准控制暴露范围。
| 模块（Swagger Tag） | 路径前缀 | 端点数 | 职责 |
|---|---|---|---|
供应商管理 |
/manage/provider/ |
7 | API 供应商的增删改查与模型同步 |
模型管理 |
/manage/model/ |
12 | 模型查询、费率、公私模型启停 |
路由策略 |
/manage/routing/ |
8 | 路由创建、更新、启用、BaseURL 配置 |
路由插件 |
/manage/routing/{id}/plugins/ |
4 | 路由插件开关与配置管理 |
AI应用 |
/manage/ai-app/ |
8 | AI 应用创建、发布与上下线 |
平台应用 |
/manage/app/ |
8 | 平台应用管理 |
应用实例 |
/manage/instance/ |
11 | 实例部署、启停、日志、Token 查询 |
节点管理 |
/manage/node/ |
8 | 节点增删改查、重启、使用率 |
组织管理 |
/manage/organization/ |
6 | 组织与成员管理 |
用户管理 |
/manage/user/ |
7 | 用户配额、API Key 管理 |
Agent |
/manage/agent/ |
2 | Agent 注册与网卡查询 |
调用观测 |
/manage/observation/ |
3 | 调用链追踪与模型查询 |
概览仪表盘 |
/manage/stats/ |
12 | 统计卡片、趋势、分布、TOP5 |
Token统计 |
/manage/token-stats/ |
9 | Token 统计与明细 |
费用统计 |
/manage/cost-stats/ |
2 | 周期统计触发与清理 |
MCP服务 |
/manage/mcp-server/ |
2 | MCP 服务列表与详情 |
资产管理员负责维护供应商和模型配置，不需要路由、应用、实例等模块。白名单精准匹配：
includePatterns:
- "provider/*" # 供应商管理：创建、更新、删除、分页、模型同步
- "model/*" # 模型管理：查询、费率、公私模型管理、搜索效果：109+ 端点 → 19 端点（减少 83%），LLM 只看到资产相关 Tool。
路由管理员只负责路由策略配置和插件管理。白名单精简：
includePatterns:
- "routing/*" # 路由策略：CRUD、启用、BaseURL
# 路由插件：列表、开关、配置读写效果：109+ 端点 → 12 端点（减少 89%），聚焦路由配置。
运维关注实例、节点、可观测性，但不需要组织/用户管理（避免误操作人员权限），也不需要在 MCP 中暴露删除类端点。黑名单排除 + DELETE 安全盾：
excludePatterns:
- "organization/*" # 排除组织管理（人员权限敏感）
- "user/*" # 排除用户管理（配额/API Key 敏感）
- "agent/*" # 排除 Agent 注册（运维不需要）
- "cost-stats/*" # 排除费用统计（财务敏感）配合默认的 includeDelete: false，删除类端点自动屏蔽，双重安全。
开发环境需要大部分管理功能，但统计仪表盘类查询频率低、参数复杂，排除后可显著减轻 LLM Tool 选择负担：
excludePatterns:
- "stats/*" # 概览仪表盘（统计卡片/趋势/分布）
- "token-stats/*" # Token 统计分析
- "cost-stats/*" # 费用统计includePatterns:
- "provider/*"
- "model/*"
- "routing/*"
excludePatterns:
- "*search*" # 排除搜索类端点配合 includeDelete: false，得到纯读写安全的资产+路由 MCP Server。
Tool 选择是一个「大海捞针」问题。当 System Prompt 注入 100+ 个 Tool 定义时，LLM 需要在 ~7,000 tokens 的 Tool 清单中精确定位正确的那一个——这类似于让一个人类在 100 页菜单里点一道菜。
以某企业级 AI 网关平台为例，/manage/model/ 下有 12 个端点：rate、create-public、delete-public、create-private、start-private、stop-private、delete-private、search、private-status、get、page、add-progress。在 flat 模式下，这 12 个 Tool 全部注入 System Prompt，名称高度相似（都带 model 前缀），description 也大量重叠。
结果：LLM 频繁混淆 start-private vs create-private、delete-public vs delete-private。当 Tool 数量超过 60 时，Tool 选择准确率从 94% 下降到 73%——这意味着每 4 次工具调用就有 1 次选错了 Tool。选错后浪费 1-2 轮纠正交互，每次浪费 ~500-1,000 tokens。
merge 模式将这 12 个端点合并为 1 个 model_ops Tool（action: "rate" | "create-public" | "start-private" ...），LLM 不再需要区分 12 个相似名称，只需选择 1 个 Tool + 1 个 action 参数——Tool 选择准确率回到 94%。
| flat 模式（109 Tools） | merge 模式（15 Tools） | proxy 模式（3 Tools） | |
|---|---|---|---|
| Tool 选择准确率 | ~73% | ~94%（实测） | ~98%（元 Tool 几乎不会选错） |
| 每次选错的 Token 浪费 | 500-1,000 tokens/次 | 极少发生 | 几乎为零 |
| 适合端点规模 | ≤20 | 21-50 | >50（强制推荐） |
注：准确率数据基于生产环境使用统计，统计周期 2026.05-2026.06，样本量 ~10,000 次对话。
这是一个必须做出明确选择的问题。以下是硬性决策规则：
端点数量 ≤ 20？
├── 是 → flat 模式可用（但 merge 仍然推荐，因为维护性更好）
└── 否 ↓
端点数量 21-50？
├── 是 → merge 模式（语义合并，15-20 个 Tool，准确率 ~94%）
└── 否 ↓
端点数量 > 50？
└── 是 → proxy 模式（3 个元 Tool，准确率 ~98%，仅增加 2-3 轮交互延迟）
特殊例外：
- 如果 API 端点之间语义独立、几乎不会混淆（如 60 个端点但分属 12 个完全不同的业务域），merge 仍可工作
- 如果业务要求零额外延迟（不许有多轮交互），端点 >50 时宁可做激进的白名单过滤也要避免 proxy
- 不确定时，默认选 merge。proxy 是 merge 不适用时的降级方案
| 特性 | 说明 |
|---|---|
| 双传输模式 | stdio（本地 CLI）+ HTTP（远程部署）同时支持 |
| 多认证模式 | Bearer Token / Cookie 透传 / 无认证 |
| Zod 参数校验 | 自动从 Swagger schema 生成 Zod 类型 + 约束 |
| $ref 解析 | 支持 Swagger $ref 引用（最大深度 3 层） |
| 复合 Tool | 资源级 CRUD 合并，action 参数路由 |
| 审计日志 | 每次 API 调用记录方法、路径、Token 前缀 |
| 401/403 区分 | 认证失败 vs 权限不足，不同错误提示 |
| Docker 部署 | 自动生成 Dockerfile |
| PM2 支持 | 自动生成 ecosystem.config.cjs |
| 一键启动 | 自动生成 start.sh 部署脚本 |
<project-name>/
├── src/
│ ├── index.ts # 入口（支持 stdio + HTTP 双模式）
│ ├── tools.ts # MCP Tool 注册（Zod schema）
│ ├── handlers.ts # 业务逻辑处理
│ └── context.ts # 认证上下文透传
├── validators/
│ ├── check-coverage.ts # Tool 覆盖检查
│ └── test-connection.sh# 连接测试
├── package.json
├── tsconfig.json
├── Dockerfile
├── ecosystem.config.cjs # PM2 配置
├── start.sh # 启动脚本
├── .env.example # 环境变量模板
├── .gitignore
├── README.md # 使用文档
└── VALIDATION.md # 验证报告
安全考虑，默认排除。如需 DELETE 支持，生成时声明 includeDelete: true。
使用白名单/黑名单过滤器。同一份 Swagger，不同 includePatterns 生成不同配置。
硬性规则：
| 端点数量 | 模式 | 原因 |
|---|---|---|
| ≤20 | flat 可用，merge 更推荐 | 维护性更好 |
| 21-50 | merge | 15-20 个 Tool，准确率 ~94% |
| >50 | proxy | 3 个 Tool，准确率 ~98%，仅增加 2-3 轮延迟 |
详见上方「聚合模式决策树」。
完全可以。生成的代码就是标准 TypeScript 项目，你可以像普通项目一样修改和维护。
- 运行时：Node.js 18+
- 语言：TypeScript
- MCP SDK：
@modelcontextprotocol/sdk - 参数校验：Zod
- 传输协议：stdio + Streamable HTTP