longarm MCP 服务器

longarm 提供 streamable HTTP MCP 服务器，用于 Agent 集成。

端点

http://<host>:<mcpPort>/mcp

健康检查：

GET /mcp

响应示例：

{ "status": "running", "transport": "mcp" }

认证

如果启用了 token 认证，MCP 请求必须包含：

Authorization: Bearer <token>

认证失败时，服务器返回：

{ "error": "Missing or invalid bearer token" }

协议细节

传输方式：通过 POST /mcp 使用 streamable HTTP
JSON-RPC 版本：2.0
longarm 返回的 MCP 协议版本：2025-06-18
支持的 RPC 方法：initialize、ping、tools/list、tools/call
initialize 响应会包含 Mcp-Session-Id 头

最小调用示例

`initialize`

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

`tools/list`

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

`tools/call`

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "open_app",
    "arguments": {
      "packageName": "com.android.settings"
    }
  }
}

工具可用性

工具可用性取决于应用设置和订阅状态。

始终可用：

screen_info
current_window
tap
long_press
open_app
open_intent
app_functions_query
app_function_call
batch_list
batch_get
batch_save
batch_delete
batch_run
batch_run_inline
batch_status
batch_history_list
batch_history_get
batch_history_export
batch_history_delete

Plus 专属：

swipe
pinch
two_finger_swipe
rotate

仅在启用 UI 检查且认证保持开启时可用：

ui_tree
ui_find
ui_wait
ui_action
ui_set_text
ui_scroll

录制的批处理任务

当用户在 Batch 标签页停止录制时，longarm 会将捕获的步骤保存为普通的、可编辑的批处理任务。录制任务与手动创建的任务具有相同的 JSON 结构和行为 —— 不存在单独的原始来源或版本生命周期。

Agent 使用标准的批处理工具处理录制任务：用 batch_list 和 batch_get 查看，用 batch_save 更新或复制，用 batch_run 执行。如果需要保留原始序列，应将编辑后的版本保存为新 id，而不是更新现有任务。

结果结构

工具调用返回 content（一个 JSON 字符串条目）、structuredContent （同样的结果，以 JSON 形式给出），以及在工具级结果失败时的 isError: true。

成功结果示例：

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\":true}"
    }
  ],
  "structuredContent": {
    "success": true
  }
}

工具级失败示例：

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\":\"Batch task not found\"}"
    }
  ],
  "structuredContent": {
    "error": "Batch task not found"
  },
  "isError": true
}

MCP 调用也会显示在 Logs 视图中，方法为 MCP，路径类似 tools/call/open_app。

核心工具参数

`screen_info` / `current_window`

两者都不需要参数（{}）。current_window 返回前台窗口的包名，以及一个尽力而为、可能为空的 activity 名称；需要启用无障碍服务。

{
  "packageName": "com.android.settings",
  "activityName": "com.android.settings.Settings"
}

`tap`

{ "x": 540, "y": 1200, "duration": 50 }

也支持基于选择器的 tap：

{
  "target": { "text": "Sign in", "role": "button" },
  "mode": "semantic_then_gesture"
}

`long_press`

{ "x": 540, "y": 1200, "duration": 1000 }

Plus 手势

// swipe
{ "startX": 540, "startY": 1800, "endX": 540, "endY": 600, "duration": 300 }

// pinch
{ "x": 540, "y": 1200, "startSpread": 400, "endSpread": 100, "angle": 0, "duration": 400 }

// two_finger_swipe
{ "startX": 540, "startY": 1800, "endX": 540, "endY": 600, "spread": 200, "duration": 400 }

// rotate
{ "x": 540, "y": 1200, "radius": 200, "startAngle": 0, "endAngle": 90, "duration": 600 }

`open_app`

{ "packageName": "com.android.settings" }

`open_intent`

{
  "action": "android.intent.action.VIEW",
  "data": "https://example.com"
}

支持的字段：action（必填）、data、mimeType、packageName、 className、categories、extras。

`app_functions_query`

发现 longarm 可见的 Android 应用中的 AppFunctions。所有参数均为可选：

{
  "packageNames": ["com.example.notes"],
  "schemaCategory": "productivity",
  "schemaName": "createNote",
  "minSchemaVersion": 1,
  "maxResults": 100
}

结果包含调用所需的准确 functionId、启用状态以及参数/返回值元数据。需要 Android AppFunctions 支持和授权；不需要无障碍服务。

`app_function_call`

{
  "packageName": "com.example.notes",
  "functionId": "createNote",
  "arguments": { "title": "Groceries" }
}

参数会根据查询到的 AppFunction 元数据进行校验和编码。应用内 Agent 通过与 MCP 相同的执行器发布并执行这些相同的工具定义。

UI 工具

选择器结构字段：nodeId、revision、text、contentDescription、 viewId、className、role、packageName、index、state、 ancestor、descendant。

// ui_tree
{ "window": "active", "maxDepth": 30, "maxNodes": 1000, "includeInvisible": false, "compact": false }

// ui_find
{ "selector": { "text": "Sign in", "role": "button" }, "limit": 20 }

// ui_wait
{ "selector": { "text": "Welcome" }, "condition": "exists", "timeoutMs": 5000, "stableForMs": 0 }

// ui_action
{ "selector": { "text": "Sign in" }, "action": "click", "fallback": "gesture" }

// ui_set_text
{ "selector": { "role": "input", "index": 0 }, "text": "[email protected]", "submit": false }

// ui_scroll
{ "selector": { "role": "list", "index": 0 }, "direction": "forward" }

批处理工具

批处理任务的结构和运行时行为见批处理任务。

MCP 特有的行为：

batch_run 和 batch_run_inline 会立即返回 runId 和 status: "processing"
batch_run 和 batch_run_inline 支持可选的布尔参数 keepScreenOn（默认 false），开启后会在运行期间保持屏幕常亮，运行结束后释放；按电源键仍会关闭屏幕
batch_status 返回当前运行器状态：

{
  "state": "idle",
  "currentTaskId": null,
  "currentRunId": null,
  "currentStepIndex": 0,
  "totalSteps": 0
}

batch_history_export 返回的是 base64 编码的 ZIP 内容，而不是原始二进制：

{
  "runId": "run_123",
  "zipBase64": "UEsDB..."
}

Longarm MCP 服务器

端点

认证

协议细节

最小调用示例

initialize

tools/list

tools/call