Software 2.0

MCP 版本 2

admin -

MCP 正在从 Python SDK 版本 1 迁移到版本 2。此次升级引入了重大变更,每位 AI 和 MCP 开发者都需要了解。在本文中,我将介绍 FastMcp 在 V2 中已被移除,取而代之的是 McpServer

虽然 v2 目前在主分支上处于预 alpha 开发阶段(预计将在 2026 年第一季度发布稳定版本),但现在提前了解这些重大变更,将为您日后避免大量重构工作。

我们将完整演示构建 MCP 服务器的过程,并考虑从 v1 到 v2 的迁移,特别关注 FastMcp 的替代方案。

官方 GitHub 迁移指南详细说明了 MCP Python SDK 从 v1 到 v2 的转变。

1、主题概述

我们正在探索 MCP Python SDK v2 的预 alpha 版本,重点关注将流行的 FastMCP 类替换为新的 McpServer 类。

这只是作为示例引导开发者了解此次迁移的一个变更。此次迁移还包括其他几项变更!

为了演示这一点,我们将构建一个终端服务器,允许 Claude Desktop 在指定的本地工作区内安全地执行 shell 命令。

2、基础知识快速回顾

如果您是模型上下文协议(Model Context Protocol)的新手,以下是它如何运作的快速说明:

  • MCP 定义: 一个开源协议,用于标准化 AI 模型访问上下文和与工具的交互方式。
  • 架构: 它依赖于 MCP 客户端(如 Claude Desktop)和 MCP 服务器(承载您的工具/数据的自定义代码)。
  • 传输方式: 通过特定的传输方式进行通信。stdio 用于本地命令行集成,而 SSE/HTTP 用于远程、云端托管的服务器。
  • 模块化: 一旦构建了 MCP 服务器,就可以在不同的 AI 应用程序中轻松复用,而无需重写集成逻辑。

3、主题概览

理解 MCP v2 转换的最佳方式是直接查看代码并使用它进行构建。我们将把内容分解为:

  • 示例变更:再见 FastMCP
  • 生成终端服务器代码
  • 集成到 Claude Desktop
  • 测试本地执行

4、再见 FastMCP

如果您最近构建过 MCP 服务器,您可能依赖 FastMCP 来快速启动服务器和工具。然而,根据官方模型上下文协议 GitHub 迁移指南,FastMCP 在版本 2 中已被完全移除。

为了更好地反映其作为 SDK 中主要服务器类的角色,它已被重构并简单地重命名为 McpServer。在功能上,该类的行为类似,但初始化服务器和注册工具的语法已转变为更明确、面向对象的方式。

5、生成终端服务器代码

为了加速我们的开发,我们可以利用 AI 辅助的 MCP 构建器工具(https://theailanguage.com/builder)。通过提供描述我们目标的简单提示——构建一个使用 stdio 传输的基于 Python 的 MCP 服务器,在工作区内安全地执行终端命令——构建器会生成我们的整个项目结构。

使用 MCP 构建器中的 AI 助手生成符合 v2 的终端服务器代码库。

生成的目录结构包括我们的工作区文件夹(作为沙箱,防止 AI 意外删除关键系统文件)、主要执行文件(main.py 和 tools.py)以及 claude_desktop_config.json 的模板。

注意,服务器仍可以在工作区目录之外执行命令,因此您需要小心。请仅将其作为教育代码使用!

6、理解 v2 McpServer 变更

让我们看看新的 MCPServer 类如何改变我们的实现。

在我们的 main.py 文件中,我们不再导入 FastMCP。相反,我们从 mcp.server.mcpserver 导入 MCPServer。

新的设置过程清晰而明确:

  1. 初始化: 我们使用 server = MCPServer("TerminalServer") 定义服务器。
  2. 注册工具: 不再使用散布在代码中的装饰器,而是使用 server.add_tool(execute_command) 显式添加我们的工具。
  3. 运行: 我们通过指定传输层来启动服务器:server.run(transport='stdio')。

在我们的 tools.py 文件中,execute_command 逻辑利用 Python 的 subprocess.run 来执行 shell 命令。因为让 AI 直接访问您的终端是非常危险的,所以代码使用了一个 local/workspace 文件夹。它还包括超时设置,并捕获 stdout 和 stderr,以便将终端输出反馈回 LLM。

7、集成到 Claude Desktop

当我们的代码通过 GitHub 生成并推送到本地机器后,我们需要将其连接到 Claude Desktop。由于我们使用的是 stdio 传输,Claude 需要确切知道我们的 Python 可执行文件在哪里,以及我们的 main.py 脚本位于何处。

为此,我们编辑 claude_desktop_config.json 文件。我们定义一个 mcpServers 对象,将其命名为 terminal-server,并指定命令(Mac/Linux 为 python3)。关键在于,在 args 数组中,我们提供 main.py 文件的绝对路径。

8、测试本地执行

保存配置后,我们必须完全退出并重新启动 Claude Desktop(使用顶部菜单栏,而不仅仅是关闭窗口)来初始化新的服务器连接。

重新启动后,点击 Claude Desktop 中的"加号"图标会显示我们的新 Terminal-server 处于活动状态。我们现在可以使用以下提示进行测试: "创建一个文件 MCP success.TXT,并向其中添加内容:'我使用协议版本 2 通过 STDIO 传输创建了我的第一个 MCP 服务器。'"

我们要求 Claude 使用我们的服务器,因为它也可以使用自己的内置功能执行相同的操作。Claude 分析请求,触发 execute_command 工具,制定正确的 shell 命令(一个通过管道传输到文本文件的 echo 命令),并执行它。检查工作区文件夹内的本地 Visual Studio Code 环境,证明集成成功:文件已完美生成。

9、结束语

虽然 v2 目前在主分支上处于预 alpha 开发阶段(预计将在 2026 年第一季度发布稳定版本),但现在提前了解这些重大变更,将为您日后避免大量重构工作。

原文链接: MCP is Migrating from Version 1 to Version 2

汇智网翻译整理,转载请标明出处