十分钟搭一个 MCP 服务器TypeScript 与 Python 双版本实战教程【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills想让 AI 替你查仓库、发消息、拉数据光靠提示词不够它得有一把钥匙——这就是 MCP 服务器。这篇 MCP 教程按最短路径讲如何构建 MCP 服务器TypeScript 和 Python 各给一份最小可运行代码十分钟跑通。什么时候你需要一个 MCP 服务器两个场景。一是让 AI 查 GitHub 上的 issue直接提问它只能按记忆回答数据是旧的把 API 包成 MCP 服务器它就能实时调接口拿真数据。二是让 AI 往 Slack 发通知、把工单同步到 Jira。这类替 AI 动手操作外部服务的需求就是 MCP 服务器的价值所在。选型先做TypeScript 还是 Python结论先行团队主力是 Node就用 TypeScript 写 MCP 服务器想最快出活、已有 Python 服务就选 Python。两边协议完全一致工具命名和返回格式对齐即可随时能换。维度TypeScriptPythonFastMCP类型安全强Zod 运行时校验坏参数当场拦截中Pydantic 校验类型提示可选开发速度中要配 tsconfig 和编译步骤快函数加个装饰器就注册好了生态依赖Node 生态官方 SDK 维护发 npm 包顺手httpx 等成熟 HTTP 库数据工具链齐全十分钟跑通初始化、注册工具、本地验证第 1 步初始化。TypeScript建目录npm init -y装上 modelcontextprotocol/sdk 和 zod配好 tsconfig 就能写代码。Python一行pip install fastmcp传输层和注册逻辑框架全包了。第 2 步注册第一个工具。工具 名字 描述 输入规则 实现其中描述是 AI 决定什么时候用我的依据务必写清楚。TypeScript 版import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new McpServer({ name: demo, version: 1.0.0 }); // 描述是 AI 选择工具的依据别写工具1这种废话 server.registerTool(get_time, { description: 获取当前时间, inputSchema: {} }, async () ({ content: [{ type: text, text: new Date().toISOString() }] })); await server.connect(new StdioServerTransport()); // stdio 传输本地调试走它Python 版更短docstring 自动变成描述from fastmcp import FastMCP from datetime import datetime mcp FastMCP(demo) mcp.tool() async def get_time() - str: 获取当前时间docstring 自动变成工具描述 return datetime.now().isoformat() mcp.run() # 默认 stdio 传输本地调试直接可用第 3 步本地验证。两种语言都先走 stdio用 MCP Inspector 连上你的进程确认 get_time 出现在工具列表里手动调用一次返回当前时间就算跑通。TypeScript 用npx modelcontextprotocol/inspector拉起Python 直接fastmcp dev main.py就有 Web 调试页。让工具说人话输入校验与返回格式为什么必须校验因为传参的是 AI不是人。它照着描述猜参数猜错了如果直接打到下游服务你拿到一个 500它也只会再猜一次。在校验层拦住、返回一句人话它下一次就传对了// 校验即文档约束写清楚AI 才知道该传什么 const schema z.object({ repo: z.string().min(2, 仓库名至少 2 个字符), limit: z.number().int().max(50).default(20), // 兜底防 AI 一次拉太多 });返回格式有两类读者。给人看的用 Markdown标题、列表一屏读完给程序对接的用 JSON字段稳定、可解析。一个工具只选一种主格式列表类工具建议用 Markdown别混着来。踩坑预警 ⚠️错误、分页、超时坑一AI 看不懂你的报错。现象下游挂了AI 只收到Error: 500然后傻重试。原因把 HTTP 原始状态码直接透传了。怎么办捕获后翻译成可操作的话——仓库不存在请检查名字拼写、请求太频繁稍后再试404、限流、网络错误分开处理。坑二列表工具一调就卡。现象大仓库查一次内存飙升或直接超时。原因一次把上千条全返回了。怎么办默认每页 20–50 条响应里带上 has_more 和 next_offset让 AI 自己翻页。坑三偶尔卡死几十秒。现象多数时候正常偶尔挂起很久。原因HTTP 客户端没设超时上游慢的时候连接被无限占住。怎么办显式设 5–10 秒超时超时统一返回上游服务响应超时请稍后重试。上线从本机 stdio 到远程 HTTPstdio 适合本地单客户端AI 客户端拉起你的进程用完即走调试方便。多人共享或跨机器访问就得切到 HTTP。TypeScript 里把 StdioServerTransport 换成 StreamableHTTPServerTransport 并监听端口Python 里给 FastMCP 指定 host、port 并声明 http 传输。切换时记住两点进程不再由客户端拉起你得自己管好生命周期多了一个网络边界至少加个 token 鉴权。下一步到这里一个能跑、能验、能上线的 MCP 服务器就齐了。别停在 get_time挑你最熟的一个 API把真实工具、错误翻译、分页补齐再用 MCP Inspector 跑几轮真实提问看 AI 用着顺不顺手。仓库里的 mcp-builder 技能带现成的评估流程可以照着出一组测试题。【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考