适用读者:要把自己的 API 暴露成 MCP 工具的人;核对旧文去向的读者。
性质:统一骨架 + 登记表。9 篇尾部旧文中,1 篇新写进 J05,其余 8 篇在此登记。
覆盖旧文:4362(Python 构建 MCP)、4363(TypeScript 构建 MCP)、4361(为你的 API 构建 MCP)、4358(Skills / MCP / 规则的区别)、4350(12 个最佳 MCP Server 推荐)、3453(DevSupport AI)、3454(AI 模拟面试官)、3455(AI 模拟面试官,重复)→ 8 篇。
1. 逐篇登记
| 旧文 | 标题 | 字符数 | 处置 | 去向与理由 |
|---|---|---|---|---|
4362 |
如何用 Python 构建 MCP 服务器(分步教程) | 14,966 | appendix |
统一骨架并入 §2(Python 侧) |
4363 |
如何用 TypeScript 构建 MCP 服务器(分步教程) | 14,602 | appendix |
并入 §2(TS 侧),与 Python 部分对照 |
4361 |
如何为你的 API 构建 MCP 服务器 | 14,625 | appendix |
并入 §2("已有 HTTP API → 工具"的映射规则) |
4358 |
Agent Skills、MCP 服务器、规则有什么区别 | 15,783 | duplicate_ref |
S21-J02(Skills/MCP/规则三层边界)+ S24-J05 §2(配置资产分层) |
4350 |
2026 年 12 个最佳 MCP Server 推荐 | 20,561 | non_knowledge |
清单型内容,时效性强(发布即过期),无判据 |
3453 |
DevSupport AI | 7,901 | appendix |
项目实战,并入 §4 登记 |
3454 / 3455 |
AI 模拟面试官(同题两版) | 6,253 / 5,226 | appendix + duplicate_ref |
判定为同题重复导出:3454 保留为登记项,3455 指向 3454 |
2. MCP 服务器的统一七步骨架(三语言同一套)
① 声明工具:name / description / inputSchema(JSON Schema)
② 选传输:stdio(本地进程)或 HTTP+SSE/Streamable HTTP(远程)
③ 实现 handler:校验入参 → 调后端 → 裁剪结果
④ 错误语义:区分「参数错」「后端不可用」「权限不足」,别都抛 500
⑤ 鉴权:远程模式必须有(token/网关),stdio 靠进程边界
⑥ 幂等:写操作带幂等键(同 S17-J03)
⑦ 测试:本地用 MCP Inspector 或自写 client 跑一遍全部工具
三语言对照:
| 维度 | Python(4362) |
TypeScript(4363) |
已有 API(4361) |
|---|---|---|---|
| 声明方式 | 装饰器/函数注册 | 对象字面量 + zod schema | 把 OpenAPI 操作映射成工具 |
| 传输 | stdio_server 常见 |
StdioServerTransport |
远程 → HTTP 传输 |
| Schema | pydantic/JSON Schema | zod → JSON Schema | 复用 OpenAPI schema(注意裁剪) |
| 典型坑 | 版本 API 变化快 | ESM/CJS 与构建产物路径 | 一次暴露太多接口 → 模型选不准 |
判据:"工具数 ≤ 10 且描述可判定"才适合直接暴露——把 80 个 API 端点全映射成工具,模型选择准确率会崩(同 S22-J05 的"工具清单筛选")。正确做法:按任务分组的"复合工具"(一个工具内部编排多次调用),而不是一端点一工具。
description 的写法(决定调用准确率):
差:查询订单
好:按订单号查询订单状态与金额。需要 orderId(字符串,业务单号,非数据库主键)。
不返回用户隐私字段。仅支持近 90 天订单。
三要素:做什么 + 需要什么参数(含格式) + 边界(时限/隐私/失败语义)。
3. 与 Skills、规则的区别(4358 的结论,主讲篇在 S21-J02)
| 形态 | 载体 | 何时加载 | 适合 |
|---|---|---|---|
| 规则(rules/AGENTS.md) | 静态文件 | 每轮/每次会话 | 长期约束、技术栈事实 |
| Skills | 带说明的指令包 | 按需触发 | 多步流程、可复用方法论 |
| MCP 服务器 | 可执行服务 | 工具调用时 | 访问外部系统(数据、API、写操作) |
判据:"要执行代码/访问外部系统 → MCP;要教方法 → Skills;要立规矩 → 规则"。
4. 两个项目登记
| 项目 | 旧文 | 要点 | 可复用结论 |
|---|---|---|---|
| DevSupport AI | 3453 |
客服/技术支持场景的检索 + 工单流转 | 工具调用要有"人工接管"出口;检索结果必须带来源 |
| AI 模拟面试官 | 3454/3455 |
题目生成 + 追问 + 评分 | 评分需 rubric 与可解释项;追问要基于上一轮回答(上下文锚定,见 S20-J05) |
重复导出记录:3454(6,253 字符)与 3455(5,226 字符)同题两版,判定为重复导出,3455 处置为 duplicate_ref → 3454。全站同类情况累计第 4 次(S08 26 对、S19 角色卡、S24 两组、此处 1 组)。
5. 缺口与待核
| 项 | 状态 |
|---|---|
| MCP 规范版本与传输方式演进(stdio / SSE / Streamable HTTP) | 待核:规范迭代快,正文只写"两种传输"的取舍 |
| Python / TypeScript SDK 具体 API 名 | 待核(版本相关,未逐版本核对) |
4350 的 12 个 Server 清单 |
判 non_knowledge(时效清单) |
4361 的 OpenAPI → 工具映射细节 |
只保留"复合工具优于端点直映射"的判据,细节待核 |
6. 下一篇
S22 系列验收(v2) —— 12 篇 / 4,132 点位 / 9 篇尾部旧文 100% 处置 / 下一系列(P19:剩余 24 篇零星)前置依赖。
本篇属于系列《S22 · AI 工程落地实战》。旧文来源:A-4362/4363/4361/4358/4350/3453/3454/3455;扩展点 E-S22-024。MCP 规范与 SDK 版本迭代较快,具体 API 名以官方文档为准(待核)。
上一篇:S22-J05 · Agent 生产循环与卡死防护