MCP channel ignores `~/.agent-device/config.json` defaults (`iosXctestrunFile`): omitting the param on any tool call triggers the built-in runner build — even while an external-xctestrun runner for the same session is alive

[oyekissliu-ux]

Environment

• agent-device version: 0.19.3 (npm, latest at time of writing)
• Node: v24.15.0
• macOS: Darwin 25.4.0; Xcode: 26.6 (no Apple ID signed in — external xctestrun per feat(ios): support external xctest runner artifact #806, built manually with CODE_SIGN_STYLE=Manual)
• MCP client: Claude Code, server registered as agent-device mcp
• Device: physical iPhone 14
• ~/.agent-device/config.json:

{
  "iosXctestrunFile": "/Users/<user>/.agent-device/apple-runner/external-manual/Build/Products/AgentDeviceRunner_AgentDeviceRunnerUITests_iphoneos26.5-arm64.xctestrun"
}

Description

The CLI resolves iosXctestrunFile from ~/.agent-device/config.json, so on a machine set up with an external XCUITest runner artifact (#806) all CLI commands work with no extra flags.

The MCP channel does not apply those config defaults. Every MCP tool call must pass iosXctestrunFile explicitly; if it is omitted, the daemon falls back to the built-in runner build (xcodebuild build-for-testing) — even when a runner launched from the external xctestrun is already up and serving the very same session (request log shows ios_runner_session_reuse with "cache":"external" moments earlier).

On machines where the built-in build cannot sign — which is exactly the scenario the external-xctestrun escape hatch exists for (#806): no provisioning available, or Xcode not signed into an Apple ID — every omitted param costs a full failed build cycle:

Error (COMMAND_FAILED): xcodebuild build-for-testing failed
Hint: Install/select a valid iOS provisioning profile, or set AGENT_DEVICE_IOS_PROVISIONING_PROFILE.

The same call with iosXctestrunFile passed explicitly succeeds immediately (snapshot returns the full accessibility tree; screenshot writes a valid PNG). So the external runner path works over MCP — the only gap is default resolution.

Reproducible Demo

1. Configure iosXctestrunFile in ~/.agent-device/config.json pointing at an externally built xctestrun (feat(ios): support external xctest runner artifact #806).
2. CLI sanity check: agent-device open <bundleId> --device <name> --platform ios then agent-device snapshot -i — works with no xctestrun flag; runner comes up from the external artifact.
3. Via MCP (Claude Code), call the snapshot tool without iosXctestrunFile (the session's external runner is still alive at this point).

[thymikee]

Triage: valid MCP config-parity bug and AFK-ready. CLI applies config-backed defaults through resolveConfigBackedFlagDefaults; the MCP executor currently builds client configuration from tool input only, so an omitted iosXctestrunFile never receives the configured default.

Implementation scope: reuse the shared config-default resolution at the MCP command boundary while preserving normal precedence and command applicability.

Acceptance:

• A temporary ~/.agent-device/config.json value for iosXctestrunFile reaches the MCP client/daemon request when the tool argument is omitted.
• An explicit MCP tool value overrides the configured default.
• Commands that do not support the option remain unaffected.
• Regression coverage proves an existing external-xctestrun session can be reused without triggering the built-in runner build.