MODULE 8/11  ·  MCP 集成

能力不够?插件来凑

🔌 MCP = Model Context Protocol

就像电脑的 USB 接口——任何设备插上就能用。MCP 让 Agent 连接任意外部工具,无需修改核心代码。

01

MCP 协议:万能插头

💡 类比

想象你的电脑只有内置功能:不能接鼠标、不能插U盘、不能连显示器。MCP 就是给 Agent 装上 USB 接口——标准化的即插即用协议,让任何外部工具都能无缝接入。

🔌 标准协议

JSON-RPC 2.0 通信格式,所有工具遵循同一套调用规范

🔍 自动发现

连接后自动获取可用工具列表,无需硬编码

🧩 热插拔

运行时动态添加/移除工具服务器,Agent 无需重启

概念说明
MCPServer提供工具的服务端——注册工具、处理调用
MCPClient连接外部工具的客户端——发现工具、发起调用
Transport通信层——stdio(本地进程)、HTTP(远程)、SSE(实时流)
Tool一个可调用的功能单元,有名称、描述、参数定义
02

架构流程 — 请求如何流动

🤖 Agent
→
🔌 MCPClient
→
📡 Transport
→
🖥️ MCPServer
→
🔧 Tool
Agent 决定调用工具
模型推理后判断需要外部能力,选择 tool_name
MCPClient 构造 JSON-RPC 请求
序列化为 {"jsonrpc":"2.0","method":"tools/call","params":{...}}
Transport 传输
通过 stdio 子进程 stdin/stdout,或 HTTP/SSE 发送到远程服务
MCPServer 接收并执行
解析请求,查找注册的工具函数,执行并返回结果
结果返回 Agent
响应沿原路返回,Agent 将结果整合进推理链
03

MCPServer:提供工具的服务端

MCPServer 是工具的"房东"——它注册工具定义、处理来自客户端的调用请求。核心三件套:register_tool、list_tools、call_tool。

Python
import json, sys

class MCPServer:
    def __init__(self, name: str):
        self.name = name
        self.tools = {}        # { "tool_name": handler_func }
        self.tool_defs = {}     # { "tool_name": {description, parameters} }

    def register_tool(self, name, description, parameters, handler):
        """注册一个工具:定义 + 处理函数"""
        self.tool_defs[name] = {
            "name": name,
            "description": description,
            "parameters": parameters   # JSON Schema
        }
        self.tools[name] = handler

    def list_tools(self):
        """返回所有已注册工具的定义列表"""
        return list(self.tool_defs.values())

    def call_tool(self, name, arguments):
        """查找并执行工具"""
        if name not in self.tools:
            return {"error": f"Tool '{name}' not found"}
        return self.tools[name](**arguments)

    def handle_request(self, request: dict) -> dict:
        """处理 JSON-RPC 2.0 请求"""
        method = request["method"]
        req_id = request.get("id")
        if method == "tools/list":
            result = self.list_tools()
        elif method == "tools/call":
            params = request["params"]
            result = self.call_tool(params["name"], params.get("arguments", {}))
        else:
            return {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": req_id}
        return {"jsonrpc": "2.0", "result": result, "id": req_id}
🔑 JSON-RPC 2.0 协议要点

所有 MCP 通信都遵循 JSON-RPC 2.0 格式:
请求:{"jsonrpc":"2.0", "id":1, "method":"tools/call", "params":{...}}
响应:{"jsonrpc":"2.0", "id":1, "result":{...}}
id 用于匹配请求和响应,method 标识操作类型。

04

MCPClient:连接外部工具

MCPClient 是 Agent 侧的"翻译官"——它连接远端的 MCPServer,发现可用工具,并把调用请求转发出去。

Python
class MCPClient:
    def __init__(self, name: str):
        self.name = name
        self.servers = {}       # { "server_name": transport }
        self.tools = {}         # { "prefixed_tool_name": tool_def }

    async def add_server(self, server_name: str, transport):
        """连接一个 MCP Server 并自动发现工具"""
        self.servers[server_name] = transport

        # 1. 请求工具列表
        response = await transport.send({
            "jsonrpc": "2.0", "id": 1,
            "method": "tools/list"
        })

        # 2. 注册发现的工具(加前缀避免冲突)
        for tool in response["result"]:
            prefixed = f"{server_name}__{tool['name']}"
            self.tools[prefixed] = {"server": server_name, **tool}

    async def call_tool(self, tool_name: str, arguments: dict):
        """调用工具:路由到对应的 server"""
        tool_info = self.tools[tool_name]
        server_name = tool_info["server"]
        transport = self.servers[server_name]
        original_name = tool_name.split("__", 1)[1]

        response = await transport.send({
            "jsonrpc": "2.0", "id": 2,
            "method": "tools/call",
            "params": {"name": original_name, "arguments": arguments}
        })
        return response["result"]

    def list_tools(self):
        """列出所有可用工具(Agent 用来决定调用哪个)"""
        return [
            {"name": name, "description": t["description"], "parameters": t.get("parameters",{})}
            for name, t in self.tools.items()
        ]
💡 工具命名策略

使用 server_name__tool_name 双下划线前缀:
filesystem__read_file、database__query、weather__forecast
避免不同 Server 注册同名工具时产生冲突。

05

工具发现 — 连接即获得能力

MCP 最优雅的设计:连接后自动获取工具定义,无需预先硬编码。

Client
1️⃣
connect()
2️⃣
tools/list
3️⃣
[{def}, ...]
4️⃣
register
Discovery Flow
# 工具发现的完整流程

# Step 1: 创建 Client
client = MCPClient("my_agent")

# Step 2: 连接 Server(自动完成发现)
transport = StdioTransport("python", "mcp_server.py")
await client.add_server("filesystem", transport)

# Step 3: 查看发现的工具
for tool in client.list_tools():
    print(f"  {tool['name']}: {tool['description']}")

# 输出:
#   filesystem__read_file: Read file contents
#   filesystem__write_file: Write content to file
#   filesystem__list_dir: List directory contents

# Step 4: 直接调用!
result = await client.call_tool("filesystem__read_file", {"path": "data.txt"})
06

三种传输方式 & 服务端示例

💻 stdio 本地

通过子进程 stdin/stdout 通信,零网络延迟,适合本地工具。

🌐 HTTP 远程

标准 HTTP POST 请求-响应,适合远程 API 和云服务。

📡 SSE 实时

Server-Sent Events 流式推送,适合长时间运行的实时任务。

示例 1:文件系统 Server

Python — filesystem_server.py
from mcp.server import MCPServer
import os

server = MCPServer("filesystem")

@server.register_tool(
    name="read_file",
    description="Read the contents of a file",
    parameters={
        "type": "object",
        "properties": {"path": {"type": "string", "description": "File path"}},
        "required": ["path"]
    }
)
def read_file(path):
    with open(path, "r") as f:
        return {"content": f.read()}

@server.register_tool(
    name="write_file",
    description="Write content to a file",
    parameters={
        "type": "object",
        "properties": {
            "path": {"type": "string"},
            "content": {"type": "string"}
        },
        "required": ["path", "content"]
    }
)
def write_file(path, content):
    with open(path, "w") as f:
        f.write(content)
    return {"success": True, "bytes": len(content)}

server.run_stdio()

示例 2:数据库 Server

Python — database_server.py
import sqlite3
from mcp.server import MCPServer

server = MCPServer("database")
db = sqlite3.connect("app.db")

@server.register_tool(
    name="query",
    description="Execute a read-only SQL query",
    parameters={
        "type": "object",
        "properties": {"sql": {"type": "string", "description": "SQL SELECT statement"}},
        "required": ["sql"]
    }
)
def query(sql):
    # 安全检查:只允许 SELECT
    if not sql.strip().upper().startswith("SELECT"):
        return {"error": "Only SELECT queries allowed"}
    cursor = db.execute(sql)
    columns = [desc[0] for desc in cursor.description]
    rows = cursor.fetchall()
    return {"columns": columns, "rows": rows, "count": len(rows)}

@server.register_tool(
    name="list_tables",
    description="List all tables in the database",
    parameters={"type": "object", "properties": {}}
)
def list_tables():
    cursor = db.execute("SELECT name FROM sqlite_master WHERE type='table'")
    return {"tables": [row[0] for row in cursor.fetchall()]}

server.run_stdio()

示例 3:API Gateway Server

Python — api_server.py
import httpx
from mcp.server import MCPServer

server = MCPServer("weather_api")
client = httpx.AsyncClient()

@server.register_tool(
    name="get_weather",
    description="Get current weather for a city",
    parameters={
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name"},
            "units": {"type": "string", "enum": ["metric", "imperial"], "default": "metric"}
        },
        "required": ["city"]
    }
)
async def get_weather(city, units="metric"):
    resp = await client.get(
        f"https://api.weather.example/v1/{city}",
        params={"units": units}
    )
    data = resp.json()
    return {
        "city": data["name"],
        "temp": data["main"]["temp"],
        "condition": data["weather"][0]["description"]
    }

server.run_http(port=8080>)
07

集成到 Agent — AgentWithMCP

最终目标:让 Agent 天然支持 MCP。继承 Agent,加入 MCP Client 能力。

Python
class AgentWithMCP(Agent):
    """继承 Agent,自动集成 MCP 工具发现和调用"""

    def __init__(self, name, model, mcp_servers=None, **kwargs):
        super().__init__(name=name, model=model, **kwargs)
        self.mcp_client = MCPClient(name)
        self.mcp_configs = mcp_servers or []

    async def initialize(self):
        """启动时连接所有 MCP Server"""
        for config in self.mcp_configs:
            if config["transport"] == "stdio":
                transport = StdioTransport(*config["command"])
            elif config["transport"] == "http":
                transport = HttpTransport(config["url"])

            await self.mcp_client.add_server(config["name"], transport)
            self.tools.register_external(self.mcp_client.list_tools())
            print(f"✅ Connected to MCP server: {config['name']}")

    async def execute_tool(self, tool_name, arguments):
        """覆写:MCP 工具走 client,本地工具走原逻辑"""
        if "__" in tool_name:
            return await self.mcp_client.call_tool(tool_name, arguments)
        return await super().execute_tool(tool_name, arguments)

# 使用方式
agent = AgentWithMCP(
    name="assistant",
    model="gpt-4",
    mcp_servers=[
        {"name": "filesystem", "transport": "stdio", "command": ["python", "fs_server.py"]},
        {"name": "database",   "transport": "stdio", "command": ["python", "db_server.py"]},
        {"name": "weather",    "transport": "http",  "url": "http://localhost:8080"},
    ]
)
await agent.initialize()
await agent.run("读取 config.yaml 并查询今天的天气")
🧩 架构一图流

AgentWithMCP = Agent + MCPClient。
本地工具走 tools.register,远程工具走 mcp_client。
execute_tool 自动路由:双下划线 → MCP,否则 → 本地。

08

🧠 知识检验

Q1: MCP 协议基于什么通信格式?

MCP 使用 JSON-RPC 2.0 作为标准通信协议。

Q2: MCPClient 如何避免不同 Server 的同名工具冲突?

使用双下划线前缀如 filesystem__read_file 来避免冲突。

Q3: 以下哪种传输方式最适合本地工具?

stdio 通过子进程通信,零网络延迟,最适合本地工具。

Q4: MCP 工具发现的正确顺序是?

先连接 Server,请求 tools/list,获取定义后注册到本地。

Q5: AgentWithMCP 如何判断一个工具是 MCP 远程工具还是本地工具?

execute_tool 检查 "__" 在工具名中,有则走 MCP Client,否则走本地逻辑。
09

🔬 深入探索

🌊 Deep Dive 1:SSE 传输的实时能力

Server-Sent Events (SSE) 不同于普通 HTTP 请求-响应,它维持一个长连接,服务端可以持续推送事件。

Protocol
// SSE 传输的 MCP 通信示例
// 1. Client 发起 SSE 连接
GET /mcp/sse HTTP/1.1
Accept: text/event-stream

// 2. Server 推送事件流
data: {"jsonrpc":"2.0", "method":"progress", "params":{"percent":30}}
data: {"jsonrpc":"2.0", "method":"progress", "params":{"percent":60}}
data: {"jsonrpc":"2.0", "id":1, "result":{"done":true}}

// 3. Client 发送请求(通过独立 HTTP POST)
POST /mcp/message HTTP/1.1
Content-Type: application/json
{"jsonrpc":"2.0", "id":2, "method":"tools/call", "params":{...}}

适合场景:长时间运行的工具(代码编译、模型推理)、需要进度报告的任务。

🛡️ Deep Dive 2:MCP 安全边界

MCP Server 是天然的安全沙箱——每个 Server 在独立进程中运行,权限范围由 Server 本身控制。

Security Pattern
class SandboxedServer(MCPServer):
    """带权限控制的 MCP Server"""

    def __init__(self, name, allowed_paths=None):
        super().__init__(name)
        self.allowed_paths = allowed_paths or []

    def check_permission(self, path):
        return any(path.startswith(p) for p in self.allowed_paths)

    def call_tool(self, name, arguments):
        # 额外的安全检查
        if name == "read_file" and not self.check_permission(arguments["path"]):
            return {"error": "Permission denied: path not allowed"}
        return super().call_tool(name, arguments)

最佳实践:每个 MCP Server 只暴露最小必要权限,Agent 无法绕过 Server 的安全检查。

🔄 Deep Dive 3:跨 Server 编排

真正强大的场景:一个 Agent 协调多个 MCP Server 完成复杂任务。

Orchestration
# 示例:Agent 执行 "分析销售数据并生成报告"

# Step 1: database Server — 查询数据
data = await mcp.call_tool("database__query", {
    "sql": "SELECT * FROM sales WHERE month='2025-06'"
})

# Step 2: 本地计算 — 数据分析(不需要 MCP)
analysis = analyze_sales(data["rows"])

# Step 3: filesystem Server — 写入报告
await mcp.call_tool("filesystem__write_file", {
    "path": "reports/june_2025.md",
    "content": format_report(analysis)
})

# Step 4: notification Server — 发送通知
await mcp.call_tool("notification__send", {
    "channel": "slack",
    "message": "6月销售报告已生成 ✅"
})

Agent 作为"指挥家",各 MCP Server 是"乐手",协同演奏出复杂的业务流程。

10

📋 本节总结

MCP 集成 — 核心要点

  • MCP = Model Context Protocol,标准化的 Agent 工具扩展协议
  • USB 类比:即插即用,任何工具通过标准接口接入 Agent
  • MCPServer:提供工具(register_tool → list_tools → call_tool)
  • MCPClient:连接 Server、发现工具、路由调用
  • JSON-RPC 2.0:所有 MCP 通信的标准协议格式
  • 三种传输:stdio(本地)、HTTP(远程)、SSE(实时流)
  • 工具发现:connect → tools/list → 获取定义 → 自动注册
  • 命名策略:server_name__tool_name 双下划线前缀避免冲突
  • 集成模式:AgentWithMCP 继承 Agent,自动路由 MCP/本地工具
  • 安全隔离:每个 Server 独立进程,权限由 Server 自身控制