fix(mcp): retain complete application results across response limits

Retain complete authenticated application Evidence when the repeated MCP representation exceeds the default receive frame or Node string limit. Return a typed transport constraint, keep useful followup queries available, and stream full canonical bundles to atomic destinations.

Verify complete Notion and Obsidian workflows on Linux and native Windows, full CLI/Evidence parity, and real large Chrome screenshot recovery. Preserve complete success contracts and caller-selected evidence paths.

Refs #1065, #1053.
This commit is contained in:
Ysopwnable
2026-10-08 23:46:02 +08:00
committed by GitHub
parent c701376777
commit a1ed4232de
43 changed files with 1314 additions and 186 deletions
+3 -1
View File
@@ -294,7 +294,9 @@ const createSessionRecorders = (
evidenceById:
session === undefined
? undefined
: (evidenceId: string) => session.evidenceById(evidenceId),
: (evidenceId: string) =>
session.evidenceForAnalysis?.(evidenceId) ??
session.evidenceById(evidenceId),
activeTarget:
session === undefined ? undefined : () => session.activeTarget(),
recordEvidence:
@@ -21,7 +21,13 @@ export const recordResult = (
);
if (recorded !== undefined && !recorded.ok)
return toCallToolResult(recorded, contract);
return toCallToolResult({ ok: true, value: evidence }, contract);
return toCallToolResult(
{ ok: true, value: evidence },
contract,
recorded === undefined
? undefined
: { retainedEvidenceId: evidence.evidence_id },
);
};
const unknownRegistration = (
+7 -1
View File
@@ -208,5 +208,11 @@ const evidenceResult = (
const recorded = options.recordEvidence?.(evidence);
return recorded !== undefined && !recorded.ok
? toCallToolResult(recorded, contract)
: toCallToolResult({ ok: true, value: evidence }, contract);
: toCallToolResult(
{ ok: true, value: evidence },
contract,
recorded === undefined
? undefined
: { retainedEvidenceId: evidence.evidence_id },
);
};
+7 -1
View File
@@ -168,5 +168,11 @@ const evidenceResult = (
const recorded = options.recordEvidence?.(evidence);
return recorded !== undefined && !recorded.ok
? toCallToolResult(recorded, contract)
: toCallToolResult({ ok: true, value: evidence }, contract);
: toCallToolResult(
{ ok: true, value: evidence },
contract,
recorded === undefined
? undefined
: { retainedEvidenceId: evidence.evidence_id },
);
};
+9 -6
View File
@@ -43,7 +43,7 @@ const registerExportEvidenceTool = ({
exportContract.name,
toolRegistrationOptions(exportContract),
async (input) => {
const bundle = session.exportEvidenceBundle();
const bundle = bundleForSerialization(session);
const written = await writeEvidenceBundle(
bundle,
input.path,
@@ -73,7 +73,7 @@ const registerSnapshotEvidenceTool = ({
snapshotContract.name,
toolRegistrationOptions(snapshotContract),
() =>
toCallToolResult(ok(session.exportEvidenceBundle()), snapshotContract),
toCallToolResult(ok(bundleForSerialization(session)), snapshotContract),
);
};
@@ -90,9 +90,9 @@ const registerImportEvidenceTool = ({
const loaded = await readEvidenceBundle(path);
if (!loaded.ok) return toCallToolResult(loaded, importContract);
const retainedUnknownRevisions = new Set(
session
.exportEvidenceBundle()
.unknowns.map((unknown) => unknownRevisionKey(unknown)),
bundleForSerialization(session).unknowns.map((unknown) =>
unknownRevisionKey(unknown),
),
);
const imported = session.importEvidenceBundle(loaded.value);
return imported.ok
@@ -103,7 +103,7 @@ const registerImportEvidenceTool = ({
(unknown) =>
!retainedUnknownRevisions.has(unknownRevisionKey(unknown)),
).length,
total: session.exportEvidenceBundle().records.length,
total: bundleForSerialization(session).records.length,
}),
importContract,
)
@@ -112,6 +112,9 @@ const registerImportEvidenceTool = ({
);
};
const bundleForSerialization = (session: BinarySessionPort): EvidenceBundle =>
session.evidenceBundleForSerialization?.() ?? session.exportEvidenceBundle();
const unknownRevisionKey = (
unknown: EvidenceBundle["unknowns"][number],
): string => `${unknown.unknown_id}:${String(unknown.revision)}`;
+65 -2
View File
@@ -1,10 +1,18 @@
import type { CallToolResult } from "@modelcontextprotocol/server";
import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";
import type { ToolContract } from "../contracts/toolContracts.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { type AnalysisError } from "../domain/analysisErrorBase.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { Result } from "../domain/result.js";
import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
import { parseMcpResponseBudget } from "../config/mcpResponseBudget.js";
import {
encodeToolResult,
MCP_RESULT_BUDGET_BYTES,
MCP_RESULT_STRING_LIMIT,
} from "./toolResultEncoding.js";
/**
* Serialize an application result as MCP text and structured content.
@@ -14,8 +22,11 @@ import type { Result } from "../domain/result.js";
export const toCallToolResult = (
result: Result<JsonValue, AnalysisError>,
contract: ToolContract,
context?: { readonly retainedEvidenceId: string },
): CallToolResult =>
result.ok ? successResult(result.value, contract) : errorResult(result.error);
result.ok
? successResult(result.value, contract, context)
: errorResult(result.error);
const errorResult = (error: AnalysisError): CallToolResult => {
const projected = projectAnalysisError(error);
@@ -35,21 +46,73 @@ const errorResult = (error: AnalysisError): CallToolResult => {
const successResult = (
value: JsonValue,
contract: ToolContract,
context: { readonly retainedEvidenceId: string } | undefined,
): CallToolResult => {
const candidate =
projectEvidence(value) ??
(contract.kind === "session" ? { result: value } : value);
const configured = parseMcpResponseBudget(
process.env.REA_MCP_MAX_RESPONSE_BYTES,
);
if (!configured.ok) return errorResult(configured.error);
const budget =
configured.value === undefined
? MCP_RESULT_BUDGET_BYTES
: configured.value - 1024;
const encoded = encodeToolResult(candidate, budget);
if (!encoded.ok)
return errorResult(
new AnalysisResourceConstraintError(
contract.name,
"transport",
encoded.constraint === "string-length"
? "The complete MCP response exceeds Node's single-string representation limit. Use a focused retained-Evidence query or export to consume the complete analysis."
: "The complete MCP response exceeds the stdio response budget. The analysis result was not truncated; use a focused retained-Evidence query or export to consume it.",
{
boundary: "mcp-response",
default_receive_buffer_bytes: STDIO_DEFAULT_MAX_BUFFER_SIZE,
result_budget_bytes: budget,
max_string_code_units: MCP_RESULT_STRING_LIMIT,
response_bytes_at_least: encoded.bytesAtLeast,
response_code_units_at_least: encoded.codeUnitsAtLeast,
constraint: encoded.constraint,
...evidenceRecovery(value, context?.retainedEvidenceId),
},
),
);
return {
content: [
{
type: "text",
text: JSON.stringify(candidate),
text: encoded.text,
},
],
structuredContent: candidate,
};
};
const evidenceRecovery = (
value: JsonValue,
retainedEvidenceId: string | undefined,
): Record<string, JsonValue> => {
const projected = projectEvidence(value);
if (
projected === undefined ||
typeof projected !== "object" ||
projected === null ||
Array.isArray(projected)
)
return {};
if (projected.evidence_id !== retainedEvidenceId)
return { evidence_id: projected.evidence_id ?? null };
return {
evidence_reference: {
kind: "retained-evidence",
evidence_id: projected.evidence_id ?? null,
},
};
};
const projectEvidence = (value: JsonValue): JsonValue | undefined => {
if (
typeof value !== "object" ||
+55
View File
@@ -0,0 +1,55 @@
import { describe, expect, it } from "vitest";
import type { JsonValue } from "../domain/jsonValue.js";
import { encodeToolResult } from "./toolResultEncoding.js";
const projectedResult = (candidate: JsonValue) => ({
content: [{ type: "text", text: JSON.stringify(candidate) }],
structuredContent: candidate,
});
describe("MCP result encoding budget", () => {
it.each([
{ result: { value: 1 } },
{ result: ["中文", "😀", "\ud800", '"\\\n'] },
{ result: "x".repeat(8191) + "😀" + '中文\n"'.repeat(20000) },
])("counts actual UTF-8 structured and escaped text bytes", (candidate) => {
const encoded = encodeToolResult(candidate);
expect(encoded.ok).toBe(true);
if (!encoded.ok) throw new Error("Expected complete encoding");
expect(encoded.text).toBe(JSON.stringify(candidate));
expect(encoded.bytes).toBe(
Buffer.byteLength(JSON.stringify(projectedResult(candidate))),
);
});
it("accounts for repeated Evidence representations", () => {
const normalized = { value: '中文"'.repeat(30000) };
const candidate = {
result: normalized,
evidence: { normalized_result: normalized },
};
const completeBytes = Buffer.byteLength(
JSON.stringify(projectedResult(candidate)),
);
expect(encodeToolResult(candidate, completeBytes).ok).toBe(true);
expect(encodeToolResult(candidate, completeBytes - 1)).toMatchObject({
ok: false,
bytesAtLeast: completeBytes,
});
});
it("stops before reading the remainder of an oversized result", () => {
const candidate: JsonValue = { text: "x".repeat(1000000) };
Object.defineProperty(candidate, "remainder", {
enumerable: true,
get() {
throw new Error("The remainder must not be read");
},
});
// Only an already-known first property is visited before exhausting the
// budget. The serializer's property discovery must not eagerly read values.
expect(() => encodeToolResult(candidate, 1000)).not.toThrow();
expect(encodeToolResult(candidate, 1000).ok).toBe(false);
});
});
+55
View File
@@ -0,0 +1,55 @@
import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";
import { constants as bufferConstants } from "node:buffer";
import type { JsonValue } from "../domain/jsonValue.js";
import { bufferedJsonParts, jsonParts } from "../domain/jsonSerialization.js";
// Leave room for the SDK's JSON-RPC envelope and protocol metadata. This budget
// follows the pinned client's actual default framing limit, not a result-row cap.
export const MCP_RESULT_BUDGET_BYTES = STDIO_DEFAULT_MAX_BUFFER_SIZE - 1024;
export const MCP_RESULT_STRING_LIMIT = bufferConstants.MAX_STRING_LENGTH - 1024;
const RESULT_ENVELOPE_BYTES =
Buffer.byteLength(
JSON.stringify({
content: [{ type: "text", text: "" }],
structuredContent: null,
}),
) - 4;
/** Result of encoding the complete repeated MCP representations within a wire budget. */
export type ToolResultEncoding =
| { readonly ok: true; readonly text: string; readonly bytes: number }
| {
readonly ok: false;
readonly bytesAtLeast: number;
readonly codeUnitsAtLeast: number;
readonly constraint: "receive-buffer" | "string-length";
};
/** Account for structured JSON and escaped text before allocating the complete text. */
export const encodeToolResult = (
value: JsonValue,
budgetBytes = MCP_RESULT_BUDGET_BYTES,
): ToolResultEncoding => {
const parts: string[] = [];
let bytes = RESULT_ENVELOPE_BYTES;
let codeUnits = RESULT_ENVELOPE_BYTES;
for (const part of bufferedJsonParts(jsonParts(value))) {
const escapedPart = JSON.stringify(part);
bytes += Buffer.byteLength(part) + Buffer.byteLength(escapedPart) - 2;
codeUnits += part.length + escapedPart.length - 2;
if (bytes > budgetBytes || codeUnits > MCP_RESULT_STRING_LIMIT)
return {
ok: false,
bytesAtLeast: bytes,
codeUnitsAtLeast: codeUnits,
constraint:
codeUnits > MCP_RESULT_STRING_LIMIT
? "string-length"
: "receive-buffer",
};
parts.push(part);
}
return { ok: true, text: parts.join(""), bytes };
};