MCP（Model Context Protocol）

快速使用

violet_agents推荐通过以下示例调用。

TIP

若直接使用如下示例，请确保环境变量中存在 TAVILY_MCP_TOKEN, GITHUB_COPILOT_TOKEN 及其对应的值

from violet_agents import ReactAgent
from violet_agents import VioletAgentsLLM
from dotenv import load_dotenv
from violet_agents import ToolRegistry
from violet_agents import SearchToolsTool, MCPTool
import os

load_dotenv()
tool_registry = ToolRegistry()
tool_registry.register_tools(SearchToolsTool(get_deferTools_callback=tool_registry.get_defer_tools, search_strategy="subAgent"))
config = {
    "mcpServers": {
        # --- HTTP/Streamable HTTP 远程服务器 ---
        "github": {
            "url": "https://api.githubcopilot.com/mcp/",
            "transport": "http",               # "http" | "streamable-http" | "sse"
            "headers": {                      # 自定义 HTTP 请求头
                "Authorization": f"Bearer {os.getenv('GITHUB_COPILOT_TOKEN')}",
            },
            # "auth": "oauth",                  # 认证方式: str (Bearer token) | "oauth" | httpx.Auth
            "timeout": 30000,                   # 超时时间 (毫秒)
        },
        "tavily": {
            "url": "https://mcp.tavily.com/mcp",
            "transport": "http",
            "headers": {
                "Authorization": f"Bearer {os.getenv('TAVILY_MCP_TOKEN')}",
            },
        },
    }
}
MCPTool(server_source=config, auto_expand=True).register_to(tool_registry, self_defer=False, expanded_defer=True)
agent = ReactAgent(
    name="VioletAgent",
    llm=VioletAgentsLLM(provider="deepseek", model="deepseek-v4-flash"),
    tool_registry=tool_registry
)
response = agent.run("我的github用户名是什么？简述https://violetagents.byteknight.top/里面的内容")
print(response.content)

MCPClient

这是本框架的 MCP 客户端，基于FastMCP开发。如果你想直接操控Client而不是让Agent操控Client，可以直接使用该类而不是使用MCPTool

server_source支持多种格式配置 MCP 服务器源：

• FastMCP 实例
• 字符串路径: Python 脚本路径（如 "server.py"）
• HTTP URL: 远程服务器（如 "https://api.example.com/mcp"）
• 命令列表: 完整命令（如 ["python", "server.py"]）
• 配置字典: 传输配置，详情请参考 fastmcp 文档

MCPTool

MCPTool类旨在搭建Agent和MCP Client的桥梁，如果你想要让Agent拥有访问外部的能力，请使用它

MCPTool构造函数参数说明

参数	类型	默认值	说明
name	str	mcp_tool	工具名称（默认为"mcp_tool"）
description	VioletAgentsLLM	None	工具描述
server_source	Union[str, List[str], FastMCP, Dict[str, Any]]	None	服务器源，支持多种格式
server_args	Optional[List[str]]	None	服务器参数列表（可选）
env	Optional[Dict[str, str]]	None	环境变量字典（优先级最高，直接传递给MCP服务器）
env_keys	Optional[List[str]]	None	要从系统环境变量加载的key列表（优先级中等）
auto_expand	bool	False	是否自动展开工具（默认False）
tool_time_out	int	60	工具调用超时时间（秒）

server_source

server_source参数支持多种格式配置 MCP 服务器源，更推荐使用配置字典（使用配置字典可支持一个MCPTool连接多个MCP Server）：

• FastMCP 实例
• 字符串路径: Python 脚本路径（如 "server.py"）
• HTTP URL: 远程服务器（如 "https://api.example.com/mcp"）
• 命令列表: 完整命令（如 ["python", "server.py"]）
• 配置字典: 传输配置，详情请参考 fastmcp 文档

可以通过设置auto_expand的值选择是否自动展开工具（推荐auto_expand = True），默认auto_expand = False

auto_expand = False时

在实例化MCPTool时若没传递参数description，则description会显示连接了几个服务器、可用工具数量、以及使用方式。若传递了参数description，则显示传递的参数对应的数据。description的值最终会传递给Agent参考使用

auto_expand = True时

在实例化MCPTool时若没传递参数description，则description会显示连接了几个服务器、可用工具数量。若传递了参数description，则显示传递的参数对应的数据。description的值最终会传递给Agent参考使用。

MCPTool实例可通过get_expanded_tool()方法获取已连接MCP服务器的工具列表

若想注册MCP服务器的工具列表到工具注册表，violet_agents推荐使用register_to()方法注册

config = {
    "mcpServers": {
        # --- HTTP/Streamable HTTP 远程服务器 ---
        "github": {
            "url": "https://api.githubcopilot.com/mcp/",
            "transport": "http",               # "http" | "streamable-http" | "sse"
            "headers": {                      # 自定义 HTTP 请求头
                "Authorization": f"Bearer {os.getenv('GITHUB_COPILOT_TOKEN')}",
            },
            # "auth": "oauth",                  # 认证方式: str (Bearer token) | "oauth" | httpx.Auth
            "timeout": 30000,                   # 超时时间 (毫秒)
        },
        "tavily": {
            "url": "https://mcp.tavily.com/mcp",
            "transport": "http",
            "headers": {
                "Authorization": f"Bearer {os.getenv('TAVILY_MCP_TOKEN')}",
            },
        },
    }
}
MCPTool(server_source=config, auto_expand=True).register_to(tool_registry, self_defer=False, expanded_defer=True)

通常情况下，上述代码块还没能让Agent具备主动获取对应MCP工具的能力，为了让Agent具备此能力，我们还需要在注册表中注册SearchToolsTool

tool_registry.register_tools(SearchToolsTool(get_deferTools_callback=tool_registry.get_defer_tools, search_strategy="subAgent"))
config = {
    "mcpServers": {
        # --- HTTP/Streamable HTTP 远程服务器 ---
        "github": {
            "url": "https://api.githubcopilot.com/mcp/",
            "transport": "http",               # "http" | "streamable-http" | "sse"
            "headers": {                      # 自定义 HTTP 请求头
                "Authorization": f"Bearer {os.getenv('GITHUB_COPILOT_TOKEN')}",
            },
            # "auth": "oauth",                  # 认证方式: str (Bearer token) | "oauth" | httpx.Auth
            "timeout": 30000,                   # 超时时间 (毫秒)
        },
        "tavily": {
            "url": "https://mcp.tavily.com/mcp",
            "transport": "http",
            "headers": {
                "Authorization": f"Bearer {os.getenv('TAVILY_MCP_TOKEN')}",
            },
        },
    }
}
MCPTool(server_source=config, auto_expand=True).register_to(tool_registry, self_defer=False, expanded_defer=True)