agentic-mobile-control/openspec/changes/apex-agent-mvp/specs/mcp-tool-server/spec.md

ADDED Requirements

Requirement: MCP tools expose capability layer without driver leakage

The system SHALL expose an MCP server whose tools (at minimum: take_screenshot, tap, swipe, input_text, launch_app, find_text, find_icon, get_ui_tree, describe_screen, list_devices, device_status) map directly to the capability/perception layer, with tool names, parameters, and return values containing no Appium/WDA/XCUIElement-specific concepts.

Scenario: MCP client calls a tool without framework knowledge

• WHEN an MCP-compatible LLM client (e.g. Claude Desktop) calls the tap tool with coordinates
• THEN the call succeeds by being routed through the capability layer to the underlying driver, and neither the tool schema nor its response exposes Appium/WDA-specific types or errors

Scenario: Tool list is stable across driver changes

• WHEN the underlying driver for a device changes (e.g. a future non-WDA driver is used) while the MCP tool set is unchanged
• THEN existing MCP tool calls continue to work without any change to tool names or parameter schemas

Requirement: MCP tool errors are semantic, not framework-specific

The system SHALL translate driver/framework-level errors (e.g. WDA connection errors, element-not-found) into clear, semantic MCP tool error responses (e.g. "device offline", "element not found") rather than passing raw framework exceptions through to the LLM.

Scenario: Device offline surfaces a clear error

• WHEN an MCP tool call targets a device that is currently offline
• THEN the tool call returns a semantic error indicating the device is unavailable, not a raw connection-refused/stack-trace style error

Requirement: REST API mirrors the same capability functions

The system SHALL provide a REST API (GET /devices, POST /devices/{id}/tap, POST /devices/{id}/screenshot, POST /devices/{id}/launch, POST /agent/task, GET /task/{id}) that calls the same underlying capability functions as the MCP tools, for manual testing and dashboard use.

Scenario: REST and MCP produce consistent results

• WHEN the same capability (e.g. screenshot) is invoked once via the REST API and once via the corresponding MCP tool for the same device
• THEN both calls exercise the same underlying capability function and produce equivalent results

Scenario: Starting a task via REST

• WHEN a caller POSTs a goal to /agent/task
• THEN the system creates a new task, returns its task id, and the task becomes queryable via GET /task/{id}