Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(mcp): retain protocol framing for oversized tool errors (#5371)
gensokyo-dev4eaf3a117b3f
diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.mdindex 912d531ea..409d7d0aa 100644--- a/docs/mcp-contracts.md+++ b/docs/mcp-contracts.md@@ -101,8 +101,9 @@ unresolved relationship reads. Cancellation remains a tool error.REA prepares complete MCP results within the pinned stdio client's 10 MiBreceive-buffer budget, including both text and structured representations and-room for the JSON-RPC envelope. Tool errors carry only their text-representation and `isError` flag, so only those count against the budget. Response budget settings are captured at startup;+room for the JSON-RPC envelope. Tool errors omit `structuredContent` from the+wire; their text, `isError`, provenance marker and negotiated protocol framing+count toward the wire budget. Response budget settings are captured at startup;restart or recreate the server to apply changes. If a result cannot fit, REA returns`resource_constraint` with `details.resource: "transport"` before constructinga document-sized string. Analysis Evidence remains complete in the current@@ -112,6 +113,12 @@ that reference for a summary, one section/module, or a stable page, or call`export_evidence_bundle` with a destination path. Completebundle exports stream canonical JSON into an atomically published file.+On protocol revision `2026-07-28`, completed replies retain the SDK's+`resultType: "complete"`, including the replacement for an oversized error.+This marks completion of the MCP exchange; Evidence coverage, partial facts+and unknowns retain their separate meaning. Legacy replies keep their existing+framing.+For oversized native function Evidence, `details.reported_limits.continuation`contains a ready-to-call `inspect_analysis_view` request for the retainedpseudocode's first page. Use its `name` and `arguments` directly, then followdiff --git a/src/server/EvidenceMcpServer.test.ts b/src/server/EvidenceMcpServer.test.tsindex ce3e7a274..18ee8d117 100644--- a/src/server/EvidenceMcpServer.test.ts+++ b/src/server/EvidenceMcpServer.test.ts@@ -1,5 +1,10 @@import { describe, expect, it } from "vitest";import { Client, InMemoryTransport } from "@modelcontextprotocol/client";+import {+ isJSONRPCResultResponse,+ type JSONRPCResultResponse,+} from "@modelcontextprotocol/server";+import { serveStdio } from "@modelcontextprotocol/server/stdio";import { z } from "zod";import { InvestigationRecords } from "../application/investigation/InvestigationRecords.js";@@ -43,104 +48,137 @@ describe("MCP request bookkeeping", () => {});describe("SDK validation error delivery", () => {- it("bounds oversized errors, retains their source, and preserves fitting and valid calls", async () => {- const delivery = new ToolResultDelivery(4096);- const records = new InvestigationRecords();- const server = new EvidenceMcpServer(- { name: "sdk-validation-budget-test", version: "1" },- { capabilities: {} },- (evidence) => records.recordEvidence(evidence),- delivery,- );- server.registerTool(- "procedure_pseudo_code",- { inputSchema: z.strictObject({ required: z.string() }) },- async () => ({ content: [{ type: "text", text: "valid call" }] }),- );- const client = new Client({- name: "sdk-validation-budget-client",- version: "1",- });- const [clientTransport, serverTransport] =- InMemoryTransport.createLinkedPair();- const oversizedKey = `unexpected_${"x".repeat(6000)}`;- try {- await server.connect(serverTransport);- await client.connect(clientTransport);-- const oversized = await client.callTool({- name: "procedure_pseudo_code",- arguments: { required: "present", [oversizedKey]: true },- });- expect(oversized.isError).toBe(true);- expect(oversized.structuredContent).toBeUndefined();- expect(oversized._meta).toEqual({- provenance: { untrusted_content: true, source: "analysis_target" },- });- expect(Buffer.byteLength(JSON.stringify(oversized))).toBeLessThan(4096);- const oversizedError = z- .object({- error: z.object({- code: z.string(),- details: z.object({- reported_limits: z.record(z.string(), z.unknown()),- }),- }),- })- .parse(JSON.parse(firstText(oversized) ?? "null"));- expect(oversizedError.error.code).toBe("resource_constraint");- const reportedLimits = oversizedError.error.details.reported_limits;- expect(reportedLimits).toMatchObject({- evidence_reference: {- kind: "retained-evidence",- evidence_id: expect.any(String),+ it.each(["2025-11-25", "2026-07-28"])(+ "bounds and retains errors through the public stdio entry on %s",+ async (revision) => {+ const delivery = new ToolResultDelivery(4096);+ const records = new InvestigationRecords();+ const server = new EvidenceMcpServer(+ { name: "sdk-validation-budget-test", version: "1" },+ { capabilities: {} },+ (evidence) => records.recordEvidence(evidence),+ delivery,+ );+ server.registerTool(+ "procedure_pseudo_code",+ { inputSchema: z.strictObject({ required: z.string() }) },+ async () => ({ content: [{ type: "text", text: "valid call" }] }),+ );+ const client = new Client(+ {+ name: "sdk-validation-budget-client",+ version: "1",},- diagnostic_truncated: true,- });- expect(reportedLimits).not.toHaveProperty("retention");- const bundle = records.exportEvidenceBundle();- expect(bundle.records).toHaveLength(1);- expect(bundle.records[0]?.operation).toBe("mcp_tool_error");- expect(bundle.records[0]?.raw_result).toMatchObject({- isError: true,- content: [- { type: "text", text: expect.stringContaining(oversizedKey) },- ],- });- const evidenceReference = z- .object({ evidence_id: z.string() })- .parse(reportedLimits.evidence_reference);- expect(bundle.records[0]?.evidence_id).toBe(- evidenceReference.evidence_id,+ revision === "2026-07-28"+ ? { versionNegotiation: { mode: { pin: revision } } }+ : { supportedProtocolVersions: [revision] },);+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ const oversizedKey = `unexpected_${"x".repeat(6000)}`;+ const serving = serveStdio(() => server, { transport: serverTransport });+ const replies: JSONRPCResultResponse[] = [];+ try {+ await client.connect(clientTransport);+ expect(client.getNegotiatedProtocolVersion()).toBe(revision);+ const receive = clientTransport.onmessage;+ clientTransport.onmessage = (message) => {+ if (isJSONRPCResultResponse(message)) replies.push(message);+ receive?.(message);+ };- const fitting = await client.callTool({- name: "procedure_pseudo_code",- arguments: { unexpected: true },- });- expect(fitting.isError).toBe(true);- expect(firstText(fitting)).toContain("Input validation error");+ // The normal reply and SDK validation error already negotiate and decode+ // correctly before oversized recovery replaces an SDK-encoded envelope.+ const valid = await client.callTool({+ name: "procedure_pseudo_code",+ arguments: { required: "present" },+ });+ expect(valid.content).toContainEqual({+ type: "text",+ text: "valid call",+ });+ const fitting = await client.callTool({+ name: "procedure_pseudo_code",+ arguments: { unexpected: true },+ });+ expect(fitting.isError).toBe(true);+ expect(firstText(fitting)).toContain("Input validation error");- const quotedKey = '"\\'.repeat(350);- const quoted = await client.callTool({- name: "procedure_pseudo_code",- arguments: { required: "present", [quotedKey]: true },- });- expect(quoted.isError).toBe(true);- expect(firstText(quoted)).toContain("Input validation error");- expect(Buffer.byteLength(JSON.stringify(quoted))).toBeLessThan(4096);- expect(records.exportEvidenceBundle().records).toHaveLength(1);+ const oversized = await client.callTool({+ name: "procedure_pseudo_code",+ arguments: { required: "present", [oversizedKey]: true },+ });+ expect(oversized.isError).toBe(true);+ expect(oversized.structuredContent).toBeUndefined();+ expect(oversized._meta).toEqual({+ provenance: { untrusted_content: true, source: "analysis_target" },+ });+ expect(Buffer.byteLength(JSON.stringify(oversized))).toBeLessThan(4096);+ const oversizedError = z+ .object({+ error: z.object({+ code: z.string(),+ details: z.object({+ reported_limits: z.record(z.string(), z.unknown()),+ }),+ }),+ })+ .parse(JSON.parse(firstText(oversized) ?? "null"));+ expect(oversizedError.error.code).toBe("resource_constraint");+ const reportedLimits = oversizedError.error.details.reported_limits;+ expect(reportedLimits).toMatchObject({+ evidence_reference: {+ kind: "retained-evidence",+ evidence_id: expect.any(String),+ },+ diagnostic_truncated: true,+ });+ expect(reportedLimits).not.toHaveProperty("retention");+ const bundle = records.exportEvidenceBundle();+ expect(bundle.records).toHaveLength(1);+ expect(bundle.records[0]?.operation).toBe("mcp_tool_error");+ expect(bundle.records[0]?.raw_result).toMatchObject({+ isError: true,+ content: [+ { type: "text", text: expect.stringContaining(oversizedKey) },+ ],+ });+ const evidenceReference = z+ .object({ evidence_id: z.string() })+ .parse(reportedLimits.evidence_reference);+ expect(bundle.records[0]?.evidence_id).toBe(+ evidenceReference.evidence_id,+ );- const valid = await client.callTool({- name: "procedure_pseudo_code",- arguments: { required: "present" },- });- expect(valid.content).toContainEqual({- type: "text",- text: "valid call",- });- } finally {- await Promise.all([client.close(), server.close()]);- }- });+ const quotedKey = '"\\'.repeat(350);+ const quoted = await client.callTool({+ name: "procedure_pseudo_code",+ arguments: { required: "present", [quotedKey]: true },+ });+ expect(quoted.isError).toBe(true);+ expect(firstText(quoted)).toContain("Input validation error");+ expect(Buffer.byteLength(JSON.stringify(quoted))).toBeLessThan(4096);+ expect(records.exportEvidenceBundle().records).toHaveLength(1);++ const recovered = await client.callTool({+ name: "procedure_pseudo_code",+ arguments: { required: "present" },+ });+ expect(recovered.content).toContainEqual({+ type: "text",+ text: "valid call",+ });+ for (const reply of replies) {+ expect(reply.result.resultType).toBe(+ revision === "2026-07-28" ? "complete" : undefined,+ );+ expect(+ Buffer.byteLength(JSON.stringify(reply)) + 1,+ ).toBeLessThanOrEqual(4096);+ }+ } finally {+ await Promise.all([client.close(), serving.close()]);+ }+ },+ );});diff --git a/src/server/EvidenceMcpServer.ts b/src/server/EvidenceMcpServer.tsindex 33ee1f24b..8598afd80 100644--- a/src/server/EvidenceMcpServer.ts+++ b/src/server/EvidenceMcpServer.ts@@ -451,7 +451,15 @@ class ErrorEvidenceTransport implements Transport {);return {...message,- result: this.delivery.toErrorToolResult(failure, targetContent),+ result: {+ ...this.delivery.toErrorToolResult(failure, targetContent),+ // The SDK stamps `resultType` on modern-era results before this+ // transport sees them; the replacement must keep the stamp or a+ // 2026-07-28 client discards REA's structured error entirely.+ ...(typeof message.result.resultType === "string"+ ? { resultType: message.result.resultType }+ : {}),+ },};}}