python-sdk 快速上手用 MCP Server 三步写出第一个工具、资源与提示词【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk本文以官方 Python SDKModel Context Protocol SDK的 First Steps 指南为主线带你在最短时间内理解 MCP 的三种核心原语工具、资源、提示词以及 HOST/Client/Server 三角色模型并用一段可运行的server.py配合 MCP Inspector 与官方Client完成全流程实测。读完本文你将掌握如何用三个装饰器注册三种能力、如何用mcp dev调试服务器、如何查看服务器声明的 capabilities以及理解你什么都没写协议却全跑通了这一 SDK 设计哲学背后的源码依据。开场三个贯穿全文档的名词——HOST、Client、Server从这一页开始MCP 文档里每一页都会出现三个词它们界定了 MCP 架构中的三个角色HOST宿主LLM 应用程序例如 Claude、IDE、Agent 运行时环境。它是用户直接对话的对象用户消息先进入 HOST。Client客户端存活在 HOST 内部、负责说 MCP方言的那一半。HOST 每连接一个服务器就运行一个对应的 Client。Server服务器用本 SDK 构建的东西向 Client 暴露各种能力。Server 永远不会直接与模型对话一切交互都经由 Client。你需要编写的是 Server。HOST 是别人的产品而 SDK 同时为你提供了一个Client——这正是 HOST 用来按 URL 连接服务器、或把服务器当作子进程拉起的那个类。Client在本页稍后出现它同时也是你日后测试自己服务器的工具。从源码看SDK 的两半有着明确的导入路径划分src/mcp/__init__.py在包顶层导出Client、ClientSession、stdio_client等客户端设施而MCPServer则位于mcp.server子包。这一点对应文档中的关键提醒不存在from mcp import MCPServer正确写法是from mcp.server import MCPServer。三种原语谁决定使用它谁就是区分点一个 MCP 服务器恰好只能暴露三种东西。它们之间真正的分水岭是——谁决定使用它们原语由谁控制它是什么示例工具Tools模型模型为了采取行动而调用的函数一次 API 调用、一次数据库写入资源Resources应用程序HOST 加载进模型上下文的数据文件内容、API 响应提示词Prompts用户可复用的消息模板用户按名称调用一条斜杠命令、一个菜单项由谁控制是整个区分的核心工具之所以执行是因为模型决定调用它资源之所以被附加是因为应用程序判断模型需要它提示词之所以运行是因为用户选择了它。如果你构建过 Web API你其实已经掌握了大部分直觉资源相当于一次GET加载数据、不改动任何状态工具相当于一次POST做实际工作、可能有副作用而提示词没有 HTTP 对应物——它更接近一条用户按名称执行的已保存的查询。一个服务器三种能力兼得三个装饰器即全部注册下面是本页的核心示例完整代码位于 docs_src/first_steps/tutorial001.pyfrom mcp.server import MCPServer mcp MCPServer(Demo) mcp.tool() def add(a: int, b: int) - int: Add two numbers. return a b mcp.resource(greeting://{name}) def greeting(name: str) - str: Greet someone by name. return fHello, {name}! mcp.prompt() def summarize(text: str) - str: Summarize a piece of text in one sentence. return fSummarize the following text in one sentence:\n\n{text}三个普普通通的函数三个装饰器每个装饰器本身就是一次完整的注册mcp.tool()把add变成一个工具mcp.resource(greeting://{name})把greeting变成一个资源模板resource templateURI 里的{name}就是函数参数mcp.prompt()把summarize变成一个提示词它返回的字符串将成为一条用户消息。其余的一切——名称、描述、参数 schema——SDK 全部从函数自身读取函数名、docstring、类型注解。你不需要在任何地方单独声明它们。源码视角装饰器背后发生了什么从 src/mcp/server/mcpserver/server.py 的MCPServer.__init__可以看到每个实例内部持有三个管理器ToolManager、ResourceManager、PromptManager并把这些注册表桥接到底层协议服务器Server的处理器上on_list_tools、on_call_tool、on_list_resources、on_read_resource、on_list_resource_templates、on_list_prompts、on_get_prompt等回调见 server.py。也就是说你的 Python 函数与 JSON-RPC 方法如tools/call、resources/read、prompts/get之间的映射在构造时就已全部接好。具体到mcp.tool()装饰器server.py它支持name、title、description、annotations、icons、meta、structured_output等可选参数不给名称时默认取函数名。注册路径为add_tool→Tool.from_functionsrc/mcp/server/mcpserver/tools/base.py参数 schema 的生成则依赖 src/mcp/server/mcpserver/utilities/func_metadata.py 中对类型注解的反射分析——这正是a: int, b: int就是add的 JSON Schema这句话的代码级含义。mcp.resource()装饰器server.py还有一个值得注意的设计模板还是静态资源完全由 URI 决定。URI 中出现{...}变量即注册为模板资源并要求 URI 变量与函数参数一一对应若 URI 无变量而函数声明了参数会在装饰时直接抛出ValueError。此外{?...}/{...}形式的查询参数在协议上可被客户端省略因此绑定到它们的函数参数必须声明默认值否则装饰阶段就会报错。试运行MCP Inspector 逐项验证用 MCP Inspector 启动这个服务器uv run mcp dev server.py打开命令输出的 URL。Inspector 为每种原语各提供一个标签页按顺序逐个体验Tools工具列表里只有一个条目add描述为Add two numbers.。表单包含两个必填的整数字段a和b。填入 1 和 2 发起调用返回结果是3。这个表单是 Inspector 从a: int, b: int自动构建出来的——其他所有客户端也都会这么做。Resources资源Resources列表是空的。greeting出现在Resource Templates之下因为greeting://{name}带有一个参数在有人提供name之前不存在任何可列出的具体资源。给它填上World并读取Hello, World!Prompts提示词列表里有一个summarize带一个必填参数text。填入一段文本获取结果你会收到一条role: user、内容为渲染后字符串的消息。提示词不过如此一个用来构建消息的函数。Inspector 通过stdio运行了你的服务器——这是 MCP 服务器可以说的传输协议之一。你现在还不需要选择它详见 docs/run/index.md运行你的服务器。Capabilities服务器如何告诉客户端我能做什么你在 Inspector 里看到了三个标签页。它是怎么知道该显示三个的客户端连接时服务器会声明自己的能力capabilities它将要应答哪些请求族。客户端依据这份声明决定自己可以提出哪些请求。你从未手写过这份声明——MCPServer替你声明好了。自己动手验证。在一个终端里让server.py以 HTTP 方式运行uv run mcp run server.py --transport streamable-http在另一个终端里用一个客户端指向它import anyio from mcp import Client async def main() - None: async with Client(http://localhost:8000/mcp) as client: print(client.server_capabilities.model_dump(exclude_noneTrue)) if __name__ __main__: anyio.run(main)完整代码见 docs_src/first_steps/tutorial001_client.py。运行python client.py输出{prompts: {list_changed: True}, resources: {subscribe: True, list_changed: True}, tools: {list_changed: True}}这个字典就是你的服务器已声明的能力。它是每个连接的客户端学到的第一件事能力客户端此后可以调用toolstools/list、tools/callresourcesresources/list、resources/templates/list、resources/readpromptsprompts/list、prompts/getMCPServer为三种原语都提供了服务因此三者总是被声明。注意看字典里没有什么completions资源模板与提示词参数的自动补全需要一个由你编写的处理器这个服务器没有注册于是该能力缺失守规矩的客户端便不会发起相关请求。这是所有可选能力遵循的规则注册了它能力就出现docs/servers/completions.md 就是证明。从源码看这套声明—响应链路是自动接通的MCPServer在构造时就把_handle_list_tools、_handle_call_tool、_handle_list_resources、_handle_read_resource、_handle_list_resource_templates、_handle_list_prompts、_handle_get_prompt全部绑定到底层Serverserver.py即使没有注册任何东西这些方法族依然可用。仓库中的测试 tests/docs_src/test_first_steps.py 精确断言了这份能力字典甚至用一个空服务器MCPServer(Empty)验证了三种能力始终声明这一行为。顺便一提这个client.py是一个完整的 MCP 客户端它的完整文档在 docs/client/index.md。而在测试场景中你无需终端和端口直接把服务器对象交给Client即可Client(mcp)。这也有一整页文档docs/get-started/testing.md。你什么都没写SDK 为你代劳的四件事回头通读这一页。你只写了三个小 Python 函数但没有写JSON Schemaa: int, b: int就是add的 schema。类型注解在注册时被反射为 JSON Schema见 src/mcp/server/mcpserver/utilities/func_metadata.py并在tools/list等方法的响应中原样返回server.py。请求处理器tools/list、resources/read、prompts/get全部替你服务好了。能力声明MCPServer替你完成了。一行协议代码版本协商、JSON-RPC 封装、能力交换——这一切都发生在mcp dev和client.py内部你全程看不见。这个产出比正是整个 SDK 的意义所在。小结与下一步HOST是 LLM 应用Client是它当中说 MCP 的那一半Server是你要构建的东西。工具由模型控制资源由应用程序控制提示词由用户控制。每种原语一个装饰器mcp.tool()、mcp.resource(uri)、mcp.prompt()。名称、描述、schema 全部来自函数本身。带{param}的 URI 生成资源模板它与具体资源分开列出。服务器的能力由 SDK 替你声明客户端只会请求服务器声明过的东西。Client(http://localhost:8000/mcp)连接运行中的服务器改传服务器对象Client(mcp)它从第一天起就是你的测试台。接下来的路线先看 docs/get-started/real-host.md连接真实 HOST把这个服务器真正放进 Claude Desktop 或 IDE然后是 docs/get-started/testing.md一页文档、一个内存客户端从此不再靠猜验证功能之后每种原语各有专属页面从模型驱动的那一个开始docs/servers/tools.md。【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考