如果你正在开发或使用 AI Agent最近一定被各种“插件”和“工具”搞得头大ChatGPT 有它的插件商店Claude 有它的自定义工具Midjourney 有它的参数体系而你想让一个 Agent 去操作数据库、调用 API、读取文件往往需要为每个平台写一套适配代码。这就像给每个品牌的手机都配一个专属充电器混乱且低效。更关键的是当你想把一个在 ChatGPT 上运行良好的“数据分析 Agent”迁移到 Claude 或本地部署的模型上时你会发现核心逻辑没变但插件接口全得重写。这种“重复造轮子”和“平台锁定”的问题正在严重拖慢 AI 应用的开发和迭代速度。今天要讨论的Agent Plugins 1.0.0正是为了解决这个核心痛点而来。它不是一个具体的 AI 模型或某个公司的产品而是一个由谷歌、亚马逊、微软、英特尔、AMD、Anthropic 等巨头共同支持的开源规范。它的目标很简单为 AI Agent 定义一套统一的“工具”或“插件”接口标准。我的核心判断是Agent Plugins 1.0.0 的发布其意义远超一个技术规范的更新。它标志着 AI 应用开发从“各家自扫门前雪”的封闭生态开始向“标准件、可组装”的工业化阶段迈进。对于开发者而言这意味着未来为 Agent 开发一个“读数据库”的能力可以像写一个遵循 RESTful 规范的 API 一样一次开发处处运行。本文将带你深入理解 Agent Plugins 规范其核心实现之一是 MCP即 Model Context Protocol并通过一个从零开始的完整示例展示如何将一个本地 Python 函数封装成一个符合规范的插件并让不同的 AI 助手如 Claude Desktop安全、稳定地调用它。你会发现统一标准带来的不仅是便利更是架构思维的转变。1. 这篇文章真正要解决的问题告别“碎片化”的 Agent 工具开发在深入技术细节之前我们必须先厘清当前 AI Agent 工具生态的混乱现状以及 Agent Plugins 要解决的具体问题。问题一平台绑定与适配成本高。假设你为 OpenAI 的 GPTs 开发了一个“天气查询工具”。这个工具的逻辑是接收城市名调用某个天气 API返回结果。当你想在 Anthropic 的 Claude 上使用同样的功能时你需要重新学习 Claude 的 Tool Use 或 Function Calling 的格式。按照 Claude 的 SDK 或 API 要求重写工具的定义和调用逻辑。重新处理可能的认证、错误返回格式差异。 这个过程不仅重复而且当工具数量增多时维护成本呈指数级上升。问题二开发与使用体验割裂。工具开发者需要关心如何定义工具名称、描述、参数 schema、如何暴露工具HTTP 服务、进程间通信、如何处理安全认证、权限。工具使用者AI 模型或另一个 Agent则需要关心如何发现工具、如何理解工具、如何调用工具。在没有标准的情况下每一对“开发者-使用者”都需要建立一套独有的通信协议如同鸡同鸭讲。问题三安全与权限控制薄弱。很多现有的 Agent 工具实现是“全有或全无”的。一旦 Agent 获得了调用某个工具的权限它就能执行该工具的所有操作缺乏细粒度的控制例如只能读数据库的 A 表不能写 B 表。这给生产环境部署带来了巨大风险。Agent Plugins 的定位就是成为这个领域的“USB 标准”或“RESTful API 规范”。它定义了工具的描述语言一个工具叫什么、能干什么、需要什么参数都用一种统一的 JSON Schema 来描述。标准的通信协议工具提供者Server和工具消费者Client通常是 AI 模型运行时之间如何建立连接、交换数据。这就是 MCPModel Context Protocol的核心作用。资源与权限模型除了工具Tools它还定义了资源Resources如文件、数据库连接和提示词模板Prompts并可以围绕它们构建权限体系。接下来我们将从概念入手逐步拆解这个规范并最终落地到一个可运行的代码示例。2. 基础概念与核心原理MCP 与 Agent Plugins 是什么关系这里有一个非常重要的概念需要澄清也是很多讨论中容易混淆的点Agent Plugins 是规范MCP 是该规范的一种具体实现和传输协议。你可以这样理解Agent Plugins是一份设计图纸定义了插件应该有哪些组成部分工具、资源、提示词以及它们的长相和接口JSON Schema。MCP (Model Context Protocol)是按照这份图纸建造房子时使用的“水电管线标准”和“建筑工艺”。它具体规定了工具提供方Server和 AI 模型Client之间如何通过标准化的消息JSON-RPC over stdio/SSE/其他传输层进行通信。目前MCP 是实现 Agent Plugins 规范最主流、最受支持的协议。因此在实践层面当我们说“开发一个 Agent Plugin”时通常就是指“开发一个 MCP Server”。核心组件解析一个符合 Agent Plugins 规范的 MCP Server 主要提供三类内容工具 (Tools)这是最核心的部分。一个工具就是一个 AI 可以调用的函数。例如search_web搜索网页、execute_sql执行 SQL、send_email发送邮件。每个工具必须有明确的名称、描述和输入参数的模式定义。资源 (Resources)代表 AI 可以读取或引用的静态或动态内容。例如一个file:///path/to/doc.md资源代表一个文件一个db://sales/customers资源可能代表数据库中的客户表。AI 可以通过“读取”资源来获取上下文信息而无需直接调用工具。提示词 (Prompts)预定义的、参数化的提示词模板。AI 可以获取这些模板并填入具体参数来使用这有助于标准化和复用复杂的提示逻辑。通信流程简述初始化MCP Client如 Claude Desktop、一个自定义的 AI 应用启动并配置了要连接的 MCP Server如一个本地运行的“数据库工具”服务器。握手与列表Client 与 Server 建立连接通常通过标准输入输出 stdio。Server 向 Client 宣告自己提供了哪些工具、资源和提示词。调用当用户向 AI 提出需求如“帮我查一下上个月的销售额”AI 模型根据对话内容决定调用哪个工具如execute_sql。Client 会向 Server 发送一个格式化的调用请求。执行与返回Server 收到请求执行对应的函数如连接数据库执行查询然后将结果返回给 Client。展示Client 将结果提供给 AI 模型AI 模型生成最终的回答给用户。这个流程的关键在于标准化。只要 Server 和 Client 都遵循 MCP 协议无论底层是 Python、Node.js 还是 Rust 写的无论 AI 模型是 Claude、GPT 还是本地部署的 Llama它们都能无缝协作。3. 环境准备与前置条件在开始动手之前我们需要准备好开发环境。本文将使用 Python 作为开发语言因为它有成熟的 MCP SDK 且易于理解。我们的目标是将一个简单的本地函数包装成 MCP Server并用 Claude Desktop一个内置了 MCP Client 的流行应用进行测试。基础环境操作系统macOS、Linux 或 Windows (WSL2 推荐)。本文命令以 macOS/Linux 为例。Python版本 3.10 或以上。确保python3和pip命令可用。包管理工具pip。代码编辑器VS Code、PyCharm 等均可。核心依赖库我们将使用 Anthropic 官方维护的mcpPython 库来简化开发。这是一个高阶 SDK隐藏了 MCP 协议底层 JSON-RPC 的细节让开发者可以像写普通 Python 函数一样创建工具。安装 Claude Desktop (用于测试)这是体验 MCP 最快捷的方式。从 Anthropic 官网下载并安装 Claude Desktop 应用。它内置了 MCP Client 支持可以直接配置本地 MCP Server。4. 核心流程拆解五步构建你的第一个 MCP 插件让我们从一个最简单的场景开始创建一个提供“计算器”功能的 MCP Server。AI 可以通过它进行基本的数学运算。通过这个例子你将清晰掌握开发一个完整插件的全流程。步骤概览创建项目与安装依赖初始化 Python 环境安装mcp库。编写工具函数用 Python 实现核心逻辑如加法、乘法。创建 MCP Server 并注册工具使用mcpSDK 将函数包装成标准工具。运行与调试 Server以独立进程方式启动 Server检查其是否正常宣告工具。配置 Claude Desktop 进行集成测试修改 Claude Desktop 配置连接我们开发的 Server并在聊天中实际调用。每一步我们都会解释“为什么这么做”以及“关键点是什么”。5. 完整示例与代码实现现在我们开始编写代码。请跟随步骤逐一操作。5.1 步骤一初始化项目打开终端创建一个新的项目目录并进入。mkdir my-first-mcp-server cd my-first-mcp-server创建一个 Python 虚拟环境以隔离依赖强烈推荐。python3 -m venv venv激活虚拟环境。在 macOS/Linux 上source venv/bin/activate在 Windows (CMD) 上.\venv\Scripts\activate安装mcp库。这是我们的核心 SDK。pip install mcp5.2 步骤二编写核心工具函数在项目根目录下创建一个名为server.py的文件。我们将在这里编写所有代码。首先导入必要的模块。mcp库提供了创建 Server 和定义工具的所有类。# server.py import mcp import asyncio from typing import Any接下来实现我们的“计算器”工具函数。为了展示 MCP 处理复杂参数的能力我们创建一个能执行多种运算的函数。# server.py (续) async def calculate( operation: str, a: float, b: float, precision: int 2 ) - str: 执行一个基础的数学运算。 Args: operation: 运算类型必须是 add, subtract, multiply, divide 中的一个。 a: 第一个运算数。 b: 第二个运算数。 precision: 结果保留的小数位数默认为2。 Returns: 格式化的运算结果字符串。 result None if operation add: result a b elif operation subtract: result a - b elif operation multiply: result a * b elif operation divide: if b 0: return 错误除数不能为零。 result a / b else: return f错误不支持的运算类型 {operation}。支持的运算有add, subtract, multiply, divide。 # 格式化结果保留指定小数位 formatted_result f{result:.{precision}f} return f{a} {operation} {b} {formatted_result}关键点解析我们使用了async def定义异步函数。MCP 协议基于异步 I/O以支持高并发。函数有清晰的文档字符串docstring。这部分极其重要AI 模型Client正是通过解析这些描述来理解工具功能的。描述应准确、简洁。参数有明确的类型注解str,float,int。MCP SDK 会利用这些信息自动生成标准的 JSON Schema。函数内部包含了简单的错误处理除零错误、非法操作类型。5.3 步骤三创建 MCP Server 并注册工具现在我们需要创建一个 MCP Server 实例并将上面的calculate函数注册为一个可供 AI 调用的“工具”。在server.py文件的末尾添加以下代码# server.py (续) # 创建 Server 实例 server mcp.Server(calculator-server) # 将 calculate 函数注册为一个工具 # mcp.Tool 装饰器会提取函数的签名和文档字符串来自动生成工具定义 server.list_tools() async def list_tools() - list[mcp.Tool]: # 这里我们手动定义工具以展示更全面的控制能力 return [ mcp.Tool( namecalculate, description执行基础数学运算加、减、乘、除。, inputSchema{ type: object, properties: { operation: { type: string, description: 要执行的运算类型, enum: [add, subtract, multiply, divide] }, a: { type: number, description: 第一个运算数 }, b: { type: number, description: 第二个运算数 }, precision: { type: integer, description: 结果保留的小数位数, default: 2 } }, required: [operation, a, b] } ) ] server.call_tool() async def call_tool(name: str, arguments: dict[str, Any]) - list[mcp.TextContent]: # 根据工具名路由到对应的处理函数 if name calculate: # 从 arguments 字典中提取参数 op arguments.get(operation) a_val arguments.get(a) b_val arguments.get(b) precision_val arguments.get(precision, 2) # 提供默认值 # 调用真正的计算函数 result_text await calculate(op, a_val, b_val, precision_val) # 返回结果必须包装在 mcp.TextContent 列表中 return [mcp.TextContent(typetext, textresult_text)] else: raise ValueError(f未知的工具: {name}) # 主函数启动 Server async def main(): # 使用 stdio 传输层这是与 Claude Desktop 等客户端通信的最简单方式 async with mcp.stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream) if __name__ __main__: asyncio.run(main())代码深度解读mcp.Server(“calculator-server”)初始化一个 Server并给它一个名字。server.list_tools()这是一个“资源声明”函数。当 Client 连接时会首先调用这个函数获取 Server 提供的所有工具列表。我们返回了一个mcp.Tool对象的列表。mcp.Tool对象这是工具的核心定义。我们手动构建了它的inputSchema。这个 JSON Schema 定义了 AI 调用工具时必须提供的参数及其类型、描述、枚举值、默认值等。enum字段特别有用它限定了operation只能取四个值极大地提高了 AI 调用的准确性。server.call_tool()这是工具调用的路由函数。当 AI 决定调用某个工具时Client 会发送请求到这里。函数参数name指定了要调用的工具名arguments是一个字典包含了 AI 根据 Schema 填充的参数值。我们在这里根据name将请求分发给具体的处理函数本例中是calculate。返回值格式call_tool必须返回一个list[mcp.TextContent]。这是协议规定的格式即使只返回一段文本也需要放在列表中。传输层mcp.stdio_server()这行代码设置了 Server 使用标准输入输出stdio作为通信通道。这是与桌面端应用如 Claude Desktop集成的最常用方式无需处理复杂的网络端口。异步运行整个 Server 是异步的使用asyncio.run(main())启动事件循环。5.4 步骤四运行与调试 Server保存server.py文件。在终端中确保虚拟环境已激活运行以下命令启动 Serverpython server.py如果一切正常你将看不到任何输出程序会挂起等待来自 stdio 的客户端连接。这是一个正常状态说明 Server 已成功启动并在监听。如何验证 Server 是否健康我们可以使用 MCP 官方提供的 CLI 工具mcp来进行测试。首先安装 CLI 工具在另一个终端窗口操作pip install ‘mcp[cli]’安装后使用mcp inspect命令来“探查”我们刚刚启动的 Server。这个命令会模拟一个 Client连接到 Server并列出其提供的所有工具。# 假设 server.py 正在运行 # 在另一个终端执行 python -m mcp inspect python server.py关键点mcp inspect后面的python server.py是一个命令CLI 会启动这个命令对应的进程并将其 stdio 作为通信通道。这与 Claude Desktop 的工作方式一致。如果成功你将看到类似如下的输出Inspecting server started by: python server.py Tools (1): - calculate: 执行基础数学运算加、减、乘、除。 Resources (0): Prompts (0):这证明我们的 MCP Server 运行成功并正确宣告了一个名为calculate的工具。你可以按CtrlC停止inspect命令和server.py。6. 运行结果与效果验证在 Claude Desktop 中实际调用纸上得来终觉浅让我们在真实的 AI 助手环境中测试这个插件。6.1 配置 Claude DesktopClaude Desktop 的配置文件通常位于macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件不存在就创建它。用文本编辑器打开这个 JSON 文件添加 MCP Server 的配置。// claude_desktop_config.json { mcpServers: { my-calculator: { command: /absolute/path/to/your/venv/bin/python, args: [/absolute/path/to/your/my-first-mcp-server/server.py], env: { PYTHONPATH: /absolute/path/to/your/my-first-mcp-server } } } }配置详解”my-calculator”给这个 Server 起一个任意名字。”command”Python 解释器的绝对路径。这里必须是虚拟环境中的python以确保依赖可用。你可以通过which python在激活的虚拟环境中命令获取。”args”一个列表第一个元素是我们 Server 脚本的绝对路径。”env”可选可以设置环境变量PYTHONPATH确保脚本能正确导入本地模块。重要提醒路径中的/absolute/path/to/your/必须替换为你电脑上的真实路径。例如/Users/yourname/Projects/my-first-mcp-server/venv/bin/python。保存配置文件。6.2 重启 Claude Desktop 并测试完全退出 Claude Desktop 应用然后重新启动。重启后配置才会生效。现在打开 Claude Desktop新建一个对话。你可以直接向 Claude 提问例如“请使用计算器工具计算 123.45 乘以 678.9结果保留 3 位小数。”如果配置正确Claude 会识别到可用的calculate工具并在后台调用它。你会在它的回复中看到类似这样的过程Claude 的思考过程可能不会直接显示取决于界面“用户需要做乘法计算。我有一个可用的工具叫calculate。我需要用operation“multiply”,a123.45,b678.9,precision3的参数来调用它。”Claude 的回复“我调用计算器工具计算了一下。 123.45 multiply 678.9 83810.205”恭喜这意味着你的第一个 MCP 插件已经成功在 Claude Desktop 中运行。AI 助手现在拥有了一个你自定义的、安全受控的数学计算能力。7. 常见问题与排查思路在开发和集成过程中你可能会遇到一些问题。下表列出了常见问题及其解决方法。问题现象可能原因排查方式解决方案运行python server.py后立即报错或退出1. Python 依赖未安装。2. 代码语法错误。3. 虚拟环境未激活。1. 检查终端是否有ModuleNotFoundError。2. 使用python -m py_compile server.py检查语法。3. 确认终端提示符前有(venv)字样。1. 在激活的虚拟环境中运行pip install mcp。2. 根据错误信息修正代码。3. 运行source venv/bin/activate(Linux/macOS) 或.\venv\Scripts\activate(Windows)。mcp inspect命令失败提示连接错误或超时1. Server 脚本未正常启动或崩溃。2.mcp inspect命令拼写错误。3. Server 代码中传输层设置错误。1. 单独运行python server.py看是否挂起。2. 检查是否安装了mcp[cli]。3. 检查server.py中是否使用了async with mcp.stdio_server()...。1. 修复 Server 代码中的错误确保它能持续运行。2. 确保命令为python -m mcp inspect python server.py。3. 确保代码结构与示例一致。Claude Desktop 重启后看不到新工具1. 配置文件路径错误。2. 配置文件格式错误JSON 语法。3. Claude Desktop 未完全重启。4. Server 命令路径错误。1. 确认配置文件在正确目录且名称正确。2. 使用 JSON 验证器如jq或在线工具检查配置文件。3. 在活动监视器中强制结束 Claude Desktop 进程后再启动。4. 检查command和args中的路径是否绝对、有效。1. 严格按照上文路径放置文件。2. 修正 JSON 格式确保引号、逗号正确。3. 彻底重启应用。4. 使用绝对路径并确保虚拟环境 Python 可执行。Claude 能识别工具但调用失败1. Server 端call_tool函数逻辑有误。2. 参数类型不匹配。3. Server 进程意外终止。1. 查看 Claude Desktop 是否有错误提示有时在界面角落。2. 在 Server 代码中添加日志打印print(arguments, filesys.stderr)。3. 检查终端中运行的server.py是否有错误输出。1. 调试call_tool函数确保参数提取和函数调用正确。2. 确保arguments中的类型与inputSchema和函数参数匹配。3. 确保 Server 代码有健壮的错误处理不会因异常崩溃。工具调用结果不符合预期1. 工具函数内部逻辑错误。2. AI 误解了工具描述传入了错误参数。1. 在工具函数内添加打印语句调试。2. 检查 Claude 调用工具时生成的参数部分客户端会显示。1. 单元测试你的工具函数。2. 优化工具的description和参数的description使其更清晰无歧义。使用enum严格限制取值范围。8. 最佳实践与工程建议当你掌握了基础开发流程后以下建议能帮助你构建更健壮、更实用的 MCP 插件并融入真实的工程体系。8.1 工具设计原则单一职责一个工具只做一件事。不要设计一个handle_database工具来同时处理查询、插入、更新。应该拆分成query_database、insert_record、update_record等多个工具。这能让 AI 更准确地理解和使用。描述清晰工具和参数的description字段是 AI 理解功能的唯一依据。要用自然语言清晰描述功能、输入输出和边界条件。例如“查询用户信息仅能通过用户ID查询。”就比“查询用户”好得多。利用 Schema 约束尽可能使用 JSON Schema 的强大功能。为字符串参数设置enum枚举值为数字设置minimum/maximum使用pattern定义正则表达式验证。这能前置过滤掉无效请求降低错误率。安全第一永远假设 AI 可能生成恶意或错误的调用参数。在工具函数内部必须进行二次验证和授权检查。例如一个删除文件的工具不仅要验证文件路径参数格式还要检查该路径是否在允许的目录范围内。8.2 项目结构与代码组织对于复杂的插件不建议把所有代码堆在server.py里。my-mcp-plugin/ ├── pyproject.toml # 项目依赖和元数据 ├── src/ │ └── my_plugin/ │ ├── __init__.py │ ├── server.py # MCP Server 主文件 │ ├── tools/ │ │ ├── __init__.py │ │ ├── calculator.py │ │ └── database.py # 其他工具模块 │ └── utils/ │ └── helpers.py # 公共工具函数 ├── configs/ │ └── allowed_paths.json # 配置文件 └── README.md在server.py中可以这样组织# src/my_plugin/server.py import mcp from .tools import calculator, database server mcp.Server(“my-advanced-plugin”) server.list_tools() async def list_tools(): # 从各个模块收集工具定义 tools [] tools.extend(calculator.get_tools()) # 返回一个Tool列表 tools.extend(database.get_tools()) return tools server.call_tool() async def call_tool(name: str, arguments: dict): # 路由到对应的工具处理模块 if name.startswith(“calc_”): return await calculator.handle_tool(name, arguments) elif name.startswith(“db_”): return await database.handle_tool(name, arguments) else: raise ValueError(f“Unknown tool: {name}”)8.3 生产环境部署考量传输层选择stdio适合与桌面应用集成。对于服务端部署应考虑更稳定的传输层如SSE (Server-Sent Events)或WebSocket。mcp库也支持这些。生命周期管理生产环境的 Server 需要作为守护进程运行并具备健康检查、日志记录和监控能力。可以考虑使用systemd(Linux) 或进程管理工具如supervisord、pm2。配置外部化数据库连接字符串、API 密钥、允许操作的路径等敏感或可变配置不应硬编码在代码中。应通过环境变量或配置文件读取。错误处理与日志在call_tool函数和每个工具函数中使用try…except捕获所有异常并返回友好的错误信息给 Client同时将详细错误记录到日志文件或日志系统如structlog中便于排查。8.4 进阶功能探索资源Resources让 AI 能“读取”你的数据。例如可以提供一个file:///reports/daily.md资源AI 在回答关于日报的问题时会自动读取该文件作为上下文。这比让 AI 主动调用“读文件”工具更自然。提示词Prompts将复杂的提示词模板化。例如定义一个名为“code_review”的提示词它接受“code_snippet”和“language”参数。AI 可以直接获取这个模板来执行代码审查保证了审查标准的一致性。动态工具工具列表不是一成不变的。你可以根据配置、权限或系统状态在list_tools函数中动态返回不同的工具集。例如对普通用户只提供查询工具对管理员额外提供管理工具。9. 总结与后续学习方向通过本文的实践你已经掌握了 Agent Plugins (MCP) 规范的核心它通过定义一套标准协议将 AI 的能力工具封装成可插拔、跨平台、安全可控的组件。回顾整个流程其价值链条非常清晰开发者只需用熟悉的语言Python/Node.js/Rust编写业务函数并用 SDK 将其包装成标准工具。协议层 (MCP)负责处理工具发现、调用、数据传输的标准化通信解耦了工具提供方和消费方。AI 客户端 (如 Claude Desktop)无需关心工具的具体实现只需按照协议调用即可无限扩展其能力。这带来的范式转变是巨大的。未来我们可能会看到工具市场像 npm 或 PyPI 一样出现共享 MCP 插件的市场。开发者可以发布一个“股票数据查询”插件所有兼容 MCP 的 AI 应用都能直接使用。专业化 Agent 开发你可以像组装乐高一样将数据库插件、绘图插件、邮件插件组合起来快速构建一个高度定制化的“数据分析与报告 Agent”。企业级集成企业内部系统CRM、ERP、OA可以通过 MCP Server 暴露安全可控的 API让企业级 AI 助手在权限范围内操作业务系统真正成为生产力工具。你的下一步深化尝试开发一个与真实系统交互的插件例如连接 SQLite/MySQL 数据库的查询工具或调用一个公共 REST API 的插件。探索客户端不局限于 Claude Desktop。研究如何在你自己的 Python 或 JavaScript 应用中集成 MCP Client让你自研的 AI 应用也具备调用标准插件的能力。关注生态除了 Anthropic 的mcp库关注社区中其他语言的 SDK如 TypeScript 的modelcontextprotocol/sdk和更多支持 MCP 的客户端如 Cursor IDE、Windsurf 等。统一标准的价值总是在生态繁荣时才真正显现。Agent Plugins 1.0.0 和 MCP 迈出了关键的第一步。作为开发者现在正是深入理解并参与构建这个新生态的最佳时机。从今天这个简单的计算器插件开始去创造能解决实际问题的 AI 能力吧。