MCP 服务架构文档

历史路径说明

文中出现的 archive/desktop-legacy/ 路径是历史实现位置。

继续开发时，请以当前 desktop/ 目录下的实现为准。

这篇文档暂时保留作架构整理参考，还没有进入首批正式导航。

概述

MCP (Model Context Protocol) 服务是一种标准化协议，用于 AI Agent 与外部工具/服务之间的通信。本项目实现了完整的 MCP 服务器管理功能，支持 stdio 和 HTTP 两种传输方式。

功能特性

1. MCP 服务器管理

功能	说明
创建服务器	支持 stdio 和 HTTP 两种传输类型
更新服务器	动态更新服务器配置
删除服务器	删除 MCP 服务器
测试连接	验证服务器连接状态
连接/断开	手动控制服务器连接
工具刷新	动态刷新可用工具列表

2. 传输类型

stdio 传输

• 通过标准输入输出与本地进程通信
• 适用于本地 MCP 服务
• 配置项：command, args, env

HTTP 传输

• 通过 HTTP API 与远程服务通信
• 适用于远程 MCP 服务
• 配置项：endpoint, headers

3. 服务器状态

状态	说明
created	已创建，未测试
testing	正在测试连接
connected	已连接
degraded	连接降级（部分功能可用）
disconnected	已断开
failed	连接失败

4. 自动重连机制

• 指数退避算法（上限 300 秒）
• 自动重连失败/降级的服务器
• 记录重连尝试次数

技术架构

目录结构

archive/desktop-legacy/src-tauri/src/
├── runtime/
│   ├── mcp.rs              # MCP 运行时核心
│   └── tools/
│       └── mcp.rs          # MCP 工具封装
├── commands/
│   └── mcp.rs              # Tauri 命令接口
archive/desktop-legacy/src/
├── services/
│   └── mcpApi.ts           # 前端 API 服务
└── pages/
    └── Agent/
        └── McpPage.tsx     # MCP 管理页面

核心模块

RuntimeState (Rust)

负责 MCP 服务器的运行时管理：

// 主要方法
list_mcp_servers()              // 列出所有 MCP 服务器
create_mcp_server()             // 创建 MCP 服务器
update_mcp_server()             // 更新 MCP 服务器
delete_mcp_server()             // 删除 MCP 服务器
test_mcp_server()               // 测试连接
connect_mcp_server()            // 连接服务器
disconnect_mcp_server()         // 断开服务器
refresh_mcp_server_tools()      // 刷新工具列表

McpApiService (TypeScript)

前端 MCP API 服务封装：

// 主要方法
listServers()                   // 获取服务器列表
createServer(payload)           // 创建服务器
updateServer(serverId, payload) // 更新服务器
deleteServer(serverId)          // 删除服务器
testServer(serverId)            // 测试连接
connectServer(serverId)         // 连接服务器
disconnectServer(serverId)      // 断开服务器
refreshServerTools(serverId)    // 刷新工具

API 接口

Tauri Commands

命令	参数	返回值
mcp_server_list	-	McpServer[]
mcp_server_create	name, transport, endpoint?, command?, args?, env?, headers?, metadata?, enabled?	{ success: boolean, id: string }
mcp_server_update	server_id, name?, transport?, endpoint?, command?, args?, env?, headers?, metadata?, enabled?	McpServer
mcp_server_delete	server_id	{ success: boolean }
mcp_server_test	server_id	{ success: boolean, error?: string }
mcp_server_connect	server_id	{ success: boolean }
mcp_server_disconnect	server_id	{ success: boolean }
mcp_server_refresh_tools	server_id, tools?	{ success: boolean, tools: Tool[] }

数据结构

interface McpServer {
  id: string;
  name: string;
  transport: 'stdio' | 'http';
  endpoint?: string;
  command?: string;
  args?: string[];
  env?: Record<string, string>;
  headers?: Record<string, string>;
  metadata?: Record<string, any>;
  enabled: boolean;
  status: 'created' | 'testing' | 'connected' | 'degraded' | 'disconnected' | 'failed';
  last_error?: string;
  last_checked_at?: string;
  created_at: string;
  updated_at: string;
}

前端页面

MCP 管理页面

路径：/pages/Agent/McpPage.tsx

功能：

• 查看 MCP 服务器列表
• 创建新服务器
• 编辑服务器配置
• 测试连接状态
• 连接/断开操作
• 删除服务器

使用示例

创建 stdio 类型服务器

await mcpApi.createServer({
  name: '本地文件系统服务',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/Users/user/docs'],
  enabled: true
});

创建 HTTP 类型服务器

await mcpApi.createServer({
  name: '远程 API 服务',
  transport: 'http',
  endpoint: 'https://api.example.com/mcp',
  headers: {
    'Authorization': 'Bearer token'
  },
  enabled: true
});

刷新工具列表

// 自动发现可用工具
await mcpApi.refreshServerTools(serverId);

// 或手动指定工具
await mcpApi.refreshServerTools(serverId, [
  { name: 'tool1', description: '工具1' },
  { name: 'tool2', description: '工具2' }
]);

错误处理

错误码	说明	处理建议
name cannot be empty	服务器名称为空	提供有效名称
server_id cannot be empty	服务器 ID 为空	检查服务器 ID
failed to connect	连接失败	检查服务器配置和网络
failed to lock sqlite	数据库锁定	重试操作
server not found	服务器不存在	验证服务器 ID

相关文件

• archive/desktop-legacy/src-tauri/src/runtime/mcp.rs - MCP 运行时核心
• archive/desktop-legacy/src-tauri/src/runtime/tools/mcp.rs - MCP 工具封装
• archive/desktop-legacy/src-tauri/src/commands/mcp.rs - Tauri 命令
• archive/desktop-legacy/src/services/mcpApi.ts - 前端 API
• archive/desktop-legacy/src/pages/Agent/McpPage.tsx - 前端页面