MCP: devices and apps return a top-level array as structuredContent, which spec-enforcing MCP clients (e.g. Claude Code) reject — the tools are unusable even though the daemon executes them successfully

[oyekissliu-ux]

Environment

• agent-device version: 0.19.3 (npm, latest at time of writing)
• Node: v24.15.0
• macOS: Darwin 25.4.0
• MCP client: Claude Code, server registered as agent-device mcp in mcpServers
• Device: physical iPhone 14 (also reproduces with no device connected — devices fails the same way)

Description

When agent-device is registered as an MCP server in Claude Code, calling the devices or apps tools always fails on the client side with a schema validation error, because the tool result's structuredContent is a JSON array.

Per the MCP specification, CallToolResult.structuredContent must be a JSON object, and clients are allowed to validate that. Claude Code does, so the call is rejected before the agent ever sees the result:

MCP server "agent-device" returned a malformed result that failed schema validation: [
  {
    "expected": "record",
    "code": "invalid_type",
    "path": [
      "structuredContent"
    ],
    "message": "Invalid input: expected record, received array"
  }
]

The daemon side is fine — events.ndjson shows both commands completing successfully at the exact time of the rejected calls:

{"st":"...","kind":"request.finished","command":"devices","status":"ok","summary":"Finished devices","details":{"durationMs":1791}}
{"st":"...","kind":"request.finished","command":"apps","status":"ok","summary":"Finished apps","details":{"durationMs":1818}}

So the failure is purely in the MCP result shape. Other tools we exercised (session, appstate, snapshot, screenshot, open) return object-shaped structuredContent and validate fine.

This effectively breaks the device-resolution step of any MCP-driven workflow in Claude Code: an agent cannot enumerate devices or installed apps through MCP and has to shell out to the CLI instead.

Reproducible Demo

1. Register agent-device as an MCP server in Claude Code (mcpServers: { "agent-device": { "command": "agent-device", "args": ["mcp"] } }).
2. From a Claude Code session, invoke the devices MCP tool (no parameters), or apps with a device selector.

[thymikee]

Triage: valid MCP protocol bug and AFK-ready. The daemon succeeds; the failure is at the MCP success-result projection in src/mcp/command-tools.ts, which currently assigns raw command results to structuredContent.

Implementation scope: guarantee object-shaped MCP structured content for array-returning commands without changing CLI/Node return contracts or agent-friendly text rendering.

Acceptance:

• devices and apps succeed in a spec-validating MCP client.
• Their structuredContent is an object with a deterministic envelope consistent with the advertised output schema.
• Existing object-returning commands and text output remain unchanged.
• Regression tests cover both array-returning commands and an existing object-returning command.