从零到一搭建你的第一个 MCP 服务器附完整避坑清单【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skillsskills3/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_length2) mcp.tool(namegithub_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 分页处理、输入校验这些细节直接决定模型用起来顺不顺场景做法模型传入垃圾输入空串、越界的 limit全部交给 Pydantic 模型min_length2、ge1, le100、extraforbid绝不手写 if 判断搜索结果一次几百条撑爆上下文分页是标配默认limit20返回has_more与next_offset永远别一次拉全量上游 API 响应慢或无响应统一用httpx.AsyncClient并设timeout30.0把超时异常转成一句人能看懂的提示模型看不懂错误、反复重试错误措辞写成问题 下一步Error: 404 资源未找到请检查 ID 是否正确上线前的自查清单所有工具名带服务前缀、用 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从零到一：搭建你的第一个 MCP 服务器（附完整避坑清单）
从零到一搭建你的第一个 MCP 服务器附完整避坑清单【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skillsskills3/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_length2) mcp.tool(namegithub_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 分页处理、输入校验这些细节直接决定模型用起来顺不顺场景做法模型传入垃圾输入空串、越界的 limit全部交给 Pydantic 模型min_length2、ge1, le100、extraforbid绝不手写 if 判断搜索结果一次几百条撑爆上下文分页是标配默认limit20返回has_more与next_offset永远别一次拉全量上游 API 响应慢或无响应统一用httpx.AsyncClient并设timeout30.0把超时异常转成一句人能看懂的提示模型看不懂错误、反复重试错误措辞写成问题 下一步Error: 404 资源未找到请检查 ID 是否正确上线前的自查清单所有工具名带服务前缀、用 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考