perf(mcp)!: default to compact input schema advertisements (#5975)

Use compact MCP input advertisements by default while preserving explicit full, canonical validation, output contracts and complete Evidence. Require an explicit selected catalog for runtime identity and honor both profiles in CLI status.

Real ripgrep/Zellij SDK tasks, independent ELF oracle, actual client trials, profile parity workflows and CI are recorded in experiments/analysis-efficiency/mcp-input-catalog.md. SDK token estimates improve; actual Codex token savings and general latency/memory gains are not established.

Refs #5861

BREAKING CHANGE: MCP input advertisements default to compact. Set REA_MCP_INPUT_SCHEMA_PROFILE=full for complete advertised guidance and nested constraints.
This commit is contained in:
gensokyo-dev authored and GitHub committed 2026-10-22 00:17:11 +08:00
1 parent 01ee6551b4
commit aa51e43439
45 files changed
+3887 -331

No files matched your search

+8
View File
@@ -8,6 +8,8 @@ import { providerCapabilitySet } from "../contracts/toolOutputSchemaPrimitives.j
import { providerCapabilitySets } from "./binary/BinarySessionStatus.js";
import { sqliteDatabaseCapability } from "./sqlite/SqliteDatabaseCapability.js";
import { CURRENT_ENTRYPOINT_PATH } from "../process/CurrentEntrypointPath.js";
import { createCatalogIdentity } from "../catalogIdentity.js";
import { compactPresentationForMcpInputSchemaProfile } from "../config/mcpInputSchemaProfile.js";
/** Read target-free provider status and operation availability. */
export const runSessionStatus = async (
@@ -33,6 +35,12 @@ export const runSessionStatus = async (
server_identity: createServerIdentity({
startedAt: new Date().toISOString(),
commandPath: CURRENT_ENTRYPOINT_PATH,
catalog: createCatalogIdentity(
compactPresentationForMcpInputSchemaProfile(
config.value.mcpInputSchemaProfile,
),
config.value.mcpOutputSchemaProfile ?? "full",
),
}),
};
} finally {
+2 -2
View File
@@ -1,4 +1,4 @@
import { CATALOG_IDENTITY } from "../catalogIdentity.js";
import { DEFAULT_CATALOG_IDENTITY } from "../catalogIdentity.js";
import { PRODUCT_IDENTITY } from "../identity.js";
import { ok } from "../domain/result.js";
import type { DoctorHost } from "./Doctor.js";
@@ -36,7 +36,7 @@ export const createDoctorHostFixture = (
installedSkillIdentity: () =>
Promise.resolve({
version: PRODUCT_IDENTITY.skillVersion,
toolCount: CATALOG_IDENTITY.counts.mcp_tools,
toolCount: DEFAULT_CATALOG_IDENTITY.counts.mcp_tools,
canonical: true,
}),
...overrides,
+6 -5
View File
@@ -45,7 +45,7 @@ import {
type InstalledSkillIdentity,
type SkillPathIssue,
} from "./SetupSkill.js";
import { CATALOG_IDENTITY } from "../catalogIdentity.js";
import { DEFAULT_CATALOG_IDENTITY } from "../catalogIdentity.js";
import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../identity.js";
import {
readClientRegistrationStatuses,
@@ -178,7 +178,8 @@ interface DoctorIdentity {
readonly cli_package_version: string;
readonly expected_skill_version: string;
readonly sdk: typeof SDK_IDENTITY;
readonly catalog: typeof CATALOG_IDENTITY;
/** Package default advertisement; the active server reports its selected profile. */
readonly catalog: typeof DEFAULT_CATALOG_IDENTITY;
readonly live_server: {
readonly state: "unknown";
readonly remediation: string;
@@ -390,8 +391,8 @@ const collectDoctorIdentity = async (
expected_skill_version: PRODUCT_IDENTITY.skillVersion,
sdk: SDK_IDENTITY,
catalog: {
counts: CATALOG_IDENTITY.counts,
digests: CATALOG_IDENTITY.digests,
counts: DEFAULT_CATALOG_IDENTITY.counts,
digests: DEFAULT_CATALOG_IDENTITY.digests,
},
live_server: {
state: "unknown",
@@ -422,7 +423,7 @@ const skillIdentityAligned = (
identity: InstalledSkillIdentity | undefined,
): boolean =>
identity?.version === PRODUCT_IDENTITY.skillVersion &&
identity.toolCount === CATALOG_IDENTITY.counts.mcp_tools &&
identity.toolCount === DEFAULT_CATALOG_IDENTITY.counts.mcp_tools &&
identity.canonical;
const skillIdentityState = (
+2 -2
View File
@@ -18,7 +18,7 @@ import type {
} from "./Doctor.js";
import type { LinuxDistribution } from "./LinuxHopper.js";
import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../identity.js";
import { CATALOG_IDENTITY } from "../catalogIdentity.js";
import { DEFAULT_CATALOG_IDENTITY } from "../catalogIdentity.js";
import type { ClientRegistrationStatus } from "./ClientRegistrationStatus.js";
import { setupRegistrationCommand } from "./SetupHost.js";
import { CURRENT_ENTRYPOINT_PATH } from "../process/CurrentEntrypointPath.js";
@@ -228,7 +228,7 @@ export class FakeSetupHost implements SetupHost {
cli_package_version: PRODUCT_IDENTITY.packageVersion,
expected_skill_version: PRODUCT_IDENTITY.skillVersion,
sdk: SDK_IDENTITY,
catalog: CATALOG_IDENTITY,
catalog: DEFAULT_CATALOG_IDENTITY,
live_server: {
state: "unknown",
remediation: "Inspect the running server.",
+10 -4
View File
@@ -19,6 +19,7 @@ import {
import type { McpOutputSchemaProfile } from "./config/mcpOutputSchemaProfile.js";
import {
COMPACT_INPUT_SCHEMA_BUDGET_BYTES,
compactPresentationForMcpInputSchemaProfile,
type McpInputSchemaProfile,
} from "./config/mcpInputSchemaProfile.js";
import { RECORDED_CATALOG_DIGEST_PROFILES } from "./recordedCatalogDigests.js";
@@ -111,7 +112,7 @@ const digestCatalogs = (
/**
* Catalog digests over the given tool contracts. Exported so tests can prove
* which contract fields the identity covers; production uses
* {@link CATALOG_IDENTITY}.
* {@link FULL_CATALOG_IDENTITY}.
*/
export const createCatalogDigests = (
contracts: readonly ToolContract[] = TOOL_CONTRACTS,
@@ -191,7 +192,12 @@ export const createCatalogIdentity = (
};
/**
* Stable, schema-sensitive identity; schema digests are recorded at build time
* or computed on first use.
* Full input/output advertisement identity. Digests are recorded at build time
* or computed on first use; this is independent of the configured default.
*/
export const CATALOG_IDENTITY = createCatalogIdentity();
export const FULL_CATALOG_IDENTITY = createCatalogIdentity();
/** Default MCP advertisement; explicit full/custom selections have their own identity. */
export const DEFAULT_CATALOG_IDENTITY = createCatalogIdentity(
compactPresentationForMcpInputSchemaProfile(undefined),
);
+5 -5
View File
@@ -12,16 +12,16 @@ export const COMPACT_INPUT_SCHEMA_BUDGET_BYTES = 13 * 1024;
export const mcpInputSchemaProfileSchema = z.enum(["full", "compact"]);
/** Select the exact compact presentation budget shared by registration and identity. */
/** Select the default compact advertisement, preserving an explicit full choice. */
export const compactPresentationForMcpInputSchemaProfile = (
profile: "full" | "compact" | undefined,
): { readonly budgetBytes: number } | undefined =>
profile === "compact"
? { budgetBytes: COMPACT_INPUT_SCHEMA_BUDGET_BYTES }
: undefined;
profile === "full"
? undefined
: { budgetBytes: COMPACT_INPUT_SCHEMA_BUDGET_BYTES };
const profileConstraint =
'REA_MCP_INPUT_SCHEMA_PROFILE must be "full" (default) or "compact". The compact profile advertises bounded input schemas with fewer nested annotations for providers with schema compatibility constraints.';
'REA_MCP_INPUT_SCHEMA_PROFILE must be "compact" (default) or "full". The compact profile advertises bounded input schemas with fewer nested annotations; full preserves complete advertised input guidance.';
export type McpInputSchemaProfile = z.infer<typeof mcpInputSchemaProfileSchema>;
+3
View File
@@ -77,6 +77,9 @@ export const parseConfig = (
...(env.REA_MCP_INPUT_SCHEMA_PROFILE === undefined
? {}
: { mcpInputSchemaProfile: env.REA_MCP_INPUT_SCHEMA_PROFILE }),
...(env.REA_MCP_OUTPUT_SCHEMA_PROFILE === undefined
? {}
: { mcpOutputSchemaProfile: env.REA_MCP_OUTPUT_SCHEMA_PROFILE }),
analysisProvider: env.REA_ANALYSIS_PROVIDER,
...(env.REA_IDA_MCP_CONFIG === undefined
? {}
+2
View File
@@ -4,10 +4,12 @@ import type { AnalysisProviderSelector } from "../contracts/providerSelection.js
import type { GhidraLanguageOverride } from "./ghidraLanguageOverride.js";
import type { McpInputSchemaProfile } from "./mcpInputSchemaProfile.js";
import type { McpOutputSchemaProfile } from "./mcpOutputSchemaProfile.js";
export interface AppConfig {
readonly mcpMaxResponseBytes?: number;
readonly mcpInputSchemaProfile?: McpInputSchemaProfile;
readonly mcpOutputSchemaProfile?: McpOutputSchemaProfile;
readonly analysisProvider: AnalysisProviderSelector;
readonly idaMcpConfigPath?: string;
readonly ghidraInstallDir: string | undefined;
+5 -2
View File
@@ -26,7 +26,10 @@ import {
presentAdvertisedInputSchema,
type CompactInputSchemaPresentation,
} from "../contracts/compactInputSchema.js";
import { CATALOG_IDENTITY, createCatalogIdentity } from "../catalogIdentity.js";
import {
FULL_CATALOG_IDENTITY,
createCatalogIdentity,
} from "../catalogIdentity.js";
import { transformAdvertisedInputJsonSchema } from "../contracts/toolSchemaMetadata.js";
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import {
@@ -165,7 +168,7 @@ export class EvidenceMcpServer extends RequestTrackingMcpServer {
: { budgetBytes: compactPresentation.budgetBytes };
this.catalogIdentity =
this.compactPresentation === undefined && !this.omitOutputSchemas
? CATALOG_IDENTITY
? FULL_CATALOG_IDENTITY
: createCatalogIdentity(
this.compactPresentation,
this.omitOutputSchemas ? "off" : "full",
+3 -6
View File
@@ -1,10 +1,7 @@
import { dirname, basename, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import {
CATALOG_IDENTITY,
type createCatalogIdentity,
} from "./catalogIdentity.js";
import type { createCatalogIdentity } from "./catalogIdentity.js";
import { PRODUCT_IDENTITY, SDK_IDENTITY } from "./identity.js";
/** Optional observations supplied by a client comparing its expected server. */
@@ -34,9 +31,9 @@ export const createServerIdentity = (input: {
readonly expected?: ExpectedServerIdentity;
readonly client?: ConnectedClientIdentity;
readonly protocolVersion?: string | undefined;
readonly catalog?: ReturnType<typeof createCatalogIdentity>;
readonly catalog: ReturnType<typeof createCatalogIdentity>;
}) => {
const catalog = input.catalog ?? CATALOG_IDENTITY;
const catalog = input.catalog;
const serverPath = input.commandPath || undefined;
const reasons: string[] = [];
if (