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:
@@ -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 = (
|
||||
|
||||
@@ -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 },
|
||||
);
|
||||
};
|
||||
|
||||
@@ -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 },
|
||||
);
|
||||
};
|
||||
|
||||
@@ -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)}`;
|
||||
|
||||
@@ -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" ||
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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 };
|
||||
};
|
||||
Reference in New Issue
Block a user