2.5 KiB
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
taptool 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}