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 通信
错误处理：针对网络和服务器问题的健壮错误管理
资源管理：正确清理连接和资源

先决条件

在运行这些示例之前：

安装依赖：
```
pip install -r requirements.txt
```

设置环境：


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

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


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

工作原理

连接流程

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

代码示例


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]
)

快速开始

快速入门

选择一个示例进行探索：
- 文件系统代理：用于文件操作
- Firecrawl 代理：用于高级网页抓取和研究
按照每个示例目录中的指南操作

使用 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 工具可实现：

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

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

作者与出处

原作者：Shubhamsaboo

来源：Shubhamsaboo

原文： https://github.com/Shubhamsaboo/awesome-llm-apps

许可证：Apache-2.0

整理人：灏天文库整理

由灏天文库结构化整理，提供目录导航、全文检索与在线阅读，便于系统化学习

MCP工具集成