From ce50199672a2bcc3d30956a59bc25887fafcd915 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 11:06:40 +0100 Subject: [PATCH 01/10] feat(mcp)!: return text-only tool results by default; add mcp --structured Clients that receive structuredContent show the model that JSON and drop the compact text, so typed tools paid for the larger form. The MCP server now advertises no outputSchema and returns text only, on success and on error. `agent-device mcp --structured` restores output schemas and structuredContent; the AI SDK data host keeps always-structured results. JSON text renders compactly, and includeCost renders JSON text so the cost reaches text-only clients. The output-schema guard validates the structured server's schemas. Co-Authored-By: Claude Opus 5.5 --- docs/adr/0012-interactive-replay.md | 2 +- .../src/flag-definitions-connection.ts | 10 ++ .../src/schema/command-overrides.ts | 3 +- packages/contracts/src/cli-flags.ts | 1 + scripts/integration-progress-model.ts | 1 + src/__tests__/cli-exit-paths.test.ts | 4 +- src/ai-sdk/index.ts | 2 +- src/bin.ts | 4 +- src/cli.ts | 4 +- src/cli/entry.test.ts | 16 ++- src/cli/entry.ts | 14 ++- .../command-tools-gesture-tap.test.ts | 2 +- .../command-tools-input-docs.test.ts | 2 +- .../command-tools-operator-inputs.test.ts | 14 ++- .../command-tools-option-field.test.ts | 4 +- .../__tests__/command-tools-parity.test.ts | 14 ++- .../command-tools-structured-content.test.ts | 119 ++++++++++++++---- .../command-tools-system-schemas.test.ts | 4 +- .../command-tools-target-args.test.ts | 4 +- .../command-tools-timeout-note.test.ts | 6 +- src/mcp/__tests__/command-tools.test.ts | 79 ++++++------ src/mcp/__tests__/router-structured.test.ts | 75 +++++++++++ src/mcp/command-tools.ts | 78 +++++++----- src/mcp/router.ts | 57 +++++++-- src/mcp/server.ts | 42 ++++--- src/mcp/tool-control-fields.ts | 2 +- src/mcp/tool-input-config.test.ts | 2 + test/output-economy/mcp-output-schema.test.ts | 16 ++- website/docs/docs/agent-setup.md | 8 +- 29 files changed, 418 insertions(+), 171 deletions(-) create mode 100644 src/mcp/__tests__/router-structured.test.ts diff --git a/docs/adr/0012-interactive-replay.md b/docs/adr/0012-interactive-replay.md index 5cce34c76a..04d0c2023f 100644 --- a/docs/adr/0012-interactive-replay.md +++ b/docs/adr/0012-interactive-replay.md @@ -91,7 +91,7 @@ The report carries a bounded `screen`, ranked `suggestions`, one `repairHint` en - Capture failure never replaces or conceals the original replay cause. - Serialized ceilings are 8/24/64 KiB for the compact, default, and full response levels. Overflow goes to a redacted session-scoped artifact. - Entered text is never serialized. Native `.ad` replay replaces expanded variable values with `` in human-readable divergence fields. -- Every surface (daemon text, JSON, Node client `AppError`, MCP `structuredContent`) preserves the structured error. No surface may reduce divergence to text and discard repair data. +- Every surface (daemon text, JSON, Node client `AppError`, MCP text, and MCP `structuredContent` on a structured server) preserves the repair data. No surface may reduce divergence to text that discards it. The default MCP server returns text only, so its error text carries the step, the repair hint with the concrete resume command, the screen, and the suggestions. Resume is `replay --from N --plan-digest `. `N` is a 1-based index into the fully expanded executable plan. diff --git a/packages/command-registry/src/flag-definitions-connection.ts b/packages/command-registry/src/flag-definitions-connection.ts index 9a02452cbb..6850d78990 100644 --- a/packages/command-registry/src/flag-definitions-connection.ts +++ b/packages/command-registry/src/flag-definitions-connection.ts @@ -94,6 +94,16 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ projectConfig: false, recorded: false, }, + { + key: 'mcpStructured', + names: ['--structured'], + type: 'boolean', + usageLabel: '--structured', + usageDescription: + 'MCP: advertise tool output schemas and return structuredContent; results are text only by default', + projectConfig: false, + recorded: false, + }, { key: 'tenant', names: ['--tenant'], diff --git a/packages/command-surface/src/schema/command-overrides.ts b/packages/command-surface/src/schema/command-overrides.ts index b85a5930af..9d19f499c0 100644 --- a/packages/command-surface/src/schema/command-overrides.ts +++ b/packages/command-surface/src/schema/command-overrides.ts @@ -152,8 +152,9 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = { text: { summary: 'Start MCP server', description: - 'Start the official stdio MCP server. It exposes structured command tools backed by the agent-device client. It accepts no flags or arguments other than --help and --version; configure it with AGENT_DEVICE_* environment variables or AGENT_DEVICE_CONFIG.', + 'Start the official stdio MCP server. It exposes command tools backed by the agent-device client. Tool results are compact text. With --structured, tools also advertise output schemas and return structuredContent, for clients that read results as data. It accepts no other flags or arguments besides --help and --version; configure it with AGENT_DEVICE_* environment variables or AGENT_DEVICE_CONFIG.', }, + allowedFlags: ['mcpStructured'], }, proxy: { text: { diff --git a/packages/contracts/src/cli-flags.ts b/packages/contracts/src/cli-flags.ts index f233bb82a2..a30fe6ae91 100644 --- a/packages/contracts/src/cli-flags.ts +++ b/packages/contracts/src/cli-flags.ts @@ -43,6 +43,7 @@ export type CliFlags = CloudProviderProfileFields & daemonServerMode?: DaemonServerMode; proxyHost?: string; proxyPort?: number; + mcpStructured?: boolean; tenant?: string; sessionIsolation?: SessionIsolationMode; runId?: string; diff --git a/scripts/integration-progress-model.ts b/scripts/integration-progress-model.ts index 419db0630b..f019844d62 100644 --- a/scripts/integration-progress-model.ts +++ b/scripts/integration-progress-model.ts @@ -359,6 +359,7 @@ function summarizeProviderScenarioFlagExclusions() { 'textStdin', 'proxyHost', 'proxyPort', + 'mcpStructured', 'stale', ], }, diff --git a/src/__tests__/cli-exit-paths.test.ts b/src/__tests__/cli-exit-paths.test.ts index 733d30fe77..28efee9c67 100644 --- a/src/__tests__/cli-exit-paths.test.ts +++ b/src/__tests__/cli-exit-paths.test.ts @@ -19,7 +19,8 @@ import { runCli } from '../cli.ts'; import { runWebCommand } from '../cli/commands/web.ts'; import { exitAfterFlush } from '../cli/process-exit.ts'; -const MCP_ARGS_MESSAGE = 'mcp accepts no flags or arguments other than --help and --version.'; +const MCP_ARGS_MESSAGE = + 'mcp accepts no flags or arguments other than --structured, --help, and --version.'; import { installIsolatedCliTestEnv } from './cli-test-env.ts'; import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; import type { DaemonResponse } from '@agent-device/daemon-client'; @@ -278,6 +279,7 @@ test('#1596: a failing `test` suite exits 1 through the flushed exit path', asyn test.each([ { argv: ['mcp', '--json'], stream: 'stdout', message: MCP_ARGS_MESSAGE }, { argv: ['mcp', '--debug'], stream: 'stderr', message: MCP_ARGS_MESSAGE }, + { argv: ['mcp', '--structured', '--debug'], stream: 'stderr', message: MCP_ARGS_MESSAGE }, { argv: ['mcp', 'extra'], stream: 'stderr', diff --git a/src/ai-sdk/index.ts b/src/ai-sdk/index.ts index d9b1eb7a78..7ae00fc986 100644 --- a/src/ai-sdk/index.ts +++ b/src/ai-sdk/index.ts @@ -100,7 +100,7 @@ export async function createAgentDeviceTools( if (platform) hiddenFields.add('platform'); const tools: ToolSet = {}; - for (const definition of listCommandTools()) { + for (const definition of listCommandTools({ outputSchemas: true })) { if (set === 'core' && resolveCommandFrameworkTier(definition.name) !== 'core') continue; tools[definition.name] = tool({ diff --git a/src/bin.ts b/src/bin.ts index c42815e437..6d0dfc9a41 100644 --- a/src/bin.ts +++ b/src/bin.ts @@ -17,10 +17,10 @@ runEntry( mcp: async () => { const { runAgentDeviceMcpServer } = await import('./mcp/server.ts'); return { - runAgentDeviceMcpServer: async () => + runAgentDeviceMcpServer: async (options) => await withCommandHost( { host, requestEnv: undefined }, - async () => await runAgentDeviceMcpServer(), + async () => await runAgentDeviceMcpServer(options), ), }; }, diff --git a/src/cli.ts b/src/cli.ts index d49494ae63..d5e11c386b 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -311,9 +311,9 @@ async function parseCliInputOrExit( return await exitOnParseFailure( new AppError( 'INVALID_ARGS', - 'mcp accepts no flags or arguments other than --help and --version.', + 'mcp accepts no flags or arguments other than --structured, --help, and --version.', { - hint: 'Run agent-device mcp alone. Configure the server with AGENT_DEVICE_* environment variables or AGENT_DEVICE_CONFIG.', + hint: 'Run agent-device mcp or agent-device mcp --structured. Configure the server with AGENT_DEVICE_* environment variables or AGENT_DEVICE_CONFIG.', }, ), argv, diff --git a/src/cli/entry.test.ts b/src/cli/entry.test.ts index 8968bcf71c..7d8fc73c17 100644 --- a/src/cli/entry.test.ts +++ b/src/cli/entry.test.ts @@ -15,6 +15,7 @@ function harness(options: { bundledVersion?: string; cli?: EntryModules['cli'] } const stderr: string[] = []; const cliArgv: string[][] = []; const exits: number[] = []; + const mcpServers: Array<{ structured: boolean }> = []; const modules: EntryModules = { help: async () => { loaded.push('help'); @@ -32,7 +33,11 @@ function harness(options: { bundledVersion?: string; cli?: EntryModules['cli'] } }), mcp: async () => { loaded.push('mcp'); - return { runAgentDeviceMcpServer: async () => {} }; + return { + runAgentDeviceMcpServer: async (options) => { + mcpServers.push(options); + }, + }; }, version: async () => { loaded.push('version'); @@ -50,7 +55,7 @@ function harness(options: { bundledVersion?: string; cli?: EntryModules['cli'] } stdout: (text) => stdout.push(text), stderr: (text) => stderr.push(text), }); - return { run, loaded, stdout, stderr, cliArgv, exits }; + return { run, loaded, stdout, stderr, cliArgv, exits, mcpServers }; } test('every registered alias prints its canonical help without loading the CLI', async () => { @@ -88,13 +93,16 @@ test('no command prints usage and exits 1 after flushing', async () => { assert.deepEqual(entry.exits, [1]); }); -test('only a bare mcp starts the server; help prints usage and other arguments reach the CLI', async () => { +test('mcp and mcp --structured start the server; help prints usage and other arguments reach the CLI', async () => { const server = harness(); await server.run(['mcp']); - assert.deepEqual(server.loaded, ['mcp']); + await server.run(['mcp', '--structured']); + assert.deepEqual(server.loaded, ['mcp', 'mcp']); + assert.deepEqual(server.mcpServers, [{ structured: false }, { structured: true }]); for (const argv of [ ['mcp', '--state-dir', './sd'], + ['mcp', '--structured', '--json'], ['mcp', 'extra'], ['--json', 'mcp'], ]) { diff --git a/src/cli/entry.ts b/src/cli/entry.ts index b3e8b0b205..844979af8f 100644 --- a/src/cli/entry.ts +++ b/src/cli/entry.ts @@ -5,7 +5,7 @@ export type EntryModules = Readonly<{ resolveHelpTargetUsageText(target: string): string | null; }>; cli: () => Promise<{ runCliProcess(argv: string[]): Promise }>; - mcp: () => Promise<{ runAgentDeviceMcpServer(): Promise }>; + mcp: () => Promise<{ runAgentDeviceMcpServer(options: { structured: boolean }): Promise }>; version: () => Promise<{ readVersion(): string }>; processExit: () => Promise<{ exitAfterFlush(code: number): Promise }>; }>; @@ -33,7 +33,8 @@ async function dispatch(argv: string[], modules: EntryModules, io: EntryIo): Pro if (isVersionRequest(argv)) return await printVersion(modules, io); const helpTarget = simpleHelpTarget(argv); if (helpTarget !== undefined) return await printHelp(helpTarget, argv, modules, io); - if (isMcpServerRequest(argv)) return await (await modules.mcp()).runAgentDeviceMcpServer(); + const mcpServer = mcpServerRequest(argv); + if (mcpServer) return await (await modules.mcp()).runAgentDeviceMcpServer(mcpServer); await runCli(argv, modules); } @@ -68,9 +69,12 @@ function isVersionRequest(argv: string[]): boolean { return argv.length === 1 && (argv[0] === '--version' || argv[0] === '-V'); } -/** Only a bare `mcp` starts the server; the full CLI rejects any flag or argument beside it. */ -function isMcpServerRequest(argv: string[]): boolean { - return argv.length === 1 && argv[0] === 'mcp'; +/** Only `mcp` and `mcp --structured` start the server; the full CLI rejects any other argument. */ +function mcpServerRequest(argv: string[]): { structured: boolean } | undefined { + if (argv[0] !== 'mcp') return undefined; + if (argv.length === 1) return { structured: false }; + if (argv.length === 2 && argv[1] === '--structured') return { structured: true }; + return undefined; } /** `null` = general usage, a string = one command's help, `undefined` = not a help request. */ diff --git a/src/mcp/__tests__/command-tools-gesture-tap.test.ts b/src/mcp/__tests__/command-tools-gesture-tap.test.ts index 538a4d533c..325f56166a 100644 --- a/src/mcp/__tests__/command-tools-gesture-tap.test.ts +++ b/src/mcp/__tests__/command-tools-gesture-tap.test.ts @@ -5,7 +5,7 @@ import { createClientTransport } from '@agent-device/test-kit'; import { createCommandToolExecutor, listCommandTools } from '../command-tools.ts'; test('MCP gesture tool exposes tap contacts bounded to 2 to 5 points', () => { - const gesture = listCommandTools().find((tool) => tool.name === 'gesture'); + const gesture = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'gesture'); assert.ok(gesture); assert.deepEqual(gesture.inputSchema.properties?.points, { type: 'array', diff --git a/src/mcp/__tests__/command-tools-input-docs.test.ts b/src/mcp/__tests__/command-tools-input-docs.test.ts index 6fa1b5b79c..9849cbf5ec 100644 --- a/src/mcp/__tests__/command-tools-input-docs.test.ts +++ b/src/mcp/__tests__/command-tools-input-docs.test.ts @@ -141,7 +141,7 @@ const UNDESCRIBED_TOOL_INPUTS = new Set([ test('MCP tool inputs do not add undocumented properties', () => { const undescribed: string[] = []; - for (const tool of listCommandTools()) { + for (const tool of listCommandTools({ outputSchemas: true })) { for (const [key, schema] of Object.entries(tool.inputSchema.properties ?? {})) { if (!schema.description) undescribed.push(`${tool.name}.${key}`); } diff --git a/src/mcp/__tests__/command-tools-operator-inputs.test.ts b/src/mcp/__tests__/command-tools-operator-inputs.test.ts index 351fd32fa4..2e9e44dab9 100644 --- a/src/mcp/__tests__/command-tools-operator-inputs.test.ts +++ b/src/mcp/__tests__/command-tools-operator-inputs.test.ts @@ -46,7 +46,7 @@ const MODEL_WRITABLE_COMMON_KEYS = [ ] as const; test('MCP tool schemas advertise no operator-owned inputs', () => { - for (const tool of listCommandTools()) { + for (const tool of listCommandTools({ outputSchemas: true })) { const properties = tool.inputSchema.properties ?? {}; for (const key of OPERATOR_OWNED_KEYS) { assert.equal(key in properties, false, `${tool.name} advertises ${key}`); @@ -59,7 +59,7 @@ test('MCP tool schemas advertise no operator-owned inputs', () => { // assertions above would stay green while the model lost the ability to say // which device a call targets. test('MCP tool schemas keep every common input the model may write', () => { - const wait = listCommandTools().find((tool) => tool.name === 'wait'); + const wait = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'wait'); assert.ok(wait, 'expected an MCP tool named wait'); const properties = wait.inputSchema.properties ?? {}; for (const key of MODEL_WRITABLE_COMMON_KEYS) { @@ -89,7 +89,7 @@ test('MCP refuses every explicit operator-owned argument with guidance', async ( }); test('MCP neither advertises nor admits the retired readiness budget', async () => { - for (const tool of listCommandTools()) { + for (const tool of listCommandTools({ outputSchemas: true })) { const properties = tool.inputSchema.properties ?? {}; assert.equal('readinessTimeoutMs' in properties, false, `${tool.name} advertises it`); } @@ -245,7 +245,7 @@ test('MCP still resolves operator env values outside the model-writable surface' }); test('MCP neither advertises nor admits the CLI-only fill textStdin marker', async () => { - for (const tool of listCommandTools()) { + for (const tool of listCommandTools({ outputSchemas: true })) { const properties = tool.inputSchema.properties ?? {}; assert.equal('textStdin' in properties, false, `${tool.name} advertises it`); } @@ -274,7 +274,7 @@ test('MCP neither advertises nor admits the CLI-only fill textStdin marker', asy // so no schema offers the switch. The operator still sets it, through the environment or the user // config, and that value reaches the command route. test('MCP neither advertises nor admits the stabilization opt-out, and still resolves the operator default', async () => { - for (const tool of listCommandTools()) { + for (const tool of listCommandTools({ outputSchemas: true })) { const properties = tool.inputSchema.properties ?? {}; assert.equal('postGestureStabilization' in properties, false, `${tool.name} advertises it`); } @@ -316,7 +316,9 @@ test('MCP neither advertises nor admits the stabilization opt-out, and still res // The proxy lease device spec is not operator infrastructure, so the schema offers it (issue #3864). test('MCP open, install, reinstall and uninstall advertise the proxy lease device spec', () => { for (const name of ['open', 'install', 'reinstall', 'uninstall']) { - const tool = listCommandTools().find((candidate) => candidate.name === name); + const tool = listCommandTools({ outputSchemas: true }).find( + (candidate) => candidate.name === name, + ); assert.ok(tool, `expected an MCP tool named ${name}`); const properties = tool.inputSchema.properties ?? {}; for (const key of LEASE_DEVICE_SPEC_KEYS) { diff --git a/src/mcp/__tests__/command-tools-option-field.test.ts b/src/mcp/__tests__/command-tools-option-field.test.ts index 6a71ff4678..83462ad48a 100644 --- a/src/mcp/__tests__/command-tools-option-field.test.ts +++ b/src/mcp/__tests__/command-tools-option-field.test.ts @@ -25,7 +25,9 @@ async function toolPropertyWithPlantedOption( Object.assign(declaration, plant); const { listCommandTools } = await import('../command-tools.ts'); - const entry = listCommandTools().find((candidate) => candidate.name === tool); + const entry = listCommandTools({ outputSchemas: true }).find( + (candidate) => candidate.name === tool, + ); assert.ok(entry, `expected an MCP tool for ${tool}`); const found = entry.inputSchema.properties?.[property]; assert.ok(found, `expected the ${tool} tool to publish the ${property} input`); diff --git a/src/mcp/__tests__/command-tools-parity.test.ts b/src/mcp/__tests__/command-tools-parity.test.ts index ebed1e4b6e..c8088c4e6d 100644 --- a/src/mcp/__tests__/command-tools-parity.test.ts +++ b/src/mcp/__tests__/command-tools-parity.test.ts @@ -35,6 +35,7 @@ test('MCP collection results use object envelopes without changing object result wait: { waitedMs: 10 }, } satisfies Record<'devices' | 'apps' | 'wait', CommandExecutionResult>; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: () => ({}) as AgentDeviceClient, runCommand: async (_client, name) => results[name as keyof typeof results], }); @@ -57,7 +58,9 @@ test('MCP collection results use object envelopes without changing object result ['devices', devices], ['apps', apps], ] as const) { - const schema = listCommandTools().find((tool) => tool.name === name)?.outputSchema; + const schema = listCommandTools({ outputSchemas: true }).find( + (tool) => tool.name === name, + )?.outputSchema; assert.ok(schema, `${name} advertises an output schema`); assert.deepEqual(validateAgainstSchema(result.structuredContent, schema), []); } @@ -74,6 +77,7 @@ test('MCP open keeps device-selection evidence in structured content and JSON te }, }; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: () => ({}) as AgentDeviceClient, runCommand: async () => openResult, }); @@ -93,7 +97,7 @@ test('MCP advertises and round-trips the strict wait absent field', async () => return { waitedMs: 0 }; }, }); - const waitTool = listCommandTools().find((tool) => tool.name === 'wait'); + const waitTool = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'wait'); assert.equal( (waitTool?.inputSchema.properties?.absent as { type?: string } | undefined)?.type, 'string', @@ -126,11 +130,12 @@ test('MCP fill projects target-bound unconfirmed verification through its advert }, } satisfies CommandExecutionResult<'fill'>; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: () => ({}) as AgentDeviceClient, runCommand: async () => fillResult, }); - const fillTool = listCommandTools().find((tool) => tool.name === 'fill'); + const fillTool = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'fill'); assert.ok(fillTool?.outputSchema); assert.equal(fillTool.outputSchema, COMMAND_OUTPUT_SCHEMAS.fill); const unconfirmedBranch = fillTool.outputSchema.oneOf?.find( @@ -175,11 +180,12 @@ test('MCP fold advertises the native-panel discriminator and rejects a screen mi 'Folded to open (hinge 180°, LCD-1 native panel 669x951pt, not snapshot coordinates); refs from before the pose change are stale', } satisfies CommandExecutionResult<'fold'>; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: () => ({}) as AgentDeviceClient, runCommand: async () => foldResult, }); - const foldTool = listCommandTools().find((tool) => tool.name === 'fold'); + const foldTool = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'fold'); assert.ok(foldTool?.outputSchema); assert.equal(foldTool.outputSchema, COMMAND_OUTPUT_SCHEMAS.fold); diff --git a/src/mcp/__tests__/command-tools-structured-content.test.ts b/src/mcp/__tests__/command-tools-structured-content.test.ts index 5ec2f45386..76b8b86327 100644 --- a/src/mcp/__tests__/command-tools-structured-content.test.ts +++ b/src/mcp/__tests__/command-tools-structured-content.test.ts @@ -4,19 +4,65 @@ import type { AgentDeviceClient } from '@agent-device/command-surface'; import { AppError } from '@agent-device/kernel/errors'; import { createCommandToolExecutor } from '../command-tools.ts'; -test('MCP returns structuredContent for typed tools, and for untyped tools only on request', async () => { - const snapshotResult = { - nodes: [ - { ref: 'e2', type: 'Button', label: 'Save', rect: { x: 1.5, y: 2.5, width: 3, height: 4 } }, - ], - truncated: false, - }; - const executor = createCommandToolExecutor({ +const snapshotResult = { + nodes: [ + { ref: 'e2', type: 'Button', label: 'Save', rect: { x: 1.5, y: 2.5, width: 3, height: 4 } }, + ], + truncated: false, +}; + +function executorReturning( + structuredContent: 'declared' | 'always' | undefined, + result: (name: string) => unknown = (name) => + name === 'snapshot' ? snapshotResult : { message: 'Tapped @e2 (10, 20)' }, +) { + return createCommandToolExecutor({ createClient: () => ({}) as AgentDeviceClient, - runCommand: async (_client, name) => - name === 'snapshot' ? snapshotResult : { message: 'Tapped @e2 (10, 20)' }, + runCommand: async (_client, name) => result(name) as never, + ...(structuredContent ? { structuredContent } : {}), + }); +} + +test('the default executor returns text only, from typed and untyped tools', async () => { + const executor = executorReturning(undefined); + + const press = await executor.execute('press', { target: { kind: 'ref', ref: '@e2' } }); + const snapshot = await executor.execute('snapshot', {}); + const json = await executor.execute('snapshot', { mcpOutputFormat: 'json' }); + + assert.equal('structuredContent' in press, false); + assert.equal(press.content[0]?.text, 'Tapped @e2 (10, 20)'); + assert.equal('structuredContent' in snapshot, false); + assert.match(snapshot.content[0]?.text ?? '', /@e2 \[button\] "Save"/); + assert.equal('structuredContent' in json, false); + assert.deepEqual(JSON.parse(json.content[0]?.text ?? ''), snapshotResult); +}); + +test('the default executor returns a failed call as error text only', async () => { + const executor = executorReturning(undefined, () => { + throw new AppError('COMMAND_FAILED', 'snapshot failed'); }); + const result = await executor.execute('snapshot', {}); + + assert.equal(result.isError, true); + assert.equal('structuredContent' in result, false); + assert.match(result.content[0]?.text ?? '', /^Error \(COMMAND_FAILED\): snapshot failed/); +}); + +test('the default executor renders includeCost as JSON text, because the cost rides only on the data', async () => { + const waitResult = { waitedMs: 42, cost: { wallClockMs: 42, runnerRoundTrips: 0 } }; + const executor = executorReturning(undefined, () => waitResult); + + const result = await executor.execute('wait', { includeCost: true }); + + assert.equal('structuredContent' in result, false); + assert.deepEqual(JSON.parse(result.content[0]?.text ?? ''), waitResult); +}); + +test('declared returns structuredContent for typed tools, and for untyped tools only on request', async () => { + const executor = executorReturning('declared'); + const compact = await executor.execute('snapshot', {}); assert.equal(compact.structuredContent, undefined); assert.match(compact.content[0]?.text ?? '', /@e2 \[button\] "Save"/); @@ -29,12 +75,7 @@ test('MCP returns structuredContent for typed tools, and for untyped tools only }); test('a data host gets structuredContent from untyped tools by default', async () => { - const snapshotResult = { nodes: [{ ref: 'e2', label: 'Save' }], truncated: false }; - const executor = createCommandToolExecutor({ - createClient: () => ({}) as AgentDeviceClient, - runCommand: async () => snapshotResult, - structuredContent: 'always', - }); + const executor = executorReturning('always'); const result = await executor.execute('snapshot', {}); @@ -44,23 +85,17 @@ test('a data host gets structuredContent from untyped tools by default', async ( test.each([ ['a non-default responseLevel', { responseLevel: 'digest' }], ['includeCost', { includeCost: true }], -])('an untyped tool returns structuredContent with %s', async (_case, opt) => { - const executor = createCommandToolExecutor({ - createClient: () => ({}) as AgentDeviceClient, - runCommand: async () => ({ path: '/tmp/shot.png' }), - }); +])('declared returns structuredContent from an untyped tool with %s', async (_case, opt) => { + const executor = executorReturning('declared', () => ({ path: '/tmp/shot.png' })); const result = await executor.execute('screenshot', opt); assert.deepEqual(result.structuredContent, { path: '/tmp/shot.png' }); }); -test('a failed untyped tool still returns its error in structuredContent', async () => { - const executor = createCommandToolExecutor({ - createClient: () => ({}) as AgentDeviceClient, - runCommand: async () => { - throw new AppError('COMMAND_FAILED', 'snapshot failed'); - }, +test('declared returns a failed untyped tool error in structuredContent', async () => { + const executor = executorReturning('declared', () => { + throw new AppError('COMMAND_FAILED', 'snapshot failed'); }); const result = await executor.execute('snapshot', {}); @@ -68,3 +103,33 @@ test('a failed untyped tool still returns its error in structuredContent', async assert.equal(result.isError, true); assert.equal((result.structuredContent as { code?: string } | undefined)?.code, 'COMMAND_FAILED'); }); + +test('MCP command tool executor renders JSON text when requested', async () => { + const executor = createCommandToolExecutor({ + createClient: () => ({}) as AgentDeviceClient, + runCommand: async (_client, _name, input) => { + assert.deepEqual(input, {}); + return { + nodes: [ + { + ref: 'e1', + index: 0, + depth: 0, + type: 'Button', + label: 'Continue', + enabled: true, + }, + ], + truncated: false, + }; + }, + }); + + const result = await executor.execute('snapshot', { mcpOutputFormat: 'json' }); + + // Compact: JSON text is what a text-only client shows the model. + assert.equal( + result.content[0]?.text, + '{"nodes":[{"ref":"e1","index":0,"depth":0,"type":"Button","label":"Continue","enabled":true}],"truncated":false}', + ); +}); diff --git a/src/mcp/__tests__/command-tools-system-schemas.test.ts b/src/mcp/__tests__/command-tools-system-schemas.test.ts index 3ffdcdf27f..f3d893d962 100644 --- a/src/mcp/__tests__/command-tools-system-schemas.test.ts +++ b/src/mcp/__tests__/command-tools-system-schemas.test.ts @@ -195,7 +195,9 @@ test('MCP navigation output schemas advertise the closed dispatch shapes', () => }); test('MCP tv remote outputSchema accepts named buttons and raw codes and refuses other strings', () => { - const tvRemote = listCommandTools().find((tool) => tool.name === 'tv-remote'); + const tvRemote = listCommandTools({ outputSchemas: true }).find( + (tool) => tool.name === 'tv-remote', + ); assert.ok(tvRemote?.outputSchema); for (const button of ['up', 'volume-down', 'android-keycode:300', 'android-keycode:2147483647']) { assert.deepEqual( diff --git a/src/mcp/__tests__/command-tools-target-args.test.ts b/src/mcp/__tests__/command-tools-target-args.test.ts index af617e9b67..d19ffacb85 100644 --- a/src/mcp/__tests__/command-tools-target-args.test.ts +++ b/src/mcp/__tests__/command-tools-target-args.test.ts @@ -53,7 +53,7 @@ test('an unknown argument answers with a call example the tool accepts', async ( test('every tool hint example is accepted by that tool', async () => { const executor = createReadingExecutor(); - for (const { name } of listCommandTools()) { + for (const { name } of listCommandTools({ outputSchemas: true })) { const refused = await executor.execute(name, { notAnArgument: true }); const example = exampleFromHint(toolText(refused), `Example call: ${name} `); const retried = toolText(await executor.execute(name, example)); @@ -81,6 +81,6 @@ test('the removed nested target reaches its migration guidance over MCP', async assert.equal(result.isError, true); assert.match(toolText(result), /target was removed; pass the UI target at the top level/); - const press = listCommandTools().find((tool) => tool.name === 'press'); + const press = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'press'); assert.ok(press && !('target' in (press.inputSchema.properties ?? {}))); }); diff --git a/src/mcp/__tests__/command-tools-timeout-note.test.ts b/src/mcp/__tests__/command-tools-timeout-note.test.ts index f60b060400..d3d6a69cab 100644 --- a/src/mcp/__tests__/command-tools-timeout-note.test.ts +++ b/src/mcp/__tests__/command-tools-timeout-note.test.ts @@ -9,7 +9,7 @@ import { listCommandTools } from '../command-tools.ts'; // command's declared policy — sourced from the registry, so the declared // number cannot drift from the enforced one. test('every MCP tool description declares its timeout envelope', () => { - for (const tool of listCommandTools()) { + for (const tool of listCommandTools({ outputSchemas: true })) { const policy = resolveCommandTimeoutPolicy(tool.name); if (policy.envelopeMs === 'unbounded') { assert.match( @@ -35,7 +35,9 @@ test('every MCP tool description declares its timeout envelope', () => { // rewrite (or a broken note) shows up as a literal diff, not just as // registry-vs-registry agreement. test('the declared envelopes carry the known tier values', () => { - const descriptions = new Map(listCommandTools().map((tool) => [tool.name, tool.description])); + const descriptions = new Map( + listCommandTools({ outputSchemas: true }).map((tool) => [tool.name, tool.description]), + ); assert.match(descriptions.get('devices') ?? '', / Times out after 90s\.$/); assert.match(descriptions.get('install') ?? '', / Times out after 480s\.$/); assert.match(descriptions.get('install-from-source') ?? '', / Times out after 600s\.$/); diff --git a/src/mcp/__tests__/command-tools.test.ts b/src/mcp/__tests__/command-tools.test.ts index 3b05d227ed..91fd106fce 100644 --- a/src/mcp/__tests__/command-tools.test.ts +++ b/src/mcp/__tests__/command-tools.test.ts @@ -12,6 +12,7 @@ test('MCP command tool executor hides client creation behind an execution adapte const createdConfigs: unknown[] = []; const calls: unknown[] = []; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: (config) => { createdConfigs.push(config); return client; @@ -36,7 +37,8 @@ test('MCP command tool executor hides client creation behind an execution adapte }, ]); assert.deepEqual(result.structuredContent, { message: 'Ran wait', ok: true }); - assert.equal(result.content[0]?.text, 'Ran wait'); + // The cost rides only on the data, so includeCost renders the result as JSON text. + assert.deepEqual(JSON.parse(result.content[0]?.text ?? ''), { message: 'Ran wait', ok: true }); }); test('MCP command tool executor renders optimized snapshot text by default', async () => { @@ -70,6 +72,7 @@ test('MCP renders a non-default response level as JSON text, not misleading opti // be the digest payload verbatim (JSON), even though mcpOutputFormat is optimized. const digest = { nodeCount: 3, refs: [{ ref: 'e1', label: 'Continue' }], truncated: false }; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: () => ({}) as AgentDeviceClient, runCommand: async () => digest, }); @@ -85,35 +88,10 @@ test('MCP renders a non-default response level as JSON text, not misleading opti assert.doesNotMatch(result.content[0]?.text ?? '', /Snapshot: 0 nodes/); }); -test('MCP command tool executor renders JSON text when requested', async () => { - const executor = createCommandToolExecutor({ - createClient: () => ({}) as AgentDeviceClient, - runCommand: async (_client, _name, input) => { - assert.deepEqual(input, {}); - return { - nodes: [ - { - ref: 'e1', - index: 0, - depth: 0, - type: 'Button', - label: 'Continue', - enabled: true, - }, - ], - truncated: false, - }; - }, - }); - - const result = await executor.execute('snapshot', { mcpOutputFormat: 'json' }); - - assert.match(result.content[0]?.text ?? '', /^\{\n {2}"nodes": \[/); - assert.match(result.content[0]?.text ?? '', /"label": "Continue"/); -}); - test('MCP tool schemas add MCP client config fields at the MCP boundary', () => { - const devicesTool = listCommandTools().find((tool) => tool.name === 'devices'); + const devicesTool = listCommandTools({ outputSchemas: true }).find( + (tool) => tool.name === 'devices', + ); assert.ok(devicesTool); assert.equal('stateDir' in (devicesTool.inputSchema.properties ?? {}), false); @@ -134,7 +112,7 @@ test('MCP tool schemas add MCP client config fields at the MCP boundary', () => // #1625: `list` must be accepted by the MCP input surface, not only the CLI // parser — the enum here is what the MCP server validates tool calls against. test('MCP find tool schema accepts the read-only list action', () => { - const findTool = listCommandTools().find((tool) => tool.name === 'find'); + const findTool = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'find'); assert.ok(findTool); const actionEnum = (findTool.inputSchema.properties?.action as { enum?: unknown[] } | undefined) @@ -188,7 +166,7 @@ test('MCP pins every find-list ref so a plain follow-up press forwards pinned', }); test('MCP gesture tool exposes and forwards two-finger pan topology', async () => { - const gesture = listCommandTools().find((tool) => tool.name === 'gesture'); + const gesture = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'gesture'); assert.ok(gesture); assert.deepEqual(gesture.inputSchema.properties?.pointerCount, { type: 'integer', @@ -226,7 +204,7 @@ test('MCP gesture tool exposes and forwards two-finger pan topology', async () = }); test('MCP gesture metadata exposes pan/transform duration', () => { - const gesture = listCommandTools().find((tool) => tool.name === 'gesture'); + const gesture = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'gesture'); assert.ok(gesture); assert.equal(gesture.inputSchema.properties?.velocity, undefined); assert.deepEqual(gesture.inputSchema.properties?.durationMs, { @@ -238,7 +216,7 @@ test('MCP gesture metadata exposes pan/transform duration', () => { }); test('MCP gesture tool exposes generic drag endpoints and bounded timing phases', () => { - const gesture = listCommandTools().find((tool) => tool.name === 'gesture'); + const gesture = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'gesture'); assert.ok(gesture); assert.deepEqual(gesture.inputSchema.properties?.kind, { type: 'string', @@ -274,7 +252,7 @@ test('MCP gesture tool exposes generic drag endpoints and bounded timing phases' }); test('MCP swipe tool exposes bounded repetition inputs', () => { - const swipe = listCommandTools().find((tool) => tool.name === 'swipe'); + const swipe = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'swipe'); assert.ok(swipe); assert.deepEqual(swipe.inputSchema.properties?.count, { type: 'integer', @@ -294,6 +272,7 @@ test('MCP includeCost:true opts into agent-cost: sets client.cost, strips the ar const createdConfigs: unknown[] = []; const calls: unknown[] = []; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: (config) => { createdConfigs.push(config); return {} as AgentDeviceClient; @@ -320,6 +299,7 @@ test('MCP includeCost:true opts into agent-cost: sets client.cost, strips the ar test('MCP includeCost absent/false leaves the request shape untouched (no cost config)', async () => { const createdConfigs: unknown[] = []; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: (config) => { createdConfigs.push(config); return {} as AgentDeviceClient; @@ -352,6 +332,7 @@ test('MCP responseLevel:digest opts into a verbosity level: sets client.response const createdConfigs: unknown[] = []; const calls: unknown[] = []; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: (config) => { createdConfigs.push(config); return {} as AgentDeviceClient; @@ -374,6 +355,7 @@ test('MCP responseLevel:digest opts into a verbosity level: sets client.response test('MCP responseLevel absent leaves the request shape untouched (no responseLevel config)', async () => { const createdConfigs: unknown[] = []; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: (config) => { createdConfigs.push(config); return {} as AgentDeviceClient; @@ -401,7 +383,7 @@ test('MCP responseLevel rejects unknown values at the boundary', async () => { }); test('MCP keyboard outputSchema advertises flat contract discriminants', () => { - const tools = listCommandTools(); + const tools = listCommandTools({ outputSchemas: true }); const keyboard = tools.find((tool) => tool.name === 'keyboard'); assert.ok(keyboard); @@ -418,7 +400,7 @@ test('MCP keyboard outputSchema advertises flat contract discriminants', () => { }); test('MCP clipboard outputSchema advertises action union branches', () => { - const tools = listCommandTools(); + const tools = listCommandTools({ outputSchemas: true }); const clipboard = tools.find((tool) => tool.name === 'clipboard'); assert.ok(clipboard); @@ -430,7 +412,7 @@ test('MCP clipboard outputSchema advertises action union branches', () => { }); test('MCP newly typed outputSchemas advertise public contract keys', () => { - const tools = listCommandTools(); + const tools = listCommandTools({ outputSchemas: true }); const wait = tools.find((tool) => tool.name === 'wait'); assert.ok(wait); @@ -447,7 +429,7 @@ test('MCP newly typed outputSchemas advertise public contract keys', () => { }); test('MCP click outputSchema validates default and digest resolution disclosures', () => { - const click = listCommandTools().find((tool) => tool.name === 'click'); + const click = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'click'); assert.ok(click?.outputSchema); assert.equal(click.outputSchema, COMMAND_OUTPUT_SCHEMAS.click); @@ -508,7 +490,7 @@ test('MCP stopped trace schema advertises its downloadable trace artifact', () = }); test('MCP untyped object tools stay byte-identical: no outputSchema key', () => { - const tools = listCommandTools(); + const tools = listCommandTools({ outputSchemas: true }); // snapshot is intentionally absent from the typed registry (dynamic shape). const snapshot = tools.find((tool) => tool.name === 'snapshot'); @@ -526,11 +508,12 @@ test('MCP boot structuredContent is consistent with its advertised outputSchema' booted: true, }; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: () => ({}) as AgentDeviceClient, runCommand: async () => bootResult, }); - const bootTool = listCommandTools().find((tool) => tool.name === 'boot'); + const bootTool = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'boot'); assert.ok(bootTool?.outputSchema); const required = bootTool.outputSchema.required ?? []; for (const key of required) { @@ -672,7 +655,9 @@ test('MCP prepare schema mirrors its PublicPlatform contract', () => { }); test('MCP session tool exposes publication and resolves state-dir without a daemon round-trip', async () => { - const sessionTool = listCommandTools().find((tool) => tool.name === 'session'); + const sessionTool = listCommandTools({ outputSchemas: true }).find( + (tool) => tool.name === 'session', + ); assert.ok(sessionTool); assert.deepEqual( (sessionTool.inputSchema.properties?.action as { enum?: unknown[] } | undefined)?.enum, @@ -763,6 +748,7 @@ function replayDivergenceError(): AppError { test('MCP tool error is a ref-issuing result: isError, structuredContent, and pinned screen refs', async () => { const runCalls: Array<{ name: string; input: unknown }> = []; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: () => ({}) as AgentDeviceClient, runCommand: async (_client, name, input) => { runCalls.push({ name, input }); @@ -843,6 +829,7 @@ test('ambiguous interaction errors pin their candidate refs for the next mutatio // command), and the MCP text carries BOTH concrete commands. --- test("MCP projections carry a caution divergence's alternateFrom (structuredContent) and both --from commands (text)", async () => { const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: () => ({}) as AgentDeviceClient, runCommand: async (_client, name) => { if (name === 'replay') { @@ -890,7 +877,9 @@ test("MCP projections carry a caution divergence's alternateFrom (structuredCont test('MCP get/is/find/snapshot tools expose record and noRecord in their input schema', () => { for (const name of ['get', 'is', 'find', 'snapshot']) { - const tool = listCommandTools().find((candidate) => candidate.name === name); + const tool = listCommandTools({ outputSchemas: true }).find( + (candidate) => candidate.name === name, + ); assert.ok(tool, `expected an MCP tool named ${name}`); const properties = tool.inputSchema.properties ?? {}; assert.equal( @@ -931,7 +920,7 @@ test('MCP forwards record/noRecord from a get tool call through to the executed // --- #1310: `noRecord` on every recordable command's MCP tool schema --- test('MCP tool schemas advertise noRecord for every recordable command', () => { - for (const tool of listCommandTools()) { + for (const tool of listCommandTools({ outputSchemas: true })) { const properties = tool.inputSchema.properties ?? {}; if (resolveCommandRecordsSessionAction(tool.name)) { assert.equal( @@ -1007,7 +996,9 @@ test('MCP record refuses the removed maxSize input with migration guidance', asy test('MCP screenshot and record schemas do not advertise the retired maxSize input', () => { for (const name of ['screenshot', 'record']) { - const tool = listCommandTools().find((candidate) => candidate.name === name); + const tool = listCommandTools({ outputSchemas: true }).find( + (candidate) => candidate.name === name, + ); assert.ok(tool); assert.equal('maxSize' in (tool.inputSchema.properties ?? {}), false); } diff --git a/src/mcp/__tests__/router-structured.test.ts b/src/mcp/__tests__/router-structured.test.ts new file mode 100644 index 0000000000..da2f054323 --- /dev/null +++ b/src/mcp/__tests__/router-structured.test.ts @@ -0,0 +1,75 @@ +import assert from 'node:assert/strict'; +import { afterEach, beforeEach, test, vi } from 'vitest'; +import * as daemonClient from '@agent-device/daemon-client'; +import { createMcpMessageHandler, handleMcpMessage, type McpMessageHandler } from '../router.ts'; +import { validateAgainstSchema } from './output-schema-validator.ts'; + +type Tool = { name: string; outputSchema?: Record }; +type CallResult = { + isError: boolean; + structuredContent?: unknown; + content: Array<{ text: string }>; +}; + +const DEVICE = { + platform: 'ios', + target: 'mobile', + kind: 'simulator', + id: 'sim-1', + name: 'iPhone', +}; + +beforeEach(() => { + // The whole route below the daemon transport is real: router, executor, client, formatter. + vi.spyOn(daemonClient, 'createEnsuredDaemonTransport').mockReturnValue(async (req) => { + if (req.command !== 'devices') throw new Error(`unexpected daemon command ${req.command}`); + return { ok: true, data: { devices: [{ ...DEVICE, booted: true }] } } as never; + }); +}); + +afterEach(() => { + vi.restoreAllMocks(); +}); + +async function listTools(handle: McpMessageHandler): Promise { + const response = await handle({ jsonrpc: '2.0', id: 'list', method: 'tools/list' }); + assert.ok(response && 'result' in response); + return (response.result as { tools: Tool[] }).tools; +} + +async function callDevices(handle: McpMessageHandler): Promise { + const response = await handle({ + jsonrpc: '2.0', + id: 'call', + method: 'tools/call', + params: { name: 'devices', arguments: {} }, + }); + assert.ok(response && 'result' in response); + return response.result as CallResult; +} + +test('the default server advertises no outputSchema and returns text only', async () => { + const tools = await listTools(handleMcpMessage); + assert.deepEqual( + tools.filter((tool) => 'outputSchema' in tool).map((tool) => tool.name), + [], + ); + + const result = await callDevices(handleMcpMessage); + assert.equal(result.isError, false, result.content[0]?.text); + assert.equal('structuredContent' in result, false); + assert.equal(result.content[0]?.text, 'iPhone (ios simulator target=mobile) booted=true'); +}); + +test('a structured server advertises outputSchemas and returns structuredContent that matches them', async () => { + const structured = createMcpMessageHandler({ structured: true }); + const tools = await listTools(structured); + const devicesSchema = tools.find((tool) => tool.name === 'devices')?.outputSchema; + assert.ok(devicesSchema); + assert.ok(tools.find((tool) => tool.name === 'press')?.outputSchema); + + const result = await callDevices(structured); + assert.equal(result.isError, false, result.content[0]?.text); + assert.deepEqual(result.structuredContent, { devices: [{ ...DEVICE, booted: true }] }); + assert.deepEqual(validateAgainstSchema(result.structuredContent, devicesSchema), []); +}); diff --git a/src/mcp/command-tools.ts b/src/mcp/command-tools.ts index 755d23ba99..18ad5710a3 100644 --- a/src/mcp/command-tools.ts +++ b/src/mcp/command-tools.ts @@ -59,14 +59,20 @@ type CommandToolExecutorDeps = { name: CommandName, input: Record, ) => Promise; - /** - * `always` returns `structuredContent` for every successful call. A host that reads results as - * data, such as the AI SDK adapter, sets it; the MCP server leaves it unset. - */ - structuredContent?: 'always'; + structuredContent?: StructuredContentMode; }; -type CommandToolExecutor = { +/** + * When a result carries `structuredContent`. Unset, results are text only: clients that show the + * model `structuredContent` instead of the text would otherwise replace the compact text with JSON. + * `declared` returns it from every tool that declares an outputSchema, from other tools when the + * call asks for machine output, and on every error; `agent-device mcp --structured` sets it. + * `always` returns it from every call; a host that reads results as data, such as the AI SDK + * adapter, sets it. + */ +export type StructuredContentMode = 'declared' | 'always'; + +export type CommandToolExecutor = { /** `signal` cancels the call: an abort closes its in-flight daemon request and the call settles as an error result. */ execute: ( name: string, @@ -119,7 +125,8 @@ function toolInputAudience(metadata: AdmissionMetadata): InputAudienceMap { }; } -export function listCommandTools(): Array<{ +/** `outputSchemas` advertises each typed tool's outputSchema; only a structured host returns data that matches it. */ +export function listCommandTools(options: { outputSchemas: boolean }): Array<{ name: string; description: string; inputSchema: JsonSchema; @@ -129,7 +136,7 @@ export function listCommandTools(): Array<{ // The registry is keyed by the typed-result commands only (CommandResultMap), // so guard the lookup; untyped tools resolve to no outputSchema. const outputSchema = - definition.name in MCP_COMMAND_OUTPUT_SCHEMAS + options.outputSchemas && definition.name in MCP_COMMAND_OUTPUT_SCHEMAS ? MCP_COMMAND_OUTPUT_SCHEMAS[definition.name as keyof typeof MCP_COMMAND_OUTPUT_SCHEMAS] : undefined; const advertised = advertisedInputSchema(definition.name, definition); @@ -175,6 +182,7 @@ export function createCommandToolExecutor(deps: CommandToolExecutorDeps = {}): C if (rejection) { return await buildErrorToolResult( new AppError('INVALID_ARGS', rejection.message, compactHint(rejection.hint)), + deps.structuredContent, refPins, undefined, input.session, @@ -199,7 +207,7 @@ export function createCommandToolExecutor(deps: CommandToolExecutorDeps = {}): C refPins.mergeCommandResult(name, result, config.client.stateDir, commandInput.session); return { isError: false, - ...(deps.structuredContent === 'always' || returnsStructuredContent(name, config) + ...(returnsStructuredContent(deps.structuredContent, name, config) ? { structuredContent: await projectStructuredContent(name, result) } : {}), content: [ @@ -212,8 +220,7 @@ export function createCommandToolExecutor(deps: CommandToolExecutorDeps = {}): C input: commandInput, result, env: host.env, - outputFormat: config.outputFormat, - responseLevel: config.client.responseLevel, + config, }), }, ], @@ -221,6 +228,7 @@ export function createCommandToolExecutor(deps: CommandToolExecutorDeps = {}): C } catch (error) { return await buildErrorToolResult( error, + deps.structuredContent, refPins, config.client.stateDir, commandInput.session, @@ -232,12 +240,13 @@ export function createCommandToolExecutor(deps: CommandToolExecutorDeps = {}): C /** * ADR 0012: a command error is a ref-issuing result — `isError: true`, the - * normalized error as `structuredContent`, and an `available` + * normalized error as `structuredContent` for a structured host, and an `available` * `divergence.screen`'s refs merged/pinned at `refsGeneration` like any * ref-issuing success. Merge-only; never clears existing pins. */ async function buildErrorToolResult( error: unknown, + mode: StructuredContentMode | undefined, refPins: ToolRefPinStore, stateDir: string | undefined, session: unknown, @@ -246,13 +255,11 @@ async function buildErrorToolResult( refPins.mergeErrorDetails(normalized.details, stateDir, session); return { isError: true, - structuredContent: normalized, + ...(mode ? { structuredContent: normalized } : {}), content: [{ type: 'text', text: formatToolErrorText(normalized) }], }; } -export const commandToolExecutor = createCommandToolExecutor(); - async function createClient( deps: CommandToolExecutorDeps, config: AgentDeviceClientConfig, @@ -288,17 +295,15 @@ async function runCommand( return await commandSurface.runCommand(client, name, input); } -/** - * A typed tool must return its declared `structuredContent`. A tool without an `outputSchema` has - * no structured contract, so it returns the compact text alone unless the caller asks for machine - * output. Some clients, Claude Code among them, show the model `structuredContent` instead of the - * text, so an unrequested raw result would replace the compact text in the model's context. - */ -function returnsStructuredContent(name: CommandName, config: McpToolConfig): boolean { - if (name in MCP_COMMAND_OUTPUT_SCHEMAS) return true; - return ( - rendersJsonText(config.outputFormat, config.client.responseLevel) || config.client.cost === true - ); +/** See {@link StructuredContentMode}: a declared tool must return its declared `structuredContent`. */ +function returnsStructuredContent( + mode: StructuredContentMode | undefined, + name: CommandName, + config: McpToolConfig, +): boolean { + if (mode === 'always') return true; + if (mode !== 'declared') return false; + return name in MCP_COMMAND_OUTPUT_SCHEMAS || rendersJsonText(config); } function readMcpToolConfig( @@ -566,15 +571,14 @@ async function renderToolText(params: { input: Record; result: CommandExecutionResult; env: EnvMap; - outputFormat: McpOutputFormat; - responseLevel?: ResponseLevel; + config: McpToolConfig; }): Promise { // A non-default responseLevel (digest/full) hands back a leveled payload whose // shape the optimized CLI formatters do not understand (e.g. the snapshot // formatter expects `nodes`, which the digest drops) — rendering it through - // them would print misleading text that contradicts `structuredContent`. Emit - // the leveled payload verbatim as JSON instead. - if (rendersJsonText(params.outputFormat, params.responseLevel)) { + // them would print misleading text. The cost rides only on the data, which the + // formatters drop. Emit the payload verbatim as JSON instead. + if (rendersJsonText(params.config)) { return renderJsonText(params.result); } const cliOutput = await formatCliOutput({ @@ -600,10 +604,16 @@ function toolTextWithWarnings(name: CommandName, cliOutput: CliOutput): string { return stderr === '' ? text : `${text}${text.endsWith('\n') ? '' : '\n'}${stderr}`; } -function rendersJsonText(outputFormat: McpOutputFormat, responseLevel?: ResponseLevel): boolean { - return outputFormat === 'json' || (responseLevel !== undefined && responseLevel !== 'default'); +/** Machine output requested: the JSON form, a leveled payload, or the cost that rides only on the data. */ +function rendersJsonText(config: McpToolConfig): boolean { + const { responseLevel, cost } = config.client; + return ( + config.outputFormat === 'json' || + (responseLevel !== undefined && responseLevel !== 'default') || + cost === true + ); } function renderJsonText(value: unknown): string { - return typeof value === 'string' ? value : JSON.stringify(value, null, 2); + return typeof value === 'string' ? value : JSON.stringify(value); } diff --git a/src/mcp/router.ts b/src/mcp/router.ts index 3c7db9ed01..5709afdbbf 100644 --- a/src/mcp/router.ts +++ b/src/mcp/router.ts @@ -1,4 +1,9 @@ -import { listCommandTools, commandToolExecutor, type ToolResult } from './command-tools.ts'; +import { + createCommandToolExecutor, + listCommandTools, + type CommandToolExecutor, + type ToolResult, +} from './command-tools.ts'; import type { JsonRpcId, JsonRpcRequestEnvelope } from '@agent-device/kernel/contracts'; import { AppError } from '@agent-device/kernel/errors'; import { @@ -29,10 +34,39 @@ type JsonRpcResponse = | { jsonrpc: '2.0'; id: JsonRpcId; result: unknown } | { jsonrpc: '2.0'; id: JsonRpcId; error: { code: number; message: string; data?: unknown } }; +type McpMessageContext = { signal?: AbortSignal }; + +export type McpMessageHandler = ( + message: JsonRpcMessage, + context?: McpMessageContext, +) => Promise; + +/** + * One server's tools and results. Results are text only by default: no tool advertises an + * outputSchema and no result carries `structuredContent`, because clients that show the model + * `structuredContent` would replace the compact text with JSON. `structured` (`agent-device mcp + * --structured`) advertises outputSchemas and returns the `structuredContent` that matches them. + */ +export function createMcpMessageHandler(options: { structured: boolean }): McpMessageHandler { + const server: McpServer = { + structured: options.structured, + executor: createCommandToolExecutor( + options.structured ? { structuredContent: 'declared' } : {}, + ), + }; + return async (message, context = {}) => await handleServerMessage(server, message, context); +} + +/** The default server's handler: text-only results. */ +export const handleMcpMessage = createMcpMessageHandler({ structured: false }); + +type McpServer = { structured: boolean; executor: CommandToolExecutor }; + /** `signal` aborts a `tools/call` the client cancelled; other methods finish too fast to need it. */ -export async function handleMcpMessage( +async function handleServerMessage( + server: McpServer, message: JsonRpcMessage, - context: { signal?: AbortSignal } = {}, + context: McpMessageContext, ): Promise { if (message.jsonrpc !== '2.0' || typeof message.method !== 'string') { return errorResponse(message.id ?? null, -32600, 'Invalid JSON-RPC request.'); @@ -42,7 +76,7 @@ export async function handleMcpMessage( try { const era = resolveProtocolEra(message.method, message.params); - const result = await handleRequest(message.method, message.params, era, context.signal); + const result = await handleRequest(server, message.method, message.params, era, context.signal); return successResponse(message.id, finalizeResult(result, era)); } catch (error) { if (error instanceof UnsupportedProtocolVersionError) { @@ -65,6 +99,7 @@ export async function handleMcpMessage( } async function handleRequest( + server: McpServer, method: string, params: unknown, era: ProtocolEra, @@ -106,21 +141,25 @@ async function handleRequest( case 'ping': return {}; case 'tools/list': - // Descriptor tools plus the MCP-only guide tool. `listCommandTools()` stays + // Descriptor tools plus the MCP-only guide tool. `listCommandTools({ outputSchemas: true })` stays // descriptor-only because the AI SDK surface reuses it; the composition is the // router's. return { - tools: [...listCommandTools(), HELP_TOOL], + tools: [...listCommandTools({ outputSchemas: server.structured }), HELP_TOOL], ...cacheFields(era, STATIC_RESULT_CACHE_TTL_MS), }; case 'tools/call': - return await callTool(params, signal); + return await callTool(server.executor, params, signal); default: throw new JsonRpcMethodNotFoundError(`Unsupported MCP method: ${method}`); } } -async function callTool(params: unknown, signal: AbortSignal | undefined): Promise { +async function callTool( + executor: CommandToolExecutor, + params: unknown, + signal: AbortSignal | undefined, +): Promise { const record = asRecord(params); const name = stringField(record, 'name'); try { @@ -128,7 +167,7 @@ async function callTool(params: unknown, signal: AbortSignal | undefined): Promi // Command-level failures are handled (and ref-pinned) by the executor's // own catch; this one covers failures outside a resolved command call // (unknown tool name, malformed params). - return await commandToolExecutor.execute(name, optionalArguments(record.arguments), { signal }); + return await executor.execute(name, optionalArguments(record.arguments), { signal }); } catch (error) { return textToolResult(formatToolErrorText(normalizeToolError(error)), true); } diff --git a/src/mcp/server.ts b/src/mcp/server.ts index af55046993..0a1a291ab5 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -1,13 +1,21 @@ -import { handleMcpMessage, type JsonRpcMessage } from './router.ts'; +import { + createMcpMessageHandler, + handleMcpMessage, + type JsonRpcMessage, + type McpMessageHandler, +} from './router.ts'; import { jsonRpcRequestSchema, type JsonRpcId } from '@agent-device/kernel/contracts'; -type JsonRpcResponse = Awaited>>; +type JsonRpcResponse = NonNullable>>; type PayloadContext = { signal?: AbortSignal }; type PayloadHandler = (payload: unknown, context: PayloadContext) => Promise; type MessageWriter = (message: unknown) => void; -export async function runAgentDeviceMcpServer(): Promise { - const session = createMcpStdioSession(); +/** `structured`: `agent-device mcp --structured`; see `createMcpMessageHandler`. */ +export async function runAgentDeviceMcpServer(options: { structured: boolean }): Promise { + const session = createMcpStdioSession({ + handlePayload: createMcpPayloadHandler(createMcpMessageHandler(options)), + }); process.stdin.setEncoding('utf8'); process.stdin.on('data', (chunk: string) => { session.receive(chunk); @@ -128,29 +136,32 @@ export function createMcpStdioSession( }; } -export function handleMcpPayload( - payload: unknown, - context: PayloadContext = {}, -): Promise { - if (Array.isArray(payload)) { - return handleMcpBatch(payload); - } - return handleInboundMessage(payload, context); +function createMcpPayloadHandler(handleMessage: McpMessageHandler) { + return async (payload: unknown, context: PayloadContext = {}): Promise => + Array.isArray(payload) + ? await handleMcpBatch(handleMessage, payload) + : await handleInboundMessage(handleMessage, payload, context); } +/** The default server's payload handler: text-only results. */ +export const handleMcpPayload = createMcpPayloadHandler(handleMcpMessage); + /** * JSON-RPC batching exists only for legacy clients (MCP 2025-06-18 removed it). A `tools/call` in a * batch is refused with -32600: it could not be cancelled on its own or queued behind other tool * calls, so it is accepted only as its own message. */ -async function handleMcpBatch(messages: unknown[]): Promise { +async function handleMcpBatch( + handleMessage: McpMessageHandler, + messages: unknown[], +): Promise { const responses: JsonRpcResponse[] = []; for (const message of messages) { const parsed = singleMessage(message); const response = parsed?.jsonrpc === '2.0' && parsed.method === 'tools/call' ? batchedToolCallResponse(parsed.id) - : await handleInboundMessage(message); + : await handleInboundMessage(handleMessage, message); responses.push(...responseArray(response)); } return responses.length > 0 ? responses : null; @@ -175,6 +186,7 @@ function batchedToolCallResponse(id: JsonRpcId | undefined): JsonRpcResponse | n // genuinely malformed payloads (non-object, or wrong-typed jsonrpc/method/id) are // rejected with the standard -32600 Invalid Request error. async function handleInboundMessage( + handleMessage: McpMessageHandler, raw: unknown, context: PayloadContext = {}, ): Promise { @@ -184,7 +196,7 @@ async function handleInboundMessage( } catch { return invalidRequestResponse(bestEffortId(raw)); } - return handleMcpMessage(message, context); + return handleMessage(message, context); } function invalidRequestResponse(id: JsonRpcId): JsonRpcResponse { diff --git a/src/mcp/tool-control-fields.ts b/src/mcp/tool-control-fields.ts index 08dd87d9e8..fdb466927c 100644 --- a/src/mcp/tool-control-fields.ts +++ b/src/mcp/tool-control-fields.ts @@ -38,7 +38,7 @@ const MCP_TOOL_CONFIG_FIELDS = { includeCost: { schema: { type: 'boolean', - description: 'Add agent cost (cost.wallClockMs, …) to the result.', + description: 'Add agent cost (cost.wallClockMs, …) to the result, returned as JSON text.', }, }, responseLevel: { diff --git a/src/mcp/tool-input-config.test.ts b/src/mcp/tool-input-config.test.ts index 88dd6c1610..ca710796fb 100644 --- a/src/mcp/tool-input-config.test.ts +++ b/src/mcp/tool-input-config.test.ts @@ -53,6 +53,7 @@ test('a nested batch step naming another device fails before any daemon request' return { ok: true, data: {} }; }; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: (config, devicePin) => createAgentDeviceClient(config, { transport, devicePin }), }); @@ -78,6 +79,7 @@ test('a devicePin in tool input is rejected before a client exists, and the conf return { ok: true, data: {} }; }; const executor = createCommandToolExecutor({ + structuredContent: 'declared', createClient: (config, devicePin) => { createdWith.push(devicePin); return createAgentDeviceClient(config, { transport, devicePin }); diff --git a/test/output-economy/mcp-output-schema.test.ts b/test/output-economy/mcp-output-schema.test.ts index de99f1f91a..1a745f5065 100644 --- a/test/output-economy/mcp-output-schema.test.ts +++ b/test/output-economy/mcp-output-schema.test.ts @@ -1,6 +1,6 @@ import { expect, test } from 'vitest'; -import type { CommandName } from '@agent-device/command-surface'; -import { listCommandTools } from '../../src/mcp/command-tools.ts'; +import type { CommandName, JsonSchema } from '@agent-device/command-surface'; +import { createMcpMessageHandler } from '../../src/mcp/router.ts'; import { validateAgainstSchema } from '../../src/mcp/__tests__/output-schema-validator.ts'; import { captureOutputEconomyDaemonResponses } from './daemon-route-fixtures.ts'; @@ -22,7 +22,17 @@ const samples: Array<[string, CommandName, Record]> = [ ['network digest', 'network', daemon.networkDigest], ]; -const outputSchemas = new Map(listCommandTools().map((tool) => [tool.name, tool.outputSchema])); +// The schemas a client of `agent-device mcp --structured` reads from tools/list: only that mode +// advertises outputSchemas, and its typed tools return the daemon data as structuredContent. +const listed = await createMcpMessageHandler({ structured: true })({ + jsonrpc: '2.0', + id: 'list', + method: 'tools/list', +}); +if (!listed || !('result' in listed)) throw new Error('tools/list failed'); +const tools = (listed.result as { tools: Array<{ name: string; outputSchema?: JsonSchema }> }) + .tools; +const outputSchemas = new Map(tools.map((tool) => [tool.name, tool.outputSchema])); // A sample is checked once its tool advertises an outputSchema; untyped tools have nothing to violate. const typedSamples = samples.flatMap(([label, name, data]) => { const schema = outputSchemas.get(name); diff --git a/website/docs/docs/agent-setup.md b/website/docs/docs/agent-setup.md index f519409b98..9d7e7df5c0 100644 --- a/website/docs/docs/agent-setup.md +++ b/website/docs/docs/agent-setup.md @@ -51,15 +51,17 @@ Capture screenshots, logs, network, audio, perf, traces, recordings, and `.ad` r ## MCP server -`agent-device mcp` starts the stdio MCP server. It exposes installed CLI commands as structured tools. Some local workflows are CLI-only and have no MCP tool. +`agent-device mcp` starts the stdio MCP server. It exposes installed CLI commands as tools. Some local workflows are CLI-only and have no MCP tool. -`agent-device mcp` accepts no flags or arguments other than `--help` and `--version`; any other argument fails with `INVALID_ARGS`. To configure the server, set `AGENT_DEVICE_*` environment variables or `AGENT_DEVICE_CONFIG` in the client's server entry. For example, set the state directory with `AGENT_DEVICE_STATE_DIR`, and the remote `tenant`, `runId`, and `leaseId` with `AGENT_DEVICE_TENANT`, `AGENT_DEVICE_RUN_ID`, and `AGENT_DEVICE_LEASE_ID` (or the same keys in `~/.agent-device/config.json`). Tool calls cannot pass these values. +`agent-device mcp` accepts no flags or arguments other than `--structured`, `--help`, and `--version`; any other argument fails with `INVALID_ARGS`. To configure the server, set `AGENT_DEVICE_*` environment variables or `AGENT_DEVICE_CONFIG` in the client's server entry. For example, set the state directory with `AGENT_DEVICE_STATE_DIR`, and the remote `tenant`, `runId`, and `leaseId` with `AGENT_DEVICE_TENANT`, `AGENT_DEVICE_RUN_ID`, and `AGENT_DEVICE_LEASE_ID` (or the same keys in `~/.agent-device/config.json`). Tool calls cannot pass these values. For web automation, MCP tools can target `platform: "web"` once the managed browser backend is set up, but `agent-device web setup` and `agent-device web doctor` are CLI-only. Run setup from a terminal that uses the same state directory as the MCP server before you ask an MCP client to drive a browser session. MCP-only clients don't need a separately installed skill. When a client connects (`initialize` and `server/discover`), the server returns short `instructions` with the core workflow: start with `open`, act with `settle: true`, verify, `close`, how to keep refs accurate, and how to recover when the accessibility tree is sparse. An MCP-only `help` tool returns the same guides as `agent-device help `. Agents don't call `help` at startup; they call it for specialized work (gestures, scripting, TV, macOS, web, remote, debugging) or when a command is unclear. -Tool results are compact text. A tool that declares an output schema, such as `press` or `wait`, also returns `structuredContent` that matches it. On success, other tools, such as `snapshot` and `open`, return text only, because some clients show the model `structuredContent` instead of the text. They return `structuredContent` when you pass `mcpOutputFormat: "json"`, a non-default `responseLevel`, or `includeCost`. A failed call always returns the error in `structuredContent`. +Tool results are compact text, such as `@e4 [button] "Products"` lines and settled UI diffs. Tools declare no output schema, and results carry no `structuredContent`, because some clients show the model `structuredContent` instead of the text. Pass `mcpOutputFormat: "json"`, a non-default `responseLevel`, or `includeCost` to get the result as JSON text. + +If your client reads results as data, start the server with `agent-device mcp --structured`. Tools that have a typed result, such as `press` or `wait`, then declare an output schema and return `structuredContent` that matches it. Other tools return `structuredContent` when you ask for JSON as above. A failed call returns the error in `structuredContent`. Tools that act on a UI element take its target as top-level arguments, in the same words as the CLI: `press {"ref":"@e12"}`, `click {"selector":"id=\"submit\""}`, or `press {"x":120,"y":340}`. `get` takes `ref` or `selector`. From c031ce51279615313584bf09fb4f25cbee565fda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 11:08:08 +0100 Subject: [PATCH 02/10] refactor(mcp): keep the structured-content mode private and restore a tool-list comment Co-Authored-By: Claude Opus 5.5 --- src/mcp/command-tools.ts | 2 +- src/mcp/router.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mcp/command-tools.ts b/src/mcp/command-tools.ts index 18ad5710a3..c406e5edc7 100644 --- a/src/mcp/command-tools.ts +++ b/src/mcp/command-tools.ts @@ -70,7 +70,7 @@ type CommandToolExecutorDeps = { * `always` returns it from every call; a host that reads results as data, such as the AI SDK * adapter, sets it. */ -export type StructuredContentMode = 'declared' | 'always'; +type StructuredContentMode = 'declared' | 'always'; export type CommandToolExecutor = { /** `signal` cancels the call: an abort closes its in-flight daemon request and the call settles as an error result. */ diff --git a/src/mcp/router.ts b/src/mcp/router.ts index 5709afdbbf..df07cbc787 100644 --- a/src/mcp/router.ts +++ b/src/mcp/router.ts @@ -141,7 +141,7 @@ async function handleRequest( case 'ping': return {}; case 'tools/list': - // Descriptor tools plus the MCP-only guide tool. `listCommandTools({ outputSchemas: true })` stays + // Descriptor tools plus the MCP-only guide tool. `listCommandTools()` stays // descriptor-only because the AI SDK surface reuses it; the composition is the // router's. return { From b1fc6ad6858a1dd2ac06dc558b055a8cac1d1a73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 11:16:55 +0100 Subject: [PATCH 03/10] fix(mcp): shape pre-command tool-call errors by server mode; address review notes A structured server now returns structuredContent for an unknown tool or malformed arguments too: the router's catch builds its result through the executor, the one owner of the mode. The mcp help names --structured and the JSON-text opt-ins, ADR 0012 qualifies the resume command, input-schema tests read the default listing, and the AI SDK keeps a test for its output schemas. Co-Authored-By: Claude Opus 5.5 --- docs/adr/0012-interactive-replay.md | 2 +- .../src/schema/command-overrides.ts | 2 +- src/ai-sdk/__tests__/index.test.ts | 10 ++++++++++ .../__tests__/command-tools-gesture-tap.test.ts | 4 +++- src/mcp/__tests__/command-tools-input-docs.test.ts | 2 +- .../command-tools-operator-inputs.test.ts | 12 ++++++------ .../__tests__/command-tools-option-field.test.ts | 2 +- .../command-tools-structured-content.test.ts | 2 +- .../__tests__/command-tools-target-args.test.ts | 4 ++-- .../__tests__/command-tools-timeout-note.test.ts | 4 ++-- src/mcp/__tests__/router-structured.test.ts | 14 ++++++++++++++ src/mcp/command-tools.ts | 4 ++++ src/mcp/router.ts | 10 +--------- 13 files changed, 47 insertions(+), 25 deletions(-) diff --git a/docs/adr/0012-interactive-replay.md b/docs/adr/0012-interactive-replay.md index 04d0c2023f..cf4d32c9f2 100644 --- a/docs/adr/0012-interactive-replay.md +++ b/docs/adr/0012-interactive-replay.md @@ -91,7 +91,7 @@ The report carries a bounded `screen`, ranked `suggestions`, one `repairHint` en - Capture failure never replaces or conceals the original replay cause. - Serialized ceilings are 8/24/64 KiB for the compact, default, and full response levels. Overflow goes to a redacted session-scoped artifact. - Entered text is never serialized. Native `.ad` replay replaces expanded variable values with `` in human-readable divergence fields. -- Every surface (daemon text, JSON, Node client `AppError`, MCP text, and MCP `structuredContent` on a structured server) preserves the repair data. No surface may reduce divergence to text that discards it. The default MCP server returns text only, so its error text carries the step, the repair hint with the concrete resume command, the screen, and the suggestions. +- Every surface (daemon text, JSON, Node client `AppError`, MCP text, and MCP `structuredContent` on a structured server) preserves the repair data. No surface may reduce divergence to text that discards it. The default MCP server returns text only, so its error text carries the step, the repair hint (with the concrete resume command when `resume.allowed` is true), the screen, and the suggestions. Resume is `replay --from N --plan-digest `. `N` is a 1-based index into the fully expanded executable plan. diff --git a/packages/command-surface/src/schema/command-overrides.ts b/packages/command-surface/src/schema/command-overrides.ts index 9d19f499c0..7181017f13 100644 --- a/packages/command-surface/src/schema/command-overrides.ts +++ b/packages/command-surface/src/schema/command-overrides.ts @@ -152,7 +152,7 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = { text: { summary: 'Start MCP server', description: - 'Start the official stdio MCP server. It exposes command tools backed by the agent-device client. Tool results are compact text. With --structured, tools also advertise output schemas and return structuredContent, for clients that read results as data. It accepts no other flags or arguments besides --help and --version; configure it with AGENT_DEVICE_* environment variables or AGENT_DEVICE_CONFIG.', + 'Start the official stdio MCP server. It exposes command tools backed by the agent-device client. Tool results are compact text by default; mcpOutputFormat: "json", a non-default responseLevel, or includeCost returns JSON text. With --structured, tools also advertise output schemas and return structuredContent, including errors, for clients that read results as data. It accepts no other flags or arguments besides --structured, --help, and --version; configure it with AGENT_DEVICE_* environment variables or AGENT_DEVICE_CONFIG.', }, allowedFlags: ['mcpStructured'], }, diff --git a/src/ai-sdk/__tests__/index.test.ts b/src/ai-sdk/__tests__/index.test.ts index 8bce8f113e..d148ebf7aa 100644 --- a/src/ai-sdk/__tests__/index.test.ts +++ b/src/ai-sdk/__tests__/index.test.ts @@ -204,6 +204,16 @@ test('asks the executor for structuredContent from every tool, because execute r assert.deepEqual(executorDeps, [{ structuredContent: 'always' }]); }); +test('typed tools keep their output schema for the data host; untyped tools declare none', async () => { + const { tools } = await createAgentDeviceTools({ session: 'my-session', set: 'all' }); + const outputSchemaOf = (name: string) => + (tools[name] as unknown as { outputSchema?: { jsonSchema: { required?: string[] } } }) + .outputSchema; + + assert.deepEqual(outputSchemaOf('devices')?.jsonSchema.required, ['devices']); + assert.equal(outputSchemaOf('snapshot'), undefined); +}); + test("the AI SDK call's abortSignal reaches the executor", async () => { const { tools } = await createAgentDeviceTools({ session: 'my-session' }); const controller = new AbortController(); diff --git a/src/mcp/__tests__/command-tools-gesture-tap.test.ts b/src/mcp/__tests__/command-tools-gesture-tap.test.ts index 325f56166a..ba1819c58c 100644 --- a/src/mcp/__tests__/command-tools-gesture-tap.test.ts +++ b/src/mcp/__tests__/command-tools-gesture-tap.test.ts @@ -5,7 +5,9 @@ import { createClientTransport } from '@agent-device/test-kit'; import { createCommandToolExecutor, listCommandTools } from '../command-tools.ts'; test('MCP gesture tool exposes tap contacts bounded to 2 to 5 points', () => { - const gesture = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'gesture'); + const gesture = listCommandTools({ outputSchemas: false }).find( + (tool) => tool.name === 'gesture', + ); assert.ok(gesture); assert.deepEqual(gesture.inputSchema.properties?.points, { type: 'array', diff --git a/src/mcp/__tests__/command-tools-input-docs.test.ts b/src/mcp/__tests__/command-tools-input-docs.test.ts index 9849cbf5ec..84a5e159c8 100644 --- a/src/mcp/__tests__/command-tools-input-docs.test.ts +++ b/src/mcp/__tests__/command-tools-input-docs.test.ts @@ -141,7 +141,7 @@ const UNDESCRIBED_TOOL_INPUTS = new Set([ test('MCP tool inputs do not add undocumented properties', () => { const undescribed: string[] = []; - for (const tool of listCommandTools({ outputSchemas: true })) { + for (const tool of listCommandTools({ outputSchemas: false })) { for (const [key, schema] of Object.entries(tool.inputSchema.properties ?? {})) { if (!schema.description) undescribed.push(`${tool.name}.${key}`); } diff --git a/src/mcp/__tests__/command-tools-operator-inputs.test.ts b/src/mcp/__tests__/command-tools-operator-inputs.test.ts index 2e9e44dab9..61c8eecc1a 100644 --- a/src/mcp/__tests__/command-tools-operator-inputs.test.ts +++ b/src/mcp/__tests__/command-tools-operator-inputs.test.ts @@ -46,7 +46,7 @@ const MODEL_WRITABLE_COMMON_KEYS = [ ] as const; test('MCP tool schemas advertise no operator-owned inputs', () => { - for (const tool of listCommandTools({ outputSchemas: true })) { + for (const tool of listCommandTools({ outputSchemas: false })) { const properties = tool.inputSchema.properties ?? {}; for (const key of OPERATOR_OWNED_KEYS) { assert.equal(key in properties, false, `${tool.name} advertises ${key}`); @@ -59,7 +59,7 @@ test('MCP tool schemas advertise no operator-owned inputs', () => { // assertions above would stay green while the model lost the ability to say // which device a call targets. test('MCP tool schemas keep every common input the model may write', () => { - const wait = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'wait'); + const wait = listCommandTools({ outputSchemas: false }).find((tool) => tool.name === 'wait'); assert.ok(wait, 'expected an MCP tool named wait'); const properties = wait.inputSchema.properties ?? {}; for (const key of MODEL_WRITABLE_COMMON_KEYS) { @@ -89,7 +89,7 @@ test('MCP refuses every explicit operator-owned argument with guidance', async ( }); test('MCP neither advertises nor admits the retired readiness budget', async () => { - for (const tool of listCommandTools({ outputSchemas: true })) { + for (const tool of listCommandTools({ outputSchemas: false })) { const properties = tool.inputSchema.properties ?? {}; assert.equal('readinessTimeoutMs' in properties, false, `${tool.name} advertises it`); } @@ -245,7 +245,7 @@ test('MCP still resolves operator env values outside the model-writable surface' }); test('MCP neither advertises nor admits the CLI-only fill textStdin marker', async () => { - for (const tool of listCommandTools({ outputSchemas: true })) { + for (const tool of listCommandTools({ outputSchemas: false })) { const properties = tool.inputSchema.properties ?? {}; assert.equal('textStdin' in properties, false, `${tool.name} advertises it`); } @@ -274,7 +274,7 @@ test('MCP neither advertises nor admits the CLI-only fill textStdin marker', asy // so no schema offers the switch. The operator still sets it, through the environment or the user // config, and that value reaches the command route. test('MCP neither advertises nor admits the stabilization opt-out, and still resolves the operator default', async () => { - for (const tool of listCommandTools({ outputSchemas: true })) { + for (const tool of listCommandTools({ outputSchemas: false })) { const properties = tool.inputSchema.properties ?? {}; assert.equal('postGestureStabilization' in properties, false, `${tool.name} advertises it`); } @@ -316,7 +316,7 @@ test('MCP neither advertises nor admits the stabilization opt-out, and still res // The proxy lease device spec is not operator infrastructure, so the schema offers it (issue #3864). test('MCP open, install, reinstall and uninstall advertise the proxy lease device spec', () => { for (const name of ['open', 'install', 'reinstall', 'uninstall']) { - const tool = listCommandTools({ outputSchemas: true }).find( + const tool = listCommandTools({ outputSchemas: false }).find( (candidate) => candidate.name === name, ); assert.ok(tool, `expected an MCP tool named ${name}`); diff --git a/src/mcp/__tests__/command-tools-option-field.test.ts b/src/mcp/__tests__/command-tools-option-field.test.ts index 83462ad48a..3faab397c3 100644 --- a/src/mcp/__tests__/command-tools-option-field.test.ts +++ b/src/mcp/__tests__/command-tools-option-field.test.ts @@ -25,7 +25,7 @@ async function toolPropertyWithPlantedOption( Object.assign(declaration, plant); const { listCommandTools } = await import('../command-tools.ts'); - const entry = listCommandTools({ outputSchemas: true }).find( + const entry = listCommandTools({ outputSchemas: false }).find( (candidate) => candidate.name === tool, ); assert.ok(entry, `expected an MCP tool for ${tool}`); diff --git a/src/mcp/__tests__/command-tools-structured-content.test.ts b/src/mcp/__tests__/command-tools-structured-content.test.ts index 76b8b86327..ba97e7e118 100644 --- a/src/mcp/__tests__/command-tools-structured-content.test.ts +++ b/src/mcp/__tests__/command-tools-structured-content.test.ts @@ -26,7 +26,7 @@ function executorReturning( test('the default executor returns text only, from typed and untyped tools', async () => { const executor = executorReturning(undefined); - const press = await executor.execute('press', { target: { kind: 'ref', ref: '@e2' } }); + const press = await executor.execute('press', { ref: '@e2' }); const snapshot = await executor.execute('snapshot', {}); const json = await executor.execute('snapshot', { mcpOutputFormat: 'json' }); diff --git a/src/mcp/__tests__/command-tools-target-args.test.ts b/src/mcp/__tests__/command-tools-target-args.test.ts index d19ffacb85..7400656a91 100644 --- a/src/mcp/__tests__/command-tools-target-args.test.ts +++ b/src/mcp/__tests__/command-tools-target-args.test.ts @@ -53,7 +53,7 @@ test('an unknown argument answers with a call example the tool accepts', async ( test('every tool hint example is accepted by that tool', async () => { const executor = createReadingExecutor(); - for (const { name } of listCommandTools({ outputSchemas: true })) { + for (const { name } of listCommandTools({ outputSchemas: false })) { const refused = await executor.execute(name, { notAnArgument: true }); const example = exampleFromHint(toolText(refused), `Example call: ${name} `); const retried = toolText(await executor.execute(name, example)); @@ -81,6 +81,6 @@ test('the removed nested target reaches its migration guidance over MCP', async assert.equal(result.isError, true); assert.match(toolText(result), /target was removed; pass the UI target at the top level/); - const press = listCommandTools({ outputSchemas: true }).find((tool) => tool.name === 'press'); + const press = listCommandTools({ outputSchemas: false }).find((tool) => tool.name === 'press'); assert.ok(press && !('target' in (press.inputSchema.properties ?? {}))); }); diff --git a/src/mcp/__tests__/command-tools-timeout-note.test.ts b/src/mcp/__tests__/command-tools-timeout-note.test.ts index d3d6a69cab..adcb6553ca 100644 --- a/src/mcp/__tests__/command-tools-timeout-note.test.ts +++ b/src/mcp/__tests__/command-tools-timeout-note.test.ts @@ -9,7 +9,7 @@ import { listCommandTools } from '../command-tools.ts'; // command's declared policy — sourced from the registry, so the declared // number cannot drift from the enforced one. test('every MCP tool description declares its timeout envelope', () => { - for (const tool of listCommandTools({ outputSchemas: true })) { + for (const tool of listCommandTools({ outputSchemas: false })) { const policy = resolveCommandTimeoutPolicy(tool.name); if (policy.envelopeMs === 'unbounded') { assert.match( @@ -36,7 +36,7 @@ test('every MCP tool description declares its timeout envelope', () => { // registry-vs-registry agreement. test('the declared envelopes carry the known tier values', () => { const descriptions = new Map( - listCommandTools({ outputSchemas: true }).map((tool) => [tool.name, tool.description]), + listCommandTools({ outputSchemas: false }).map((tool) => [tool.name, tool.description]), ); assert.match(descriptions.get('devices') ?? '', / Times out after 90s\.$/); assert.match(descriptions.get('install') ?? '', / Times out after 480s\.$/); diff --git a/src/mcp/__tests__/router-structured.test.ts b/src/mcp/__tests__/router-structured.test.ts index da2f054323..419ae0f2f1 100644 --- a/src/mcp/__tests__/router-structured.test.ts +++ b/src/mcp/__tests__/router-structured.test.ts @@ -73,3 +73,17 @@ test('a structured server advertises outputSchemas and returns structuredContent assert.deepEqual(result.structuredContent, { devices: [{ ...DEVICE, booted: true }] }); assert.deepEqual(validateAgainstSchema(result.structuredContent, devicesSchema), []); }); + +test('a tool call that fails before reaching a command follows the server mode', async () => { + const call = { jsonrpc: '2.0', id: 'bad', method: 'tools/call' } as const; + const params = { name: 'no-such-tool', arguments: {} }; + const structured = await createMcpMessageHandler({ structured: true })({ ...call, params }); + const text = await handleMcpMessage({ ...call, params }); + + assert.ok(structured && 'result' in structured && text && 'result' in text); + const structuredResult = structured.result as CallResult; + assert.equal(structuredResult.isError, true); + assert.equal((structuredResult.structuredContent as { code?: string }).code, 'INVALID_ARGS'); + assert.equal('structuredContent' in (text.result as CallResult), false); + assert.match((text.result as CallResult).content[0]?.text ?? '', /^Error \(INVALID_ARGS\)/); +}); diff --git a/src/mcp/command-tools.ts b/src/mcp/command-tools.ts index c406e5edc7..c9cc467455 100644 --- a/src/mcp/command-tools.ts +++ b/src/mcp/command-tools.ts @@ -79,6 +79,8 @@ export type CommandToolExecutor = { input: Record, options?: { signal?: AbortSignal }, ) => Promise; + /** A failure outside a resolved command call, shaped like this executor's own errors. */ + errorResult: (error: unknown) => Promise; }; type McpOutputFormat = 'optimized' | 'json'; @@ -154,6 +156,8 @@ export function listCommandTools(options: { outputSchemas: boolean }): Array<{ export function createCommandToolExecutor(deps: CommandToolExecutorDeps = {}): CommandToolExecutor { const refPins = createToolRefPinStore(); return { + errorResult: async (error) => + await buildErrorToolResult(error, deps.structuredContent, refPins, undefined, undefined), execute: async (name, input, options = {}) => { if (!isCommandName(name)) { throw new AppError('INVALID_ARGS', `Unknown command tool: ${name}`); diff --git a/src/mcp/router.ts b/src/mcp/router.ts index df07cbc787..e55ffcd7fd 100644 --- a/src/mcp/router.ts +++ b/src/mcp/router.ts @@ -12,7 +12,6 @@ import { HELP_TOOL, MCP_SERVER_INSTRUCTIONS, } from './server-guide.ts'; -import { formatToolErrorText, normalizeToolError } from './tool-error.ts'; import { cacheFields, finalizeResult, @@ -169,17 +168,10 @@ async function callTool( // (unknown tool name, malformed params). return await executor.execute(name, optionalArguments(record.arguments), { signal }); } catch (error) { - return textToolResult(formatToolErrorText(normalizeToolError(error)), true); + return await executor.errorResult(error); } } -function textToolResult(text: string, isError = false): ToolResult { - return { - isError, - content: [{ type: 'text', text }], - }; -} - function successResponse(id: JsonRpcId, result: unknown): JsonRpcResponse { return { jsonrpc: '2.0', id, result }; } From 98a3594f1e04df1f1ef40e1d4fb1666e3c754447 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 11:22:56 +0100 Subject: [PATCH 04/10] docs(replay): align the divergence surface contract with text-only MCP The default MCP server returns divergence errors as text that carries the repair fields; only --structured and data hosts add structuredContent. Cover the default-mode text, its resume command, and its ref pinning. Co-Authored-By: Claude Opus 5.5 --- .../ad-replay/docs/divergence-and-resume.md | 12 +++-- .../command-tools-divergence-text.test.ts | 51 +++++++++++++++++++ 2 files changed, 59 insertions(+), 4 deletions(-) create mode 100644 src/mcp/__tests__/command-tools-divergence-text.test.ts diff --git a/packages/ad-replay/docs/divergence-and-resume.md b/packages/ad-replay/docs/divergence-and-resume.md index a31e245486..471a3f107e 100644 --- a/packages/ad-replay/docs/divergence-and-resume.md +++ b/packages/ad-replay/docs/divergence-and-resume.md @@ -39,7 +39,7 @@ The daemon computes it under ADR 0012 decision 6, R3. Every divergence includes it, with `manual` when no safer route is proven. It is never absent or null. Its small fixed size permits inclusion at every response level, including `--level digest`. -It must survive these four projections unchanged: daemon text summary, JSON, Node client `AppError`, and MCP `structuredContent`. +It must survive these projections unchanged: daemon text summary, JSON, Node client `AppError`, MCP text, and MCP `structuredContent` where MCP returns it. `screen` has two discriminated forms. `{ state: "available", refsGeneration, refs, truncated }` is a fresh healthy snapshot digest. @@ -96,7 +96,10 @@ All surfaces preserve the daemon error. The Node client rejects with `AppError` and retains `details.divergence`. CLI exits nonzero. Text shows a compact report; JSON includes the complete structured error. -MCP returns `isError: true`, the object in `structuredContent`, and the same compact text summary. +MCP returns `isError: true` and the same compact text summary. +The default MCP server returns that text only, so the text carries the repair fields: step, repair hint, screen refs, and suggestions. +The repair hint includes the concrete resume command when `resume.allowed` is true. +Only `agent-device mcp --structured` and data hosts, such as the AI SDK adapter, also return the object in `structuredContent`. MCP treats divergence as a ref-issuing result, including on the error path. Before return, it merges and pins every `screen` ref with `refsGeneration`. CLI and direct clients receive the daemon error's unpinned refs and generation. @@ -232,8 +235,9 @@ Successful text replay prints one line with replayed count and wall time. - Divergence reports: compact/default/full field and byte ceilings; digest output includes `suggestionCount` without entries; redaction, overflow artifacts, artifact-write failure, available/sparse/capture-failed screens, and original-cause preservation. - Resume: digest emission and rejection after script/include/expansion changes; `resume.allowed` reasons, `--from` indexing, variable-output rejection, control-flow rejection, and `test --from` rejection. - Surfaces: daemon/client/CLI/MCP tests prove typed divergence survives failure. - JSON and MCP structured output retain it. + JSON and MCP structured output (`--structured` and data hosts) retain it. + Default MCP error text carries the repair fields, and MCP pins its screen refs in both modes. MCP pins only actionable error-path refs. No text-only path discards the report. - `repairHint` is present and identical in text, JSON, client `AppError`, and MCP `structuredContent`, including compact `--level digest`. + `repairHint` is present and identical in text, JSON, client `AppError`, MCP text, and MCP `structuredContent` where returned, including compact `--level digest`. - `--update` retirement: no source-file rewrite; suggestions remain bounded, ranked, and deduplicated under the suggestion total order. diff --git a/src/mcp/__tests__/command-tools-divergence-text.test.ts b/src/mcp/__tests__/command-tools-divergence-text.test.ts new file mode 100644 index 0000000000..be916fe693 --- /dev/null +++ b/src/mcp/__tests__/command-tools-divergence-text.test.ts @@ -0,0 +1,51 @@ +import assert from 'node:assert/strict'; +import { test } from 'vitest'; +import type { AgentDeviceClient } from '@agent-device/command-surface'; +import { AppError } from '@agent-device/kernel/errors'; +import { createCommandToolExecutor } from '../command-tools.ts'; + +// The default MCP server returns text only, so a replay divergence must reach the model through +// the error text with its repair data, and its screen refs must still be pinned. +test('a default-mode divergence is error text carrying the repair data, and its refs are pinned', async () => { + const runCalls: Array<{ name: string; input: unknown }> = []; + const executor = createCommandToolExecutor({ + createClient: () => ({}) as AgentDeviceClient, + runCommand: async (_client, name, input) => { + runCalls.push({ name, input }); + if (name !== 'replay') return {}; + throw new AppError('REPLAY_DIVERGENCE', 'Replay failed at step 2 (click "Save")', { + divergence: { + version: 1, + kind: 'action-failure', + step: { index: 2, source: { path: '/tmp/flow.ad', line: 2 } }, + action: 'click "Save"', + screen: { + state: 'available', + refsGeneration: 12, + refs: [{ ref: 'e5', role: 'button', label: 'Save' }], + }, + suggestions: [ + { selector: 'id="save"', basis: 'id', ref: 'e5', role: 'button', label: 'Save' }, + ], + suggestionCount: 1, + resume: { allowed: true, from: 2, planDigest: 'digest-abc' }, + repairHint: 'state-repair', + }, + }); + }, + }); + + const result = await executor.execute('replay', { path: '/tmp/flow.ad' }); + + assert.equal(result.isError, true); + assert.equal('structuredContent' in result, false); + const text = result.content[0]?.text ?? ''; + assert.match(text, /^Error \(REPLAY_DIVERGENCE\)/); + assert.match(text, /Divergence at step 2 \(\/tmp\/flow\.ad:2\)/); + assert.match(text, /Repair hint: state-repair — .*--from 2 --plan-digest digest-abc/); + assert.match(text, /@e5 \[button\] "Save"/); + assert.match(text, /\[id\] "Save" id="save"/); + + await executor.execute('press', { ref: '@e5' }); + assert.deepEqual(runCalls[1]?.input, { ref: '@e5~s12' }); +}); From b4613c680623e723be213d2a112dfb1a29aee520 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 11:37:33 +0100 Subject: [PATCH 05/10] refactor(mcp): delete the default-server handlers without a production caller runAgentDeviceMcpServer builds its own payload handler, so the module-level handleMcpMessage and handleMcpPayload only served tests. Tests now build the handler for the mode they exercise, and the stdio session takes its handler explicitly. Co-Authored-By: Claude Opus 5.5 --- src/mcp/__tests__/router-structured.test.ts | 4 ++- src/mcp/__tests__/router.test.ts | 7 ++-- src/mcp/__tests__/server-cancellation.test.ts | 7 ++-- src/mcp/__tests__/server-validation.test.ts | 8 ++++- src/mcp/router.ts | 3 -- src/mcp/server.ts | 32 +++++++------------ 6 files changed, 31 insertions(+), 30 deletions(-) diff --git a/src/mcp/__tests__/router-structured.test.ts b/src/mcp/__tests__/router-structured.test.ts index 419ae0f2f1..71c83c8624 100644 --- a/src/mcp/__tests__/router-structured.test.ts +++ b/src/mcp/__tests__/router-structured.test.ts @@ -1,7 +1,7 @@ import assert from 'node:assert/strict'; import { afterEach, beforeEach, test, vi } from 'vitest'; import * as daemonClient from '@agent-device/daemon-client'; -import { createMcpMessageHandler, handleMcpMessage, type McpMessageHandler } from '../router.ts'; +import { createMcpMessageHandler, type McpMessageHandler } from '../router.ts'; import { validateAgainstSchema } from './output-schema-validator.ts'; type Tool = { name: string; outputSchema?: Record }; @@ -27,6 +27,8 @@ beforeEach(() => { }); }); +const handleMcpMessage = createMcpMessageHandler({ structured: false }); + afterEach(() => { vi.restoreAllMocks(); }); diff --git a/src/mcp/__tests__/router.test.ts b/src/mcp/__tests__/router.test.ts index 16dc831c20..056e5d994f 100644 --- a/src/mcp/__tests__/router.test.ts +++ b/src/mcp/__tests__/router.test.ts @@ -3,13 +3,16 @@ import { test } from 'vitest'; import { listCliCommandNames } from '@agent-device/command-registry/catalog'; import { helpTopicIds } from '../../commands/schema/cli-help.ts'; import { listMcpExposedCommandNames } from '@agent-device/command-registry/registry'; -import { handleMcpMessage } from '../router.ts'; +import { createMcpMessageHandler } from '../router.ts'; import { HELP_TOOL_NAME, MCP_SERVER_INSTRUCTIONS, terminalOnlyCommandNames, } from '../server-guide.ts'; -import { handleMcpPayload } from '../server.ts'; +import { createMcpPayloadHandler } from '../server.ts'; + +const handleMcpMessage = createMcpMessageHandler({ structured: false }); +const handleMcpPayload = createMcpPayloadHandler({ structured: false }); test('MCP exposes every automatable CLI command as a structured direct tool, plus the MCP-only help tool', async () => { const response = await handleMcpMessage({ diff --git a/src/mcp/__tests__/server-cancellation.test.ts b/src/mcp/__tests__/server-cancellation.test.ts index 233ea29557..6d28a4e500 100644 --- a/src/mcp/__tests__/server-cancellation.test.ts +++ b/src/mcp/__tests__/server-cancellation.test.ts @@ -1,7 +1,7 @@ import assert from 'node:assert/strict'; import { afterEach, test, vi } from 'vitest'; import * as daemonClient from '@agent-device/daemon-client'; -import { createMcpStdioSession } from '../server.ts'; +import { createMcpPayloadHandler, createMcpStdioSession } from '../server.ts'; afterEach(() => { vi.restoreAllMocks(); @@ -24,7 +24,10 @@ test('notifications/cancelled aborts the daemon request of a running tools/call }), ); const writes: unknown[] = []; - const session = createMcpStdioSession({ write: (message) => writes.push(message) }); + const session = createMcpStdioSession({ + handlePayload: createMcpPayloadHandler({ structured: false }), + write: (message) => writes.push(message), + }); session.receive( `${JSON.stringify({ diff --git a/src/mcp/__tests__/server-validation.test.ts b/src/mcp/__tests__/server-validation.test.ts index cb85b24893..ba2d4b7b06 100644 --- a/src/mcp/__tests__/server-validation.test.ts +++ b/src/mcp/__tests__/server-validation.test.ts @@ -1,7 +1,9 @@ import assert from 'node:assert/strict'; import { setImmediate } from 'node:timers/promises'; import { test } from 'vitest'; -import { createMcpStdioSession, handleMcpPayload } from '../server.ts'; +import { createMcpPayloadHandler, createMcpStdioSession } from '../server.ts'; + +const handleMcpPayload = createMcpPayloadHandler({ structured: false }); type JsonRpcResponse = { jsonrpc: '2.0'; @@ -90,6 +92,7 @@ test('a batch rejects only its malformed element while routing the valid ones', test('a malformed payload received on stdio is written as a -32600 error response', async () => { const writes: JsonRpcResponse[] = []; const session = createMcpStdioSession({ + handlePayload: handleMcpPayload, write: (message) => { writes.push(message as JsonRpcResponse); }, @@ -106,6 +109,7 @@ test('a malformed payload received on stdio is written as a -32600 error respons test('a blank line does not hold back the request after it in the same chunk', async () => { const writes: JsonRpcResponse[] = []; const session = createMcpStdioSession({ + handlePayload: handleMcpPayload, write: (message) => writes.push(message as JsonRpcResponse), }); @@ -119,6 +123,7 @@ test('a blank line does not hold back the request after it in the same chunk', a test('a malformed line answers -32700 and the next line in the chunk is still served', async () => { const writes: JsonRpcResponse[] = []; const session = createMcpStdioSession({ + handlePayload: handleMcpPayload, write: (message) => writes.push(message as JsonRpcResponse), }); @@ -133,6 +138,7 @@ test('a malformed line answers -32700 and the next line in the chunk is still se test('a final request without a trailing newline is served at end of input', async () => { const writes: JsonRpcResponse[] = []; const session = createMcpStdioSession({ + handlePayload: handleMcpPayload, write: (message) => writes.push(message as JsonRpcResponse), }); diff --git a/src/mcp/router.ts b/src/mcp/router.ts index e55ffcd7fd..c346f5ce70 100644 --- a/src/mcp/router.ts +++ b/src/mcp/router.ts @@ -56,9 +56,6 @@ export function createMcpMessageHandler(options: { structured: boolean }): McpMe return async (message, context = {}) => await handleServerMessage(server, message, context); } -/** The default server's handler: text-only results. */ -export const handleMcpMessage = createMcpMessageHandler({ structured: false }); - type McpServer = { structured: boolean; executor: CommandToolExecutor }; /** `signal` aborts a `tools/call` the client cancelled; other methods finish too fast to need it. */ diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 0a1a291ab5..cdba410005 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -1,9 +1,4 @@ -import { - createMcpMessageHandler, - handleMcpMessage, - type JsonRpcMessage, - type McpMessageHandler, -} from './router.ts'; +import { createMcpMessageHandler, type JsonRpcMessage, type McpMessageHandler } from './router.ts'; import { jsonRpcRequestSchema, type JsonRpcId } from '@agent-device/kernel/contracts'; type JsonRpcResponse = NonNullable>>; @@ -13,9 +8,7 @@ type MessageWriter = (message: unknown) => void; /** `structured`: `agent-device mcp --structured`; see `createMcpMessageHandler`. */ export async function runAgentDeviceMcpServer(options: { structured: boolean }): Promise { - const session = createMcpStdioSession({ - handlePayload: createMcpPayloadHandler(createMcpMessageHandler(options)), - }); + const session = createMcpStdioSession({ handlePayload: createMcpPayloadHandler(options) }); process.stdin.setEncoding('utf8'); process.stdin.on('data', (chunk: string) => { session.receive(chunk); @@ -37,16 +30,14 @@ export async function runAgentDeviceMcpServer(options: { structured: boolean }): * `tools/call`, queued or running, and the server sends no response for it. A batch never carries * a `tools/call`: see `handleMcpBatch`. */ -export function createMcpStdioSession( - options: { - handlePayload?: PayloadHandler; - write?: MessageWriter; - } = {}, -): { +export function createMcpStdioSession(options: { + handlePayload: PayloadHandler; + write?: MessageWriter; +}): { receive: (chunk: string) => void; end: () => Promise; } { - const handlePayload = options.handlePayload ?? handleMcpPayload; + const handlePayload = options.handlePayload; const write = options.write ?? writeMessage; const inFlight = new Set>(); const toolCalls = new Map(); @@ -105,7 +96,7 @@ export function createMcpStdioSession( if (line.length === 0) return; let payload: unknown; try { - // The decoded value stays untyped here; handleMcpPayload validates it at the boundary. + // The decoded value stays untyped here; the payload handler validates it at the boundary. payload = JSON.parse(line) as unknown; } catch (error) { write({ @@ -136,16 +127,15 @@ export function createMcpStdioSession( }; } -function createMcpPayloadHandler(handleMessage: McpMessageHandler) { +/** One server's JSON-RPC payload boundary: single messages and legacy batches. */ +export function createMcpPayloadHandler(options: { structured: boolean }) { + const handleMessage = createMcpMessageHandler(options); return async (payload: unknown, context: PayloadContext = {}): Promise => Array.isArray(payload) ? await handleMcpBatch(handleMessage, payload) : await handleInboundMessage(handleMessage, payload, context); } -/** The default server's payload handler: text-only results. */ -export const handleMcpPayload = createMcpPayloadHandler(handleMcpMessage); - /** * JSON-RPC batching exists only for legacy clients (MCP 2025-06-18 removed it). A `tools/call` in a * batch is refused with -32600: it could not be cancelled on its own or queued behind other tool From 41cb57513eba0f46e025ae29f8df4268b9dd5743 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 12:12:07 +0100 Subject: [PATCH 06/10] test(mcp): measure the default server's tool list in the schema budget guard Co-Authored-By: Claude Opus 5.5 --- src/mcp/__tests__/command-tools-schema-budget.test.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mcp/__tests__/command-tools-schema-budget.test.ts b/src/mcp/__tests__/command-tools-schema-budget.test.ts index 0b50e4bdf9..46093cbe97 100644 --- a/src/mcp/__tests__/command-tools-schema-budget.test.ts +++ b/src/mcp/__tests__/command-tools-schema-budget.test.ts @@ -9,7 +9,7 @@ import { CONFIG_LOADER_AUDIENCE, MCP_TOOL_CONFIG_AUDIENCE } from '../tool-contro const INPUT_SCHEMA_BUDGET_BYTES = 5 * 1024; test('every MCP tool input schema stays within the byte budget', () => { - const oversized = listCommandTools() + const oversized = listCommandTools({ outputSchemas: false }) .map((tool) => ({ name: tool.name, bytes: Buffer.byteLength(JSON.stringify(tool.inputSchema)), @@ -33,7 +33,7 @@ test('no MCP tool advertises an operator-owned input', () => { for (const key of ['tenant', 'config', 'remoteConfig']) { assert.ok(operatorKeys.has(key), `expected ${key} to be operator-owned`); } - for (const tool of listCommandTools()) { + for (const tool of listCommandTools({ outputSchemas: false })) { const properties = tool.inputSchema.properties ?? {}; const advertised = [...operatorKeys].filter((key) => Object.hasOwn(properties, key)); assert.deepEqual(advertised, [], `${tool.name} advertises operator-owned inputs`); From 791c722cfda0748fc7c1aa022105ea76ff36b633 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 12:18:45 +0100 Subject: [PATCH 07/10] docs(mcp): record why default errors are text, mark --structured help-only ADR 0012 records why default MCP errors drop structuredContent. The REPLAY_DIVERGENCE hint names the report, not details.divergence, which default MCP text does not expose. mcpStructured is declared for help and argument rejection; the process entry's argv check is its one runtime read. Two comments cite the current listCommandTools signature. Co-Authored-By: Claude Opus 5.5 --- docs/adr/0012-interactive-replay.md | 1 + packages/contracts/src/cli-flags.ts | 3 +++ packages/kernel/src/errors-code-policy.test.ts | 2 +- packages/kernel/src/errors.ts | 2 +- src/ai-sdk/index.ts | 2 +- src/cli/entry.ts | 6 +++++- src/mcp/router.ts | 2 +- 7 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/adr/0012-interactive-replay.md b/docs/adr/0012-interactive-replay.md index cf4d32c9f2..55095e58d2 100644 --- a/docs/adr/0012-interactive-replay.md +++ b/docs/adr/0012-interactive-replay.md @@ -92,6 +92,7 @@ The report carries a bounded `screen`, ranked `suggestions`, one `repairHint` en - Serialized ceilings are 8/24/64 KiB for the compact, default, and full response levels. Overflow goes to a redacted session-scoped artifact. - Entered text is never serialized. Native `.ad` replay replaces expanded variable values with `` in human-readable divergence fields. - Every surface (daemon text, JSON, Node client `AppError`, MCP text, and MCP `structuredContent` on a structured server) preserves the repair data. No surface may reduce divergence to text that discards it. The default MCP server returns text only, so its error text carries the step, the repair hint (with the concrete resume command when `resume.allowed` is true), the screen, and the suggestions. + Why: clients that receive `structuredContent` show the model that JSON and drop the text, so a default `structuredContent` error replaced the compact report with the larger JSON. Keeping `structuredContent` on default errors was rejected for that reason; a client that reads errors as data opts in with `agent-device mcp --structured`. Resume is `replay --from N --plan-digest `. `N` is a 1-based index into the fully expanded executable plan. diff --git a/packages/contracts/src/cli-flags.ts b/packages/contracts/src/cli-flags.ts index a30fe6ae91..b45163114b 100644 --- a/packages/contracts/src/cli-flags.ts +++ b/packages/contracts/src/cli-flags.ts @@ -43,6 +43,9 @@ export type CliFlags = CloudProviderProfileFields & daemonServerMode?: DaemonServerMode; proxyHost?: string; proxyPort?: number; + // Declared for `mcp --help` and for the CLI's rejection of other `mcp` arguments; nothing + // reads the parsed value. The process entry starts the server from argv (`mcp --structured`) + // before the CLI module loads, so that one argv check is the flag's only runtime read. mcpStructured?: boolean; tenant?: string; sessionIsolation?: SessionIsolationMode; diff --git a/packages/kernel/src/errors-code-policy.test.ts b/packages/kernel/src/errors-code-policy.test.ts index 8fe1a68d7d..e3687782bb 100644 --- a/packages/kernel/src/errors-code-policy.test.ts +++ b/packages/kernel/src/errors-code-policy.test.ts @@ -174,7 +174,7 @@ const EXPECTED_HINT_BY_CODE: Record = { UNAUTHORIZED: 'Refresh daemon metadata and retry the command.', AMBIGUOUS_MATCH: 'Multiple candidates matched. Narrow the query or pass an exact identifier.', REPLAY_DIVERGENCE: - 'Read the divergence report (details.divergence) for the screen and selector suggestions to repair the step.', + 'Repair the step from the divergence report: its screen and selector suggestions.', REPAIR_SESSION_EXPIRED: 'The --save-script repair session was reaped before it was finalized; re-run replay