valkryhx/google_adk_agent / skills/dynamic-mcp
Dynamic MCP Loader
Verified动态 MCP 工具加载器,支持运行时连接远程 HTTP/SSE MCP 服务或启动本地 MCP 进程,让 Agent 根据需求即时扩展能力。适用于用户提到不熟悉的 MCP 服务时,通过搜索发现连接方式后动态加载。
tools.py
View on GitHub"""
Dynamic MCP Loader Skill - 动态 MCP 工具加载器
提供运行时动态加载 MCP 服务的能力,支持远程 HTTP/SSE 连接和本地进程启动。
Agent 可以根据搜索结果自主发现并加载新的 MCP 工具,实现能力的即时扩展。
"""
import os
import shutil
import asyncio
from typing import List, Optional, Dict, Literal, Tuple
from urllib.parse import urlparse
# ADK 核心组件
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import (
StdioServerParameters,
StreamableHTTPConnectionParams
)
def get_tools(agent, session_service, app_info) -> List:
"""
返回动态 MCP 加载工具
利用 ADK 的依赖注入机制,获取当前 agent 实例,从而能够在运行时
修改 agent.tools 列表,实现动态工具挂载。
"""
# --- 安全配置 ---
ALLOWED_LOCAL_COMMANDS = {"npx", "npx.cmd", "uvx", "node", "python", "python3",'cmd', 'cmd.exe'}
def _is_safe_arg(arg: str) -> bool:
"""防止 Shell 注入攻击"""
dangerous_chars = ['|', '>', '<', ';', '&', '`', '$(']
return not any(char in arg for char in dangerous_chars)
# async def _wrap_mcp_tool(original_tool, mcp_identifier: str):
# """
# 包装 MCP 工具,提供断线检测和友好错误提示
# Args:
# original_tool: 原始 MCP 工具函数
# mcp_identifier: MCP 服务标识符(用于错误提示)
# Returns:
# 包装后的工具函数
# """
# async def wrapped(*args, **kwargs):
# try:
# # 调用原始工具
# return await original_tool(*args, **kwargs)
# except Exception as e:
# err_msg = str(e)
# # 检测常见的断线错误特征
# disconnect_keywords = [
# "all connection attempts failed",
# "session termination failed",
# "connection closed",
# "disconnect",
# "shutdown",
# "connection error",
# "not connected"
# ]
# if any(keyword in err_msg.lower() for keyword in disconnect_keywords):
# # 返回友好的断线提示,而非抛出异常
# return (
# f"[MCP 连接已断开] {mcp_identifier} 服务不可用。\n\n"
# f"可能原因:\n"
# f"1. 浏览器进程已关闭\n"
# f"2. MCP 服务意外退出\n"
# f"3. 网络连接中断\n\n"
# f"建议操作: 使用 connect_mcp 重新连接"
# )
# # 其他异常正常抛出
# raise
# # 保持原函数的元数据
# wrapped.__name__ = getattr(original_tool, '__name__', 'unknown_tool')
# wrapped.__doc__ = getattr(original_tool, '__doc__', '')
# return wrapped
async def _verify_mcp_connection(toolset: McpToolset, timeout: int = 10) -> Tuple[bool, str]:
"""
验证 MCP 连接并主动触发工具发现
Args:
toolset: McpToolset 实例
timeout: 超时时间(秒)
Returns:
(成功标志, 消息)
"""
try:
# 【关键修复】直接调用 get_tools() 而非等待后检查属性
# 这与测试脚本的成功方式一致
tools = await asyncio.wait_for(toolset.get_tools(), timeout=timeout)
if tools:
# 优先使用 name 属性(MCPTool的标准属性),其次才是 __name__
tool_names = [getattr(t, 'name', getattr(t, '__name__', str(t))) for t in tools]
return True, f"成功发现 {len(tools)} 个工具: {', '.join(tool_names[:3])}{'...' if len(tools) > 3 else ''}"
# 理论上不会到达这里(get_tools 应该返回列表或抛出异常)
return False, "未发现工具,连接可能失败"
except asyncio.TimeoutError:
return False, f"连接超时({timeout}秒内未响应),请检查服务地址和端口"
except ConnectionError as e:
# 捕获我们主动抛出的连接错误
return False, f"无法连接到 MCP 服务: {str(e)}"
except BaseException as e:
error_msg = str(e)
# 友好化错误消息
if "401" in error_msg or "Unauthorized" in error_msg:
return False, "认证失败,请检查 API Key 是否正确"
elif "403" in error_msg or "Forbidden" in error_msg:
return False, "访问被拒绝,请确认 API Key 权限"
elif "ConnectError" in error_msg or "connection" in error_msg.lower():
return False, "无法连接到 MCP 服务,请确认服务地址和端口是否正确"
elif "network" in error_msg.lower():
return False, f"网络连接失败: {error_msg}"
else:
return False, f"连接失败: {error_msg}"
async def connect_mcp(
mode: Literal["remote", "local"],
source: str,
args: Optional[List[str]] = None,
env_vars: Optional[Dict[str, str]] = None,
api_key: Optional[str] = None
) -> str:
"""
[全能加载器] 连接远程 MCP 服务或启动本地 MCP 进程,以动态扩展 Agent 能力。
Args:
mode: 连接模式。
- 'remote': 连接 HTTP/SSE 服务 (如 Context7, Exa)。
- 'local': 启动本地命令行工具 (如 npx, python)。
source:
- 当 mode='remote' 时,填写 URL (如 'https://mcp.context7.com/mcp')。
- 当 mode='local' 时,填写基础命令 (如 'npx', 'python')。
args:
- 当 mode='local' 时必填。参数列表 (如 ['-y', '@modelcontextprotocol/server-git'])。
- 当 mode='remote' 时忽略。
env_vars:
- (可选) 本地模式专用。需要注入的环境变量 (例如 {'BRAVE_API_KEY': '...'})。
api_key:
- (可选) 远程模式专用。API Key,用于远程服务认证。
- 智能检测服务类型:
* Context7 (context7.com): 使用 'CONTEXT7_API_KEY' header
* 其他服务: 使用 'Authorization: Bearer {api_key}' header
- 格式示例:'ctx7sk-xxx' (Context7) 或 'mcp_sk_xxx' (标准服务)
Returns:
执行结果信息字符串
"""
# 1. 初始化变量
connection_params = None
if args is None:
args = []
if env_vars is None:
env_vars = {}
# 2. 分支逻辑处理
try:
# ============================
# 分支 A: 远程 HTTP/SSE 模式
# ============================
if mode == "remote":
if not source.startswith("http"):
return f"[Error] 远程模式下 source 必须是 HTTP/HTTPS URL,收到: {source}"
target_url = source
# A-1. 远程去重检查
for tool in agent.tools:
if isinstance(tool, McpToolset) and hasattr(tool, 'connection_params'):
if isinstance(tool.connection_params, StreamableHTTPConnectionParams):
# 简单的 URL 比较 (忽略末尾斜杠)
if tool.connection_params.url.rstrip('/') == target_url.rstrip('/'):
return f"无需重复连接:已连接到远程服务 {target_url}"
# A-2. 配置参数(支持 API Key 认证)
headers = {
# 必需的 MCP SSE headers(很多服务器要求这两个)
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json"
}
# 添加认证 header
if api_key:
# 智能检测服务类型并使用对应的 header
if "context7.com" in target_url.lower():
# Context7 使用自定义 header
headers["CONTEXT7_API_KEY"] = api_key
print(f"[DynamicMCP] 连接远程(Context7 认证): {target_url}")
else:
# 标准 MCP 服务使用 Bearer token
headers["Authorization"] = f"Bearer {api_key}"
print(f"[DynamicMCP] 连接远程(Bearer 认证): {target_url}")
else:
print(f"[DynamicMCP] 连接远程(无认证): {target_url}")
connection_params = StreamableHTTPConnectionParams(
url=target_url,
headers=headers
)
# ============================
# 分支 B: 本地 Process 模式
# ============================
elif mode == "local":
command = source
# B-1. 安全校验
if command not in ALLOWED_LOCAL_COMMANDS:
return f"[Security] 拒绝执行:命令 '{command}' 不在白名单中 ({ALLOWED_LOCAL_COMMANDS})。"
for arg in args:
if not _is_safe_arg(arg):
return f"[Security] 参数 '{arg}' 含非法字符,拒绝执行。"
if not shutil.which(command):
return f"[System] 找不到命令 '{command}'。请确保已安装 Node.js/Python 环境。"
# B-2. 本地去重检查
for tool in agent.tools:
if isinstance(tool, McpToolset) and hasattr(tool, 'connection_params'):
if isinstance(tool.connection_params, StdioServerParameters):
cp = tool.connection_params
if cp.command == command and cp.args == args:
return f"无需重复启动:本地服务 '{command} {args}' 已在运行。"
# B-3. 配置参数
final_env = os.environ.copy()
final_env.update(env_vars)
connection_params = StdioServerParameters(
command=command,
args=args,
env=final_env
)
print(f"[DynamicMCP] 启动本地: {command} {args}")
else:
return f"[Error] 未知的模式 '{mode}',仅支持 'remote' 或 'local'。"
# 3. 统一执行挂载与验证
if connection_params:
new_toolset = McpToolset(connection_params=connection_params)
# 【关键优化】主动验证连接并等待工具发现
print(f"[DynamicMCP] 正在验证连接...")
success, message = await _verify_mcp_connection(new_toolset, timeout=15)
if not success:
# 验证失败,不添加到 agent.tools
return f"[Error] {message}"
# 【关键修复】验证成功后,将 toolset 添加到 agent.tools
# 这一步是必需的,否则工具无法被 Agent 调用
agent.tools.append(new_toolset)
print(f"[DynamicMCP] 已将 MCP toolset 添加到 agent.tools")
# 【用户体验优化】构建详细的工具列表信息
tools = await new_toolset.get_tools()
display_limit = 1000
tool_lines = []
for i, tool in enumerate(tools[:display_limit], 1):
name = getattr(tool, 'name', 'unknown')
desc = getattr(tool, 'description', '')
# 只取描述的第一行,可以限制长度
desc = desc.strip().split('\n')[0][:]
tool_lines.append(f" {i}. `{name}` - {desc}")
if len(tools) > display_limit:
tool_lines.append(f" ... 还有 {len(tools) - display_limit} 个工具")
tools_list_text = '\n'.join(tool_lines)
# 返回格式化消息
return f"""✅ **{mode.upper()} MCP 连接成功**
📦 已加载 **{len(tools)}** 个工具到当前会话
🔧 **工具列表**:
{tools_list_text}
💡 现在可以直接调用这些工具了。"""
except BaseException as e:
return f"[Error] 加载 MCP 失败: {str(e)}"
return "[Error] 未知逻辑错误"
return [connect_mcp]
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |