feat(mcp)!: harden contracts and evidence references

BREAKING CHANGE: comparison tools now require session-owned Evidence IDs or approved bundle paths, and structured Evidence results use compact references.
This commit is contained in:
morluto
2026-07-16 19:49:58 +08:00
parent ad398a17f5
commit ee1cd40405
47 changed files with 1387 additions and 672 deletions
+69
View File
@@ -0,0 +1,69 @@
import { Buffer } from "node:buffer";
import { dirname, join } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { ensureGeneratedFile } from "./lib/generated-file.mjs";
const arguments_ = new Set(process.argv.slice(2));
for (const argument of arguments_)
if (argument !== "--check")
throw new Error(`Unknown MCP schema report option: ${argument}`);
const root = join(dirname(fileURLToPath(import.meta.url)), "..");
const cachebuster = `?${String(Date.now())}`;
const { TOOL_CONTRACTS } = await import(
`${pathToFileURL(join(root, "dist/contracts/toolContracts.js")).href}${cachebuster}`
);
const { toolRegistrationOptions } = await import(
`${pathToFileURL(join(root, "dist/server/toolRegistrationOptions.js")).href}${cachebuster}`
);
const bytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
const tools = TOOL_CONTRACTS.map((contract) => {
const registration = toolRegistrationOptions(contract);
const inputSchema = registration.inputSchema["~standard"].jsonSchema.input();
const outputSchema =
registration.outputSchema["~standard"].jsonSchema.output();
const wire = {
name: contract.name,
title: registration.title,
description: registration.description,
inputSchema,
outputSchema,
annotations: registration.annotations,
};
return {
name: contract.name,
bytes: bytes(wire),
input_schema_bytes: bytes(inputSchema),
output_schema_bytes: bytes(outputSchema),
wire,
};
}).sort((left, right) => left.name.localeCompare(right.name));
const maximumToolBytes = 64 * 1024;
const maximumListBytes = 512 * 1024;
const listBytes = bytes({ tools: tools.map(({ wire }) => wire) });
const oversized = tools.filter((tool) => tool.bytes > maximumToolBytes);
if (oversized.length > 0 || listBytes > maximumListBytes)
throw new Error(
`MCP schema budget exceeded: tools/list=${String(listBytes)}, oversized=${oversized.map(({ name, bytes: size }) => `${name}:${String(size)}`).join(",")}`,
);
const report = {
generated_from: "@modelcontextprotocol/server 2.0.0-beta.4 wire registration",
tool_count: tools.length,
tools_list_bytes: listBytes,
budgets: {
tools_list_bytes: maximumListBytes,
per_tool_bytes: maximumToolBytes,
},
tools: tools.map(({ wire: _wire, ...tool }) => tool),
};
await ensureGeneratedFile({
path: join(root, "docs/mcp-schema-report.json"),
source: `${JSON.stringify(report, null, 2)}\n`,
check: arguments_.has("--check"),
generateCommand: "npm run docs:generate",
});
+1 -1
View File
@@ -5,7 +5,7 @@ import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
// Route production MCP before importing Incur. Incur owns registration helpers
// such as `mcp add`, while only dist/main.js may serve the 80-tool stdio server.
// such as `mcp add`, while only dist/main.js may serve the stdio tool catalog.
const args = process.argv.slice(2);
const { default: packageJson } = await import("../package.json", {
with: { type: "json" },
+16 -3
View File
@@ -692,6 +692,18 @@ try {
(await readFile(siblingSkillPath, "utf8")) !== "unrelated skill\n"
)
throw new Error("packaged stale-skill upgrade was not isolated");
const alignedDoctor = json(
await run(cli, ["doctor", "--json"], environment),
);
if (
alignedDoctor.identity?.skill?.state !== "aligned" ||
alignedDoctor.identity?.skill?.installed_tool_count !==
TOOL_CONTRACTS.length ||
alignedDoctor.checks?.some(({ name }) => name === "skill:identity")
)
throw new Error(
"packaged doctor did not report the upgraded skill aligned",
);
await writeFile(claudeConfig, "malformed");
await writeFile(cursorConfig, '{"existing":true}\n');
@@ -860,7 +872,7 @@ try {
);
if (opened.isError === true)
throw new Error("packaged MCP could not open a binary");
const providerStatus = json(
const providerStatusEnvelope = json(
prompts.mcpText(
await client.callTool(
{ name: "binary_session", arguments: {} },
@@ -868,6 +880,7 @@ try {
),
),
);
const providerStatus = providerStatusEnvelope.result;
if (
providerStatus.analysis_provider_binding?.provider?.id !== "hopper" ||
providerStatus.analysis_provider_binding?.selection_source !== "request"
@@ -891,13 +904,13 @@ try {
)
throw new Error("packaged Linux MCP did not reject an unpinned Hopper");
} else {
if (json(prompts.mcpText(current)).normalized_result !== "fixture")
if (json(prompts.mcpText(current)).result !== "fixture")
throw new Error("packaged MCP bridge call failed");
const batch = await client.callTool(
{ name: "batch_decompile", arguments: { addresses: ["0x1000"] } },
mcpOptions,
);
const batchResult = json(prompts.mcpText(batch)).normalized_result;
const batchResult = json(prompts.mcpText(batch)).result;
if (
batch.isError === true ||
batchResult?.total !== 1 ||
+4 -2
View File
@@ -1,6 +1,8 @@
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { CATALOG_IDENTITY } from "../dist/catalogIdentity.js";
const version = process.argv[2];
if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(version ?? ""))
throw new Error("Usage: node scripts/verify-published-package.mjs <version>");
@@ -22,7 +24,7 @@ transport.stderr?.on("data", (chunk) => {
try {
await client.connect(transport);
const tools = await client.listTools();
if (tools.tools.length !== 80)
if (tools.tools.length !== CATALOG_IDENTITY.counts.mcp_tools)
throw new Error(
`Published MCP exposed ${String(tools.tools.length)} tools`,
);
@@ -40,5 +42,5 @@ try {
}
process.stdout.write(
`${JSON.stringify({ package: "rea-agents", version, mcpTools: 80 })}\n`,
`${JSON.stringify({ package: "rea-agents", version, mcpTools: CATALOG_IDENTITY.counts.mcp_tools })}\n`,
);
+3 -1
View File
@@ -362,7 +362,9 @@ try {
const expectedNames = TOOL_CONTRACTS.map(({ name }) => name).sort();
const actualNames = listed.tools.map(({ name }) => name).sort();
if (JSON.stringify(actualNames) !== JSON.stringify(expectedNames)) {
throw new Error("The real server did not expose the intended 80 tools");
throw new Error(
"The real server tool inventory did not match its contracts",
);
}
const options = { timeout };