MCP 服务器快速上手：TypeScript 与 Python 双实现的最小可运行路线

MCP 服务器快速上手TypeScript 与 Python 双实现的最小可运行路线【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skillsMCPModel Context Protocol服务器让大模型通过工具直接操作外部服务。如果你要把 AI 助手接到真实业务系统这篇用 10 分钟走一条本地能跑通的路初始化项目、注册第一个工具、本地验证再补齐校验、分页、截断这些上线前绕不开的工程细节。场景助手为什么查不了工单一个很常见的诉求在对话里问把本周涉及登录问题的工单列出来按优先级排助手只能凭印象编。原因是模型够不到工单系统的 API。补上这个缺口的做法是建一个 MCP 服务器把查询接口包装成模型可调用的工具客户端Claude Desktop、各类 Agent 框架按 MCP 协议跟它通信。服务器端有三件事必须做对工具名和描述清晰模型能选对工具输入经过校验脏参数进不了 API输出做分页和截断一次响应不撑爆上下文换成代码仓库、项目管理工具做目标服务做法完全一样。最小路径初始化项目并注册第一个工具原则是先让客户端列出工具 → 调用成功 → 拿到结果这一条链路跑通不急着覆盖所有接口。Python安装 SDK 并写出第一个工具 Python 是最短路径。装 SDK写一个文件即可pip install mcp[cli]server.py先用假返回值跑通不依赖真实 APIfrom mcp.server.fastmcp import FastMCP mcp FastMCP(ticket_mcp) mcp.tool(annotations{title: Search tickets, readOnlyHint: True}) async def ticket_search(query: str) - str: 按关键词搜索工单返回 Markdown 列表。 return f# 搜索 {query}\n- T-1001: 登录超时\n- T-1002: 重置密码 if __name__ __main__: mcp.run()TypeScript同样的工具用 SDK 注册 ⚡TypeScript 写法更长但类型系统会在项目变大时持续还本。先建项目npm init -y npm install modelcontextprotocol/sdk zodpackage.json里加type: modulesrc/index.ts核心内容import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; const server new McpServer({ name: ticket-mcp-server, version: 1.0.0 }); server.registerTool( ticket_search, { title: Search tickets, description: Search tickets by keyword, returns a Markdown list, inputSchema: { query: z.string().min(2).describe(搜索关键词) }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true } }, async ({ query }) ({ content: [{ type: text, text: # 搜索 ${query} }] }) ); server.connect(new StdioServerTransport());本地运行验证两版各有一条验证路径# Python python -m py_compile server.py python server.py # TypeScript npm run build npm start然后打开 MCP Inspectornpx modelcontextprotocol/inspector启动命令分别填python server.py或node dist/index.js。工具列表里能看到ticket_search输入 登录 点调用返回 Markdown 列表链路就算通了。TypeScript 与 Python 两种实现对比维度TypeScriptPython注册方式McpServerregisterToolFastMCPmcp.tool装饰器输入校验Zod Schema建议加.strict()Pydantic 模型建议extraforbid工具描述必须在description字段手写由 docstring 自动生成服务器命名{service}-mcp-server{service}_mcp侧重点静态类型、易 lint、生态稳定代码短、原型快选择建议Node 技术栈或工具类型复杂选 TypeScript想快速验证想法、团队偏 Python 就选 Python。两边工具命名保持一致snake_case 加服务前缀如ticket_search、ticket_create。工程化细节输入校验、分页与错误处理输入校验拒绝非法参数模型是不恶意但很随意的调用方可能传多余字段、错误类型。校验不能省TypeScriptSchema 末尾加.strict()多余字段直接报错字段上用.min()、.max()、.describe()写明约束PythonPydantic 模型设model_config ConfigDict(extraforbid)用Field(...)声明约束与说明验证方式在 Inspector 里传一个 Schema 里没有的参数正确行为是报校验错误而不是静默接受。错误提示给模型下一步不要让模型看到原始异常栈。集中写一个错误转换函数按 HTTP 状态码映射成可操作文案状态返回文案示例404错误工单不存在请检查工单号形如 T-1001403错误无权限访问该工单请检查 API key 作用域429错误触发限流请稍后重试超时错误请求超时请重试文案的关键是给模型下一步动作而不是只宣告失败。分页与截断别让一次调用拉爆上下文列表类工具必须分页否则一次拉回几千条记录limit默认 20、上限 100offset从 0 开始响应固定带has_more和next_offset模型才知道怎么翻页设全局字符上限25000 是常见取值超限截断数据并附一句结果已截断可用 offset 参数查看更多若结果既要给人看又要给程序用可加response_format参数markdown默认和json超时与日志所有 HTTP 请求设显式超时30 秒是常见值避免模型无限等待stdio 传输用 stdout 传协议消息日志必须走 stderrPython 用print(..., filesys.stderr)TypeScript 用console.error写错通道客户端会协议解析失败常见坑现象 / 原因 / 处理现象原因处理Inspector 里看不到工具还在用旧的server.tool()写法或没写description换成registerTool/mcp.tool补齐描述多余字段被静默接受Zod 没加.strict()Pydantic 没设extraforbid开严格模式再用非法参数复测单次响应过长模型分心列表工具没截断limit 无上限加分页、字符上限和截断说明两个服务器并存时工具名撞车工具名没带服务前缀改成ticket_search、repo_search这类命名客户端报协议错误或断连日志写进 stdout污染协议消息日志全部移到 stderr交付前检查清单npm run build或python -m py_compile通过MCP Inspector 能列出全部工具描述与实际行为一致只读工具都标注了readOnlyHint: true列表工具支持limit/offset响应带has_more非法输入得到明确校验错误而不是 500错误文案包含下一步动作不只是状态码大响应有截断且说明如何取更多数据下一步最小链路跑通后按顺序做三件事接真实 API把假返回值换成真实调用密钥放环境变量专门验证 401 时的报错表现补齐工具先覆盖最常用的 3-5 个操作不照抄全部端点做评估写 10 个只读、需要多步调用、答案唯一的问题让模型只用你的工具作答通过率才是服务器好不好用的硬指标仓库里skills/mcp-builder/reference/目录有完整的双语言实现指南与评估文档如mcp_best_practices.md、python_mcp_server.md、node_mcp_server.md、evaluation.mdskills/mcp-builder/scripts/evaluation.py可直接执行评估。本地没有仓库时git clone https://gitcode.com/GitHub_Trending/skills3/skills【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考