Repository navigation
feat(mcp)!: return text-only tool results by default; add mcp --structured - #4466
Conversation
Size Report
Startup median (7 runs, lower is better):
|
There was a problem hiding this comment.
6 issues found across 29 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="src/mcp/__tests__/command-tools-structured-content.test.ts">
<violation number="1" location="src/mcp/__tests__/command-tools-structured-content.test.ts:29">
P2: This test uses the retired `target` shape, so the executor returns an `INVALID_ARGS` error before the mocked command runs and the next assertion fails. Use the current top-level target form, such as `{ ref: '@e2' }`.</violation>
</file>
<file name="docs/adr/0012-interactive-replay.md">
<violation number="1" location="docs/adr/0012-interactive-replay.md:94">
P2: This ADR bullet states as an unconditional guarantee that default MCP error text carries the concrete resume command. The renderer emits that command only when `resume.allowed` is true, and `alternateFrom` only when present. Qualify the sentence so it does not overstate the contract.</violation>
</file>
<file name="src/mcp/__tests__/command-tools-timeout-note.test.ts">
<violation number="1" location="src/mcp/__tests__/command-tools-timeout-note.test.ts:12">
P3: This test now exercises only the structured tool listing, while the PR changes the default listing behavior. Call `listCommandTools({ outputSchemas: false })` here (or test both modes) so the default MCP surface remains covered.</violation>
</file>
<file name="src/ai-sdk/index.ts">
<violation number="1" location="src/ai-sdk/index.ts:103">
P3: The `outputSchemas: true` flag that keeps AI SDK tools structured has no test. `src/ai-sdk/__tests__/index.test.ts` checks the executor's `structuredContent: 'always'` but never asserts that typed tools expose `outputSchema`. Add a test that the `devices` tool from `createAgentDeviceTools` has `outputSchema` defined.</violation>
</file>
<file name="src/mcp/router.ts">
<violation number="1" location="src/mcp/router.ts:152">
P2: `--structured` drops `structuredContent` for tool-call failures handled by `callTool`: unknown command names and malformed arguments return `textToolResult` instead. Thread the mode through this catch and include the normalized error.
(Based on your team's feedback about failed-call structuredContent.)</violation>
</file>
<file name="packages/command-surface/src/schema/command-overrides.ts">
<violation number="1" location="packages/command-surface/src/schema/command-overrides.ts:155">
P3: The MCP help text contradicts its own `allowedFlags`: `--structured` is accepted, but the description says only `--help` and `--version` are allowed. Include `--structured` in that sentence and document the JSON-text opt-ins (`mcpOutputFormat: "json"`, non-default `responseLevel`, and `includeCost`) plus structured error results.</violation>
</file>
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
There was a problem hiding this comment.
All reported issues were addressed across 13 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
Apex SentinelVerdict: Since the last review: 0 new · 0 still open · 0 no longer raised No findings. Reviewed with this repository's own Sentinel configuration ( Feedback goes in the review comment threads, as a reply under the inline comment of a finding: Reply Useful? Reply Comment Earlier reviewsReview of
|
| Where | Finding |
|---|---|
src/mcp/router.ts:60 |
AGENTS.md bans fallback behavior without approval, but superseded MCP paths are kept |
Reviewed with this repository's own Sentinel configuration (9cbbae2c857d).
There was a problem hiding this comment.
Apex Sentinel: 1 new finding on 518ea29. The verdict and the full list are in the summary comment.
|
Thanks for this change. At 4562bde I found one problem that should be fixed before merge: the default text-only MCP error drops facts that clients used to get. This review comes from reading the code and tests at that commit. I did not run tests or tsc, and I did not reproduce the byte counts, the #4458 guard mutation result, or the headless Claude Code run in the PR body. In default mode, formatToolErrorText is now the only error surface. It renders code, message, cause, hint, warnings, candidates, supportedOn and divergence. It does not render Not blocking, and you can take or leave these: open PR #4468 (read at 5d4ac57, so it may change) calls The open inline thread on the default error text still stands only through the finding above. These threads look fixed at head, so you can resolve them: the retired Checks are still running: 21 passed at this commit, and one review check is still in progress. There are no conflicts. Before merge, the default MCP error text must show the dispatch disclosure with its observe-first step and the log line, ideally through |
…tured 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 <noreply@anthropic.com>
… tool-list comment Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
…n 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 <noreply@anthropic.com>
…t guard Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4562bde to
41cb575
Compare
…-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 <noreply@anthropic.com>
|
Non-blocking notes, at 791c722:
Not in this push:
|
There was a problem hiding this comment.
All reported issues were addressed across 7 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
…ault structuredContent Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Addressed the default-error finding in
The two new cases fail on the old formatter; the corrected MCP/AI SDK selection passes 227 tests. The default-mode executor case supplies Remeasured UTF-8 output for the two error fixtures:
These fixtures do not contain dispatch or log facts, so the routed regression supplies those separately. The earlier 142/165 figures describe the old formatter. Exact affected validation is running at |
… only formatHumanError uses Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The local affected run at The existing owner fixed that export in |
|
5a5995e fixes the unused |
|
At Hosted checks used merge checkout |
|
I found no code problems at 5a5995e. Both findings from the earlier review (#4466 (comment)) are fixed, and nothing from that review remains open. All CI checks pass (21 pass, 1 skipped, none failing), and there are no conflicts. I did not run the MCP/AI SDK tests, tsc or the production-exports gate locally, and I did not reproduce the remeasured error byte counts or the headless MCP client run. I judged the regression coverage by reading the pre-change formatter. Maintainer sign-off is the only step left before merge. Two open review threads are now fixed at this commit, so the author can resolve them: the |
Summary
Default
agent-device mcpreturns compact text without output schemas orstructuredContent, so clients do not replace that text with the larger JSON result. Errors use the shared CLI renderer, preserving dispatch disclosure, observe-first advice and diagnostic paths. ADR 0012 records the revised contract and rationale.agent-device mcp --structuredrestores output schemas and structured results.mcpOutputFormat: "json", non-defaultresponseLevel, andincludeCostretain their JSON-text opt-ins.42 files. Includes the #4458 output-schema guard adjustment; no new command family.
Validation
Current head:
5a5995e9adf2525a20e25e107e729077778f001a. Validation: CI. Hosted checks are green; Apex Sentinel approves with no findings. All review threads are resolved. Maintainer sign-off remains pending.At
a4bc1e6: frozen install/build and 227 MCP/AI SDK tests pass. Two new error regressions fail before the fix and pass afterward. Its exact affected gate failed at production-exports (run-FstHFp, clean checkout); prior stages passed. At5a5995e9, the repaired production-exports guard passes locally and in hosted CI. CI tested merge checkout8fbce857d8(this head plus maine54dc4d8).Review evidence: corrected error fixture sizes are 212→143 and 235→166 bytes. Earlier measurements belong to their earlier SHAs. The prior headless-client run did not capture a settled press success. No device-facing behavior changed in this review fix.
🤖 Generated with Claude Code
Open in [code]smith · Need help on this PR? Tag
@codesmith-botwith what you need.