企业官网建设流程全解析

从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_length=2, max_length=200) @mcp.tool(name="github_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 用 Zod，Python 用 Pydantic 并建议给模型加extra='forbid'拒掉预期外的字段。好处是坏参数在门口就被拦下，不会消耗一次真实的 API 调用。

命名规范：服务前缀是给别人留的

工具名统一{service}_{action}_{resource}的 snake_case，比如github_create_issue、slack_send_message。前缀别省——同一个客户端经常同时挂载多台 MCP 服务器，光秃秃的create_issue迟早和别家的撞车。服务器命名也有约定：Python 叫{service}_mcp，Node/TypeScript 叫{service}-mcp-server。

响应格式取舍：默认 Markdown，按需给 JSON

返回数据的工具挂一个response_format参数。Markdown 面向人和模型直接阅读：时间戳转成可读格式、ID 放进括号、砍掉冗余元数据；JSON 面向程序化处理：字段完整、结构稳定。默认给 Markdown，当模型要把数据传给下一步处理时再切 JSON。

分页与截断：给模型一张"下一页"

凡是列表型工具都要支持分页：入参limit+offset，出参带上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：选型对比表

官方参考文档里把 TypeScript 列为推荐栈：SDK 成熟，而且模型生成 TS 代码的准确率普遍更高。但如果你的团队平时写 Python，FastMCP 的开发速度同样能打。按团队的手感选，别追潮流。

MCP 服务器上线前自检

• 跑一次完整构建：npm run build或python -m py_compile，确认没有编译和语法错误。
• 用 MCP Inspector 逐个过一遍工具：核对工具列表展示，每种工具各试一组正常参数和一组坏参数。
• 检查四个 annotations（readOnlyHint、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