feat: add dcd-mcp stdio MCP server

[riglar]

What

Adds a local stdio MCP server shipped as a second bin (dcd-mcp) inside @devicecloud.dev/dcd, so AI agents (Claude, Cursor, VS Code) can drive devicecloud.dev. It's a third front-end onto the existing service layer — a sibling to src/commands/ — reusing resolveAuth, the gateways, and the same release-please pipeline. No auth or publishing rebuild.

Tools

Tool
dcd_list_devices	Discover devices / OS / Maestro versions
dcd_list_runs	List recent runs (filter, paginate)
dcd_get_status	Status + per-test results
dcd_download_artifacts	Download artifacts/report to disk
dcd_run_cloud_test	Submit a flow (billable)

dcd_run_cloud_test is async-by-default (returns uploadId, poll dcd_get_status), annotated destructive, and hidden under --read-only / DCD_MCP_READONLY=1. It also supports wait (bounded) and dryRun.

Design notes

• stdout is the JSON-RPC channel. Tools call services/gateways directly with a stderr logger — never the src/commands/* layer or utils/cli logger (both write stdout / can process.exit). Results go back via jsonResult/errorResult; runTool records telemetry and converts thrown errors to isError results.
• Auth is inherited from the CLI: DEVICE_CLOUD_API_KEY env or stored dcd login session; DCD_API_URL overrides the base URL. Resolved lazily + once, so tools/list works unauthenticated.
• Extracted computeCommonRoot/buildTestMetadataMap into src/services/flow-paths.ts and reused them from cloud.ts so the CLI and MCP build identical server-side paths (no copy-paste; covered by the existing cloud integration test).
• Hosted/remote (Streamable-HTTP + OAuth) deliberately deferred — would live in dcd/api + infra, not here.

Tests

pnpm test → 142 passing, including:

• test/unit/flow-paths.test.ts — the extracted path logic (guards the cloud.ts refactor)
• test/integration/mcp.integration.test.ts — spawns the built bin and drives it with the real MCP client against the mock API: tool discovery, read-only gate, destructive annotation, live list_runs/get_status round-trips (which prove stdout stays clean), and isError handling

Lint 0 errors · tsc src + test clean · pnpm build emits all MCP files (incl. shebang + chmod).

Distribution

• bin.dcd-mcp → dist/mcp/index.js; build script chmods it
• README MCP section (client config, read-only guidance, tool table)
• server.json registry manifest; CLAUDE.md architecture + entry-point docs

🤖 Generated with Claude Code

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.