# 聚浪 Auto MCP

MCP 是 `/v1` 公开服务层的 AI 适配器，不是另一套业务协议。REST 和 MCP 共用设备归属、scope、授权、工作流校验、幂等、限流、任务状态和审计规则。

- Streamable HTTP URL：`https://api.auto.julang.cn/mcp`
- 鉴权：`Authorization: Bearer jlk_...`
- 令牌创建：用户控制台“账号管理 → 创建访问令牌”
- 首版是资源服务器模式：客户端需手动配置 Bearer token，不提供动态 OAuth 授权码发放。

## 工具

| Tool | Scope | 作用 |
|---|---|---|
| `devices_list` | `devices:read` | 列出自己的 Android/iOS 设备 |
| `device_get` | `devices:read` | 读取一台设备 |
| `capabilities_list` | `capabilities:read` | 列出稳定能力原语 |
| `workflow_validate` | `tasks:write` | 白名单校验，不执行 |
| `task_create` | `tasks:write` | 幂等创建任务 |
| `task_get` | `tasks:read` | 读取状态/结果 |
| `task_cancel` | `tasks:write` | 协作式停止 |
| `task_logs` | `logs:read` | 读取结构化日志 |
| `script_validate` | `internal:execute` | 校验代码大小、权限、超时并返回 SHA-256，不执行 |
| `script_run` | `internal:execute` + `tasks:write` | 在自己的 Android/iOS 设备执行可信 JavaScript |

## AI 调用顺序

1. `devices_list` 或 `device_get` 确认目标设备。
2. `capabilities_list` 选择已声明的稳定能力；不猜测能力 ID。
3. 工作流先调 `workflow_validate`。
4. 若返回 `requiresConfirmation=true` 或能力 `risk != safe`，向用户清楚说明设备、操作和副作用，等待当次明确同意。
5. 调 `task_create`，使用新的 `idempotency_key`。网络重试必须复用原键。
6. 用 `task_get` 指数退避轮询；用户要求停止时调 `task_cancel`。
7. 需要解释执行过程时调 `task_logs`。

MCP server instructions 也明确规定：AI 不得在没有当次人工批准时自行把 `confirmation` 设为 `true`。

## 内部脚本工具

内部测试令牌可调用 `script_validate` 后再调用 `script_run`。调用方必须明确传入设备、代码、幂等键、超时、权限与网络策略。重试 `script_run` 时必须复用原幂等键；停止和结果查询继续使用 `task_cancel`、`task_get`、`task_logs`。

普通 AI 集成不应获得 `internal:execute`。该 scope 允许脚本使用端侧 JS Runtime 已实现的 UI、文件、存储和网络桥接能力。