fix: make mcp discovery-only (#556)

Author: thymikee

README.md

@@ -55,13 +55,15 @@ If you install skills separately, keep the CLI on `agent-device >= 0.14.0`. Olde
 
 - **Agent + terminal**: in Cursor, Codex, Claude Code, Windsurf, and similar clients, run `agent-device` in the integrated terminal. Start planning with `agent-device help workflow`; CLI help is authoritative.
 - **Skills or rules**: install the skill with `npx skills add callstackincubator/agent-device`, use the bundled [agent-device skill](skills/agent-device/SKILL.md), or mirror it as a thin project rule, so the agent checks the installed version and reads `agent-device help workflow` before acting. Use `agent-device help react-native` for React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence.
-- **MCP router**: use `agent-device mcp` when an MCP-aware client needs install, status, and version-matched help discovery. MCP is intentionally a thin router; device automation still runs through CLI commands.
+- **MCP router**: use `agent-device mcp` when an MCP-aware client needs to discover the CLI package, install command, version check, and first help command. MCP is discovery-only; device automation still runs through terminal CLI commands.
 
 For client-specific setup, see [AI Agent Setup](https://incubator.callstack.com/agent-device/docs/agent-setup). For agent-readable docs, use [llms-full.txt](https://incubator.callstack.com/agent-device/llms-full.txt).
 
 ### MCP Router
 
-`agent-device` ships an official stdio MCP router for discovery-oriented clients. It exposes only `status`, `install`, and `help` tools plus workflow prompts/resources; it does not expose device automation or generic shell execution over MCP.
+`agent-device` ships an official stdio MCP router for discovery-oriented clients. It exposes only a `status` tool that returns structured CLI handoff guidance: npm package name, installed version, CLI command name, install command, verify command, starting help command, and an explicit note that automation happens through the CLI.
+
+MCP clients must not use this server as a device automation surface or generic shell runner. If the CLI is missing, agents should ask a human before installing or updating packages, then verify with `agent-device --version` and start with `agent-device help workflow`.
 
 Paste one of these into clients that accept `mcpServers`, such as Cursor project `.cursor/mcp.json` or user-level MCP settings.
 

server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.callstackincubator/agent-device",
   "title": "agent-device",
-  "description": "Discovery router for the agent-device CLI with status, install, help, prompts, and resources.",
+  "description": "Let AI agents inspect, control, and debug real iOS, Android, desktop, and TV apps",
   "repository": {
     "url": "https://github.com/callstackincubator/agent-device",
     "source": "github"

src/mcp/__tests__/router.test.ts

@@ -1,145 +1,103 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import { handleMcpMessage } from '../router.ts';
-import { handleMcpPayload } from '../server.ts';
 
-test('MCP router exposes status install and help tools only', () => {
+test('MCP initialize advertises discovery-only tool capability', () => {
   const response = handleMcpMessage({
     jsonrpc: '2.0',
     id: 1,
-    method: 'tools/list',
+    method: 'initialize',
+    params: {
+      protocolVersion: '2099-01-01',
+    },
   });
 
-  assert.equal(response?.jsonrpc, '2.0');
   assert.ok(response && 'result' in response);
-  const tools = (response.result as { tools: Array<{ name: string }> }).tools;
-  assert.deepEqual(
-    tools.map((tool) => tool.name),
-    ['status', 'install', 'help'],
-  );
+  const result = response.result as {
+    protocolVersion: string;
+    capabilities: Record<string, unknown>;
+  };
+  assert.equal(result.protocolVersion, '2025-11-25');
+  assert.deepEqual(result.capabilities, { tools: {} });
 });
 
-test('MCP help tool returns versioned workflow guidance', () => {
+test('MCP tools/list exposes only status', () => {
   const response = handleMcpMessage({
     jsonrpc: '2.0',
     id: 2,
-    method: 'tools/call',
-    params: {
-      name: 'help',
-      arguments: { topic: 'workflow' },
-    },
+    method: 'tools/list',
   });
 
   assert.ok(response && 'result' in response);
-  const result = response.result as { content: Array<{ text: string }>; isError: boolean };
-  assert.equal(result.isError, false);
-  assert.match(result.content[0]?.text ?? '', /agent-device help workflow/);
-  assert.match(result.content[0]?.text ?? '', /snapshot -i/);
+  const tools = (
+    response.result as { tools: Array<{ name: string; outputSchema?: { type: string } }> }
+  ).tools;
+  assert.deepEqual(
+    tools.map((tool) => tool.name),
+    ['status'],
+  );
+  assert.equal(tools[0]?.outputSchema?.type, 'object');
 });
 
-test('MCP install tool can return npx client config', () => {
+test('MCP status tool returns structured CLI handoff guidance', () => {
   const response = handleMcpMessage({
     jsonrpc: '2.0',
     id: 3,
     method: 'tools/call',
     params: {
-      name: 'install',
-      arguments: { global: false, client: 'Cline' },
+      name: 'status',
     },
   });
 
   assert.ok(response && 'result' in response);
-  const result = response.result as { content: Array<{ text: string }> };
-  const text = result.content[0]?.text ?? '';
-  assert.match(text, /npx -y agent-device mcp/);
-  assert.match(text, /"args": \["-y","agent-device","mcp"\]/);
-  assert.match(text, /Client hint: Cline/);
-});
-
-test('MCP exposes help resources and workflow prompts', () => {
-  const resources = handleMcpMessage({
-    jsonrpc: '2.0',
-    id: 4,
-    method: 'resources/list',
-  });
-  assert.ok(resources && 'result' in resources);
-  const resourceUris = (resources.result as { resources: Array<{ uri: string }> }).resources.map(
-    (resource) => resource.uri,
-  );
-  assert.ok(resourceUris.includes('agent-device://help/workflow'));
-  assert.ok(resourceUris.includes('agent-device://help/react-native'));
-
-  const prompt = handleMcpMessage({
-    jsonrpc: '2.0',
-    id: 5,
-    method: 'prompts/get',
-    params: {
-      name: 'agent-device-dogfood',
-      arguments: { target: 'SampleApp on iOS' },
-    },
-  });
-  assert.ok(prompt && 'result' in prompt);
-  const result = prompt.result as { messages: Array<{ content: { text: string } }> };
-  assert.match(result.messages[0]?.content.text ?? '', /dogfood/);
-  assert.match(result.messages[0]?.content.text ?? '', /SampleApp on iOS/);
-});
-
-test('MCP React Native prompt routes to RN workflow guidance', () => {
-  const prompt = handleMcpMessage({
-    jsonrpc: '2.0',
-    id: 6,
-    method: 'prompts/get',
-    params: {
-      name: 'agent-device-react-native',
-    },
-  });
-
-  assert.ok(prompt && 'result' in prompt);
-  const result = prompt.result as { messages: Array<{ content: { text: string } }> };
-  assert.match(result.messages[0]?.content.text ?? '', /react-native/);
-});
-
-test('MCP initialize returns supported protocol version and unknown methods use JSON-RPC code', () => {
-  const initialized = handleMcpMessage({
-    jsonrpc: '2.0',
-    id: 6,
-    method: 'initialize',
-    params: {
-      protocolVersion: '2099-01-01',
-    },
-  });
-  assert.ok(initialized && 'result' in initialized);
-  assert.equal((initialized.result as { protocolVersion: string }).protocolVersion, '2025-11-25');
-
-  const unknown = handleMcpMessage({
-    jsonrpc: '2.0',
-    id: 7,
-    method: 'unknown/method',
-  });
-  assert.ok(unknown && 'error' in unknown);
-  assert.equal(unknown.error.code, -32601);
-});
-
-test('MCP batch requests return one JSON-RPC array response', () => {
-  const response = handleMcpPayload([
-    {
-      jsonrpc: '2.0',
-      id: 8,
-      method: 'ping',
-    },
-    {
-      jsonrpc: '2.0',
-      method: 'notifications/initialized',
-    },
-    {
-      jsonrpc: '2.0',
-      id: 9,
-      method: 'tools/list',
-    },
-  ]);
+  const result = response.result as {
+    content: Array<{ text: string }>;
+    isError: boolean;
+    structuredContent: {
+      packageName: string;
+      cliCommandName: string;
+      installCommand: string;
+      verifyCommand: string;
+      startingHelpCommand: string;
+      supportedTargets: string[];
+      capabilities: string[];
+      prerequisites: string[];
+      docsUrl: string;
+      agentDocsUrl: string;
+      firstCommands: string[];
+      automationInterface: string;
+      automationNote: string;
+      installRequiresHumanApproval: boolean;
+      installSafetyNote: string;
+    };
+  };
+  assert.equal(result.isError, false);
 
-  assert.ok(Array.isArray(response));
-  assert.equal(response.length, 2);
-  assert.equal(response[0]?.id, 8);
-  assert.equal(response[1]?.id, 9);
+  const handoff = result.structuredContent;
+  assert.deepEqual(JSON.parse(result.content[0]?.text ?? ''), handoff);
+  assert.equal(handoff.packageName, 'agent-device');
+  assert.equal(handoff.cliCommandName, 'agent-device');
+  assert.equal(handoff.installCommand, 'npm install -g agent-device@latest');
+  assert.equal(handoff.verifyCommand, 'agent-device --version');
+  assert.equal(handoff.startingHelpCommand, 'agent-device help workflow');
+  assert.ok(handoff.supportedTargets.includes('ios-simulator'));
+  assert.ok(handoff.supportedTargets.includes('android-emulator'));
+  assert.ok(handoff.capabilities.includes('inspect-ui'));
+  assert.ok(handoff.capabilities.includes('interact-with-elements'));
+  assert.ok(handoff.capabilities.includes('accessibility-snapshot'));
+  assert.ok(handoff.capabilities.includes('react-native'));
+  assert.ok(handoff.capabilities.includes('expo'));
+  assert.ok(handoff.capabilities.includes('android-adb'));
+  assert.ok(handoff.capabilities.includes('ios-xcuitest'));
+  assert.ok(handoff.prerequisites.includes('node>=22'));
+  assert.ok(handoff.prerequisites.includes('xcode-for-ios'));
+  assert.ok(handoff.prerequisites.includes('android-sdk-adb-for-android'));
+  assert.equal(handoff.docsUrl, 'https://agent-device.dev/');
+  assert.equal(handoff.agentDocsUrl, 'https://incubator.callstack.com/agent-device/llms-full.txt');
+  assert.ok(handoff.firstCommands.includes('agent-device apps --platform ios'));
+  assert.ok(handoff.firstCommands.includes('agent-device apps --platform android'));
+  assert.equal(handoff.automationInterface, 'cli');
+  assert.match(handoff.automationNote, /discovery-only/);
+  assert.equal(handoff.installRequiresHumanApproval, true);
+  assert.match(handoff.installSafetyNote, /human has approved/);
 });