test(mcp): consolidate schema profile proof at server boundaries (#11871)

This commit is contained in:
morluto authored and GitHub committed 2026-11-18 06:23:34 +08:00
1 parent e9cc643198
commit b7461b7b14
5 files changed
+103 -222

No files matched your search

@@ -7,11 +7,9 @@ import {
TOOL_CONTRACTS,
toolContract,
} from "../../../src/contracts/toolContracts.js";
import { PROMPT_CONTRACTS } from "../../../src/contracts/promptContracts.js";
import { advertisedInputJsonSchema } from "../../../src/contracts/toolSchemaMetadata.js";
import { advertiseTool } from "../../../src/contracts/advertisedTool.js";
import { createCatalogDigests } from "../../../src/contracts/catalog/catalogIdentity.js";
import { parseMcpInputSchemaProfile } from "../../../src/config/mcpInputSchemaProfile.js";
import { processScenarioSchema } from "../../../src/domain/process/processScenario.js";
import { EvidenceMcpServer } from "../../../src/server/EvidenceMcpServer.js";
import { createToolResultDelivery } from "../../../src/server/toolResult.js";
@@ -69,65 +67,35 @@ const canonicalTools = (): readonly AdvertisedTool[] =>
inputSchema: advertisedInputJsonSchema(contract),
}));
describe("MCP compact input schema profile", () => {
it("matches the catalog digest to tools/list and excludes stripped annotations", async () => {
const compactPresentation = {
budgetBytes: COMPACT_INPUT_SCHEMA_BUDGET_BYTES,
};
const compact = compactServer();
registerCatalog(compact);
const compactTools = new Map(
(await listToolsThroughTransport(compact)).map((tool) => [
tool.name,
tool,
]),
);
for (const contract of TOOL_CONTRACTS)
expect(compactTools.get(contract.name)?.inputSchema).toEqual(
advertiseTool(
{ inputSchema: advertisedInputJsonSchema(contract) },
advertisedToolPresentation("off", compactPresentation),
).inputSchema,
);
const compactIdentity = createCatalogDigests();
expect(compact.catalogIdentity.digests).toEqual(compactIdentity);
expect(
createCatalogDigests(TOOL_CONTRACTS, PROMPT_CONTRACTS, {
budgetBytes: 1,
}).tools_sha256,
).not.toBe(compactIdentity.tools_sha256);
// Examples are not advertised, so they do not change the identity.
const withoutExamples = TOOL_CONTRACTS.map((contract) =>
contract.examples.length === 0 ? contract : { ...contract, examples: [] },
);
expect(createCatalogDigests(withoutExamples).tools_sha256).toBe(
compactIdentity.tools_sha256,
);
});
});
it("extends tool descriptions only with input guidance", async () => {
it("advertises compact inputs and guidance with matching default catalog identity", async () => {
const compact = compactServer();
registerCatalog(compact);
const compactTools = await listToolsThroughTransport(compact);
expect(compactTools.length).toBe(TOOL_CONTRACTS.length);
for (const tool of compactTools) {
// Guidance the compact schema omits follows the unchanged description.
const contract = TOOL_CONTRACTS.find(({ name }) => name === tool.name);
if (contract === undefined) throw new Error(`Missing ${tool.name}`);
expect(tool.description, tool.name).toBe(
advertiseTool(
{
description: toolRegistrationOptions(contract).description,
inputSchema: advertisedInputJsonSchema(contract),
},
advertisedToolPresentation("off"),
).description,
expect(compactTools).toHaveLength(TOOL_CONTRACTS.length);
const byName = new Map(compactTools.map((tool) => [tool.name, tool]));
for (const contract of TOOL_CONTRACTS) {
const tool = byName.get(contract.name);
const expected = advertiseTool(
{
description: toolRegistrationOptions(contract).description,
inputSchema: advertisedInputJsonSchema(contract),
},
advertisedToolPresentation("off"),
);
expect(tool.inputSchema.description, tool.name).toBeUndefined();
expect(tool?.inputSchema, contract.name).toEqual(expected.inputSchema);
expect(tool?.description, contract.name).toBe(expected.description);
expect(tool?.inputSchema.description, contract.name).toBeUndefined();
}
const identity = createCatalogDigests();
expect(compact.catalogIdentity.digests).toEqual(identity);
// Examples are absent from the advertised catalog and its identity.
const withoutExamples = TOOL_CONTRACTS.map((contract) =>
contract.examples.length === 0 ? contract : { ...contract, examples: [] },
);
expect(createCatalogDigests(withoutExamples).tools_sha256).toBe(
identity.tools_sha256,
);
});
it("detects missing client-required items in nested array alternatives", () => {
@@ -354,14 +322,6 @@ it("retains parameter types and avoids client-side reference expansion", async (
});
});
it("parses the profile selection the server startup reads", () => {
expect(parseMcpInputSchemaProfile("compact")).toEqual({
ok: true,
value: "compact",
});
expect(parseMcpInputSchemaProfile("surprise")).not.toHaveProperty("value");
});
describe("MCP compact input schema canonical enforcement", () => {
it("still rejects canonical-invalid arguments the compact advertisement accepts", async () => {
const server = compactServer();
+35 -77
View File
@@ -1,6 +1,7 @@
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
import { Ajv2020 } from "ajv/dist/2020.js";
import { z } from "zod";
import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js";
import { expect, it, onTestFinished } from "vitest";
import {
@@ -13,12 +14,11 @@ import { createTestBinarySession } from "../../fixtures/binarySession.js";
import { EvidenceMcpServer } from "../../../src/server/EvidenceMcpServer.js";
import { toolRegistrationOptions } from "../../../src/server/toolRegistrationOptions.js";
import { createToolResultDelivery } from "../../../src/server/toolResult.js";
import { createCatalogIdentity } from "../../../src/contracts/catalog/catalogIdentity.js";
import type { ToolContract } from "../../../src/contracts/toolContractTypes.js";
import { DEFAULT_CATALOG_IDENTITY } from "../../../src/contracts/catalog/catalogIdentity.js";
import { advertisedSchemaErrors } from "../../fixtures/mcpAdvertisedSchemaValidity.js";
import {
COMPACT_OUTPUT_SCHEMA_BUDGET_BYTES,
resolveMcpOutputSchemaProfile,
type McpOutputSchemaProfile,
} from "../../../src/contracts/mcpSchemaPresentation.js";
import { createMcpSchemaValidation } from "../../fixtures/mcpSchemaValidation.js";
@@ -33,11 +33,8 @@ const createServer = (outputSchemaProfile: McpOutputSchemaProfile) =>
outputSchemaProfile,
);
it("omits only output schema advertisements and keeps canonical MCP output validation", async () => {
it("rejects canonical-invalid output when output schema advertisements are off", async () => {
const server = createServer("off");
expect(server.catalogIdentity.digests.combined_sha256).toBe(
DEFAULT_CATALOG_IDENTITY.digests.combined_sha256,
);
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
const client = new Client(
@@ -53,18 +50,6 @@ it("omits only output schema advertisements and keeps canonical MCP output valid
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
async () => ({
content: [{ type: "text" as const, text: "fixture" }],
structuredContent: { value: "complete" },
}),
);
const invalidContract = {
...contract,
name: "invalid_output_schema_fixture",
} satisfies ToolContract;
server.registerTool(
invalidContract.name,
toolRegistrationOptions(invalidContract),
async () => ({
content: [{ type: "text" as const, text: "invalid fixture" }],
structuredContent: { value: 42 },
@@ -74,17 +59,11 @@ it("omits only output schema advertisements and keeps canonical MCP output valid
await server.connect(serverTransport);
await client.connect(clientTransport);
try {
const tools = (await client.listTools()).tools;
expect(tools).toHaveLength(2);
expect(tools.every((tool) => tool.outputSchema === undefined)).toBe(true);
const success = await client.callTool({
name: contract.name,
arguments: {},
});
expect(success.isError).not.toBe(true);
expect(success.structuredContent).toEqual({ value: "complete" });
const { tools } = await client.listTools();
expect(tools).toMatchObject([{ name: contract.name }]);
expect(tools[0]?.outputSchema).toBeUndefined();
const invalid = await client.callTool({
name: invalidContract.name,
name: contract.name,
arguments: {},
});
expect(invalid.isError).toBe(true);
@@ -100,10 +79,10 @@ it("omits only output schema advertisements and keeps canonical MCP output valid
}
});
it("bounds output schema advertisements and keeps canonical MCP output validation", async () => {
it("strips nested guidance from compact output schemas and preserves result fields", async () => {
const server = createServer("compact");
expect(server.catalogIdentity.digests.combined_sha256).not.toBe(
DEFAULT_CATALOG_IDENTITY.digests.combined_sha256,
expect(server.catalogIdentity.digests).toEqual(
createCatalogIdentity({ outputSchemaProfile: "compact" }).digests,
);
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
@@ -130,24 +109,10 @@ it("bounds output schema advertisements and keeps canonical MCP output validatio
structuredContent: { value: "complete", nested: { count: 1 } },
}),
);
const invalidContract = {
...contract,
name: "invalid_compact_output_schema_fixture",
} satisfies ToolContract;
server.registerTool(
invalidContract.name,
toolRegistrationOptions(invalidContract),
async () => ({
content: [{ type: "text" as const, text: "invalid fixture" }],
structuredContent: { value: 42, nested: { count: 1 } },
}),
);
await server.connect(serverTransport);
await client.connect(clientTransport);
try {
const tools = (await client.listTools()).tools;
expect(tools).toHaveLength(2);
const advertised = tools.find((tool) => tool.name === contract.name)!
.outputSchema as Record<string, unknown>;
expect(advertised.type).toBe("object");
@@ -168,17 +133,6 @@ it("bounds output schema advertisements and keeps canonical MCP output validatio
value: "complete",
nested: { count: 1 },
});
const invalid = await client.callTool({
name: invalidContract.name,
arguments: {},
});
expect(invalid.isError).toBe(true);
expect(invalid.content).toEqual([
expect.objectContaining({
type: "text",
text: expect.stringContaining("Output validation error"),
}),
]);
} finally {
await client.close();
await server.close();
@@ -188,25 +142,13 @@ it("bounds output schema advertisements and keeps canonical MCP output validatio
it("keeps both output profiles below a measured one-megabyte frame", async () => {
const names = new Set(TOOL_CONTRACTS.map(({ name }) => name));
const measure = async (profile: McpOutputSchemaProfile): Promise<number> => {
const server = createServer(profile);
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
const client = new Client(
{ name: "catalog-size-test", version: "1" },
{ jsonSchemaValidator: createMcpSchemaValidation() },
);
for (const contract of TOOL_CONTRACTS)
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
async () => ({
content: [{ type: "text" as const, text: "unused" }],
}),
);
await server.connect(serverTransport);
await client.connect(clientTransport);
const harness = await createApplicationMcpHarness({
serverOptions: {
environment: { REA_MCP_OUTPUT_SCHEMA_PROFILE: profile },
},
});
try {
const listed = await client.listTools();
const listed = await harness.client.listTools();
expect(listed.tools).toHaveLength(names.size);
expect(new Set(listed.tools.map((tool) => tool.name))).toEqual(names);
if (profile === "off")
@@ -235,8 +177,7 @@ it("keeps both output profiles below a measured one-megabyte frame", async () =>
}
return Buffer.byteLength(JSON.stringify(listed), "utf8");
} finally {
await client.close();
await server.close();
await harness.close();
}
};
@@ -356,8 +297,25 @@ it("rejects canonical-invalid output that the reduced advertisement accepts", as
}
});
it.each(["REA_MCP_INPUT_SCHEMA_PROFILE", "REA_MCP_OUTPUT_SCHEMA_PROFILE"])(
"rejects a retained full profile in $0 at server startup",
async (setting) => {
await expect(
createApplicationMcpHarness({
serverOptions: { environment: { [setting]: "full" } },
}),
).rejects.toMatchObject({
settings: [
{
setting,
constraint: expect.stringMatching(/full.*removed.*compact/u),
},
],
});
},
);
it("omits output schemas by default and still delivers validated structured results", async () => {
expect(resolveMcpOutputSchemaProfile(undefined)).toBe("off");
const session = createTestBinarySession(() => {
throw new Error("No deep provider may start for a catalog listing");
});
@@ -1,40 +0,0 @@
import { describe, expect, it } from "vitest";
import { parseMcpInputSchemaProfile } from "../../../src/config/mcpInputSchemaProfile.js";
import { parseConfig } from "../../../src/config/parseConfig.js";
describe("MCP input schema profile configuration", () => {
it("accepts only the compact presentation", () => {
expect(parseMcpInputSchemaProfile(undefined)).toEqual({
ok: true,
value: undefined,
});
expect(parseMcpInputSchemaProfile("compact")).toEqual({
ok: true,
value: "compact",
});
});
// `full` was removed; a registration that still selects it fails closed.
it.each(["full", "", "FULL", "compact ", "minimal", "0"])(
"rejects unsupported profiles: %j",
(value) => {
const parsed = parseMcpInputSchemaProfile(value);
if (parsed.ok) throw new Error("Expected invalid profile");
expect(parsed.error.settings).toEqual([
{
setting: "REA_MCP_INPUT_SCHEMA_PROFILE",
constraint: expect.any(String),
},
]);
},
);
it("refuses the removed full profile at server configuration", () => {
const parsed = parseConfig({ REA_MCP_INPUT_SCHEMA_PROFILE: "full" });
if (parsed.ok) throw new Error("Expected the removed profile to fail");
expect(parsed.error.settings).toEqual([
expect.objectContaining({ setting: "REA_MCP_INPUT_SCHEMA_PROFILE" }),
]);
});
});
@@ -1,41 +0,0 @@
import { describe, expect, it } from "vitest";
import { parseMcpOutputSchemaProfile } from "../../../src/config/mcpOutputSchemaProfile.js";
import { parseConfig } from "../../../src/config/parseConfig.js";
describe("MCP output schema profile configuration", () => {
it("accepts the off and compact presentations", () => {
expect(parseMcpOutputSchemaProfile(undefined)).toEqual({
ok: true,
value: undefined,
});
for (const value of ["compact", "off"] as const)
expect(parseMcpOutputSchemaProfile(value)).toEqual({
ok: true,
value,
});
});
// `full` was removed; a registration that still selects it fails closed.
it.each(["full", "", "FULL", "compact ", "off ", "minimal", "0"])(
"rejects unsupported profiles: %j",
(value) => {
const parsed = parseMcpOutputSchemaProfile(value);
if (parsed.ok) throw new Error("Expected invalid profile");
expect(parsed.error.settings).toEqual([
{
setting: "REA_MCP_OUTPUT_SCHEMA_PROFILE",
constraint: expect.any(String),
},
]);
},
);
it("refuses the removed full profile at server configuration", () => {
const parsed = parseConfig({ REA_MCP_OUTPUT_SCHEMA_PROFILE: "full" });
if (parsed.ok) throw new Error("Expected the removed profile to fail");
expect(parsed.error.settings).toEqual([
expect.objectContaining({ setting: "REA_MCP_OUTPUT_SCHEMA_PROFILE" }),
]);
});
});
@@ -0,0 +1,44 @@
import { expect, it } from "vitest";
import { parseConfig } from "../../../src/config/parseConfig.js";
it.each(["off", "compact"] as const)(
"admits compact input and %s output in process configuration",
(output) => {
const parsed = parseConfig({
REA_MCP_INPUT_SCHEMA_PROFILE: "compact",
REA_MCP_OUTPUT_SCHEMA_PROFILE: output,
});
if (!parsed.ok) throw parsed.error;
expect(parsed.value.mcpOutputSchemaProfile).toBe(output);
},
);
const input = "REA_MCP_INPUT_SCHEMA_PROFILE";
const output = "REA_MCP_OUTPUT_SCHEMA_PROFILE";
const unsupported = ["full", "", "COMPACT", "compact "];
it.each([
...unsupported.map((value) => ({
setting: input,
value,
profiles: /compact/u,
})),
...unsupported.map((value) => ({
setting: output,
value,
profiles: /off.*compact/u,
})),
{ setting: input, value: "off", profiles: /compact/u },
])(
"rejects $setting=$value in process configuration",
({ setting, value, profiles }) => {
const parsed = parseConfig({ [setting]: value });
expect(parsed).toMatchObject({
ok: false,
error: {
settings: [{ setting, constraint: expect.stringMatching(profiles) }],
},
});
},
);