Servidor MCP de longarm

longarm expone un servidor MCP por HTTP streamable para integraciones con agentes.

Endpoint

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

Comprobación de estado:

GET /mcp

Ejemplo de respuesta:

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

Autenticación

Si la autenticación por token está activada, las solicitudes MCP deben incluir:

Authorization: Bearer <token>

Si la autenticación falla, el servidor devuelve:

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

Detalles del protocolo

transporte: HTTP streamable sobre POST /mcp
versión de JSON-RPC: 2.0
versión de protocolo MCP devuelta por longarm: 2025-06-18
métodos RPC soportados: initialize, ping, tools/list, tools/call
las respuestas de initialize incluyen un encabezado Mcp-Session-Id

Llamadas mínimas

`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"
    }
  }
}

Disponibilidad de herramientas

La disponibilidad de herramientas depende de la configuración de la app y del estado de la suscripción.

Siempre disponibles:

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

Solo Plus:

swipe
pinch
two_finger_swipe
rotate

Solo con inspección de UI y autenticación habilitadas:

ui_tree
ui_find
ui_wait
ui_action
ui_set_text
ui_scroll

Tareas por lotes grabadas

Cuando un usuario detiene una grabación en la pestaña Batch, longarm guarda los pasos capturados como una tarea por lotes normal y editable. Las tareas grabadas tienen la misma forma JSON y el mismo comportamiento que las tareas creadas manualmente — no existe un origen sin procesar separado ni un ciclo de vida de revisiones.

Los agentes usan las herramientas de lotes estándar para las tareas grabadas: batch_list y batch_get para inspeccionarlas, batch_save para actualizarlas o copiarlas, y batch_run para ejecutarlas. Si se debe conservar la secuencia original, guarda la versión editada con un id nuevo en lugar de actualizar la tarea existente.

Forma del resultado

Las llamadas a herramientas devuelven content (un elemento de tipo string JSON), structuredContent (el mismo resultado en JSON), e isError: true cuando el resultado a nivel de herramienta falló.

Ejemplo de resultado exitoso:

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

Ejemplo de fallo a nivel de herramienta:

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

Las llamadas MCP también aparecen en la vista de Logs con método MCP y rutas como tools/call/open_app.

Argumentos principales de las herramientas

`screen_info` / `current_window`

Ambas no reciben argumentos ({}). current_window devuelve el nombre de paquete de la ventana en primer plano y un nombre de actividad opcional y de mejor esfuerzo; el servicio de accesibilidad debe estar habilitado.

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

`tap`

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

También admite tap basado en selector:

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

`long_press`

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

Gestos 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"
}

Campos admitidos: action (obligatorio), data, mimeType, packageName, className, categories, extras.

`app_functions_query`

Descubre AppFunctions de las apps Android visibles para longarm. Todos los argumentos son opcionales:

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

El resultado incluye el functionId exacto, el estado habilitado y los metadatos de parámetros/retorno necesarios para una llamada. Se requiere soporte de Android AppFunctions y autorización; no se requiere accesibilidad.

`app_function_call`

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

Los argumentos se validan y codifican a partir de los metadatos de la AppFunction consultada. El Agent integrado en la app anuncia y ejecuta estas mismas definiciones de herramienta a través del mismo ejecutor que MCP.

Herramientas de UI

Campos del esquema de selector: 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" }

Herramientas de lotes

La estructura de las tareas por lotes y su comportamiento en tiempo de ejecución están documentados en Tareas por lotes.

Comportamiento específico de MCP:

batch_run y batch_run_inline devuelven inmediatamente runId y status: "processing"
batch_run y batch_run_inline admiten un booleano opcional keepScreenOn (por defecto false) que mantiene la pantalla encendida hasta que termina la ejecución; el botón de encendido sigue apagando la pantalla
batch_status devuelve el estado actual del runner:

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

batch_history_export devuelve un payload ZIP en base64, no binario sin procesar:

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