尧图网站建设 
如何构建MCP服务器TypeScript与Python双版本实现对比【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills本文以接入GitHub等外部服务的MCP服务器为例讲清TypeScript与Python两种MCP服务器实现的选型、工具设计、输入校验、分页、错误处理、测试与部署要点每个结论都对应可落地的工程做法和最小代码。为什么AI助手需要一个MCP服务器让模型给这个bug建一张Jira工单它只能回复你需要登录Jira然后点……——它听得懂但做不了。MCPModel Context Protocol服务器补的就是这一环把外部服务的操作封装成一组标准化的工具注册到服务器上模型按名称挑选工具、传入参数、拿到结果整个过程和普通函数调用很像。衡量一个MCP服务器好不好不是它包了多少API端点而是模型能不能顺畅地用这组工具把真实任务做完。所以命名、校验、响应格式、分页、错误处理这些细节都有明确的工程要求下面逐一拆开。TypeScript还是PythonMCP服务器语言怎么选两种语言都有官方SDK差异集中在开发体验和约束上维度TypeScriptPython官方框架modelcontextprotocol/sdk 的McpServerFastMCPPython SDK 的高层封装工具注册server.registerTool()显式调用mcp.tool()装饰器输入校验Zod schemaPydantic 模型工具描述必须显式写在description字段由函数签名和 docstring 自动生成项目命名{service}-mcp-server连字符{service}_mcp下划线适合场景远程服务、需要静态类型和编译检查的项目快速原型、中小规模项目官方技能库的 mcp-builder 指南把 TypeScript 列为首选SDK 质量高、静态类型对 AI 生成代码更友好、社区示例多。Python 的优势是快——FastMCP 从 docstring 直接生成工具描述一个工具往往不到十行。真正影响决策的只有一条服务器要作为多客户端共享的远程服务选 TypeScript只是本地自用的集成选 Python。MCP工具设计的5个关键决策命名用服务前缀动作动词工具名用 snake_case格式是{service}_{action}_{resource}写github_create_issue而不是create_issue。原因是模型环境里常常同时挂着好几个 MCP 服务器不带前缀会重名模型会拿错工具。名字还要以动词开头get、list、search、create让模型按任务就能定位。服务器命名同理Python 用{service}_mcpNode 用{service}-mcp-server取通用名、不带版本号从服务名就能推断出用途。用Zod或Pydantic做输入校验不要相信模型传进来的参数。所有入参都该经过 schema 在运行时校验const SearchInputSchema z.object({ query: z.string().min(2).max(200) .describe(搜索关键词例如 mcp server) });z.object声明输入结构.min()/.max()约束长度越界的输入会被直接拦下报错信息还能回传给模型。Python 侧用 Pydantic 模型并建议打开两个配置class SearchInput(BaseModel): model_config ConfigDict(str_strip_whitespaceTrue, extraforbid) query: str Field(..., min_length2, description搜索关键词)str_strip_whitespaceTrue自动去掉首尾空格extraforbid拒绝未知字段防止模型悄悄塞进来没声明过的参数。同一份数据准备两种响应格式返回数据的工具最好支持response_format参数让调用方二选一JSON 格式面向程序处理字段和元数据全量给出Markdown 格式面向模型阅读用标题和列表组织时间戳转成可读形式显示名后括号里带 ID。Markdown 版能省上下文 token也更好理解。分页给默认值别一次拉全量列出资源的工具一律尊重limit参数默认 20~50 条并在响应里带上分页元数据{ total: 150, count: 20, offset: 0, items: [], has_more: true, next_offset: 20 }has_more说明后面还有没有next_offset告诉调用方下一页从哪开始。数据集大时尤其不能把全量结果读进内存再返回。错误信息要可操作工具失败时返回的错误要给出具体建议而不是堆栈404 就写资源未找到请确认 ID 是否存在限流就附上可重试的时间。官方实践还要求把工具错误放进结果对象内部上报而不是抛成协议级错误——这样模型能看到失败原因并自行调整重试。另外每个工具都应声明四个注解readOnlyHint、destructiveHint、idempotentHint、openWorldHint告诉客户端这个工具是否只读、会不会破坏性修改、能否重复调用。它们只是提示不是安全保证但能帮客户端决定调用前要不要找用户确认。TypeScript与Python的MCP最小实现TypeScriptregisterTool显式注册TypeScript MCP 实现的骨架是 package.json、tsconfig.json加src/入口index.ts按域拆分的tools/、共享的services/、Zod schema 所在的schemas/编译产物在dist/。核心注册模式server.registerTool( github_search_repos, { title: Search GitHub Repositories, description: 按关键词搜索仓库返回名称、星标数与简介。, inputSchema: SearchInputSchema, annotations: { readOnlyHint: true, destructiveHint: false } }, async ({ query }) fetchRepos(query) );registerTool向服务器注册一个可被调用的操作第三个参数是真正的执行函数。注意用新的register*系列 API旧的server.tool()已废弃。PythonFastMCP装饰器少写样板mcp FastMCP(github_mcp) mcp.tool(namegithub_search_repos) async def github_search_repos(params: SearchInput) - str: 按关键词搜索 GitHub 仓库返回名称、星标数与简介。 ...FastMCP(github_mcp)完成服务器初始化参数即服务器名。函数的 docstring 自动成为工具描述Pydantic 参数类型自动变成输入 schema不用手写字段——这是它和 TypeScript 版最大的差别。MCP服务器测试编译检查、MCP Inspector与评估题测试分三层做编译与语法检查TypeScript 跑npm run build确认没有类型错误Python 跑python -m py_compile server.py验证语法。MCP Inspector 功能测试npx modelcontextprotocol/inspector打开一个本地可视化调试页能看到全部已注册工具并逐个手动调用、检查校验与响应格式这是 MCP 服务器教程里最直接的功能验证手段。10道复杂评估题编写 10 道真实、独立、只读、答案稳定的问题让模型纯靠工具自己作答再按答案比对打分。这一步检验的是任务完成度补上了单工具测试覆盖不到的组合能力写法细则见 评估指南。发布前再对照检查所有工具是否都用了 schema 校验列表类工具是否都有分页错误信息是否带下一步建议大响应是否做了字符限制和截断MCP服务器部署本地stdio与远程Streamable HTTP场景传输方式说明本地开发、单用户集成stdio服务器作为客户端子进程走标准输入输出无需网络配置远程服务、多客户端共享Streamable HTTP基于 HTTP 的双向通信用无状态 JSON 更易于扩展选择标准很简单本机跑就用 stdio服务多人就上 Streamable HTTP。两个容易踩的坑⚠️stdio 服务器的 stdout 被协议独占日志必须打到 stderrStreamable HTTP 服务若在本机运行绑定127.0.0.1并校验 Origin 头防止 DNS rebinding 攻击。更多细节见 最佳实践文档。两种语言在传输层的写法一致TypeScript 是npm run build后npm startPython 直接拉起进程即可。选型和五个设计决策定下来之后一个能用的 MCP 服务器一下午就能跑起来。【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何构建MCP服务器：TypeScript与Python双版本实现对比
如何构建MCP服务器TypeScript与Python双版本实现对比【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills本文以接入GitHub等外部服务的MCP服务器为例讲清TypeScript与Python两种MCP服务器实现的选型、工具设计、输入校验、分页、错误处理、测试与部署要点每个结论都对应可落地的工程做法和最小代码。为什么AI助手需要一个MCP服务器让模型给这个bug建一张Jira工单它只能回复你需要登录Jira然后点……——它听得懂但做不了。MCPModel Context Protocol服务器补的就是这一环把外部服务的操作封装成一组标准化的工具注册到服务器上模型按名称挑选工具、传入参数、拿到结果整个过程和普通函数调用很像。衡量一个MCP服务器好不好不是它包了多少API端点而是模型能不能顺畅地用这组工具把真实任务做完。所以命名、校验、响应格式、分页、错误处理这些细节都有明确的工程要求下面逐一拆开。TypeScript还是PythonMCP服务器语言怎么选两种语言都有官方SDK差异集中在开发体验和约束上维度TypeScriptPython官方框架modelcontextprotocol/sdk 的McpServerFastMCPPython SDK 的高层封装工具注册server.registerTool()显式调用mcp.tool()装饰器输入校验Zod schemaPydantic 模型工具描述必须显式写在description字段由函数签名和 docstring 自动生成项目命名{service}-mcp-server连字符{service}_mcp下划线适合场景远程服务、需要静态类型和编译检查的项目快速原型、中小规模项目官方技能库的 mcp-builder 指南把 TypeScript 列为首选SDK 质量高、静态类型对 AI 生成代码更友好、社区示例多。Python 的优势是快——FastMCP 从 docstring 直接生成工具描述一个工具往往不到十行。真正影响决策的只有一条服务器要作为多客户端共享的远程服务选 TypeScript只是本地自用的集成选 Python。MCP工具设计的5个关键决策命名用服务前缀动作动词工具名用 snake_case格式是{service}_{action}_{resource}写github_create_issue而不是create_issue。原因是模型环境里常常同时挂着好几个 MCP 服务器不带前缀会重名模型会拿错工具。名字还要以动词开头get、list、search、create让模型按任务就能定位。服务器命名同理Python 用{service}_mcpNode 用{service}-mcp-server取通用名、不带版本号从服务名就能推断出用途。用Zod或Pydantic做输入校验不要相信模型传进来的参数。所有入参都该经过 schema 在运行时校验const SearchInputSchema z.object({ query: z.string().min(2).max(200) .describe(搜索关键词例如 mcp server) });z.object声明输入结构.min()/.max()约束长度越界的输入会被直接拦下报错信息还能回传给模型。Python 侧用 Pydantic 模型并建议打开两个配置class SearchInput(BaseModel): model_config ConfigDict(str_strip_whitespaceTrue, extraforbid) query: str Field(..., min_length2, description搜索关键词)str_strip_whitespaceTrue自动去掉首尾空格extraforbid拒绝未知字段防止模型悄悄塞进来没声明过的参数。同一份数据准备两种响应格式返回数据的工具最好支持response_format参数让调用方二选一JSON 格式面向程序处理字段和元数据全量给出Markdown 格式面向模型阅读用标题和列表组织时间戳转成可读形式显示名后括号里带 ID。Markdown 版能省上下文 token也更好理解。分页给默认值别一次拉全量列出资源的工具一律尊重limit参数默认 20~50 条并在响应里带上分页元数据{ total: 150, count: 20, offset: 0, items: [], has_more: true, next_offset: 20 }has_more说明后面还有没有next_offset告诉调用方下一页从哪开始。数据集大时尤其不能把全量结果读进内存再返回。错误信息要可操作工具失败时返回的错误要给出具体建议而不是堆栈404 就写资源未找到请确认 ID 是否存在限流就附上可重试的时间。官方实践还要求把工具错误放进结果对象内部上报而不是抛成协议级错误——这样模型能看到失败原因并自行调整重试。另外每个工具都应声明四个注解readOnlyHint、destructiveHint、idempotentHint、openWorldHint告诉客户端这个工具是否只读、会不会破坏性修改、能否重复调用。它们只是提示不是安全保证但能帮客户端决定调用前要不要找用户确认。TypeScript与Python的MCP最小实现TypeScriptregisterTool显式注册TypeScript MCP 实现的骨架是 package.json、tsconfig.json加src/入口index.ts按域拆分的tools/、共享的services/、Zod schema 所在的schemas/编译产物在dist/。核心注册模式server.registerTool( github_search_repos, { title: Search GitHub Repositories, description: 按关键词搜索仓库返回名称、星标数与简介。, inputSchema: SearchInputSchema, annotations: { readOnlyHint: true, destructiveHint: false } }, async ({ query }) fetchRepos(query) );registerTool向服务器注册一个可被调用的操作第三个参数是真正的执行函数。注意用新的register*系列 API旧的server.tool()已废弃。PythonFastMCP装饰器少写样板mcp FastMCP(github_mcp) mcp.tool(namegithub_search_repos) async def github_search_repos(params: SearchInput) - str: 按关键词搜索 GitHub 仓库返回名称、星标数与简介。 ...FastMCP(github_mcp)完成服务器初始化参数即服务器名。函数的 docstring 自动成为工具描述Pydantic 参数类型自动变成输入 schema不用手写字段——这是它和 TypeScript 版最大的差别。MCP服务器测试编译检查、MCP Inspector与评估题测试分三层做编译与语法检查TypeScript 跑npm run build确认没有类型错误Python 跑python -m py_compile server.py验证语法。MCP Inspector 功能测试npx modelcontextprotocol/inspector打开一个本地可视化调试页能看到全部已注册工具并逐个手动调用、检查校验与响应格式这是 MCP 服务器教程里最直接的功能验证手段。10道复杂评估题编写 10 道真实、独立、只读、答案稳定的问题让模型纯靠工具自己作答再按答案比对打分。这一步检验的是任务完成度补上了单工具测试覆盖不到的组合能力写法细则见 评估指南。发布前再对照检查所有工具是否都用了 schema 校验列表类工具是否都有分页错误信息是否带下一步建议大响应是否做了字符限制和截断MCP服务器部署本地stdio与远程Streamable HTTP场景传输方式说明本地开发、单用户集成stdio服务器作为客户端子进程走标准输入输出无需网络配置远程服务、多客户端共享Streamable HTTP基于 HTTP 的双向通信用无状态 JSON 更易于扩展选择标准很简单本机跑就用 stdio服务多人就上 Streamable HTTP。两个容易踩的坑⚠️stdio 服务器的 stdout 被协议独占日志必须打到 stderrStreamable HTTP 服务若在本机运行绑定127.0.0.1并校验 Origin 头防止 DNS rebinding 攻击。更多细节见 最佳实践文档。两种语言在传输层的写法一致TypeScript 是npm run build后npm startPython 直接拉起进程即可。选型和五个设计决策定下来之后一个能用的 MCP 服务器一下午就能跑起来。【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考