> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 集成

> 通过 Model Context Protocol 将外部 AI 工具连接到 Zeus

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

## 端点

```
POST /mcp
```

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

## 配置

### Cursor / Claude Desktop

在 MCP 客户端配置中添加：

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

### 调试模式

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

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

## 可用工具

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

### desktop\_exec

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

```typescript theme={null}
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

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

```typescript theme={null}
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

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

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

**使用场景：**

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

### list\_workflows

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

```typescript theme={null}
list_workflows()
```

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

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

### execute\_workflow

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

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

### check\_desktop\_status

检查 Desktop App 连接状态。

```typescript theme={null}
check_desktop_status()
```

返回连接状态：

```json theme={null}
{
  "status": "connected",
  "nodes": 1,
  "node_ids": ["abc12345..."]
}
```

## 认证

MCP Gateway 支持两种认证方式：

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

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

## 架构

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

## 示例：在 Cursor 中使用 Zeus

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

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

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