从零构建MCP服务器Python与TypeScript双语言实战教程【免费下载链接】ai-engineering-from-scratchLearn it. Build it. Ship it for others.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-from-scratchMCP服务器是连接AI应用与外部工具、数据、提示模板的标准桥梁。本教程基于开源课程ai-engineering-from-scratch416节课程、20个阶段的完整AI工程体系带你不用死记协议、不装重型依赖用 Python 和 TypeScript 两套标准库即可构建一个可运行的 MCP 服务器。零基础也能跟着跑通 Demo 和测试。什么是MCP服务器为什么值得自己动手写一个MCPModel Context Protocol模型上下文协议让 AI 宿主Host通过一套统一的协议发现并调用外部能力避免每接一个工具就写一遍胶水代码的集成噩梦。一个 MCP 服务器对外提供三类服务器原语原语是什么举个例子Tools工具可执行的原子操作搜索笔记、创建笔记Resources资源带 URI 的可读内容读取某条笔记详情Prompts提示词可复用的提示模板帮我总结这条笔记协议层基于JSON-RPC 2.0通过 stdio 传输。2026-07-28 版协议最大的变化是握手initialize被移除了——每个请求都在params._meta里自带协议版本和客户端能力声明。这意味着服务器是无状态的逻辑大大简化也更容易水平扩展。 对新手来说无状态是好事你不需要在服务器里维护会话记忆每个请求自己说清楚来路即可。MCP服务器架构一张图看懂请求流转现代 MCP 服务器的分发循环只有 8 步理解它比背协议更快上手读取一行 JSON-RPC → 解析信封 → 通知不响应 → 校验 params._meta → 按方法路由 → 包装类型化结果 → 写出一行 JSON-RPC 响应 → 忘掉本次请求的元数据stdio 传输只需记住三条铁律stdout 只写 JSON-RPC 消息诊断日志走 stderr消息以换行符分隔每条响应后必须 flushstdin 到达 EOF 时立即退出进程课程文档中配有架构图与原始实现服务器架构源码Pythonmain.py服务器架构源码TypeScriptmain.ts架构图文档server-anatomy.svg动手前认识这套双语言示例工程教程以一个笔记服务器为例Python 和 TypeScript 两版暴露完全相同的方法、执行完全相同的线协议契约只依赖各自的标准库。工程目录速览教程正文docs/en.mdPython 实现code/main.py约400行含--demo演示模式TypeScript 实现code/main.ts配套测试tests/test_main.py知识测验quiz.json前置知识MCP基础概念 10 分钟速通正式动手前建议先花 10 分钟读一遍上一课《MCP基础》它会讲清楚 Host、Client、Server、Transport 四个角色的关系概念文档phases/11-llm-engineering/14-model-context-protocol/docs/en.md概念图mcp-architecture.svg最快上手一条命令跑通MCP服务器Demo这是本教程最爽的部分——两个语言版本的 Demo 都是一条命令的事 ✅Python 版在课程code目录下python3 main.py --demo python3 -m unittest discover tests -vTypeScript 版用任意 TS 运行器npx tsx main.ts --demoDemo 会依次完成 5 件事发送server/discover发现请求拿到支持的版本与能力声明列出全部工具、资源和提示模板实际调用一次工具搜索笔记演示一个不支持的协议版本错误码-32022展示每次请求都重复携带元数据、每次成功都带服务器身份信息的无状态契约跑完这两条命令你就已经拥有一个协议合规、可被 AI 宿主直接接入的 MCP 服务器了。核心机制拆解无状态请求 类型化结果每个请求都是自我介绍式的2026-07-28 版协议中每个请求的params._meta必须携带协议版本与客户端能力{ _meta: { io.modelcontextprotocol/protocolVersion: 2026-07-28, io.modelcontextprotocol/clientCapabilities: {}, io.modelcontextprotocol/clientInfo: { name: notes-client, version: 1.0.0 } } }校验规则非常清晰缺元数据 → 返回Invalid Params-32602版本不受支持 → 返回-32022并附上requested与supported两个版本数组永远不要用上一次请求的能力声明去填充这一次——这是无状态服务的红线每个成功响应都要带身份课程用一个统一的结果包装器杜绝某个处理器悄悄漏掉字段的坑所有成功结果带resultType: complete和服务器身份信息列表/读取类结果额外带ttlMs缓存有效期和cacheScopepublic或private列表顺序必须确定性排序——同样的注册表永远产出同样的顺序既方便客户端缓存也让模型上下文更稳定错误的两种姿势新手最常混淆的一点协议信封/参数不合法→ 用 JSON-RPCerror返回工具调用本身失败比如查无结果→ 正常返回内容块 isError: true另外工具注解readOnlyHint、destructiveHint等只是展示提示不是权限控制——真正的授权必须在服务器内部强制执行。从零到你的项目MCP服务器落地三步走第 1 步 · 规划原语为你的领域定义原子工具一个工具只做一件事、URI 可读资源和真正可复用的模板。领域里没有的东西就不要硬造——课程配套的服务端脚手架技能明确要求没有诚实用途就省略该原语。第 2 步 · 套上无状态骨架参考示例工程的 dispatch 循环与结果包装器把校验元数据 → 路由 → 类型化响应固化下来。可直接对照 skill-mcp-server-scaffolder.md 中的 7 项设计清单。第 3 步 · 写合规测试至少覆盖——缺少能力字段时不复用历史声明、列表顺序稳定性、-32022版本错误、私有数据必须标记cacheScope: private。进阶搭配MCP客户端完成闭环服务器建好后下一课教你用 Python 标准库写一个MCP 客户端通过server/discover探测、自动降级到旧版initialize握手完成真正的端到端调用客户端教程phases/13-tools-and-protocols/08-building-an-mcp-client/docs/en.md客户端路由图client-routing.svg学习路线推荐把MCP服务器技能装进知识体系MCP 不是孤立知识点建议按这条路线学习约 3 小时打地基MCP基础概念Phase 11 · 14约75分钟建服务器本教程对应课程Phase 13 · 07约85分钟写客户端构建MCP客户端Phase 13 · 08上生产沿着 13-tools-and-protocols 的目录继续学习传输层、采样、安全工具投毒防御、OAuth 2.1 认证等 20 节课整个课程体系的结构可以在 ROADMAP.md 中查看README.md 提供了各阶段概览。总结构建MCP服务器的关键不是背协议而是抓住三条主线——无状态请求自描述、结果统一类型化包装、列表顺序确定性。Python 和 TypeScript 双语言对照实现正好帮你把抽象的协议契约变成看得懂、跑得通的代码。Learn it. Build it. Ship it for others.【免费下载链接】ai-engineering-from-scratchLearn it. Build it. Ship it for others.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-from-scratch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考