MCP 集成 - Zeus

Zeus 通过 Model Context Protocol (MCP) 对外暴露桌面自动化能力，允许 Cursor、Claude Desktop 等外部 AI 工具直接使用 Zeus 强大的桌面自动化功能。

端点

POST /mcp

Zeus 提供 Streamable HTTP MCP 服务，供外部客户端连接。

配置

Cursor / Claude Desktop

在 MCP 客户端配置中添加：

{
  "mcpServers": {
    "zeus-desktop": {
      "url": "https://zeus-api.agentspro.cn/mcp",
      "headers": {
        "Authorization": "Bearer <jwt_token>"
      }
    }
  }
}

调试模式

本地开发时，设置环境变量 MCP_DEBUG_AUTH=true 启用调试认证：

{
  "mcpServers": {
    "zeus-desktop": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-User-Id": "<your_user_id>"
      }
    }
  }
}

可用工具

连接后，外部 MCP 客户端可以使用以下工具：

desktop_exec

在用户本地电脑上执行 shell 命令。

desktop_exec({
  command: "ls -la",
  cwd: "/path/to/directory",  // 可选
  timeout: 60000,             // 毫秒，默认 60 秒
  shell: "bash"               // 可选
})

使用场景：

文件操作：ls、cat、mkdir、mv、cp、rm、find、grep
版本控制：git status、git add、git commit、git push
包管理：npm install、pip install、brew install
编程工具：python、node 等

browser_read

从浏览器页面静默获取数据。

browser_read({
  profileId: "profile-id",
  action: "text" | "table" | "form" | "screenshot" | "html" | "url",
  selector: ".my-element"  // 可选 CSS 选择器
})

Action 类型：

text - 获取页面或元素的文本内容
table - 提取表格数据（返回二维数组）
form - 获取表单字段值（键值对）
screenshot - 页面截图（base64 PNG）
html - 获取 HTML 源码
url - 获取当前页面 URL

hitl_prompt

请求终端用户输入信息（用于验证码、确认等场景）。

hitl_prompt({
  title: "需要验证",
  message: "请输入短信验证码",
  timeout: 120,        // 秒
  inputType: "text"
})

使用场景：

短信/邮箱验证码输入
用户确认对话框
动态信息请求

list_workflows

列出 Desktop 上已发布的所有工作流工具。

list_workflows()

返回 JSON 数组，每个工作流包含：

name - 工具名称（以 workflow_ 为前缀）
description - 工具描述
inputSchema - 输入参数 JSON Schema

execute_workflow

执行已发布的工作流工具。

execute_workflow({
  workflow_name: "workflow_search_product",
  variables: '{"query": "手机", "price": "3000"}'  // JSON 字符串
})

check_desktop_status

检查 Desktop App 连接状态。

check_desktop_status()

返回连接状态：

{
  "status": "connected",
  "nodes": 1,
  "node_ids": ["abc12345..."]
}

认证

MCP Gateway 支持两种认证方式：

方式	Header	使用场景
JWT Token	`Authorization: Bearer <token>`	生产环境
调试模式	`X-User-Id: <user_id>`	开发环境（需设置 `MCP_DEBUG_AUTH=true`）

JWT Token 由 Better Auth 签发，使用 JWKS 验证（1 小时缓存）。

架构

┌─────────────────────────────────────┐
│  外部 MCP 客户端                     │
│  (Cursor, Claude Desktop 等)        │
└─────────────────────────────────────┘
                  │
                  │ Streamable HTTP
                  ▼
┌─────────────────────────────────────┐
│  Zeus MCP Gateway (/mcp)            │
│  - JWT 认证                         │
│  - 工具路由                         │
└─────────────────────────────────────┘
                  │
                  │ WebSocket
                  ▼
┌─────────────────────────────────────┐
│  Zeus Desktop App                   │
│  - Shell 命令执行                   │
│  - 浏览器自动化                     │
│  - 工作流引擎                       │
└─────────────────────────────────────┘

示例：在 Cursor 中使用 Zeus

在 Zeus Web 界面生成 API Token
配置 Cursor 的 MCP 设置
在 Cursor 中让 Claude 执行：

"使用 Zeus 列出我项目目录下的文件"
"对当前浏览器页面截图"
"在我的项目文件夹中运行 npm install"

Claude 会通过 Zeus MCP 工具在你的电脑上执行这些命令。

​端点

​配置

​Cursor / Claude Desktop

​调试模式

​可用工具

​desktop_exec

​browser_read

​hitl_prompt

​list_workflows

​execute_workflow

​check_desktop_status

​认证

​架构

​示例：在 Cursor 中使用 Zeus

端点

配置

Cursor / Claude Desktop

调试模式

可用工具

desktop_exec

browser_read

hitl_prompt

list_workflows

execute_workflow

check_desktop_status

认证

架构

示例：在 Cursor 中使用 Zeus