协议 on Kalend's Blog

A2A 协议深度解析：为什么说它是 AI Agent 时代的 HTTP

Fri, 12 Jun 2026 08:00:00 +0800

引子：Agent 世界的「巴别塔」

现在的 AI Agent 生态，像极了没有统一语言的巴别塔——LangGraph 说一种方言，CrewAI 说另一种，AutoGen 又是第三种。框架越来越多，Agent 之间却互不相通。

每对 Agent 想要协作，就得写定制胶水代码。5 个 Agent 需要 10 对集成，10 个 Agent 需要 45 对——N² 的复杂度，根本不靠谱。

Google 在 2025 年 4 月 Cloud Next 大会上发布了 A2A（Agent-to-Agent）协议，干的就是这件事：给 Agent 世界定一个统一通信标准。

先说结论：A2A 不是又一个炫技协议，它是 Agent 互联网的基础设施层。就像 HTTP 之于 Web——你不需要每天手写 HTTP 请求，但它无处不在。A2A + MCP 将成为所有多 Agent 系统的标准配置，一个管 Agent 间通信，一个管工具连接。

第一章：为什么需要 A2A？

N² 的集成噩梦只是表象，更深层的问题是：每个框架都在用自己的方式定义「Agent 是什么」「怎么找到另一个 Agent」「任务怎么流转」。

类比互联网早期：每个网络有自己的协议栈，跨网通信需要专门的网关。直到 TCP/IP 一统天下，才有了真正的互联网。A2A 想做的事一模一样——给 Agent 定义一套通用的「TCP/IP」。

A2A 的核心主张很简洁：

Agent 之间不需要暴露内部实现（不共享 memory、不共享 tools）
只需要暴露能力描述和标准接口
任何框架构建的 Agent 都能发现彼此、协商交互方式、协作完成任务

这套思路被 Linux Foundation 采纳，现在以 Apache 2.0 开源在 a2aproject/A2A，GitHub 上已超过 24,000 Stars。

为什么不是 MCP？ 因为 MCP 解决的是 Agent 和工具之间的连接（相当于 USB 接口），而 Agent 之间的协作需要更复杂的状态管理、生命周期控制和协商机制——这些 MCP 的无状态模型做不了。就像 USB 和 HTTP 不矛盾，MCP 和 A2A 也不矛盾。

第二章：三个核心概念

A2A 只围绕三个原语构建，极简但够用。理解这三个概念，就理解了 A2A 的全部设计哲学。

Agent Card——Agent 的 DNS + 名片

每个 A2A Agent 在 /.well-known/agent.json 路径下暴露一个 JSON 文件，描述自己的能力、端点、认证方式。

这东西本质就是 Agent 的 DNS 记录 + 数字名片合体：别人不需要知道你内部怎么实现，看你的 Agent Card 就知道你能干什么、怎么连你。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


{
 "name": "ticket-agent",
 "description": "企业 IT 工单管理智能体",
 "url": "https://ticket.example.com/a2a",
 "capabilities": {
 "streaming": true,
 "pushNotifications": true
 },
 "skills": [
 {
 "name": "create_ticket",
 "description": "创建 IT 工单"
 },
 {
 "name": "query_tickets",
 "description": "查询工单状态"
 }
 ],
 "authentication": {
 "schemes": ["bearer"]
 }
}

v1.0 规范引入了签名 Agent Card——用密码学签名验证域名所有权。别人拿到你的 Agent Card 时，可以验证它确实是你签发的，不是被中间人篡改过的。这对企业级部署尤其重要：你不能让一个伪造的 Agent 冒充你的财务系统。

Agent Card 还有一个很聪明的细节：/.well-known/ 路径。这是 Web 标准的约定（类似 robots.txt），意味着任何 Agent 只要知道对方域名，就能用标准路径发现对方的能力。不需要中心化注册表，纯分布式发现。

Task——协作的基本单位

A2A 用 Task 来组织一次协作交互。Task 有明确的生命周期：

1
2
3


submitted → working → input-required → completed
 → failed
 → canceled

每个 Task 都有唯一 ID、状态历史和消息记录。调用方可以随时查询 Task 状态，不需要一直保持连接。

重点是三种执行模式：

模式	适用场景	特点
同步	简单查询、秒级响应	一问一答，立即返回
异步	数据分析、长耗时任务	提交后轮询或推送通知，支持运行数小时
流式	实时生成、代码编写	SSE 推送中间结果，边算边看

异步模式是生产环境的关键——一个数据清洗 Agent 处理百万行数据，可能跑 30 分钟，A2A 通过 push notification 机制让调用方不用傻等。调用方提交任务后去做别的事，等结果就绪了再回来处理。

还有一个容易忽略的设计：input-required 状态。当被调用的 Agent 需要额外信息才能继续时（比如「请提供数据库连接字符串」），它不会直接 fail，而是切到 input-required 等待调用方补充信息。这让多轮交互变得自然——就像两个人对话时的追问。

Transport——JSON-RPC 2.0 + SSE

传输层选了 JSON-RPC 2.0 over HTTPS，流式场景用 SSE（Server-Sent Events）。

为什么不选 gRPC 或 WebSocket？因为 JSON-RPC 2.0 够简单、够通用、HTTP 原生兼容。A2A 追求的是最大范围采纳，不是追求极致性能——这和 HTTP 当年的设计哲学一致。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# 伪代码：一个 A2A 调用的基本流程
import requests

# 1. 获取对方的 Agent Card
card = requests.get("https://ticket.example.com/.well-known/agent.json").json()

# 2. 发送 Task 请求
response = requests.post(card["url"], json={
 "jsonrpc": "2.0",
 "method": "tasks/send",
 "params": {
 "task": {
 "id": "task-001",
 "message": {
 "role": "user",
 "parts": [{"text": "帮我查一下 REQ12312 的状态"}]
 }
 }
 },
 "id": 1
})

整个交互就三步：发现（拿 Agent Card）→ 发起（创建 Task）→ 跟进（获取结果或接收推送）。

一个容易忽略的优点：JSON-RPC 2.0 的 id 字段天然支持批量请求和响应关联。如果你需要同时向 5 个 Agent 发送任务，一个 HTTP 请求搞定，不需要 5 次连接。

第三章：A2A vs MCP——不是替代，是两条腿

一句话定义：

MCP 是 Agent 的 USB——连接工具（数据库、API、文件系统）
A2A 是 Agent 的 HTTP——连接其他 Agent

维度	MCP	A2A
定位	Agent ↔ 工具连接	Agent ↔ Agent 协作
通信对象	工具/资源/提示词	其他智能体
核心抽象	Tool / Resource / Prompt	Agent Card / Task
状态管理	无状态（调用即返回）	有状态（Task 生命周期）
安全模型	本地进程信任	网络级认证 + 签名
治理	Anthropic → 社区开放	Linux Foundation

三个常见误区必须澄清：

「A2A 会取代 MCP」→ 错。它们互补。一个 Agent 通过 MCP 调用数据库查询工具，同时通过 A2A 和另一个 Agent 协作完成跨部门流程。
「MCP 只能调工具」→ 不完全对。MCP 也能做简单通信，但它不管理 Task 生命周期，不适合长时间协作。
「A2A 更先进」→ 只是定位不同。MCP 解决「Agent 如何使用工具」，A2A 解决「Agent 之间如何协作」，都是基础设施层。

一个典型的企业级架构是这样的：

1
2
3
4
5
6
7
8
9


┌─────────────┐ A2A ┌─────────────┐
│ HR Agent │◄──────────►│ IT Agent │
│ (LangGraph)│ │ (Google ADK)│
└──────┬──────┘ └──────┬──────┘
 │ MCP │ MCP
 ▼ ▼
┌─────────────┐ ┌─────────────┐
│ HR 数据库 │ │ 工单系统 │
└─────────────┘ └─────────────┘

HR Agent 通过 MCP 访问 HR 数据库，通过 A2A 和 IT Agent 协作完成「新员工入职」这个跨部门任务。

第四章：生态版图

A2A 的采纳速度超出预期。从 2025 年 4 月发布到 2026 年 4 月 v1.0 稳定版，仅仅一年就完成了从实验性协议到生产级标准的跃迁。截止 2026 年 4 月：

24,000+ GitHub Stars（a2aproject/A2A），Apache 2.0 开源
6 种官方 SDK：Python、JavaScript、Go、Java、.NET、Rust
框架原生支持：Google ADK、LangGraph、CrewAI、LlamaIndex、Semantic Kernel、AutoGen、BeeAI
企业采纳：Salesforce Agentforce、SAP Joule、ServiceNow Now Assist 等已集成

DeepLearning.AI 也上线了官方 A2A 短课程，由 Google Cloud 和 IBM Research 联合出品。这说明 A2A 已经从「圈内人的玩具」变成了开发者必修课。

IBM 的 BeeAI 框架深度参与了 A2A 生态共建，不仅贡献了任务生命周期管理和多轮对话等多个核心参考实现，还推动了社区层面的协议融合讨论。ACP（Agent Communication Protocol）等同类协议也在探索与 A2A 的兼容路径——从竞争走向统一，是 Agent 生态的必然方向。

第五章：未来方向

A2A 规范仍在快速演进，几个值得关注的方向：

签名 Agent Card（已落地）： 密码学签名验证域名归属，解决企业级信任问题。这是生产部署的前置条件——在金融、医疗等受监管行业，没有签名验证的 Agent 通信根本无法通过合规审查。

Agent Directory（规划中）： 从「我知道你在哪」进化到「我能发现你」。类似 DNS 服务发现机制，让 Agent 能在一个注册中心里搜索和发现其他 Agent 的能力。目前发现依赖 /.well-known/ 约定（你需要知道对方域名），Directory 则支持模糊搜索和分类浏览。

跨域信任链（探索中）： 当 Agent A 委托 Agent B 执行任务，而 B 又需要调用 Agent C 时，如何建立端到端的信任链？目前的签名 Agent Card 解决了点对点信任，但多跳场景下的信任传递还在讨论中。这是企业级生产部署必须攻克的难题。

动态能力协商： 支持 Agent 在任务执行过程中动态添加新的交互方式（比如从文本切换到音视频）。

多租户隔离（规划中）： 企业 SaaS 场景下，同一个 Agent 服务需要为不同租户隔离数据和权限。规范路线图中已包含多租户支持的设计，预计在后续版本中落地。

Rust SDK 加入： 第六种官方 SDK，覆盖系统级高性能场景。

第六章：对我们意味着什么？

个人开发者： 现在可以构建跨框架的多 Agent 系统了。用 LangGraph 做编排 Agent，用 Google ADK 做执行 Agent，通过 A2A 通信，不再被单一框架锁定。入门门槛就是 pip install a2a-sdk。

企业： A2A 让不同部门、不同技术栈的 Agent 可以互操作。IT 部门用 Java 构建的运维 Agent 和业务部门用 Python 构建的分析 Agent，通过 A2A 标准协议就能协作。IT 采购不用再纠结选哪个框架。

趋势判断： A2A 在 2026-2027 年大概率会成为 Agent 互操作的事实标准。判断依据很简单——它是目前唯一同时具备大厂背书（Google/IBM/Salesforce）、开放治理（Linux Foundation）和活跃社区（24,000+ Stars）的方案。历史经验看，这种「三合一」组合在技术标准化中几乎没有失败的先例。

落地方案： 如果你已经在用 MCP（连接工具），那你已经走了一半。下一步是在需要多 Agent 协作的场景引入 A2A。从两个 Agent 的简单协作开始，验证流程跑通后再扩展。

一个务实的起步路径：先用 A2A Python SDK 跑通官方示例（两个本地 Agent 互发消息），然后把其中一个换成你自己的业务 Agent，逐步替换。不要一上来就搞 10 个 Agent 的复杂编排——先跑通两个，再逐步扩展。

什么时候该用 A2A？ 一个简单判断标准：如果你的系统里有 2 个以上 Agent 需要互相协作（不是简单的串行调用），而且它们可能用不同框架构建，那就是 A2A 的场景。如果只是单个 Agent 调用一堆工具，MCP 就够了。

结尾

Agent 世界的「巴别塔」正在被拆解。A2A 不是技术炫技，是基础设施——就像 HTTP 一样，你可能不会每天直接写 A2A 调用，但它会成为多 Agent 系统的默认通信层。

A2A + MCP 的组合，就是 Agent 时代的 HTTP + USB：一个管 Agent 间通信，一个管工具连接。两者互补，缺一不可。

你已经在用 MCP 了吗？准备试试 A2A 做多 Agent 协作吗？评论区聊聊你的场景。

A2A 协议深度解析：为什么说它是 AI Agent 时代的 HTTP

Fri, 12 Jun 2026 08:00:00 +0800

引子：Agent 世界的「巴别塔」

现在的 AI Agent 生态，像极了没有统一语言的巴别塔——LangGraph 说一种方言，CrewAI 说另一种，AutoGen 又是第三种。框架越来越多，Agent 之间却互不相通。

每对 Agent 想要协作，就得写定制胶水代码。5 个 Agent 需要 10 对集成，10 个 Agent 需要 45 对——N² 的复杂度，根本不靠谱。

Google 在 2025 年 4 月 Cloud Next 大会上发布了 A2A（Agent-to-Agent）协议，干的就是这件事：给 Agent 世界定一个统一通信标准。

先说结论：A2A 不是又一个炫技协议，它是 Agent 互联网的基础设施层。就像 HTTP 之于 Web——你不需要每天手写 HTTP 请求，但它无处不在。A2A + MCP 将成为所有多 Agent 系统的标准配置，一个管 Agent 间通信，一个管 Agent 与工具连接。

第一章：为什么需要 A2A？

N² 的集成噩梦只是表象，更深层的问题是：每个框架都在用自己的方式定义「Agent 是什么」「怎么找到另一个 Agent」「任务怎么流转」。

A2A 的核心主张很简洁：

Agent 之间不需要暴露内部实现（不共享 memory、不共享 tools）
只需要暴露能力描述和标准接口
任何框架构建的 Agent 都能发现彼此、协商交互方式、协作完成任务

这套思路被 Linux Foundation 采纳，现在以 Apache 2.0 开源在 a2aproject/A2A，GitHub 上已超过 24,000 Stars。

第二章：三个核心概念

A2A 只围绕三个原语构建，极简但够用。

Agent Card——Agent 的 DNS + 名片

每个 A2A Agent 在 /.well-known/agent.json 路径下暴露一个 JSON 文件，描述自己的能力、端点、认证方式。

这东西本质就是 Agent 的 DNS 记录 + 数字名片合体：别人不需要知道你内部怎么实现，看你的 Agent Card 就知道你能干什么、怎么连你。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


{
 "name": "ticket-agent",
 "description": "企业 IT 工单管理智能体",
 "url": "https://ticket.example.com/a2a",
 "capabilities": {
 "streaming": true,
 "pushNotifications": true
 },
 "skills": [
 {
 "name": "create_ticket",
 "description": "创建 IT 工单"
 },
 {
 "name": "query_tickets",
 "description": "查询工单状态"
 }
 ],
 "authentication": {
 "schemes": ["bearer"]
 }
}

v1.0 规范引入了签名 Agent Card——用密码学签名验证域名所有权。别人拿到你的 Agent Card 时，可以验证它确实是你签发的，不是被中间人篡改过的。

Task——协作的基本单位

A2A 用 Task 来组织一次协作交互。Task 有明确的生命周期：

1
2
3


submitted → working → input-required → completed
 → failed
 → canceled

重点是三种执行模式：

模式	适用场景	特点
同步	简单查询、秒级响应	一问一答，立即返回
异步	数据分析、长耗时任务	提交后轮询或推送通知，支持运行数小时
流式	实时生成、代码编写	SSE 推送中间结果，边算边看

异步模式是生产环境的关键——一个数据清洗 Agent 处理百万行数据，可能跑 30 分钟，A2A 通过 push notification 机制让调用方不用傻等。

Transport——JSON-RPC 2.0 + SSE

传输层选了 JSON-RPC 2.0 over HTTPS，流式场景用 SSE（Server-Sent Events）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# 伪代码：一个 A2A 调用的基本流程
import requests

# 1. 获取对方的 Agent Card
card = requests.get("https://ticket.example.com/.well-known/agent.json").json()

# 2. 发送 Task 请求
response = requests.post(card["url"], json={
 "jsonrpc": "2.0",
 "method": "tasks/send",
 "params": {
 "task": {
 "id": "task-001",
 "message": {
 "role": "user",
 "parts": [{"text": "帮我查一下 REQ12312 的状态"}]
 }
 }
 },
 "id": 1
})

整个交互就三步：发现（拿 Agent Card）→ 发起（创建 Task）→ 跟进（获取结果或接收推送）。

第三章：A2A vs MCP——不是替代，是两条腿

一句话定义：

MCP 是 Agent 的 USB——连接工具（数据库、API、文件系统）
A2A 是 Agent 的 HTTP——连接其他 Agent

维度	MCP	A2A
定位	Agent ↔ 工具连接	Agent ↔ Agent 协作
通信对象	工具/资源/提示词	其他智能体
核心抽象	Tool / Resource / Prompt	Agent Card / Task
状态管理	无状态（调用即返回）	有状态（Task 生命周期）
安全模型	本地进程信任	网络级认证 + 签名
治理	Anthropic → 社区开放	Linux Foundation

三个常见误区必须澄清：

「A2A 会取代 MCP」→ 错。它们互补。一个 Agent 通过 MCP 调用数据库查询工具，同时通过 A2A 和另一个 Agent 协作完成跨部门流程。
「MCP 只能调工具」→ 不完全对。MCP 也能做简单通信，但它不管理 Task 生命周期，不适合长时间协作。
「A2A 更先进」→ 只是定位不同。MCP 解决「Agent 如何使用工具」，A2A 解决「Agent 之间如何协作」，都是基础设施层。

一个典型的企业级架构是这样的：

1
2
3
4
5
6
7
8
9


┌─────────────┐ A2A ┌─────────────┐
│ HR Agent │◄──────────►│ IT Agent │
│ (LangGraph)│ │ (Google ADK)│
└──────┬──────┘ └──────┬──────┘
 │ MCP │ MCP
 ▼ ▼
┌─────────────┐ ┌─────────────┐
│ HR 数据库 │ │ 工单系统 │
└─────────────┘ └─────────────┘

HR Agent 通过 MCP 访问 HR 数据库，通过 A2A 和 IT Agent 协作完成「新员工入职」这个跨部门任务。

第四章：生态版图

A2A 的采纳速度超出预期。截止 2026 年 4 月：

24,000+ GitHub Stars（a2aproject/A2A），Apache 2.0 开源
6 种官方 SDK：Python、JavaScript、Go、Java、.NET、Rust
框架原生支持：Google ADK、LangGraph、CrewAI、LlamaIndex、Semantic Kernel、AutoGen、BeeAI
企业采纳：Salesforce Agentforce、SAP Joule、ServiceNow Now Assist 等已集成

DeepLearning.AI 也上线了官方 A2A 短课程，由 Google Cloud 和 IBM Research 联合出品。

IBM 的 BeeAI 框架深度参与了 A2A 生态共建，社区层面的协议融合一直在推进——从竞争走向统一是 Agent 生态的必然方向。

第五章：未来方向

A2A 规范仍在快速演进，几个值得关注的方向：

签名 Agent Card（已落地）： 密码学签名验证域名归属，解决企业级信任问题。这是生产部署的前置条件。

Agent Directory（规划中）： 从「我知道你在哪」进化到「我能发现你」。类似 DNS 服务发现机制，让 Agent 能在一个注册中心里搜索和发现其他 Agent 的能力。

动态能力协商： 支持 Agent 在任务执行过程中动态添加新的交互方式（比如从文本切换到音视频）。

Rust SDK 加入： 第六种官方 SDK，覆盖系统级高性能场景。

第六章：对我们意味着什么？

结尾

A2A + MCP 的组合，就是 Agent 时代的 HTTP + USB：一个管 Agent 间通信，一个管工具连接。两者互补，缺一不可。

你已经在用 MCP 了吗？准备试试 A2A 做多 Agent 协作吗？评论区聊聊你的场景。

自己写一个 MCP Server：从协议到实战的完整指南

Mon, 08 Jun 2026 08:30:00 +0800

MCP Hub 上现成的 Server 有几百个，但真正落到自己手上——公司内部 API、私有数据源、定制化工具链——没有一个现成的能直接用。这篇文章带你用 Python FastMCP 3.x 从零写一个文件管理 MCP Server，跑通本地调试、远程部署的完整链路。

MCP 协议核心概念速览

三个角色

角色	职责	例子
Host	发起连接的 LLM 应用	Claude Desktop、Cursor、VS Code Copilot
Client	Host 内部与 Server 通信的组件	Claude 内置的 MCP Client
Server	提供工具、数据、提示词的服务	你写的那个

关系很简单：Host 包含 Client，Client 连接 Server。

三个核心能力

Tools：让 LLM 调用函数（计算、查数据库、操作文件）
Resources：让 LLM 读取数据（配置文件、数据库内容）
Prompts：预定义的提示词模板，复用对话模式

两种传输方式

方式	场景	协议
stdio	本地运行，Host 直接启动你的进程	JSON-RPC over stdin/stdout
Streamable HTTP	远程部署，Host 通过 HTTP 连接	HTTP POST + SSE

MCP ≠ Function Calling

这是最大的概念误区。Function Calling 是单个模型厂商的私有接口（比如 OpenAI 的 tool_use），而 MCP 是一个开放协议——任何 LLM、任何工具，只要遵循协议规范就能互通。你可以把它理解为「工具调用界的 USB 接口」。

实战：搭建文件管理 MCP Server

环境准备

1
2
3
4
5
6
7
8
9


# Python >= 3.10
python3 --version

# 创建虚拟环境
python3 -m venv mcp-env
source mcp-env/bin/activate

# 安装 FastMCP（当前最新 3.4.x，别装旧版）
pip install fastmcp

注意：网上大量教程还在用 FastMCP 2.x 的 API（@mcp.server.tool()、FastMCP.from_tools() 等），这些在 3.x 已经全部改了。如果你照抄旧代码，会直接报错。

完整代码

创建 file_server.py：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104


import os
import json
from pathlib import Path
from fastmcp import FastMCP

mcp = FastMCP(name="FileManager")

@mcp.tool
def list_files(dir_path: str) -> str:
 """列出指定目录下的文件和子目录。
 
 Args:
 dir_path: 要列出的目录路径
 """
 path = Path(dir_path).resolve()
 if not path.exists():
 return json.dumps({"error": f"路径不存在: {dir_path}"}, ensure_ascii=False)
 if not path.is_dir():
 return json.dumps({"error": f"不是目录: {dir_path}"}, ensure_ascii=False)
 
 entries = []
 for item in sorted(path.iterdir()):
 entry = {
 "name": item.name,
 "type": "dir" if item.is_dir() else "file",
 "size": item.stat().st_size if item.is_file() else None,
 }
 entries.append(entry)
 
 return json.dumps({
 "path": str(path),
 "count": len(entries),
 "entries": entries,
 }, ensure_ascii=False, indent=2)


@mcp.tool
def read_file(file_path: str) -> str:
 """读取文件内容（文本文件，限制 10MB）。
 
 Args:
 file_path: 文件路径
 """
 path = Path(file_path).resolve()
 if not path.exists():
 return json.dumps({"error": f"文件不存在: {file_path}"}, ensure_ascii=False)
 if not path.is_file():
 return json.dumps({"error": f"不是文件: {file_path}"}, ensure_ascii=False)
 if path.stat().st_size > 10 * 1024 * 1024:
 return json.dumps({"error": "文件超过 10MB 限制"}, ensure_ascii=False)
 
 try:
 content = path.read_text(encoding="utf-8")
 return json.dumps({
 "path": str(path),
 "size": path.stat().st_size,
 "content": content,
 }, ensure_ascii=False)
 except UnicodeDecodeError:
 return json.dumps({"error": "不是文本文件或编码不支持"}, ensure_ascii=False)


@mcp.tool
def search_files(pattern: str, directory: str = ".") -> str:
 """在指定目录下按文件名模式搜索文件。
 
 Args:
 pattern: 搜索模式，支持通配符（如 *.py、test_*）
 directory: 搜索的根目录，默认为当前目录
 """
 path = Path(directory).resolve()
 if not path.exists():
 return json.dumps({"error": f"目录不存在: {directory}"}, ensure_ascii=False)
 
 matches = list(path.glob(f"**/{pattern}"))
 results = [
 {
 "path": str(m.relative_to(path)),
 "type": "dir" if m.is_dir() else "file",
 "size": m.stat().st_size if m.is_file() else None,
 }
 for m in sorted(matches)[:100] # 限制最多 100 条
 ]
 
 return json.dumps({
 "pattern": pattern,
 "directory": str(path),
 "count": len(results),
 "results": results,
 }, ensure_ascii=False, indent=2)


@mcp.resource("resource://cwd")
def get_cwd() -> str:
 """返回当前工作目录信息。"""
 return json.dumps({
 "cwd": os.getcwd(),
 "user": os.environ.get("USER", "unknown"),
 "home": str(Path.home()),
 }, ensure_ascii=False, indent=2)


if __name__ == "__main__":
 mcp.run()

代码要点

@mcp.tool 装饰器把普通函数变成 MCP Tool，函数名就是工具名，docstring 自动变成工具描述
参数用 Python type hints（str、int），FastMCP 自动生成 JSON Schema
@mcp.resource("resource://cwd") 暴露一个只读数据源，Client 可以按 URI 请求
所有返回值统一用 JSON 字符串，LLM 解析起来更可靠
路径用 Path.resolve() 处理，避免相对路径歧义

测试运行

1
2
3
4
5


# 启动 Server（stdio 模式，等待 JSON-RPC 输入）
python file_server.py

# 用 MCP Inspector 调试（需要 Node.js）
npx @modelcontextprotocol/inspector python file_server.py

MCP Inspector 会打开一个 Web 界面，你可以可视化地调用每个 Tool、查看 Schema、检查返回值。

集成到 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或对应路径：

1
2
3
4
5
6
7
8
9


{
 "mcpServers": {
 "file-manager": {
 "command": "python",
 "args": ["/绝对路径/file_server.py"],
 "cwd": "/你的工作目录"
 }
 }
}

重启 Claude Desktop，你的文件管理工具就出现在工具列表里了。

从本地到远程：部署你的 MCP Server

stdio → Streamable HTTP

本地开发用 stdio（简单直接），生产环境需要暴露 HTTP 接口。FastMCP 3.x 内置支持：

1
2
3


# 只改最后一行
if __name__ == "__main__":
 mcp.run(transport="streamable-http", host="0.0.0.0", port=8080)

或者用命令行直接启动：

1

fastmcp run file_server.py --transport streamable-http --port 8080

认证

远程部署必须加认证。MCP 规范推荐 OAuth 2.1（2025 年 6 月 spec 确定）。不要用裸 API Key——明文传输不安全。

FastMCP 3.x 支持通过中间件集成 OAuth：

1
2
3
4


from fastmcp import FastMCP

mcp = FastMCP(name="FileManager", auth_config=...)
# 具体配置参见 FastMCP 官方文档的 Authentication 章节

Docker 容器化

1
2
3
4
5
6
7
8
9


FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY file_server.py .

EXPOSE 8080
CMD ["fastmcp", "run", "file_server.py", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8080"]

1
2


docker build -t file-mcp-server .
docker run -p 8080:8080 file-mcp-server

踩坑实录：我开发 MCP Server 时遇到的 5 个坑

坑 1：FastMCP 版本陷阱

FastMCP 从 1.x → 2.x → 3.x 快速迭代，网上 90% 的教程用的都是过时 API。典型的坑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# ❌ FastMCP 2.x 写法（3.x 报错）
from fastmcp import FastMCP, Context

@mcp.tool()
async def my_tool(ctx: Context) -> str:
 ...

# ✅ FastMCP 3.x 写法
@mcp.tool
def my_tool() -> str:
 ...

教训：写代码前先 pip show fastmcp 确认版本，再去查对应版本文档。

坑 2：把 MCP 当 Function Calling 写

MCP 不只是「换个方式调用函数」。Function Calling 是单次请求-响应，MCP 是持久化的能力暴露——你的 Server 一直活着，Client 随时可以调用任何 Tool、读取任何 Resource。设计思路应该是「我这个 Server 能提供什么能力」，而不是「我这个函数怎么被调用」。

坑 3：Schema 不精确，LLM 瞎调

参数的 type hints 和 docstring 直接决定 LLM 理解你工具的准确度。下面是反面教材：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# ❌ LLM 不知道 limit 是什么范围、offset 从 0 还是 1 开始
def query(page, size):
 """查询数据"""
 ...

# ✅ 类型、范围、含义都写清楚
def query_users(
 page: int = 1, 
 size: int = 20,
) -> str:
 """分页查询用户列表。

 Args:
 page: 页码，从 1 开始
 size: 每页条数，最大 100
 """
 ...

坑 4：调试困难

MCP 用 JSON-RPC over stdio，不像 REST API 可以直接 curl 测试。你没法手动构造 JSON-RPC 消息发到 stdin。

解决方案：用 MCP Inspector（npx @modelcontextprotocol/inspector），它提供完整的可视化调试界面。或者用 FastMCP Client 写测试脚本：

1
2
3
4
5
6
7
8
9


from fastmcp import Client

async def test():
 async with Client("file_server.py") as client:
 result = await client.call_tool("list_files", {"dir_path": "/tmp"})
 print(result)

import asyncio
asyncio.run(test())

坑 5：Node 版本不兼容

如果你用 TypeScript SDK 开发 MCP Server，需要 Node >= 18。低版本会出现诡异的 ERR_MODULE_NOT_FOUND 或 SyntaxError。如果你用 npx @modelcontextprotocol/inspector 调试 Python Server，也需要确保 Node 版本够新。

1
2
3
4
5
6


# 检查版本
node --version # 需要 >= 18

# 推荐用 nvm 管理
nvm install 20
nvm use 20

总结：什么时候自己写 vs 用现成的

场景	建议
标准 API（GitHub、Slack、数据库）	用现成 Server（MCP Hub 上找）
内部工具、私有 API、定制逻辑	自己写
需要特定认证流程	自己写
简单的文件/数据操作	自己写（几十行代码搞定）

MCP Server 开发本身不难——FastMCP 一个装饰器搞定工具定义，type hints 自动生成 Schema。难的是理解协议设计理念（能力暴露 vs 函数调用）和避开版本陷阱。

推荐资源：

MCP 官方文档 — 协议规范和概念
FastMCP 官方文档 — 最新 API 参考
MCP Hub — 现成 Server 搜索

下一篇我会聊 MCP + Cursor 的进阶玩法——怎么让你的 MCP Server 真正融入日常开发工作流。