★ FEATURED ARTICLE 教程文档人工智能【免费下载链接】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-for-beginners 开源课程仓库中的 Python 计算器示例为主线完整讲解如何使用官方 Python SDK 构建一个基于 Model Context ProtocolMCP的 stdio 服务器从依赖安装、四个算术工具的注册与实现到服务器启动、函数验证与协议发现测试再到常见 JSON-RPC 报错的排查。读完本文你将掌握一个可被 Claude Desktop 等 MCP 客户端直接调用的最小可运行服务器并理解 MCP2026-07-28协议版本协商与server/discover机制的底层原理。示例在课程中的定位在 03-GettingStarted 章节中仓库为每种主流语言都准备了一套计算器入门样本包括 Java、.NET、JavaScript、TypeScript 与本文的 Python 样本。它们的共同点是通过一个提供add、subtract、multiply、divide四个基本算术工具的 MCP 服务器演示 MCP 三大服务端原语之一——工具Tools的定义、注册与暴露。Python 样本的完整源码位于 mcp_calculator_server.py配套测试位于 test_calculator.py依赖清单为 requirements.txt。环境准备与依赖安装本样本使用官方 MCP Python SDK其依赖约束写在 requirements.txt 中mcp2.1.1,3.0.0即在2.1.1且3.0.0的版本区间内安装 SDK这保证了示例所用 API如mcp.server.mcpserver.MCPServer、mcp.server.stdio.stdio_server的可用性。推荐在虚拟环境中安装# 创建并激活虚拟环境Linux/macOS python -m venv venv source venv/bin/activate # 方式一按 requirements.txt 安装 pip install -r requirements.txt # 方式二直接安装 MCP Python SDK与方式一等价 pip install mcp2.1.1,3.0.0提示完整的环境准备开发环境、IDE、包管理器等可参考 Getting Started 章节的环境搭建说明。服务器源码逐层拆解打开 mcp_calculator_server.py可以看到它分为四层导入与常量、协议兼容流封装、服务器子类、工具定义与启动入口。逐层拆解如下。1. 协议版本常量PROTOCOL_VERSION 2026-07-28 LEGACY_PROTOCOL_VERSION 2025-11-25 PROTOCOL_VERSION_KEY io.modelcontextprotocol/protocolVersion CLIENT_CAPABILITIES_KEY io.modelcontextprotocol/clientCapabilities UNSUPPORTED_PROTOCOL_VERSION_ERROR -32022MCP 协议采用YYYY-MM-DD的日期版本号。当前版本为2026-07-28该版本在传输层移除了initialize握手与协议级会话 ID使协议变为无状态2025-11-25作为旧版协议被保留以兼容老客户端。-32022则是不支持的协议版本这一 JSON-RPC 错误码用于版本协商失败时的报错。2. 服务器类的核心骨架class CalculatorMCPServer(MCPServer): def __init__(self, name: str): super().__init__(name) self._lowlevel_server.add_request_handler( server/discover, RequestParams, self._discover, )服务器继承自 SDK 的MCPServer并在构造时注册了server/discover请求处理器。server/discover是2026-07-28协议中客户端用于探测服务器能力的关键方法其响应见_discover返回supportedVersions服务器支持的协议版本列表[2026-07-28, 2025-11-25]capabilities服务器能力如工具支持情况由底层_lowlevel_server.get_capabilities()按客户端协商的协议版本生成instructions服务器使用说明。配套的_DefaultVersionStream与_SupportedVersionsStream两个封装类负责协议兼容前者为无版本信息的旧式连接注入当前协议版本元数据后者在收到-32022版本错误时把supported列表回填给客户端保证新旧客户端都能平滑对接。3. 四个工具的注册mcp CalculatorMCPServer(Calculator MCP Server) mcp.tool() def add(a: float, b: float) - float: Add two numbers together and return the result. return a b mcp.tool() def subtract(a: float, b: float) - float: Subtract b from a and return the result. return a - b mcp.tool() def multiply(a: float, b: float) - float: Multiply two numbers together and return the result. return a * b mcp.tool() def divide(a: float, b: float) - float: Divide a by b and return the result. if b 0: raise ValueError(Cannot divide by zero) return a / bmcp.tool()装饰器把普通 Python 函数变成 MCP 工具。这里有几个值得注意的细节函数名即工具名add、subtract、multiply、divide四个工具会通过tools/list暴露给客户端类型注解即参数 Schemaa: float、b: float会被 SDK 自动转换为 JSON Schema 用于参数校验Docstring 即工具描述函数的三引号注释成为工具的 description帮助 LLM 理解何时调用该工具异常即错误响应divide在除零时抛出ValueError(Cannot divide by zero)SDK 会将其转换为 JSON-RPC 错误返回给客户端这正是与 JavaScript/TypeScript 样本中通过isError: true标记错误在写法上的差异但效果等价。4. 启动入口与 stdio 传输def run(self) - None: import asyncio asyncio.run(self.run_stdio_async()) async def run_stdio_async(self) - None: async with stdio_server() as (read_stream, write_stream): await self._lowlevel_server.run( _DefaultVersionStream(read_stream), _SupportedVersionsStream(write_stream), self._lowlevel_server.create_initialization_options(), ) if __name__ __main__: mcp.run()服务器通过mcp.server.stdio.stdio_server()使用STDIO 传输从标准输入stdin读取 JSON-RPC 2.0 请求向标准输出stdout写回响应。STDIO 是本地 MCP 服务器与客户端如 Claude Desktop、VS Code通信的推荐方式具备子进程级隔离与低开销优势MCP 的远程场景则使用 Streamable HTTP 传输。关于两种传输的更多背景可参考 01-CoreConcepts 的协议与传输层说明。启动服务器预期中的 JSON-RPC 报错按 README 说明启动服务器python mcp_calculator_server.py在终端直接运行并手动输入内容时你会看到 JSON-RPC 校验错误如Invalid JSON: EOF while parsing a value——这是完全正常的现象。原因在于MCP 服务器是被动组件它只接受符合 JSON-RPC 2.0 格式的 MCP 客户端消息而不是接受用户在终端里直接敲入的数字或表达式。当你在终端按下回车输入了非 JSON-RPC 内容stdin 解析自然失败。正确的交互方式是把该服务器配置到 MCP 客户端中。以 Claude Desktop 为例在客户端配置中注册命令python /path/to/mcp_calculator_server.py随后便可在对话中直接要求计算 5 3由客户端负责把模型意图封装成tools/call请求发给服务器。双重测试函数级验证与协议级验证配套的 test_calculator.py 不仅验证了算术逻辑还覆盖了协议层行为是学习 MCP 测试思路的极佳范本。函数级测试from mcp_calculator_server import add, subtract, multiply, divide result add(5, 3) assert result 8该脚本直接导入四个工具函数逐一对add(5, 3) 8、subtract(10, 4) 6、multiply(7, 6) 42、divide(15, 3) 5做断言并额外验证除零时抛出ValueError且错误消息为Cannot divide by zero。这一步与服务器是否运行无关用于在启动前快速确认工具逻辑正确python test_calculator.py协议级测试测试脚本中更关键的是request_server与test_protocol_discovery两个部分它们通过subprocess启动一个新的服务器进程向其标准输入写入一行 JSON-RPC 请求再解析标准输出的首行响应以此模拟真实客户端request {jsonrpc: 2.0, id: 1, method: method, params: params} process subprocess.run( [sys.executable, server], inputjson.dumps(request) \n, capture_outputTrue, textTrue, timeout10, checkTrue, )随后验证三组协议行为server/discover发现响应中的supportedVersions必须同时包含2026-07-28与2025-11-25capabilities.tools不为空且resultType、ttlMs、cacheScope字段符合协议约束tools/list清单暴露的工具名集合必须恰好是{add, subtract, multiply, divide}initialize握手旧协议兼容以2025-11-25发起初始化响应中协商出的protocolVersion仍为2025-11-25。这段测试直接印证了前面源码分析中的结论服务器通过_SupportedVersionsStream对新旧协议版本提供双向兼容既能被2026-07-28客户端通过server/discover发现也能与2025-11-25老客户端完成握手。这也是本样本相比只测函数更深一层的地方——它验证了服务器在真实 JSON-RPC 会话中的行为。常见故障排查根据 README 的故障排除章节集中解决两个高频问题症状原因与解决ModuleNotFoundError: No module named mcp未安装 MCP Python SDK。执行pip install mcp2.1.1,3.0.0或pip install -r requirements.txt直接运行时出现Invalid JSON: EOF while parsing a value等 JSON-RPC 错误服务器只接受格式正确的 MCP 客户端消息不接受终端直接输入。请改用 MCP 客户端如 Claude Desktop或通过test_calculator.py中的subprocess方式发起请求除上述两点外还可对照 01-first-server 课程的常见问题表 排查工具执行错误、参数 Schema 校验失败等通用问题。跨语言对照与下一步把本样本与 TypeScript/JavaScript 计算器、.NET 计算器 对照可以看出MCP 的核心抽象在语言之间高度一致工具 名称 参数 Schema 处理函数差异只在装饰器/注册 API 的语法层面Python 用mcp.tool()TypeScript 用server.tool(add, {a: z.number(), b: z.number()}, handler).NET 用[McpServerTool]特性。这种一致性正是 MCP AI 应用的 USB-C 接口定位的体现。掌握本样本后推荐继续学习01-first-server从零搭建你的第一个服务器含 MCP Inspector 图形化调试02-client编写连接服务器的客户端03-llm-client让 LLM 与服务器协商执行08-testing更多服务器与客户端测试方法。总结通过本文你完整走通了 mcp-for-beginners Python 计算器样本的四个关键环节安装mcp2.1.1,3.0.0、实现mcp.tool()装饰器注册四个工具、运行stdio 传输 预期内的 JSON-RPC 报错、验证函数断言与server/discover/tools/list/initialize协议级测试。在此基础上你也理解了2026-07-28协议的无状态设计、server/discover发现机制以及服务器如何通过-32022错误码与supported列表实现新旧协议版本的双向兼容——这些正是从能跑通示例迈向写出生产级 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点击查看免费下载相关推荐运行与测试 .NET MCP 服务器mcp-for-beginners 计算器示例与 MCP Inspector 实战指南运行与测试 .NET MCP 服务器mcp for beginners 计算器示例与 MCP Inspector 实战指南 本指南以 mcp for begi教程文档人工智能mcp-for-beginners 实战用 PythonFastMCP从零实现 MCP 服务器与客户端mcp for beginners 实战用 PythonFastMCP从零实现 MCP 服务器与客户端 本文基于开源课程 mcp for beginner教程文档人工智能MCP协议接口测试mcp-for-beginners Postman实战MCP协议接口测试mcp for beginners Postman实战 MCPModel Context Protocol作为连接AI模型与外部工具的标教程文档人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
