Google ADK-Python项目中MCPToolset在Windows平台上的兼容性问题解析

问题背景

在Google ADK-Python项目中，开发者使用MCPToolset.from_server方法连接MCP服务器时，在Windows平台上遇到了严重的兼容性问题。这个问题表现为当尝试通过npx启动ADK代理时，系统会抛出RuntimeError，其根源是Python的asyncio.subprocess模块中的NotImplementedError。

问题现象

当开发者在Windows 11系统上按照官方文档指引，使用Python 3.11至3.13版本运行示例代码时，会遇到以下错误链：

1. 首先触发asyncio.base_events中的NotImplementedError
2. 进而导致mcp/client/stdio/win32.py中的进程创建失败
3. 最终表现为RuntimeError: "error getting root agent"

技术分析

这个问题的核心在于Windows平台上Python的asyncio子进程处理机制存在限制。具体表现为：

1. 子进程传输层未实现：Windows平台上asyncio的_make_subprocess_transport方法直接抛出NotImplementedError，这表明底层子进程传输机制在Windows上尚未完全实现。

2. 异步上下文管理问题：错误发生在尝试通过async_exit_stack管理MCPToolset的异步上下文时，表明工具集的初始化过程依赖于子进程创建。

3. 版本兼容性：该问题在Python 3.11至3.13版本中均存在，说明这不是某个特定版本的回归问题，而是Windows平台上的长期限制。

解决方案演进

项目团队已经针对此问题进行了架构调整：

1. API简化：移除了显式的exit_stack管理需求，简化了工具集的使用方式。

2. 直接集成方式：推荐开发者直接将MCPToolset作为工具列表的一部分传递给LlmAgent，而不是单独初始化。

3. 路径处理改进：强调必须使用绝对路径，并推荐使用os.path.abspath动态构建路径。

最佳实践建议

对于需要在Windows平台上使用ADK-Python项目的开发者，建议采用以下方式：

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

# 定义目标文件夹路径
TARGET_FOLDER_PATH = "your/relative/path"  # 替换为实际路径

root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='filesystem_assistant_agent',
    instruction='帮助用户管理他们的文件。您可以列出文件、读取文件等。',
    tools=[
        MCPToolset(
            connection_params=StdioServerParameters(
                command='npx',
                args=[
                    "-y",
                    "@modelcontextprotocol/server-filesystem",
                    os.path.abspath(TARGET_FOLDER_PATH),
                ],
            )
        )
    ],
)

注意事项

1. 路径规范：必须使用绝对路径，且确保npx进程有权限访问该路径。

2. 版本选择：建议从源码安装或等待1.10及以上版本发布，因为1.0版本仍存在一些问题。

3. 工具过滤：可通过tool_filter参数选择性暴露MCP服务器提供的工具，增强安全性。

总结

Windows平台上Python异步子进程处理的特殊性导致了ADK-Python项目中MCP工具集的初始化问题。项目团队通过简化API设计和改变使用模式解决了这一兼容性问题。开发者应遵循最新的使用规范，避免直接使用已被弃用的from_server方法，转而采用将MCPToolset直接集成到LlmAgent工具列表中的方式。这种调整不仅解决了Windows兼容性问题，还简化了代码结构，提高了易用性。