教程文档人工智能【免费下载链接】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点击查看免费下载MCPModel Context Protocol自 2025-06-18 规范起将独立的 SSEServer-Sent Events传输标记为废弃并明确推荐stdio 传输作为本地 MCP 服务器的首选方案。本文以本仓库03-GettingStarted/05-stdio-server课程的完整解决方案为主体逐行剖析 TypeScript、Python、.NET 三种运行时的 stdio 服务器实现覆盖传输原理、工具定义、JSON-RPC 消息处理、Inspector 调试与 Claude Desktop 集成帮助你快速掌握当前规范下构建 MCP 服务器的标准姿势。背景为什么 stdio 成为推荐的 MCP 传输方式根据 课程主文档 的说明MCP 规范定义了两种主要的传输机制stdio—— 通过标准输入/输出流通信推荐用于本地服务器Streamable HTTP—— 用于远程服务器内部可能使用 SSE。在 2025-06-18 规范之前独立的 SSE 端点方案需要搭建 HTTP 服务器、配置路由与会话管理复杂度高且引入了额外的攻击面。规范更新后该方案被Streamable HTTP取代对于本地场景stdio 是更简单、更安全、性能更好的选择。本课程的解决方案也据此全部升级为 stdio 传输。stdio 传输的工作原理stdio 传输的通信模型非常直接简单通信服务器从标准输入stdin读取 JSON-RPC 消息并向标准输出stdout写入消息基于进程客户端将 MCP 服务器作为子进程启动消息格式每条消息是独立的 JSON-RPC 请求、通知或响应以换行符分隔日志服务器可以通过标准错误stderr写入 UTF-8 字符串用于日志输出。同时规范对协议交互提出了三点硬性要求见课程主文档消息必须以换行符分隔且不得包含内嵌换行服务器不得向stdout写入任何非 MCP 消息的内容客户端不得向服务器的stdin写入任何非 MCP 消息的内容。这解释了为什么所有解决方案的日志输出都严格走stderr——stdout是 MCP 协议的专属通道任何污染都会破坏客户端与服务器之间的 JSON-RPC 解析。解决方案总览三种运行时的完整实现本课程的 solution 目录 提供了三种语言的标准答案每种方案都完整演示了stdio 传输的搭建Setup服务器工具的声明与实现Tools正确的 JSON-RPC 消息处理JSON-RPC handling与 Claude 等 MCP 客户端的集成Integration。运行时实现位置技术要点TypeScriptsolution/typescriptMCP TypeScript SDK Zod 参数校验Pythonsolution/pythonMCP Python SDK asyncio.NETsolution/dotnetMicrosoft.Extensions.Hosting 依赖注入三个服务器暴露的工具体系保持一致add(a, b)加法、multiply(a, b)乘法、get_greeting(name)个性化问候、get_server_info()服务器信息便于对照学习各语言 SDK 的差异。TypeScript基于 MCP SDK 的 stdio 服务器依赖与工程配置参考 package.json核心依赖是modelcontextprotocol/sdk 1.26.0与zod^3.24.2工程脚本中已预置好构建、启动与调试命令{ scripts: { build: tsc, start: node build/index.js, inspector: npx modelcontextprotocol/inspector node build/index.js } }安装依赖并编译npm install npm run build服务器实例与传输接入在 src/index.ts 中首先创建Server实例并声明工具能力import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new Server( { name: example-stdio-server, version: 1.0.0, }, { capabilities: { tools: {}, }, } );随后用 Zod 为每个工具定义参数模式如add需要两个 number 类型的参数a、b为请求处理阶段提供运行时校验import { z } from zod; const AddArgsSchema z.object({ a: z.number().describe(First number), b: z.number().describe(Second number), });工具注册与 JSON-RPC 请求处理MCP 客户端通过两个标准 JSON-RPC 方法与服务器交互tools/list列出工具与tools/call调用工具。SDK 以 Schema 常量形式暴露它们服务器只需注册对应的请求处理器ListToolsRequestSchema处理器返回工具清单每个工具包含name、description与符合 JSON Schema 规范的inputSchema见 src/index.ts#L47-L95CallToolRequestSchema处理器根据request.params.name分发到对应工具先用 Zod 解析参数再执行逻辑并以content: [{ type: text, text: ... }]结构返回见 src/index.ts#L98-L164。实现get_server_info时返回 JSON 序列化的服务器元数据case get_server_info: { return { content: [ { type: text, text: JSON.stringify({ server_name: example-stdio-server, version: 1.0.0, transport: stdio, capabilities: [tools], }, null, 2), }, ], }; }启动与优雅退出入口函数创建StdioServerTransport实例并connect到服务器实现 stdin/stdout 通信src/index.ts#L167-L172async function runServer() { console.error(Starting MCP stdio server...); // 日志走 stderr const transport new StdioServerTransport(); await server.connect(transport); }同时监听SIGINT/SIGTERM信号实现优雅退出src/index.ts#L175-L183。启动方式npm start启动后服务器会看似卡住——这是正常现象它正在等待来自stdin的 JSON-RPC 消息。Python基于 asyncio 的 stdio 服务器依赖与运行环境按 Python 解决方案文档需要 Python 3.8并建议使用uv管理环境。安装 MCP SDKpython -m venv venv source venv/bin/activate # macOS/LinuxWindows 用 venv\Scripts\activate pip install mcp使用 list_tools / call_tool 处理器定义工具server.py 采用 Python SDK 的显式处理器风格用server.list_tools()装饰器声明工具清单每个工具通过Tool模型描述名称、描述与inputSchemaserver.py#L28-L72server.list_tools() async def list_tools() - list[Tool]: return [ Tool( nameadd, descriptionAdd two numbers together, inputSchema{ type: object, properties: { a: {type: number, description: First number}, b: {type: number, description: Second number} }, required: [a, b] } ), # multiply / get_greeting / get_server_info 同理 ]工具调用逻辑由server.call_tool()处理器统一接管根据工具名分发并返回TextContent列表server.py#L74-L103server.call_tool() async def call_tool(name: str, arguments: dict) - list[TextContent]: if name add: result arguments[a] arguments[b] logger.info(fAdding {arguments[a]} {arguments[b]} {result}) return [TextContent(typetext, textstr(result))] # ... else: raise ValueError(fUnknown tool: {name})使用 stdio_server 上下文管理器运行入口函数通过mcp.server.stdio.stdio_server()上下文管理器拿到读写流再交给server.run()启动事件循环server.py#L105-L123async def main(): logger.info(Starting MCP stdio server...) async with stdio_server() as (read_stream, write_stream): await server.run( read_stream, write_stream, server.create_initialization_options() ) if __name__ __main__: asyncio.run(main())启动与 TypeScript 一样简单python server.py补充说明课程主文档还演示了 Python SDK 的另一种装饰器风格——直接用server.tool()装饰普通函数即可暴露工具见 课程主文档的 Python 示例。两种写法等价前者适合对工具注册过程做更精细控制后者更简洁。.NET基于依赖注入的 stdio 服务器主机构建从 WebApplication 到 Host.NET 方案的核心差异在于旧的 HTTP/SSE 服务器需要WebApplication.CreateBuilder()app.MapMcp()路由配置而 stdio 方案退化为普通控制台主机Program.csvar builder Host.CreateApplicationBuilder(args); builder.Services .AddMcpServer() .WithStdioServerTransport() .WithToolsTools();.WithStdioServerTransport()替代了旧的.WithHttpTransport()工具类Tools直接注册进 DI 容器。日志同样配置为输出到控制台即 stderr 通道见 Program.cs#L24-L29builder.Services.AddLogging(logging { logging.ClearProviders(); logging.AddConsole(); logging.SetMinimumLevel(LogLevel.Information); });构建后调用app.RunAsync()启动Program.cs#L39-L47。用特性声明工具工具定义在 Tools.cs 中类标注[McpServerToolType]每个方法标注[McpServerTool]并配合[Description]提供人类可读说明构造函数注入ILoggerTools实现结构化日志[McpServerToolType] public sealed class Tools { private readonly ILoggerTools _logger; public Tools(ILoggerTools logger) _logger logger; [McpServerTool, Description(Add two numbers together)] public async Taskstring AddNumbers( [Description(The first number)] int a, [Description(The second number)] int b) { var result a b; _logger.LogInformation(Adding {A} {B} {Result}, a, b, result); return await Task.FromResult(${a} {b} {result}); } // MultiplyNumbers / GetGreeting / GetServerInfo 同理 }.NET 实现天然获得依赖注入、结构化日志、异步支持和特性驱动的工具元数据运行时可直接复用宿主容器的全部能力。运行与测试dotnet restore dotnet build dotnet run测试与调试使用 MCP InspectorMCP Inspector 是调试 stdio 服务器的标准工具它会将你的服务器作为子进程启动并提供一个 Web 界面用于查看服务器能力capabilities用不同参数交互式测试工具监控客户端与服务器之间的 JSON-RPC 消息排查连接问题。三种运行时对应的启动命令运行时Inspector 命令TypeScriptnpm run inspector等价于npx modelcontextprotocol/inspector node build/index.jsPythonnpx modelcontextprotocol/inspector python server.py.NETnpx modelcontextprotocol/inspector dotnet run也可以不经过 Inspector直接向服务器进程发送 JSON-RPC 消息验证响应Python 示例见 Python 方案文档{jsonrpc: 2.0, id: 1, method: tools/list}服务器会返回可用工具清单。这种方式适合快速验证传输层是否工作正常。调试要点课程主文档与三份方案文档共同强调日志一律走stderr严禁写stdout——那是 MCP 消息的专属通道确保所有 JSON-RPC 消息以换行符分隔、不含内嵌换行先实现简单工具验证链路再逐步添加复杂功能使用 Inspector 校验消息格式与工具参数 Schema。与 Claude Desktop / VS Code 集成构建完成的 stdio 服务器可以直接接入 Claude Desktop 等 MCP 客户端。以 Windows 的%APPDATA%\Claude\claude_desktop_config.jsonmacOS 为~/Library/Application Support/Claude/claude_desktop_config.json为例三种运行时的配置如下Python{ mcpServers: { example-stdio-server: { command: python, args: [path/to/server.py] } } }TypeScript{ mcpServers: { example-stdio-server: { command: node, args: [path/to/build/index.js] } } }.NET{ mcpServers: { example-stdio-server: { command: dotnet, args: [run, --project, path/to/server.csproj] } } }配置完成后重启 Claude即可加载新服务器。之后便可在对话中自然调用工具例如Calculate the sum of 15 and 27、Can you greet me using the greeting tool?、Whats the server info?。若要在 VS Code 中直接调试服务器可创建.vscode/launch.json调试配置以 Python 为例见 课程主文档{ version: 0.2.0, configurations: [ { name: Debug MCP Server, type: python, request: launch, program: server.py, console: integratedTerminal } ] }设置断点后即可配合 Inspector 边调试边验证消息交互。小结与后续学习路径通过本课的三份解决方案你已经掌握了为什么 stdio 是当前 MCP 规范推荐的本地传输方式以及它相比废弃 SSE 方案的优势无 HTTP 服务器、子进程模型、JSON-RPC over stdin/stdout、更安全更易调试在 TypeScript、Python、.NET 三种运行时下搭建 stdio 服务器、注册工具、处理 JSON-RPC 请求的完整方法使用 MCP Inspector 测试工具、排查连接问题的标准流程将服务器接入 Claude Desktop / VS Code 的配置方式。stdout通道纪律只写协议消息、stderr日志约定、换行分隔的 JSON-RPC 格式是贯穿三种实现的共同内核——理解这三条你就掌握了 stdio 传输的精髓。继续深入学习可以接着阅读本仓库的相邻主题HTTP StreamingStreamable HTTP远程 MCP 服务器的另一种受支持传输MCP 安全最佳实践为服务器实现安全防护部署策略将服务器投入生产环境更多跨语言可运行示例见 samples 目录Java / C# / JavaScript / TypeScript / Python / Rust。赞分享教程文档人工智能【免费下载链接】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点击查看免费下载相关推荐MCP stdio 传输实战基于 mcp-for-beginners 多语言示例构建本地 MCP ServerMCP stdio 传输实战基于 mcp for beginners 多语言示例构建本地 MCP Server 本文以 mcp for beginners 仓教程文档人工智能基于 stdio 传输构建 MCP ServerTypeScript、Python 与 .NET 多语言实战指南基于 stdio 传输构建 MCP ServerTypeScript、Python 与 .NET 多语言实战指南 本指南以 mcp for beginners教程文档人工智能基于 stdio 传输构建 MCP Python 服务器搭建、测试与客户端集成的完整实战指南mcp-for-beginners基于 stdio 传输构建 MCP Python 服务器搭建、测试与客户端集成的完整实战指南mcp for beginners 本教程以开源课程 mcp教程文档人工智能上一篇GroundingDINO 十分钟跑通文本引导目标检测第一次推理下一篇DSOD性能优化指南调整batch size如何让mAP提升1.2%实验数据大公开创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考