跳到主要内容

MCP 模块概览

MCP（Model Context Protocol）模块负责管理与外部 MCP 服务器的连接、工具发现、格式转换和调用执行。本模块采用分层架构，核心位于主进程（main），通过 IPC 暴露给渲染进程。

架构图​

graph TB
    subgraph Renderer["渲染进程"]
        McpPage["McpServersPage"]
        McpForm["McpServerForm"]
        McpManage["McpManageDialog"]
        UseMcp["useMcpMode Hook"]
        UseMgmt["useMcpManagement Hook"]
    end

    subgraph Main["主进程"]
        McpRouter["McpRouter<br/>(IPC 路由)"]
        McpService["McpService<br/>(连接池)"]
        ToolsLoader["ToolsLoader<br/>(格式转换)"]
        DepCheck["DependencyCheckService<br/>(依赖检查)"]

        subgraph Transports["传输层"]
            Stdio["StdioClientTransport"]
            SSE["SSEClientTransport"]
            HTTP["StreamableHTTPClientTransport"]
        end

        subgraph TinyElf["TinyElf 引擎"]
            McpAdapter["McpToolAdapter<br/>(ITool 封装)"]
            DirectAdapter["DirectMcpToolAdapter<br/>(内置服务器)"]
            Tracker["McpProcessTracker<br/>(进程追踪)"]
        end
    end

    subgraph Worker["Worker 线程"]
        McpWorker["mcp.worker.ts<br/>(CLI 桥接)"]
    end

    subgraph External["外部"]
        MCP1["MCP Server A<br/>(stdio)"]
        MCP2["MCP Server B<br/>(SSE/HTTP)"]
        ClaudeCLI["claude CLI"]
    end

    McpPage -->|IPC| McpRouter
    McpRouter --> McpService
    McpRouter --> DepCheck
    McpService --> Stdio
    McpService --> SSE
    McpService --> HTTP
    Stdio --> MCP1
    SSE --> MCP2
    HTTP --> MCP2
    McpService --> ToolsLoader
    McpService --> McpAdapter
    McpAdapter --> McpService
    DirectAdapter --> MCP1
    Tracker --> DirectAdapter
    McpWorker --> ClaudeCLI

关键文件​

文件路径职责
McpService.tsdesktop/app/main/services/capabilities/tools/mcp-users/连接池管理、客户端生命周期、工具缓存
ToolsLoader.tsdesktop/app/main/services/capabilities/tools/mcp-users/MCP 工具到 OpenAI/Anthropic/Gemini 格式的转换
DependencyCheckService.tsdesktop/app/main/services/capabilities/tools/mcp-users/命令行依赖检测与自动安装
McpRouter.tsdesktop/app/main/services/routers/IPC 路由注册，参数校验
McpToolAdapter.tsdesktop/app/main/services/agent-core/engine/tinyelf/tools/MCPTool 到 ITool 的适配器
McpProcessTracker.tsdesktop/app/main/services/agent-core/engine/tinyelf/tools/子进程 PID 追踪与清理
mcp.worker.tsdesktop/app/main/workers/Worker 线程，CLI 桥接
mcp-types.tsdesktop/app/shared/contracts/共享类型定义
mcp-presets.tsdesktop/app/shared/官方 MCP 服务器预设
mcp-detector.tsdesktop/app/main/lib/utils/MCP 配置检测工具
McpServersPage.tsxrenderer/src/pages/MCP 服务器管理页面
McpServerForm.tsxrenderer/src/features/settings/components/tabs/tools-tab/添加/编辑表单
McpManageDialog.tsxrenderer/src/features/marketplace/components/mcp/Agent 关联管理
useMcpMode.tsrenderer/src/features/marketplace/hooks/mcp/MCP 模式与工具选择 Hook
useMcpManagement.tsrenderer/src/features/settings/components/tabs/tools-tab/hooks/CRUD 管理 Hook

IPC 通道​

所有 MCP 相关 IPC 通道通过 McpRouter 注册，使用 secureHandle 进行认证：

通道方向参数返回值说明
mcp:listR→M无McpServerRecord[]列出所有服务器
mcp:addR→MMcpServerInputMcpActionResult添加服务器
mcp:addJsonR→MMcpServerJsonInputMcpActionResultJSON 批量添加
mcp:removeR→MMcpServerRemoveInputMcpActionResult删除服务器
mcp:updateR→M{ id, updates }McpActionResult更新服务器配置
mcp:testR→MMcpServerRemoveInputMcpTestResult测试连接
mcp:discoverR→MMcpServerRemoveInputMcpDiscoverResult发现工具/资源/提示词
mcp:list-server-toolsR→M{ serverId }MCPTool[]列出单个服务器的工具
mcp:list-all-toolsR→M无MCPTool[]列出所有活跃服务器的工具
mcp:call-toolR→M{ serverId, toolName, args, callId }MCPCallToolResponse调用工具
mcp:check-dependencyR→M{ command }DependencyCheckResult检查依赖
mcp:install-dependencyR→M{ command }DependencyInstallResult安装依赖

核心类型​

type McpServerTransport = 'stdio' | 'http' | 'sse';
type McpServerScope = 'user' | 'local';
type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
type McpMode = 'disabled' | 'auto' | 'manual';

interface McpServerRecord {
  id: string;
  name: string;
  scope: McpServerScope;
  type: McpServerTransport;
  config: McpServerConfig;
  isActive?: boolean;
  isTrusted?: boolean;
  disabledTools?: string[];
  installSource?: 'builtin' | 'manual' | 'protocol' | 'unknown';
  createdAt?: number;
  updatedAt?: number;
}

interface MCPTool {
  id: string;           // mcp__serverName__toolName
  serverId: string;
  serverName: string;
  name: string;
  description?: string;
  inputSchema: Record<string, any>;
  type: 'mcp';
}

模块间依赖关系​

graph LR
    McpRouter --> McpService
    McpRouter --> DependencyCheckService
    McpService --> ConfigStore["Electron Store<br/>(mcp-config)"]
    McpService --> MCP_SDK["@modelcontextprotocol/sdk"]
    ToolsLoader --> McpService
    McpToolAdapter --> McpService
    CompletionService["CompletionService"] --> ToolsLoader
    TinyElfEngine --> McpToolAdapter
    TinyElfEngine --> DirectMcpToolAdapter

数据流​

工具加载流程​

用户发起聊天
    ↓
CompletionService 调用 setupMcpTools()
    ↓
fetchMcpTools() 根据 MCP 模式决定加载哪些服务器
    ↓ (auto: 所有活跃服务器 / manual: 选中的服务器)
McpService.listServerTools() / listAllActiveServerTools()
    ↓ (检查缓存 → 命中返回 / 未命中则 initClient + listTools)
ToolsLoader 转换为目标格式 (OpenAI / Anthropic / Gemini)
    ↓
工具定义注入到 LLM 请求中

工具调用流程​

LLM 返回 tool_call (name = mcp__server__tool)
    ↓
解析服务器 ID 和工具名
    ↓
McpService.callTool(serverId, toolName, args, callId)
    ↓
initClient() 确保连接 → client.callTool()
    ↓
返回 MCPCallToolResponse (isError, content[])
    ↓
结果回传给 LLM 继续对话

相关文档​