Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

perf(mcp): advertise each tool JSON Schema once per target (#1059)

Kaoru08225ccb9241be15
diff --git a/src/contracts/toolSchemaMetadata.test.ts b/src/contracts/toolSchemaMetadata.test.ts
new file mode 100644
index 000000000..1753bd949
--- /dev/null
+++ b/src/contracts/toolSchemaMetadata.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+
+import { TOOL_CONTRACTS, toolContract } from "./toolContracts.js";
+import {
+ toolInputSchemaWithMetadata,
+ toolOutputSchemaWithMetadata,
+} from "./toolSchemaMetadata.js";
+
+const target = "draft-2020-12";
+
+describe("advertised tool JSON Schema", () => {
+ it("projects each canonical contract once per target", () => {
+ for (const contract of TOOL_CONTRACTS) {
+ const input = toolInputSchemaWithMetadata(contract)["~standard"];
+ const output = toolOutputSchemaWithMetadata(contract)["~standard"];
+ const advertisedInput = input.jsonSchema.input({ target });
+ const advertisedOutput = output.jsonSchema.output({ target });
+
+ expect(input.jsonSchema.input({ target }), contract.name).toBe(
+ advertisedInput,
+ );
+ expect(output.jsonSchema.output({ target }), contract.name).toBe(
+ advertisedOutput,
+ );
+ expect(advertisedInput.examples, contract.name).toEqual(
+ contract.examples.map(({ input: example }) => example),
+ );
+ expect(advertisedOutput, contract.name).toEqual(
+ contract.outputSchema["~standard"].jsonSchema.output({ target }),
+ );
+ }
+ });
+
+ it("keeps other targets and library options distinct", () => {
+ const contract = toolContract("open_binary");
+ const input = toolInputSchemaWithMetadata(contract)["~standard"];
+ const latest = input.jsonSchema.input({ target });
+ const draft07 = input.jsonSchema.input({ target: "draft-07" });
+ const libraryOptions = { unrepresentable: "any" };
+ const configured = input.jsonSchema.input({ target, libraryOptions });
+
+ expect(latest.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
+ expect(draft07.$schema).toBe("http://json-schema.org/draft-07/schema#");
+ expect(input.jsonSchema.input({ target: "draft-07" })).toBe(draft07);
+ expect(configured).not.toBe(latest);
+ expect(input.jsonSchema.input({ target, libraryOptions })).not.toBe(
+ configured,
+ );
+ expect(
+ toolInputSchemaWithMetadata(contract).safeParse(
+ contract.examples[0]?.input,
+ ).success,
+ ).toBe(true);
+ });
+});
diff --git a/src/contracts/toolSchemaMetadata.ts b/src/contracts/toolSchemaMetadata.ts
index 79c477b61..90762695b 100644
--- a/src/contracts/toolSchemaMetadata.ts
+++ b/src/contracts/toolSchemaMetadata.ts
@@ -47,37 +47,72 @@ const PROPERTY_DESCRIPTIONS: Readonly<Record<string, string>> = {
unknown_id: "Exact residual-unknown identifier.",
};
+type JsonSchemaProjection = z.ZodType["~standard"]["jsonSchema"]["input"];
+
/** Attach caller guidance to a canonical schema for the SDK wire projection. */
export const toolInputSchemaWithMetadata = <Contract extends ToolContract>(
contract: Contract,
-): Contract["inputSchema"] => {
- const schema = contract.inputSchema.meta(
- z.globalRegistry.get(contract.inputSchema) ?? {},
+): Contract["inputSchema"] =>
+ withAdvertisedJsonSchema(
+ contract.inputSchema,
+ "input",
+ (project) => (options) => ({
+ ...describeProperties(project(options)),
+ examples: contract.examples.map(({ input }) => input),
+ }),
);
- const standard = schema["~standard"];
- const inputJsonSchema = standard.jsonSchema?.input;
- if (inputJsonSchema === undefined)
- throw new TypeError(
- "Tool input schema does not expose Standard JSON Schema",
- );
+/** Advertise a canonical output schema without reconverting it per listing. */
+export const toolOutputSchemaWithMetadata = <Contract extends ToolContract>(
+ contract: Contract,
+): Contract["outputSchema"] =>
+ withAdvertisedJsonSchema(contract.outputSchema, "output");
+
+const withAdvertisedJsonSchema = <Schema extends z.ZodType>(
+ canonical: Schema,
+ io: "input" | "output",
+ advertise: (project: JsonSchemaProjection) => JsonSchemaProjection = (
+ project,
+ ) => project,
+): Schema => {
// Zod's input projection drops root metadata when a descendant transforms.
// Preserve the parser and let the SDK own conversion of everything else.
+ const schema = canonical.meta(z.globalRegistry.get(canonical) ?? {});
+ const standard = schema["~standard"];
+ const project = standard.jsonSchema?.[io];
+ if (project === undefined)
+ throw new TypeError(
+ `Tool ${io} schema does not expose Standard JSON Schema`,
+ );
Object.defineProperty(schema, "~standard", {
value: {
...standard,
jsonSchema: {
...standard.jsonSchema,
- input: (options: Parameters<typeof inputJsonSchema>[0]) => ({
- ...describeProperties(inputJsonSchema(options)),
- examples: contract.examples.map(({ input }) => input),
- }),
+ [io]: memoizeByTarget(advertise(project)),
},
},
});
return schema;
};
+// The SDK reconverts every registered schema on each `tools/list`, although a
+// registered contract cannot change. Like the SDK's own memoized output
+// projection, the advertised value is shared and treated as read-only.
+const memoizeByTarget = (
+ project: JsonSchemaProjection,
+): JsonSchemaProjection => {
+ const byTarget = new Map<string, Record<string, unknown>>();
+ return (options) => {
+ if (options.libraryOptions !== undefined) return project(options);
+ const cached = byTarget.get(options.target);
+ if (cached !== undefined) return cached;
+ const projected = project(options);
+ byTarget.set(options.target, projected);
+ return projected;
+ };
+};
+
const describeProperties = (
value: Readonly<Record<string, unknown>>,
): Record<string, unknown> =>
diff --git a/src/server/toolRegistrationOptions.ts b/src/server/toolRegistrationOptions.ts
index 100648d5c..0f0b92679 100644
--- a/src/server/toolRegistrationOptions.ts
+++ b/src/server/toolRegistrationOptions.ts
@@ -1,5 +1,8 @@
import type { ToolContract } from "../contracts/toolContracts.js";
-import { toolInputSchemaWithMetadata } from "../contracts/toolSchemaMetadata.js";
+import {
+ toolInputSchemaWithMetadata,
+ toolOutputSchemaWithMetadata,
+} from "../contracts/toolSchemaMetadata.js";
/** Project the canonical Zod contracts directly into SDK registration. */
export const toolRegistrationOptions = <Contract extends ToolContract>(
@@ -14,6 +17,6 @@ export const toolRegistrationOptions = <Contract extends ToolContract>(
title: contract.title,
description: contract.description,
inputSchema: toolInputSchemaWithMetadata(contract),
- outputSchema: contract.outputSchema,
+ outputSchema: toolOutputSchemaWithMetadata(contract),
annotations: contract.annotations,
});