从0到1构建MCP服务器的完整工程指南【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills当 AI 能聊 GitHub API 却干不了查询时MCP服务器就是填上这个缺口的东西——它把模型接到真实系统上让 AI 真正调用外部服务替你查仓库、开工单、发消息。AI 能回答却做不到瓶颈在手你问模型这个仓库最近有什么更新它能给你讲清楚 commit、tag、release 是怎么回事却拿不出这个仓库真实的更新列表。卡点不在智商而在手段LLM 像一个顶级顾问精通每个系统的操作手册但只长了一张嘴没有手。MCP 服务器就是那双手。它站在模型和外部服务中间把一组明确定义的工具暴露给模型模型只需要表达意图服务器负责翻译成具体的 API 调用再把结果带回来。AI 在闲聊和AI 在干活之间差的正是这一层。 MCP 开发动手前三个关键决策决策一先读协议规范再定传输方式写代码前先想清楚服务器怎么和客户端通信。MCP 协议里本地单人场景走 stdio远程多客户端场景走 Streamable HTTP。这个选择直接影响项目结构和部署方式得在动手前敲定而不是写完再返工。协议细节以 MCP 官方规范为准本仓库的skills/mcp-builder/reference/mcp_best_practices.md里有一份浓缩过的速查。决策二拆解目标 API反推工具清单打开目标服务的 API 文档只关心三件事哪些端点是高频操作、鉴权走 OAuth 还是 API Key、数据模型长什么样。然后反推工具清单操作越常用越靠前。这里藏着一个更隐蔽的决策工具粒度。你可以暴露贴近端点的原子工具让 agent 自己组合也可以封装一步到位的工作流工具拿不准时倾向做全面覆盖把组合权留给模型。决策三划定工具边界暴露什么不暴露什么模型只能看到你注册的东西每多一个工具就多占一份上下文和注意力。先列一张清单目标用户完成任务最少需要哪几个操作哪些只是锦上添花。第一版建议不放写操作先把读路径打磨到模型用得顺手再逐步加写能力。最小可运行示例注册第一个 MCP 工具以 TypeScript 为主线。TS SDK 的registerTool三要素名字、元数据含 Zod 输入 schema、处理函数。注意description不会自动生成必须手写const server new McpServer({ name: github-mcp-server, version: 1.0.0 }); server.registerTool( github_search_repos, { title: Search GitHub Repositories, description: Search repositories by name or description, inputSchema: { query: z.string().min(2) }, annotations: { readOnlyHint: true, destructiveHint: false } }, async ({ query }) ({ content: [{ type: text, text: await search(query) }] }) );Python 走 FastMCP 的装饰器风格Pydantic 负责校验mcp FastMCP(github_mcp) class SearchInput(BaseModel): query: str Field(min_length2, max_length200) mcp.tool(namegithub_search_repos, annotations{title: Search Repositories, readOnlyHint: True}) async def search_repos(params: SearchInput) - str: 按名称或描述搜索仓库返回格式化结果。 return await github_search(params.query)两者差异就两点Python 里 docstring 自动变成工具描述TypeScript 里必须显式传Python 的校验交给 Pydantic 模型TypeScript 的 Zod schema 同时还是类型来源。两套完整写法可对照skills/mcp-builder/reference/node_mcp_server.md和skills/mcp-builder/reference/python_mcp_server.md。 MCP 工具注册的工程细节让 schema 校验而不是让 if-else 兜底所有输入约束都写进校验 schema字符串长度、数值区间、枚举、允不允许额外字段。TypeScript 用 ZodPython 用 Pydantic 并建议给模型加extraforbid拒掉预期外的字段。好处是坏参数在门口就被拦下不会消耗一次真实的 API 调用。命名规范服务前缀是给别人留的工具名统一{service}_{action}_{resource}的 snake_case比如github_create_issue、slack_send_message。前缀别省——同一个客户端经常同时挂载多台 MCP 服务器光秃秃的create_issue迟早和别家的撞车。服务器命名也有约定Python 叫{service}_mcpNode/TypeScript 叫{service}-mcp-server。响应格式取舍默认 Markdown按需给 JSON返回数据的工具挂一个response_format参数。Markdown 面向人和模型直接阅读时间戳转成可读格式、ID 放进括号、砍掉冗余元数据JSON 面向程序化处理字段完整、结构稳定。默认给 Markdown当模型要把数据传给下一步处理时再切 JSON。分页与截断给模型一张下一页凡是列表型工具都要支持分页入参limitoffset出参带上has_more、next_offset、total_count。默认 20-50 条任何情况别把全量数据加载进内存。响应特别大时主动截断并在文案里说明截断点模型才不会误以为数据是全的。{ total: 150, count: 20, has_more: true, next_offset: 20 }错误信息教模型下一步怎么办错误消息不是把堆栈甩给模型而是告诉它接下来该干什么。404 就说资源未找到请检查 ID 格式429 就说触发限流请等待 N 秒或缩小查询范围。工具级错误放在 result 对象里返回不要用协议层错误同时别把内部实现细节泄给客户。MCP TypeScript 与 MCP Python选型对比表维度TypeScriptMCP SDKPythonFastMCP工具注册server.registerTool显式声明mcp.tool装饰器输入校验Zod schema兼作类型来源Pydantic 模型描述生成必须手写不读 JSDocdocstring 自动提取类型安全静态类型编译期就报错运行时校验兜底项目骨架package.json tsconfig src/distrequirements.txt 模块化文件样板代码量偏多偏少适合场景远程服务、长期维护的产品快速原型、数据团队场景官方参考文档里把 TypeScript 列为推荐栈SDK 成熟而且模型生成 TS 代码的准确率普遍更高。但如果你的团队平时写 PythonFastMCP 的开发速度同样能打。按团队的手感选别追潮流。MCP 服务器上线前自检跑一次完整构建npm run build或python -m py_compile确认没有编译和语法错误。用 MCP Inspector 逐个过一遍工具核对工具列表展示每种工具各试一组正常参数和一组坏参数。检查四个 annotationsreadOnlyHint、destructiveHint、idempotentHint、openWorldHint和工具实际行为是否一致客户端靠它们判断风险标错了是实打实的隐患。让模型做一道复杂题看它会不会选对工具、能不能多次调用把事做完、出错时有没有顺着你的错误信息重试。确认网络调用都有超时API Key 只从环境变量读取代码里不留明文。收尾stdio、Streamable HTTP以及你的下一步本地开发用 stdio客户端把服务器当子进程拉起零网络配置唯一要记住的是日志必须写 stderr因为 stdout 是协议通道打一行 log 进去连接就废了。远程部署用 Streamable HTTP一套部署服务多个客户端适合团队共用同一台服务器的场景。别急着做满。挑一个你天天用的服务建一个只含三个工具的最小 MCP 服务器——一个查询、一个列表、一个写操作——先在本地客户端里跑通再用真实使用记录迭代。这比任何教程都更能告诉你下一版该加什么。【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从0到1构建MCP服务器的完整工程指南
从0到1构建MCP服务器的完整工程指南【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills当 AI 能聊 GitHub API 却干不了查询时MCP服务器就是填上这个缺口的东西——它把模型接到真实系统上让 AI 真正调用外部服务替你查仓库、开工单、发消息。AI 能回答却做不到瓶颈在手你问模型这个仓库最近有什么更新它能给你讲清楚 commit、tag、release 是怎么回事却拿不出这个仓库真实的更新列表。卡点不在智商而在手段LLM 像一个顶级顾问精通每个系统的操作手册但只长了一张嘴没有手。MCP 服务器就是那双手。它站在模型和外部服务中间把一组明确定义的工具暴露给模型模型只需要表达意图服务器负责翻译成具体的 API 调用再把结果带回来。AI 在闲聊和AI 在干活之间差的正是这一层。 MCP 开发动手前三个关键决策决策一先读协议规范再定传输方式写代码前先想清楚服务器怎么和客户端通信。MCP 协议里本地单人场景走 stdio远程多客户端场景走 Streamable HTTP。这个选择直接影响项目结构和部署方式得在动手前敲定而不是写完再返工。协议细节以 MCP 官方规范为准本仓库的skills/mcp-builder/reference/mcp_best_practices.md里有一份浓缩过的速查。决策二拆解目标 API反推工具清单打开目标服务的 API 文档只关心三件事哪些端点是高频操作、鉴权走 OAuth 还是 API Key、数据模型长什么样。然后反推工具清单操作越常用越靠前。这里藏着一个更隐蔽的决策工具粒度。你可以暴露贴近端点的原子工具让 agent 自己组合也可以封装一步到位的工作流工具拿不准时倾向做全面覆盖把组合权留给模型。决策三划定工具边界暴露什么不暴露什么模型只能看到你注册的东西每多一个工具就多占一份上下文和注意力。先列一张清单目标用户完成任务最少需要哪几个操作哪些只是锦上添花。第一版建议不放写操作先把读路径打磨到模型用得顺手再逐步加写能力。最小可运行示例注册第一个 MCP 工具以 TypeScript 为主线。TS SDK 的registerTool三要素名字、元数据含 Zod 输入 schema、处理函数。注意description不会自动生成必须手写const server new McpServer({ name: github-mcp-server, version: 1.0.0 }); server.registerTool( github_search_repos, { title: Search GitHub Repositories, description: Search repositories by name or description, inputSchema: { query: z.string().min(2) }, annotations: { readOnlyHint: true, destructiveHint: false } }, async ({ query }) ({ content: [{ type: text, text: await search(query) }] }) );Python 走 FastMCP 的装饰器风格Pydantic 负责校验mcp FastMCP(github_mcp) class SearchInput(BaseModel): query: str Field(min_length2, max_length200) mcp.tool(namegithub_search_repos, annotations{title: Search Repositories, readOnlyHint: True}) async def search_repos(params: SearchInput) - str: 按名称或描述搜索仓库返回格式化结果。 return await github_search(params.query)两者差异就两点Python 里 docstring 自动变成工具描述TypeScript 里必须显式传Python 的校验交给 Pydantic 模型TypeScript 的 Zod schema 同时还是类型来源。两套完整写法可对照skills/mcp-builder/reference/node_mcp_server.md和skills/mcp-builder/reference/python_mcp_server.md。 MCP 工具注册的工程细节让 schema 校验而不是让 if-else 兜底所有输入约束都写进校验 schema字符串长度、数值区间、枚举、允不允许额外字段。TypeScript 用 ZodPython 用 Pydantic 并建议给模型加extraforbid拒掉预期外的字段。好处是坏参数在门口就被拦下不会消耗一次真实的 API 调用。命名规范服务前缀是给别人留的工具名统一{service}_{action}_{resource}的 snake_case比如github_create_issue、slack_send_message。前缀别省——同一个客户端经常同时挂载多台 MCP 服务器光秃秃的create_issue迟早和别家的撞车。服务器命名也有约定Python 叫{service}_mcpNode/TypeScript 叫{service}-mcp-server。响应格式取舍默认 Markdown按需给 JSON返回数据的工具挂一个response_format参数。Markdown 面向人和模型直接阅读时间戳转成可读格式、ID 放进括号、砍掉冗余元数据JSON 面向程序化处理字段完整、结构稳定。默认给 Markdown当模型要把数据传给下一步处理时再切 JSON。分页与截断给模型一张下一页凡是列表型工具都要支持分页入参limitoffset出参带上has_more、next_offset、total_count。默认 20-50 条任何情况别把全量数据加载进内存。响应特别大时主动截断并在文案里说明截断点模型才不会误以为数据是全的。{ total: 150, count: 20, has_more: true, next_offset: 20 }错误信息教模型下一步怎么办错误消息不是把堆栈甩给模型而是告诉它接下来该干什么。404 就说资源未找到请检查 ID 格式429 就说触发限流请等待 N 秒或缩小查询范围。工具级错误放在 result 对象里返回不要用协议层错误同时别把内部实现细节泄给客户。MCP TypeScript 与 MCP Python选型对比表维度TypeScriptMCP SDKPythonFastMCP工具注册server.registerTool显式声明mcp.tool装饰器输入校验Zod schema兼作类型来源Pydantic 模型描述生成必须手写不读 JSDocdocstring 自动提取类型安全静态类型编译期就报错运行时校验兜底项目骨架package.json tsconfig src/distrequirements.txt 模块化文件样板代码量偏多偏少适合场景远程服务、长期维护的产品快速原型、数据团队场景官方参考文档里把 TypeScript 列为推荐栈SDK 成熟而且模型生成 TS 代码的准确率普遍更高。但如果你的团队平时写 PythonFastMCP 的开发速度同样能打。按团队的手感选别追潮流。MCP 服务器上线前自检跑一次完整构建npm run build或python -m py_compile确认没有编译和语法错误。用 MCP Inspector 逐个过一遍工具核对工具列表展示每种工具各试一组正常参数和一组坏参数。检查四个 annotationsreadOnlyHint、destructiveHint、idempotentHint、openWorldHint和工具实际行为是否一致客户端靠它们判断风险标错了是实打实的隐患。让模型做一道复杂题看它会不会选对工具、能不能多次调用把事做完、出错时有没有顺着你的错误信息重试。确认网络调用都有超时API Key 只从环境变量读取代码里不留明文。收尾stdio、Streamable HTTP以及你的下一步本地开发用 stdio客户端把服务器当子进程拉起零网络配置唯一要记住的是日志必须写 stderr因为 stdout 是协议通道打一行 log 进去连接就废了。远程部署用 Streamable HTTP一套部署服务多个客户端适合团队共用同一台服务器的场景。别急着做满。挑一个你天天用的服务建一个只含三个工具的最小 MCP 服务器——一个查询、一个列表、一个写操作——先在本地客户端里跑通再用真实使用记录迭代。这比任何教程都更能告诉你下一版该加什么。【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考