Pydantic AI MCP Agent 实战:基于 Model Context Protocol 无缝接入外部工具

原创2026-09-17 11:02:371,829 阅读
文章标签:示例工程人工智能AI Agent

Pydantic AI MCP Agent 实战:基于 Model Context Protocol 无缝接入外部工具

导读

本文将围绕 pydantic-ai-mcp-agent 项目,系统讲解如何基于 Pydantic AI 框架构建一个可动态接入任意 MCP(Model Context Protocol)工具服务器的 AI Agent。读完本文,你将掌握 MCP 客户端与 Pydantic AI 工具的自动转换原理、与 Claude Desktop 完全一致的 mcp_config.json 配置方法、交互式 CLI 与 FastAPI 服务的搭建方式,以及如何将其部署到 Live Agent Studio 平台。

一、项目概览:MCP 与 Pydantic AI 的组合

Model Context Protocol(MCP)是当前 AI 应用接入外部工具的事实标准接口协议。本项目的核心思路是:让 Pydantic AI 构建的 Agent 通过 MCP 协议访问外部工具服务器,从而获得文件系统、数据库、网络服务等能力。其 MCP 配置格式与 Claude Desktop、Windsurf、Cline 等工具完全一致,这意味着你此前为这些桌面工具编写过的任何 MCP 服务器配置,都可以原样复用到自己的 Python Agent 中。

项目由两套实现组成:

  1. CLI 实现(仓库根目录):面向本地交互式聊天场景,包含 pydantic_mcp_agent.py(主程序)、mcp_client.py(MCP 连接客户端)和 mcp_config.json(MCP 服务器配置)。
  2. Live Agent Studio 集成(studio-integration-version 目录):面向平台化部署,包含 pydantic_mcp_agent_endpoint.py(FastAPI 端点)、简化版 pydantic_mcp_agent.py 以及 Dockerfile。

核心依赖版本(以仓库 requirements.txt 为准):pydantic-ai==0.0.41、mcp==1.5.0、openai==1.66.3,另含 rich(终端美化)、python-dotenv(环境变量加载)等。注意:仓库中该文件为 UTF-16 编码,阅读时需以 UTF-16 方式打开。

二、工作原理:从配置到工具调用的六步链路

2.1 整体架构

系统的工作流程可概括为六个环节:

  1. 配置:在 mcp_config.json 中声明一个或多个 MCP 服务器(命令、参数、环境变量);
  2. 连接:通过 stdio 建立与 MCP 服务器的进程间通信连接;
  3. 工具发现:调用 MCP 的 list_tools 接口获取服务器暴露的全部工具;
  4. 工具转换:将每个 MCP 工具包装成 Pydantic AI 兼容的 Tool 对象;
  5. Agent 初始化:用转换后的工具列表创建 Pydantic AI Agent;
  6. 执行:Agent 接收用户输入,自主决定调用哪些 MCP 工具完成任务。

2.2 关键组件

  • MCPClient:管理一个或多个 MCP 服务器的连接生命周期(配置加载、批量启动、统一清理);
  • MCPServer:封装与单个 MCP 服务器的通信细节(stdio 传输、会话初始化、工具列表获取、工具调用);
  • Tool Conversion:负责 MCP 工具到 Pydantic AI 工具的类型与 Schema 映射;
  • Agent:由 Pydantic AI 提供的推理核心,负责解析用户请求并编排工具调用。

三、快速开始:三步为你的 Agent 接入 MCP 工具

如果你只想在自己的项目中快速复用这套能力,README 提供了极简的三步路径。

3.1 复制客户端并安装依赖

把 mcp_client.py 复制到你的项目,然后安装两个核心包:

pip install pydantic-ai mcp

3.2 编写 MCP 服务器配置

创建 mcp_config.json,其结构与 Claude Desktop 的 MCP 配置完全一致,可直接参考 mcp_config_example.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\colem\\oTTomator\\ottomator-agents\\pydantic-ai-mcp-agent"
      ]
    },
    "sqlite": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "./data:/mcp",
        "mcp/sqlite",
        "--db-path",
        "/mcp/test.db"
      ]
    }
  }
}

3.3 创建带工具的 Agent

import mcp_client
from pydantic_ai import Agent

async def get_pydantic_ai_agent():
    client = mcp_client.MCPClient()
    client.load_servers("mcp_config.json")
    tools = await client.start()
    return client, Agent(model='your-llm-here', tools=tools)

在主函数中按需取用:

client, agent = await get_pydantic_ai_agent()

此后,这个 Pydantic AI Agent 便自动获得了 mcp_config.json 中所有 MCP 服务器暴露的全部工具——无需手动注册任何工具函数,配置即工具。

四、配置详解:与 Claude Desktop 兼容的 mcp_config.json

4.1 配置结构与字段语义

每个 MCP 服务器条目包含三个核心字段:

字段 说明 示例值
command 启动 MCP 服务器的可执行命令 npx、docker、python、node 等
args 传给命令的参数列表 ["-y", "@modelcontextprotocol/server-filesystem", "./"]
env 注入服务器进程的环境变量(可省略) {} 或 {"KEY": "value"}

4.2 示例服务器解析

示例配置展示了两种典型启动方式:

  • filesystem 服务器:通过 npx -y @modelcontextprotocol/server-filesystem <路径> 启动,第二个参数是允许服务器访问的根目录。它依赖 Node.js 环境(这也是项目前置要求中包含 Node.js 的原因)。
  • sqlite 服务器:通过 docker run --rm -i -v ./data:/mcp mcp/sqlite --db-path /mcp/test.db 启动,将宿主机 ./data 目录挂载进容器,数据库文件落在 /mcp/test.db。注意 --rm -i 保证容器用完即销毁且保持交互流。

4.3 底层命令解析逻辑

从 mcp_client.py 的源码可以看到,MCPServer.initialize 会对 command 做特殊处理:

command = (
    shutil.which("npx")
    if self.config["command"] == "npx"
    else self.config["command"]
)

即:当命令是 npx 时,会先通过 shutil.which 解析出 npx 的绝对路径,再构造 StdioServerParameters 交给 stdio_client 建立传输;若 command 解析失败(如系统未安装 Node.js),会抛出 ValueError。env 字段为空或缺失时会被置为 None,交由 MCP 客户端使用默认环境。

五、源码级解析:MCP 工具到 Pydantic AI 工具的自动转换

5.1 MCPClient:多服务器管理器

MCPClient 的三个核心方法构成完整生命周期:

  • load_servers(config_path):读取 JSON 配置,为每个条目创建 MCPServer 实例(此时不建立连接,属于懒加载);
  • start():依次 initialize 每个服务器并调用 create_pydantic_ai_tools() 收集工具;任一服务器初始化失败时记录 logging.error 并调用 cleanup_servers() 回滚已建立的连接,返回空列表;
  • cleanup():先逐个关闭服务器,再关闭自身持有的 AsyncExitStack,确保进程退出时不留孤儿子进程。

5.2 MCPServer:单服务器通信与工具转换

MCPServer 是转换机制的核心,值得关注三处实现细节:

初始化与资源管理:initialize 使用 AsyncExitStack.enter_async_context 依次挂载 stdio_client 和 ClientSession,并调用 session.initialize() 完成 MCP 握手;失败时自动 cleanup 并重新抛出异常。cleanup 方法内部用 asyncio.Lock 保护,避免并发清理竞态。

工具发现与转换:create_pydantic_ai_tools 通过 (await self.session.list_tools()).tools 一次性拉取服务器声明的全部工具,然后逐个调用 create_tool_instance:

def create_tool_instance(self, tool: MCPTool) -> PydanticTool:
    async def execute_tool(**kwargs: Any) -> Any:
        return await self.session.call_tool(tool.name, arguments=kwargs)

    async def prepare_tool(ctx: RunContext, tool_def: ToolDefinition) -> ToolDefinition | None:
        tool_def.parameters_json_schema = tool.inputSchema
        return tool_def

    return PydanticTool(
        execute_tool,
        name=tool.name,
        description=tool.description or "",
        takes_ctx=False,
        prepare=prepare_tool
    )

这里的转换包含两层关键适配:

  1. 执行层:每个 MCP 工具被包装成一个 async def execute_tool(**kwargs) 闭包,运行时通过 session.call_tool(tool.name, arguments=kwargs) 将参数转发给远程服务器——Pydantic AI 的调用结果即是 MCP 服务器的原始返回。
  2. Schema 层:利用 Pydantic AI 的 prepare 钩子,在工具定义生成阶段把 MCP 工具自带的 inputSchema(JSON Schema)注入 tool_def.parameters_json_schema,从而让 Agent 获得与远程工具完全一致的参数校验与描述信息。takes_ctx=False 表示该工具不接收 RunContext。

5.3 六步链路与源码的对应关系

流程环节 源码落点
配置加载 MCPClient.load_servers(mcp_client.py)
stdio 连接 MCPServer.initialize 中 stdio_client(server_params)(mcp_client.py)
工具发现 session.list_tools()(mcp_client.py)
工具转换 create_tool_instance 的闭包与 prepare 钩子(mcp_client.py)
Agent 初始化 Agent(model=..., tools=tools)(pydantic_mcp_agent.py)
工具执行 execute_tool → session.call_tool

六、运行交互式 CLI

6.1 环境变量

CLI 应用通过 pydantic_mcp_agent.py 中的 get_model() 读取以下环境变量(均有默认值):

变量 作用 默认值
MODEL_CHOICE 模型名称 gpt-4o-mini
BASE_URL LLM API 基础地址 https://api.openai.com/v1
LLM_API_KEY API 密钥 no-api-key-provided
PROVIDER 提供商标识(README 列出) 无默认值

项目使用 OpenAIModel 统一承载模型,因此 BASE_URL 可以指向 OpenAI、OpenRouter 等 OpenAI 兼容端点;配合本地 Ollama 服务时则无需 API Key。环境变量通过 python-dotenv 的 load_dotenv() 从 .env 文件加载。

6.2 完整启动步骤

# 1. 创建并激活虚拟环境(Windows)
python -m venv venv
venv\Scripts\activate

# 2. (macOS/Linux)
python -m venv venv
source venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置 .env(参考 .env.example)
#    PROVIDER=openai / openrouter / ollama
#    BASE_URL=<你的 API 地址>
#    LLM_API_KEY=<你的密钥>
#    MODEL_CHOICE=gpt-4o-mini

# 5. 配置 mcp_config.json(参考 mcp_config_example.json)

# 6. 启动 CLI
python pydantic_mcp_agent.py

6.3 CLI 交互体验

main() 的实现展示了完整的聊天循环:

  • 输入 exit、quit、bye、goodbye 任意一个即退出;
  • 使用 rich.live.Live 配合 agent.run_stream() 实现流式 Markdown 输出——stream_text(delta=True) 逐段累积 token,live.update(Markdown(curr_message)) 让终端实时渲染;
  • 每轮对话通过 result.all_messages() 累积 message_history,使 Agent 具备多轮上下文记忆;
  • try/finally 保证退出时必然调用 mcp_client.cleanup(),正确释放 MCP 子进程资源。

七、如何扩展

README 给出了四条扩展路径,结合源码可进一步明确做法:

  1. 添加更多 MCP 服务器:在 mcp_config.json 的 mcpServers 对象中追加新条目即可,MCPClient.start() 会自动批量发现并合并所有服务器的工具,无需改动业务代码。
  2. 创建自定义工具:遵循 MCP 规范开发自己的服务器,只要实现 stdio 协议即可被本客户端无缝接入;也可以不依赖 MCP,直接在 Agent 中注册 Pydantic AI 原生工具(参考 extras/non_mcp_agent.py 的对照实现)。
  3. 增强 Agent:替换 get_model() 中的模型配置、调整 Agent(...) 参数,即可针对检索、代码审查等场景定制行为。
  4. 添加记忆能力:集成 Mem0 等外部记忆系统,让 Agent 跨会话记住用户偏好。

此外 extras 目录还提供了 basic_mcp_agent.py(最简接入示例)、experimental_mcp_client.py(实验版客户端,使用并发清理与 asyncio.gather)以及 pydantic_mcp_streamlit.py(Streamlit Web 界面示例),可供对照学习。

八、Live Agent Studio 集成:FastAPI + Supabase + Docker

8.1 端点架构

studio-integration-version 中的 pydantic_mcp_agent_endpoint.py 将同一套 MCP Agent 包装成生产可用的 HTTP 服务,包含四个关键设计:

  • 生命周期管理:FastAPI lifespan 在应用启动时异步初始化全局 mcp_agent,保证每个请求复用同一 Agent 实例;
  • Bearer Token 认证:verify_token 依赖 HTTPBearer 校验请求头中的 token 是否等于环境变量 API_BEARER_TOKEN;该变量未配置时返回 500,token 不匹配返回 401;
  • CORS 全开:allow_origins=["*"],便于前端跨域调用;
  • 请求模型:POST /api/pydantic-mcp-agent,请求体包含 query、user_id、request_id、session_id 四个字段,响应体仅返回 success 布尔值(异步任务式设计)。

8.2 Supabase 会话存储

端点依赖 Supabase 持久化多轮对话,核心逻辑在 fetch_conversation_history 与 store_message 两个函数中:

  • 读取:按 session_id 过滤、按 created_at 倒序取最近 10 条,再反转得到时间正序的历史,转换为 Pydantic AI 的 ModelRequest/ModelResponse 消息格式传入 agent.run(..., message_history=messages);
  • 写入:用户消息以 type="human"、Agent 回复以 type="ai" 写入 messages 表,data 字段可携带 request_id、错误详情等附加信息;
  • 错误兜底:Agent 执行异常时仍会写入一条致歉回复,并把 error 与 request_id 存入 data。

需要在 Supabase 中预先创建 messages 表,字段结构如下:

字段 类型 说明
id UUID 主键
created_at Timestamp with time zone 创建时间
session_id Text 会话标识
message JSON 含 type、content 及可选 data

8.3 环境变量与部署

在 studio-integration-version 目录配置 .env:

MODEL_CHOICE=gpt-4o-mini
BASE_URL=<你的 API 地址>
LLM_API_KEY=<你的密钥>
SUPABASE_URL=<Supabase 项目地址>
SUPABASE_SERVICE_KEY=<Supabase 服务角色密钥>
API_BEARER_TOKEN=<自定义的 API 认证令牌>

本地启动:

cd studio-integration-version
python pydantic_mcp_agent_endpoint.py

服务默认监听 0.0.0.0:8001(见 uvicorn.run(app, host="0.0.0.0", port=8001))。

8.4 Docker 部署

仓库提供的 Dockerfile 基于 ottomator/base-python:latest 基础镜像:

cd studio-integration-version
docker build -t pydantic-mcp-agent .
docker run -p 8001:8001 --env-file .env pydantic-mcp-agent

Dockerfile 将 PORT 作为构建参数(默认 8001)写入 ENV,最后通过 uvicorn pydantic_mcp_agent_endpoint:app --host 0.0.0.0 --port ${PORT} 启动,--env-file 负责把本地 .env 注入容器。

九、环境要求与注意事项

  • Python 3.9+:项目基于 pydantic-ai 0.0.41 与 mcp 1.5.0,异步接口(AsyncExitStack、asyncio.Lock)依赖较新的 Python 版本;
  • Node.js:若使用 npx 启动类 filesystem 的 MCP 服务器,需确保 Node.js 可用;initialize 中对 npx 做了 shutil.which 探测,缺失时会直接报错;
  • LLM 服务:OpenAI API Key 为默认前提;OpenRouter 等兼容端点只需修改 BASE_URL;本地 Ollama 可免除 Key;
  • Docker:示例中的 sqlite 服务器以容器方式运行,需要本机 Docker 环境;
  • 仓库中根目录与 studio-integration-version 的 requirements.txt 均为 UTF-16 编码,若直接以 UTF-8 读取会报解码错误,请按 UTF-16 解析或使用 iconv 转换。

十、总结

通过本文可以完整掌握:MCP 协议与 Pydantic AI 组合下的 Agent 工具接入范式、与 Claude Desktop 兼容的 mcp_config.json 配置、基于 prepare 钩子的工具 Schema 自动注入原理、流式 CLI 的构建方法,以及 FastAPI + Supabase + Docker 的生产化部署链路。整个项目最核心的价值在于一次编写、随处复用——任何符合 MCP 标准的服务器(文件系统、SQLite、GitHub、Slack 等)都能通过同一套 mcp_client.py 瞬间接入你的 Pydantic AI Agent,让工具扩展从"写代码"变成"改配置"。

登录后查看全文
ottomator-agents