教程文档人工智能【免费下载链接】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 课程中“Advanced server usage高级 Server 用法”一节的 Python 示例工程展开完整讲解从虚拟环境搭建、依赖安装、代码运行到预期输出的全过程并结合仓库内server.py、client.py与tools/目录的源码实现剖析低层 Server 的list_tools/call_tool双处理器架构与 Pydantic 输入校验原理。读完本文你将掌握如何在本地跑通一个基于 stdio 传输的 MCP Python 示例并理解其可扩展架构的核心设计思想。一、示例工程概览文档对应哪个代码仓库本节对应的原文档位于仓库根目录下的 translations/bg/03-GettingStarted/10-advanced/code/python/README.md保加利亚语翻译版英文原文见 03-GettingStarted/10-advanced/code/python/README.md其内容是整个 10-advanced 章节 Python 示例的运行说明书。该示例工程的完整源码位于 03-GettingStarted/10-advanced/code/python/采用章节 README 中推荐的“低层 Server 独立工具目录”架构目录结构如下python/ --| client.py # 基于 stdio 传输的 MCP 客户端入口 --| server.py # 低层 MCP Server仅注册两个请求处理器 --| tools ----| __init__.py # 工具注册表以字典形式集中暴露所有工具 ----| add.py # add 工具的定义与处理函数 ----| schema.py # 基于 Pydantic 的输入模型JSON Schema 来源二、环境准备创建虚拟环境并安装mcp[cli]原文档给出的第一步是创建并激活 Python 虚拟环境python -m venv venv source ./venv/bin/activatepython -m venv venv会在当前目录生成名为venv的隔离虚拟环境避免 MCP SDK 依赖污染系统 Pythonsource ./venv/bin/activate在 Linux/macOS 下激活该环境Windows 下对应为venv\Scripts\activate激活后后续pip安装与python运行均在此环境中进行。第二步是安装依赖pip install mcp[cli]这里需要重点说明[cli]这个 extra 的含义mcp是 Model Context Protocol 的官方 Python SDK基础包已包含ClientSession、StdioServerParameters、mcp.server.stdio等核心模块而[cli]额外附带命令行工具相关依赖。示例的客户端与服务器分别通过from mcp import ClientSession, StdioServerParameters, types与from mcp.server.lowlevel import NotificationOptions, Server导入 SDK这些正是由mcp包提供的核心 API。若后续需要直接使用mcp命令行如配合 MCP Inspector 调试该 extra 也是必需的。三、运行示例python client.py与预期输出环境就绪后在原文档即 03-GettingStarted/10-advanced/code/python/README.md中执行python client.py正常情况下终端会输出两行关键信息Available tools: [add] Result of add tool: metaNone content[TextContent(typetext, text8.0, annotationsNone, metaNone)] structuredContentNone isErrorFalse这两行输出逐字验证了整个 MCP 调用链已经走通Available tools: [add]客户端成功发起tools/list请求服务器返回当前唯一的工具addResult of add tool: ...客户端随后以参数{a: 5, b: 3}发起tools/call请求服务器返回TextContent(typetext, text8.0)即5 3 8.0add工具将输入强制转为float后求和故结果带小数位。注意text8.0这一细节它印证了 tools/add.py 中float(input_model.a) float(input_model.b)的实现——Pydantic 模型字段声明为float后传入的整数5、3被转换为浮点数参与运算。四、源码级剖析低层 Server 的双处理器架构要理解示例为何能以“一个 Server 一个 tools 目录”就完成工具注册与调用需要通读 server.py 的实现。与常规FastMCP逐个mcp.tool()注册的方式不同低层 Server 只为每个特性类型工具、资源、提示词维护两个处理器本示例中即4.1 工具列表处理器handle_list_tools对应 server.py 中的server.list_tools()装饰器函数。其核心逻辑是遍历tools注册表中的每一个工具定义将其包装为符合 MCP 协议返回类型的types.Toolserver.list_tools() async def handle_list_tools() - list[types.Tool]: List available tools. vm_tools [] for tool in tools.values(): print(fRegistered tool: {tool[name]}) vm_tools.append( types.Tool( nametool[name], descriptiontool[description], inputSchemaconvert_to_json(tool[input_schema]), ) ) return vm_tools这里的convert_to_json是示例中一个关键辅助函数见 server.py它接收一个 Pydantic 模型类通过model_cls.schema()取得 JSON Schema再精简为{type: object, properties: ..., required: ...}结构作为 MCP 协议要求的inputSchema返回。这一设计让工具作者只需要声明 Pydantic 模型无需手写 JSON Schema。4.2 工具调用处理器handle_call_tool对应 server.py 中的server.call_tool()装饰器函数。它接收工具名name与参数字典arguments通过名称查表、调用对应 handler 并统一包装返回结果server.call_tool() async def handle_call_tool( name: str, arguments: dict[str, str] | None ) - list[types.TextContent]: if name not in tools: raise ValueError(fUnknown tool: {name}) tool tools[name] result default try: result await toolhandler except Exception as e: raise ValueError(fError calling tool {name}: {str(e)}) return [ types.TextContent(typetext, textstr(result)) ]可见未知工具名会抛出ValueError已知工具通过await toolhandler异步调用参数校验的失败会由 handler 内部抛出异常进而在此处被捕获并转换为错误信息避免服务器进程崩溃。所有工具的返回内容统一封装为types.TextContent这也是客户端最终打印出text8.0的直接原因。4.3 服务器启动与生命周期管理server.py 中的run()函数展示了低层 Server 的启动方式使用mcp.server.stdio.stdio_server()获取标准输入输出流再调用server.run(...)传入InitializationOptions含server_nameexample-server、server_version0.1.0与通过server.get_capabilities()计算的 capabilities。其中NotificationOptions()用于声明服务器支持的协议通知类型experimental_capabilities{}表示未启用实验性能力。4.4tools/目录工具定义与校验的落点工具侧由三个文件组成形成了“Schema 声明 → 工具定义 → 集中注册”的清晰链路tools/schema.py 定义 Pydantic 输入模型from pydantic import BaseModel class AddInputModel(BaseModel): a: float b: floattools/add.py 定义工具元信息与处理函数from .schema import AddInputModel async def add_handler(args) - float: try: # Validate input using Pydantic model input_model AddInputModel(**args) except Exception as e: raise ValueError(fInvalid input: {str(e)}) Handler function for the add tool. return float(input_model.a) float(input_model.b) add { name: add, description: Adds two numbers, input_schema: AddInputModel, handler: add_handler }这里体现了章节 README 强调的“在 handler 内做校验”策略AddInputModel(**args)会依据a、b两个float字段对传入参数进行类型与必填性校验参数缺失或类型不符会抛出异常并被捕获为ValueError。工具字典的四要素name、description、input_schema、handler与服务器端handle_list_tools/handle_call_tool的读取字段一一对应这就是两个处理器能“无差别”驱动任意工具的原因。tools/init.py 以字典形式集中注册工具from .add import add tools { add[name] : add }今后每新增一个工具只需在tools/下新增“Schema 文件 工具定义文件”并在__init__.py中追加一条注册项服务器端代码完全不需要改动——这正是该架构可扩展性的核心。五、客户端视角stdio 传输与调用链验证client.py 演示了 MCP 客户端通过 stdio 传输与本示例服务器的完整交互流程共三步构建服务器启动参数StdioServerParameters(commandpython, args[server.py])指明以python server.py子进程方式启动服务器建立会话并初始化stdio_client(server_params)打开双向标准流ClientSession(read, write)建立会话随后await session.initialize()完成 MCP 握手依次调用协议方法session.list_tools()获取工具清单并打印名称session.call_tool(add, {a: 5, b: 3})调用 add 工具并打印结果对象。从打印出的Result对象可以看出MCP 的工具调用返回值是一个包含content、meta、structuredContent、isError等字段的结构化结果isErrorFalse表明调用成功content[TextContent(...)]中承载服务器返回的文本内容。客户端入口通过asyncio.run(run())驱动异步流程见 client.py。六、从示例到架构为什么选用低层 Server示例背后对应章节 03-GettingStarted/10-advanced/README.md 对“常规 Server vs 低层 Server”做了系统对比常规 ServerPython 的FastMCP、TypeScript 的McpServer通过mcp.tool()/registerTool逐个注册特性而低层 Server 则“每个特性类型只写两个处理器”——一个负责list列出全部特性、一个负责call分发调用请求。本示例正是该理念的落地在 server.py 中无论将来注册多少个工具服务器侧代码体量保持不变新增工具的工作全部收敛到tools/目录内。章节 README 还给出了一种可直接推广的目录组织方式app --| tools --| resources --| prompts并指出低层 Server 的另一个优势在于可访问某些高级特性例如课程后续章节如 Sampling、Elicitation 相关能力只有在低层 Server 上才可用其中 Sampling 已在 MCP 协议版本2026-07-28中标记为 legacy/废弃特性。此外原文档在 03-GettingStarted/10-advanced/README.md 中还布置了扩展练习Assignment在给定代码基础上继续增加工具、资源和提示词并体会“只需要在tools/目录中新增文件、无需改动其他位置”的架构优势该练习未提供官方答案。读者可以参照本示例的add工具模式在tools/下复制出subtract.py、multiply.py等新工具并更新__init__.py注册表即可直观验证这一结论。七、小结一条完整的验证闭环从 translations/bg/03-GettingStarted/10-advanced/code/python/README.md或英文原文 03-GettingStarted/10-advanced/code/python/README.md出发本示例形成了“环境搭建 → 依赖安装 → 一键运行 → 输出验证”的完整闭环且每一步都有仓库源码作为事实依据环节命令/文件关键结论环境隔离python -m venv venv source ./venv/bin/activate独立运行 MCP SDK依赖安装pip install mcp[cli]官方 Python SDK 及其 CLI extra服务器server.pylist_tools/call_tool双处理器 stdio 启动工具定义tools/add.py名称/描述/Schema/处理器四要素字典输入校验tools/schema.pyPydanticAddInputModel(a, b)客户端client.pyinitialize → list_tools → call_tool预期输出Available tools: [add]/text8.0验证工具列表与调用结果均正确按此步骤在本地依次执行三条命令即可复现完整的 MCP 低层 Server 端到端交互再结合本节源码逐行阅读就能透彻理解“两个处理器驱动任意工具”这一低层 Server 架构设计的精髓。赞分享教程文档人工智能【免费下载链接】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 实战用 TypeScript 低级服务器构建可验证的 MCP 工具并借助 MCP Inspector 完成端到端测试mcp for beginners 实战用 TypeScript 低级服务器构建可验证的 MCP 工具并借助 MCP Inspector 完成端到端测试 本教程文档人工智能mcp-for-beginners 进阶指南用 MCP 低层服务器Low-Level Server打造可扩展、可验证的工具架构mcp for beginners 进阶指南用 MCP 低层服务器Low Level Server打造可扩展、可验证的工具架构 本篇文章是 mcp for教程文档人工智能mcp-for-beginners 实战运行并理解基于低层服务器的 Python MCP 示例mcp for beginners 实战运行并理解基于低层服务器的 Python MCP 示例 导读 本文以 mcp for beginners 课程第 10教程文档人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考