MCP工具集成

MCP 工具集成

欢迎阅读 模型上下文协议 (MCP) 集成指南！本示例展示了如何通过标准化的 MCP 协议，将您的 ADK 代理与外部数据源和工具连接起来。

您将学到的内容

• MCP 基础知识：了解模型上下文协议
• ADK ↔ MCP 集成：使用 MCPToolset 连接到 MCP 服务器
• 外部工具访问：利用 MCP 服务器上的工具
• 服务器通信：处理本地和远程 MCP 服务器
• 实际应用：结合文件系统和维基百科的实际示例

核心概念：模型上下文协议

模型上下文协议 (MCP) 是一种开放标准，使 AI 代理能够：

• 一致地访问外部数据源
• 使用远程服务器上的工具
• 与各种应用进行通信
• 在交互过程中保持上下文一致性

MCP 如何与 ADK 配合

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  ADK Agent  │◄──►│ MCPToolset  │◄──►│ MCP Server  │
│             │    │             │    │             │
│   Gemini    │    │   Bridge    │    │   Tools     │
└─────────────┘    └─────────────┘    └─────────────┘
​

MCPToolset 充当桥梁，实现以下功能：

• 连接到 MCP 服务器（本地或远程）
• 自动发现可用工具
• 将 MCP 工具转换为 ADK 兼容格式
• 管理连接的生命周期

集成模式

1. 使用外部 MCP 服务器

连接到现有的 MCP 服务器：

• 文件系统服务器：文件操作
• 维基百科服务器：知识检索
• 数据库服务器：数据访问
• API 服务器：外部服务集成

2. 通信协议

• 服务器发送事件 (SSE)：用于远程服务器的实时通信
• 标准 I/O：用于 MCP 服务器的本地进程通信

本教程中的示例

示例 1：文件系统代理

位置：./filesystem_agent/

• Connect to filesystem MCP server
• Perform file operations (read, write, list)
• Handle local file system interactions
• Use Standard I/O communication

Example 2: Firecrawl Agent

Location: ./firecrawl_agent/

• 连接到 Firecrawl MCP 服务器以进行高级网页抓取
• 执行单页抓取、批量处理和网站爬虫
• 利用 AI 驱动的分析提取结构化数据
• 进行多源合成的深度网络研究
• 使用标准 I/O 通信与云 API 集成

项目结构

4_4_mcp_tools/
├── README.md                    # This file - MCP integration guide
├── requirements.txt             # MCP dependencies
├── filesystem_agent/            # Filesystem MCP integration
│   ├── __init__.py             # Package initialization
│   ├── agent.py                # Main agent implementation
│   └── README.md               # Filesystem agent guide
├── firecrawl_agent/             # Firecrawl web scraping integration
│   ├── __init__.py             # Package initialization
│   ├── agent.py                # Main agent implementation
│   └── README.md               # Firecrawl agent guide
​

关键特性

• 无缝集成：MCPToolset 处理所有 MCP 协议细节
• 自动发现：工具自动发现并可用
• 多种协议：支持 stdio 和 SSE 通信
• 错误处理：针对网络和服务器问题的健壮错误管理
• 资源管理：正确清理连接和资源

先决条件

在运行这些示例之前：

1. 安装依赖：

   pip install -r requirements.txt
   ​

2. 设置环境：

   # From the root tutorials directory
   cp env.example .env
   # Edit .env and add your Google AI API key
   ​

3. Node.js 用于 MCP 服务器（适用于社区服务器）：

   # Install Node.js if not already installed
   # Required for npm/npx based MCP servers
   ​

工作原理

连接流程

1. 使用连接参数初始化 MCPToolset
2. 建立与 MCP 服务器的连接
3. 通过 MCP 协议发现工具
4. 将工具适配为 ADK 格式
5. 在代理对话中使用工具
6. 完成后清理连接

代码示例

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StdioServerParameters

# Create MCP toolset for external server
toolset = MCPToolset(
    connection_params=StdioServerParameters(
        command='npx',
        args=['-y', '@modelcontextprotocol/server-filesystem', '/path/to/folder']
    )
)

# Create agent with MCP tools
agent = LlmAgent(
    model='gemini-3-flash-preview',
    name='mcp_agent',
    instruction='Use MCP tools to help users',
    tools=[toolset]
)
​

快速开始

快速入门

1. 选择一个示例进行探索：

   • 文件系统代理：用于文件操作
   • Firecrawl 代理：用于高级网页抓取和研究

2. 按照每个示例目录中的指南操作

3. 使用 ADK Web 运行：

   # From the root tutorials directory
   adk web
   ​

示例 walkthrough

文件系统代理示例

# Connect to filesystem MCP server
toolset = MCPToolset(
    connection_params=StdioServerParameters(
        command='npx',
        args=['-y', '@modelcontextprotocol/server-filesystem', '/path/to/folder']
    )
)

# Ask agent to use filesystem tools
# "List files in the current directory"
# "Read the contents of sample.txt"
​

Firecrawl 代理示例

# Connect to Firecrawl MCP server
toolset = MCPToolset(
    connection_params=StdioServerParameters(
        command='npx',
        args=['-y', 'firecrawl-mcp'],
        env={'FIRECRAWL_API_KEY': 'your_api_key'}
    )
)

# Ask agent to use web scraping tools
# "Scrape the homepage of https://example.com"
# "Find all blog post URLs on https://blog.example.com"
# "Search for recent AI research papers and extract summaries"
# "Extract product details from this e-commerce page: [URL]"
​

最佳实践

• 连接管理：始终妥善处理连接生命周期
• 错误处理：针对网络问题实施健壮的错误处理
• 资源清理：使用正确的清理模式处理连接
• 安全性：验证输入并妥善处理身份验证
• 性能：考虑在高吞吐量场景下使用连接池

故障排除

常见问题

• 连接错误：检查服务器 URL 和网络连接
• 工具未找到：确认服务器正在运行且工具已暴露
• 身份验证：确保 API 密钥和凭据正确
• 版本兼容性：检查 MCP 协议版本兼容性

调试命令

# Test MCP server connection
npx @modelcontextprotocol/inspector

# Check ADK agent logs
adk web --debug
​

下一步

完成本教程后：

• 教程 4：记忆代理 - 添加记忆功能
• 教程 5：工作流代理 - 多步骤流程
• 教程 6：多代理系统 - 代理协作

更多资源

• MCP 规范 - 协议详细信息
• ADK MCP 文档 - 集成指南
• 社区 MCP 服务器 - 可直接使用的服务器

实际应用

MCP 工具可实现：

• 知识检索：访问维基百科、数据库、文档
• 文件操作：读取、写入、管理文件和目录
• API 集成：连接外部服务和 API
• 数据处理：转换和分析来自不同来源的数据
• 自定义工具：创建并共享跨代理的专用工具

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文语言版本的文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。