企业官网建设流程全解析

从零到一：搭建你的第一个 MCP 服务器（附完整避坑清单）

【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills

skills3/skills 仓库是 Agent Skills 官方开源精选集，其中的 mcp-builder 技能完整沉淀了 MCP 服务器搭建的方法论。MCP 服务器是连接 AI 与真实外部服务的桥梁——你是否遇到过 AI 只会聊天、却动不了真实 API 的尴尬？

核心概念：MCP 服务器在请求流向中的位置

先搞清楚你在链路里的位置。一次 AI 外部工具调用的请求流向是这样：

用户指令 → AI 客户端（如 Claude） → MCP 服务器（你写的进程） → 目标服务 API ← 结构化结果 ← 模型继续推理 ←

用户说话后，客户端按名字调用工具；你的服务器负责校验输入、请求真实 API、返回结构化结果；客户端把结果塞回模型上下文，模型接着推理。你只写中间那一段：让模型明白该调哪个工具、传什么参数、怎么读结果。

动手前必做的三件事

调研：

• 通读 MCP 规范，至少弄懂两件事：传输机制（stdio / streamable HTTP）与工具的定义结构
• 列出目标服务 API 的端点、认证方式与限流规则
• 判断标准：写不出"先接哪 3 个端点"，说明调研还没做完

设计：

• MCP 工具注册命名遵循{服务}_{动作}_{资源}，如github_create_issue
• 提前定响应格式：默认 Markdown（人和模型都好读），留 JSON 开关给程序化消费
• 判断标准：工具超过 5 个时必须加服务前缀，再考虑按业务域拆成多个服务器

选型：

• 语言：Python 的 FastMCP 能从函数签名和 docstring 自动生成 schema，上手最快；TypeScript 团队用官方 SDK 亦可，思路一致
• 传输：本地单客户端用 stdio，远程多客户端用 streamable HTTP
• 判断标准：不暴露到网络、只给自己开发环境用，就选 stdio

注册第一个 MCP 工具

先装依赖并跑通本地验证环境：

pip install "mcp[cli]>=1.1.0" python your_server.py

然后用 Python 完成一次完整的 MCP 工具注册——一个带输入校验的搜索类工具：

from pydantic import BaseModel, Field from mcp.server.fastmcp import FastMCP import json mcp = FastMCP("github_mcp") class SearchInput(BaseModel): query: str = Field(..., description="搜索关键词，如 rust 或 machine-learning", min_length=2) @mcp.tool(name="github_search_repos", annotations={"title": "Search GitHub Repos", "readOnlyHint": True}) async def search_repos(params: SearchInput) -> str: """按关键词搜索 GitHub 仓库，返回带分页元数据的 JSON 列表。""" data = await api_search(params.query) return json.dumps({"items": data["items"][:30], "has_more": len(data["items"]) > 30}) mcp.run()

这里有个坑：docstring 会自动成为工具描述，写清楚"做什么、返回什么"，模型才知道何时该调它。annotations里的readOnlyHint告诉客户端这是个只读操作，可以放心调用。

常见报错与解决

• ModuleNotFoundError: No module named 'mcp'——没装 SDK，执行pip install "mcp[cli]"即可。
• 服务器一启动就被 Inspector 断开——代码里print往 stdout 打了日志，污染了 stdio 协议通道；所有日志改走 stderr。
• 模型反复传参失败、报ValidationError——通常是输入模型把可选字段写成了必填；给可选字段加默认值，并在Field的description里写明示例。

MCP 输入校验与分页：让它更健壮

最小示例能跑通只是及格线。MCP 分页处理、输入校验这些细节，直接决定模型用起来顺不顺：

上线前的自查清单

• 所有工具名带服务前缀、用 snake_case —— 避免与其他服务器撞名
• 同类工具返回格式统一（都 JSON 或都 Markdown） —— 解析逻辑可复用
• 列表工具返回has_more/next_offset—— 模型知道还有下一页
• 大响应做了字符数截断 —— 防止上下文被撑爆
• 所有网络请求都有超时兜底 —— 防服务器卡死
• 每个工具声明了 readOnly / destructive / idempotent 注解 —— 客户端预判调用风险
• 用 MCP Inspector 逐个工具验证过 —— 真实通道比本地猜测靠谱

到这里，你已经完成了 MCP 服务器搭建的完整闭环：注册工具、加输入校验与分页、通过 Inspector 验证。下一步可以按真实 API 继续扩工具，或照着 MCP 评估指南 写 10 道评估题让模型实测。更多注册模式与错误处理范式，见仓库内的 MCP Python 实现指南 和 最佳实践清单。

【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills