教程文档人工智能【免费下载链接】mcp-for-beginnersThis open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.项目地址https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners点击查看免费下载本文以本仓库 TypeScript 官方解题方案 为主体结合 课程讲义 与源码实现系统讲解如何基于 MCPModel Context Protocol规范 2025-06-18 推荐的stdio 传输用 TypeScript 构建一个可被 Claude Desktop、VS Code 等客户端消费的本地 MCP 服务器。读完本文你将掌握 stdio 传输的通信原理、MCP SDK 的工具注册与调用机制、Inspector 调试方法以及如何将该服务器接入真实客户端。为什么从 SSE 迁移到 stdio 传输MCP 规范 2025-06-18 起独立的 SSEServer-Sent Events传输已被弃用deprecated取而代之的是两种主要传输机制stdio通过标准输入/输出流通信推荐用于本地服务器Streamable HTTP用于远程服务器内部可能仍使用 SSE。本仓库的 TypeScript 解题方案正是基于这一规范更新而重写的。课程讲义 明确指出stdio 是当前规范中最常用、最被推荐的传输方式它为大多数 MCP 服务器实现提供了简单且高效的构建路径。stdio 传输的工作原理stdio 传输的核心机制非常简洁简单通信服务器从标准输入stdin读取 JSON-RPC 消息并向标准输出stdout发送消息基于进程客户端将 MCP 服务器作为子进程启动消息格式消息是独立的 JSON-RPC 请求、通知或响应以换行符newline分隔日志输出服务器可以通过标准错误流stderr输出 UTF-8 字符串用于日志记录。关键协议要求按照规范stdio 服务器必须遵守以下约束要求说明消息必须按换行符分隔消息内容中不得包含内嵌换行符服务器不得污染stdoutstdout上只能输出合法的 MCP 消息日志必须走stderr客户端不得污染stdin客户端写入服务器stdin的内容只能是合法的 MCP 消息这条规则直接决定了后续开发中用console.error()而非console.log()这一最佳实践是 stdio 服务器开发中极易踩坑的关键点。项目结构速览TypeScript 解题方案位于 03-GettingStarted/05-stdio-server/solution/typescript/目录结构如下typescript/ ├── src/ │ └── index.ts # 主服务器实现 ├── build/ # 编译后的 JavaScript自动生成 ├── package.json # 项目配置 ├── tsconfig.json # TypeScript 配置 └── README.md # 本文对应的说明文档整个服务器只有一个源文件src/index.ts代码量约 190 行充分体现了 stdio 传输无需 HTTP 服务器、无需路由与会话管理的简洁性。前置条件在开始之前请确保环境满足Node.js 18或更高版本npm 或 yarn包管理器。第一步安装依赖并构建进入 solution/typescript 目录执行npm install npm run build从 package.json 可以看到关键依赖与脚本运行时依赖modelcontextprotocol/sdk版本要求1.26.0与zod^3.24.2前者提供 MCP 协议实现后者用于工具参数的运行时校验开发依赖typescript^5.3.3与types/node^20.11.24type: module采用 ES Module 规范这也是源码中使用.js后缀导入路径的原因脚本build:tsc—— 编译 TypeScriptstart:node build/index.js—— 启动服务器inspector:npx modelcontextprotocol/inspector node build/index.js—— 一键启动调试器bin字段将mcp-stdio-server命令映射到./build/index.js便于全局安装后直接以命令方式启动。tsconfig.json 的编译目标为ES2022、模块系统为Node16输出目录为./build并启用了strict严格模式。版本提示源码头部注释与文档均声明本示例遵循 MCP 规范 2025-06-18而package.json的 description 字段写的是aligned with MCP Specification 2025-11-25可见 SDK 版本在持续演进实际使用时以你安装的 SDK 所支持的规范版本为准。第二步深入源码——服务器如何构建完整实现见 src/index.ts。我们按逻辑拆解它的四个核心环节。1. 创建 Server 实例并声明能力const server new Server( { name: example-stdio-server, version: 1.0.0, }, { capabilities: { tools: {}, }, } );第一参数是服务器身份信息名称与版本第二参数声明capabilities。本例声明了tools能力表示该服务器向客户端暴露可调用的工具Tool。2. 用 zod 定义工具参数模式服务器为工具参数定义了三个 zod schemasrc/index.tsconst AddArgsSchema z.object({ a: z.number().describe(First number), b: z.number().describe(Second number), }); const MultiplyArgsSchema z.object({ a: z.number().describe(First number), b: z.number().describe(Second number), }); const GreetingArgsSchema z.object({ name: z.string().describe(Name of the person to greet), });zod 在这里承担双重职责参数类型声明供 schema 定义复用与运行时校验调用时用parse校验并解构参数。3. 注册 tools/list 处理器server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ /* 四个工具的完整描述 */ ], }; });客户端通过tools/list请求获取工具清单。每个工具描述包含name、description与inputSchemaJSON Schema 格式其中get_server_info的inputSchema为空对象properties: {}表示该工具无需任何参数。4. 注册 tools/call 处理器server.setRequestHandler(CallToolRequestSchema, async (request) { const { name, arguments: args } request.params; switch (name) { case add: { const { a, b } AddArgsSchema.parse(args); const result a b; console.error(Adding ${a} ${b} ${result}); // Log to stderr return { content: [ { type: text, text: ${a} ${b} ${result}, }, ], }; } // ... multiply / get_greeting / get_server_info default: throw new Error(Unknown tool: ${name}); } });这里有几个值得注意的实现细节响应统一使用content数组包裹元素类型为text每次调用都通过console.error()向stderr输出日志——这正是 stdio 协议要求的正确做法get_server_info用JSON.stringify(..., null, 2)返回结构化的服务器元数据服务器名、版本、传输类型、能力列表遇到未知工具名时抛出Error向客户端报告失败。5. 连接 stdio 传输并启动async function runServer() { console.error(Starting MCP stdio server...); // Log to stderr const transport new StdioServerTransport(); await server.connect(transport); console.error(Server connected via stdio transport); // Log to stderr }StdioServerTransport封装了 stdin/stdout 上的 JSON-RPC 消息读写与换行分隔处理server.connect(transport)完成协议握手。启动入口还处理了优雅退出process.on(SIGINT, () { console.error(Received SIGINT, shutting down gracefully); process.exit(0); }); process.on(SIGTERM, () { console.error(Received SIGTERM, shutting down gracefully); process.exit(0); }); runServer().catch((error) { console.error(Server error:, error); process.exit(1); });服务器对SIGINT/SIGTERM信号进行捕获并优雅退出同时捕获启动阶段的异常并输出错误日志。第三步运行服务器npm start重要提示stdio 服务器与旧的 SSE 服务器运行方式完全不同——它不会启动 Web 服务器而是通过 stdin/stdout 通信。因此运行后终端会看起来像是卡住了这是完全正常的它正在等待来自 stdin 的 JSON-RPC 消息。第四步用 MCP Inspector 测试服务器方法一通过 npm 脚本推荐npm run inspector该命令将把你的服务器作为子进程启动打开一个用于测试的 Web 界面让你交互式地测试服务器上的所有工具。方法二直接命令行启动 Inspector也可以直接调用 Inspector显式指定启动命令npx modelcontextprotocol/inspector node build/index.js服务器提供的四个工具工具签名说明addadd(a, b)两个数字相加multiplymultiply(a, b)两个数字相乘get_greetingget_greeting(name)生成个性化问候语get_server_infoget_server_info()获取服务器信息在 Inspector 界面中你可以观察到客户端与服务器之间交换的 JSON-RPC 消息如tools/list、tools/call这为协议层面的调试提供了极佳的可视化手段。第五步接入 Claude Desktop要将该服务器接入 Claude Desktop把以下配置写入claude_desktop_config.json{ mcpServers: { example-stdio-server: { command: node, args: [path/to/build/index.js] } } }配置要点command为启动进程的可执行文件这里是nodeargs传入编译产物build/index.js的绝对路径配置后重启 Claude Desktop即可在对话中调用add、multiply、get_greeting、get_server_info等工具。stdio 与已弃用 SSE 的对比stdio 传输当前推荐✅ 更简单的设置——无需 HTTP 服务器✅ 更好的安全性——没有 HTTP 端点暴露✅ 基于子进程的通信✅ JSON-RPC over stdin/stdout✅ 更好的性能。SSE 传输已弃用❌ 需要搭建 Express 服务器❌ 需要复杂的路由与会话管理❌ 更多依赖Express、HTTP 处理❌ 额外的安全考量❌ 已在 MCP 规范 2025-06-18 中弃用。开发与调试技巧日志一律使用console.error()console.log()会写入stdout而stdout被协议保留用于 MCP 消息污染stdout会直接破坏通信测试前先npm run buildstart与inspector脚本都指向build/目录下的编译产物未编译会导致启动失败优先用 Inspector 做可视化调试可以直观查看工具列表、参数校验结果与 JSON-RPC 消息流确保所有 JSON 消息格式正确协议要求消息按换行符分隔且不含内嵌换行优雅退出已内置服务器会自动处理SIGINT/SIGTERM信号。跨语言对照同一解决方案的另两种实现本仓库的 解题方案总览 提供了 TypeScript、Python、.NET 三种运行时的完整实现帮助你理解 stdio 服务器在不同生态中的落地方式Pythonserver.py 使用mcp官方 SDK通过server.list_tools()与server.call_tool()装饰器注册工具用stdio_server()上下文管理器建立传输并通过logging模块将日志输出到stderr.NETProgram.cs 基于Host.CreateApplicationBuilder与依赖注入通过.AddMcpServer().WithStdioServerTransport().WithToolsTools()链式配置Tools.cs 则用[McpServerTool]特性声明工具方法。三者共享同一套工具集add、multiply、get_greeting、get_server_info和相同的 stdio 协议约束对照阅读可以快速掌握跨语言实现 MCP 服务器的共性模式。小结通过本文你已经完整走通了用 TypeScript 构建 MCP stdio 服务器的全部流程理解协议原理、安装构建、深入源码、启动测试、接入 Claude Desktop。关键要点总结如下stdio 是本地 MCP 服务器当前推荐的传输方式相比 SSE 更简单、更安全、性能更好服务器本质是一个等待 stdin 消息的子进程stderr是日志通道、stdout是协议通道MCP SDK 的ServerStdioServerTransport组合把协议细节封装到极致开发者只需关注工具的定义与实现MCP Inspector 是调试 stdio 服务器的首选工具可视化地呈现 JSON-RPC 交互全过程。在此基础上可以继续探索本仓库的进阶主题HTTP StreamingStreamable HTTP 传输 用于远程服务器场景以及 MCP 安全最佳实践 为服务器加固。赞分享教程文档人工智能【免费下载链接】mcp-for-beginnersThis open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.项目地址https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners点击查看免费下载相关推荐基于 stdio 传输构建 MCP 服务器从原理到调试集成的完整实战指南mcp-for-beginners基于 stdio 传输构建 MCP 服务器从原理到调试集成的完整实战指南mcp for beginners 本教程面向希望快速掌握 Model Conte教程文档人工智能基于 MCP SDK 构建 TypeScript stdio 服务器从零实现、调试到接入 Claudemcp-for-beginners 实战解析基于 MCP SDK 构建 TypeScript stdio 服务器从零实现、调试到接入 Claudemcp for beginners 实战解析 导读教程文档人工智能MCP for Beginners基于 stdio 传输构建多语言 MCP 服务器TypeScript / Python / .NET 完整实现解析MCP for Beginners基于 stdio 传输构建多语言 MCP 服务器TypeScript / Python / .NET 完整实现解析 MC教程文档人工智能上一篇Teleport 许可到期告警机制解析基于 Cluster Alerts 的 License 过期预警与提醒设计RFD 83下一篇探索Yet Another Dialog命令行中的GTK对话框解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考