文件系统代理-MCP集成

文件系统代理 - MCP 集成

本示例演示了如何使用 MCPToolset 将 ADK 代理连接到 文件系统 MCP 服务器。该代理可通过模型上下文协议执行文件操作，例如读取、写入和列出文件。

本示例展示的内容

• MCP 服务器连接：连接到 @modelcontextprotocol/server-filesystem
• 文件操作：读取、写入、列出文件和目录
• 标准输入输出通信：使用标准输入输出与本地 MCP 服务器进行通信
• 自动工具发现：让 ADK 发现并使用可用的文件系统工具

工作原理

MCP 服务器设置

代理连接到提供以下工具的文件系统 MCP 服务器：

• list_directory：列出文件和文件夹
• read_file：读取文件内容
• write_file：将内容写入文件
• create_directory：创建新目录

连接流程

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

开始使用

先决条件

1. Node.js 和 npm：文件系统 MCP 服务器所需
2. ADK 环境：已使用您的 Google AI API 密钥进行设置
3. 依赖项：从 requirements.txt 安装

运行代理

1. 导航到教程根目录：

   cd ai_agent_framework_crash_course/google_adk_tutorials/
   ​

2. 启动 ADK Web：

   adk web
   ​

3. 选择代理：从下拉菜单中选择 filesystem_mcp_agent

4. 测试命令：

   • “列出当前目录中的文件”
   • “读取 sample.txt 的内容”
   • “创建一个名为 hello.txt 的新文件，内容为 Hello World!”
   • “向我展示目录中的所有文本文件”

示例对话

列出文件

User: List files in the current directory
Agent: I'll list the files in the current directory for you.
[Uses list_directory tool]
Found the following files:
- sample.txt
- hello.txt
​

读取文件

User: Read the contents of sample.txt
Agent: I'll read the contents of sample.txt for you.
[Uses read_file tool]
The file contains:
This is a sample file for the MCP filesystem agent demonstration.
You can read, write, and list files using MCP tools.
​

写入文件

User: Create a new file called notes.txt with the content "Meeting notes for today"
Agent: I'll create the file notes.txt with your specified content.
[Uses write_file tool]
Successfully created notes.txt with the content "Meeting notes for today".
​

代码结构

代理定义

root_agent = LlmAgent(
    model='gemini-3-flash-preview',
    name='filesystem_mcp_agent',
    instruction="""
    You are a helpful filesystem assistant that can help users manage their files.
    You have access to filesystem tools through the Model Context Protocol (MCP).
    """,
    tools=[
        MCPToolset(
            connection_params=StdioServerParameters(
                command='npx',
                args=['-y', '@modelcontextprotocol/server-filesystem', DEMO_FOLDER]
            )
        )
    ]
)
​

演示环境

代理使用代理文件的父目录进行演示：

• 位置：filesystem_agent 文件夹的父目录
• 示例文件：包含演示内容的 sample.txt
• 工作目录：可被 MCP 服务器访问，以确保安全操作

️ 可用工具

文件系统 MCP 服务器会自动提供以下工具：

高级用法

工具过滤

MCPToolset(
    connection_params=StdioServerParameters(
        command='npx',
        args=['-y', '@modelcontextprotocol/server-filesystem', DEMO_FOLDER]
    ),
    tool_filter=['list_directory', 'read_file']  # Only expose specific tools
)
​

重要提示

• 安全性：MCP 服务器仅能访问指定目录
• Node.js 必需：文件系统服务器通过 npx 运行
• 工作目录：使用父目录以便轻松访问项目文件
• 错误处理：代理会优雅地处理文件未找到和权限错误

故障排除

常见问题

1. 未找到 Node.js：

   # Install Node.js
   # macOS: brew install node
   # Ubuntu: sudo apt install nodejs npm
   ​

2. 权限错误：

   • 确保目录可写
   • 检查文件权限

3. MCP 服务器未启动：

   • 确认 Node.js 是否安装
   • 检查端口是否可用
   • 查看控制台日志

调试命令

# Test MCP server directly
npx @modelcontextprotocol/server-filesystem /path/to/folder

# Run with debug logging
adk web --debug
​

下一步

在尝试本示例后：

1. 自定义目录：将 DEMO_FOLDER 更改为您的首选位置
2. 添加更多工具：探索其他 MCP 服务器
3. 尝试服务器代理：学习如何创建自定义 MCP 服务器
4. 与工作流集成：与其他 ADK 功能结合使用

相关文档

• ADK MCP 工具 - 官方文档
• MCP 文件系统服务器 - 服务器详细信息
• 模型上下文协议 - 协议规范

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