1426 字
约 4 分钟
9
S22-X02 · MCP 服务器构建与项目登记(附录)

适用读者:要把自己的 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 生产循环与卡死防护

S22-X02 · MCP 服务器构建与项目登记(附录)
https://www.clxhxhhr.top/posts/5527/
作者
clxstart
发布于
2024-12-31
许可协议
CC BY-NC-SA 4.0
评论
0 条
还没有评论,先写一条吧。