Skip to content

Commit bb0c2a9

Browse files
t3dotggclaude
andcommitted
feat(server): MCP tool schemas drop JSON noise
Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent e3592ef commit bb0c2a9

4 files changed

Lines changed: 114 additions & 4 deletions

File tree

‎apps/server/src/mcp/McpHttpServer.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ import {
3535
MAX_REPORTED_DEPTH,
3636
toolOutcome,
3737
} from "../telemetry/ProviderDimensions.ts";
38+
import { advertisedJsonSchema } from "./advertisedJsonSchema.ts";
3839
import * as McpInvocationContext from "./McpInvocationContext.ts";
3940
import * as McpToolAccess from "./McpToolAccess.ts";
4041
import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
@@ -448,7 +449,7 @@ const registerPreviewSnapshot = Effect.fn("McpHttpServer.registerPreviewSnapshot
448449
tool: new McpSchema.Tool({
449450
name: tool.name,
450451
description: Tool.getDescription(tool),
451-
inputSchema: Tool.getJsonSchema(tool),
452+
inputSchema: advertisedJsonSchema(tool),
452453
annotations: {
453454
...Context.getOption(tool.annotations, Tool.Title).pipe(
454455
Option.map((title) => ({ title })),
@@ -632,7 +633,7 @@ const registerImageTool = Effect.fn("McpHttpServer.registerImageTool")(function*
632633
tool: new McpSchema.Tool({
633634
name: tool.name,
634635
description: Tool.getDescription(tool),
635-
inputSchema: Tool.getJsonSchema(tool),
636+
inputSchema: advertisedJsonSchema(tool),
636637
annotations: {
637638
...Context.getOption(tool.annotations, Tool.Title).pipe(
638639
Option.map((title) => ({ title })),
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
import { expect, it } from "@effect/vitest";
2+
import * as Schema from "effect/Schema";
3+
import { Tool } from "effect/ai";
4+
5+
import { advertisedJsonSchema } from "./advertisedJsonSchema.ts";
6+
7+
it("drops JSON noise but keeps null where it is required", () => {
8+
const Every = Schema.Struct({ ms: Schema.Int });
9+
const tool = Tool.make("example", {
10+
parameters: Schema.Struct({
11+
threadId: Schema.optional(Schema.NullOr(Schema.String)),
12+
beforeRunId: Schema.NullOr(Schema.String),
13+
limit: Schema.optional(Schema.Int),
14+
every: Schema.Union([Every, Schema.fromJsonString(Every)]),
15+
target: Schema.optional(
16+
Schema.NullOr(
17+
Schema.Union([
18+
Schema.Struct({ kind: Schema.Literal("url"), url: Schema.String }),
19+
Schema.Struct({ kind: Schema.Literal("number"), number: Schema.Int }),
20+
]),
21+
),
22+
),
23+
}),
24+
});
25+
26+
expect(advertisedJsonSchema(tool)).toEqual({
27+
type: "object",
28+
properties: {
29+
threadId: { type: "string" },
30+
beforeRunId: { anyOf: [{ type: "string" }, { type: "null" }] },
31+
limit: { type: "integer" },
32+
every: { type: "object", properties: { ms: { type: "integer" } }, required: ["ms"] },
33+
target: {
34+
anyOf: [
35+
{
36+
type: "object",
37+
properties: { kind: { type: "string", enum: ["url"] }, url: { type: "string" } },
38+
required: ["kind", "url"],
39+
},
40+
{
41+
type: "object",
42+
properties: { kind: { type: "string", enum: ["number"] }, number: { type: "integer" } },
43+
required: ["kind", "number"],
44+
},
45+
],
46+
},
47+
},
48+
required: ["beforeRunId", "every"],
49+
});
50+
});
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
import { Tool } from "effect/ai";
2+
3+
type Json = unknown;
4+
type JsonObject = { [key: string]: Json };
5+
6+
const isObject = (value: Json): value is JsonObject =>
7+
typeof value === "object" && value !== null && !Array.isArray(value);
8+
9+
const isNullSchema = (value: Json) =>
10+
isObject(value) && value.type === "null" && Object.keys(value).length === 1;
11+
12+
const isBareAnyOf = (value: Json): value is { anyOf: Array<Json> } =>
13+
isObject(value) && Array.isArray(value.anyOf) && Object.keys(value).length === 1;
14+
15+
// A `Schema.fromJsonString` fallback. Advertised beside object shapes, it invites stringified input.
16+
const isJsonStringSchema = (value: Json) =>
17+
isObject(value) && value.type === "string" && value.contentMediaType === "application/json";
18+
19+
const SAFE_INTEGER_BOUNDS: Record<string, number> = {
20+
maximum: Number.MAX_SAFE_INTEGER,
21+
minimum: Number.MIN_SAFE_INTEGER,
22+
};
23+
24+
const compact = (schema: Json, optional: boolean): Json => {
25+
if (Array.isArray(schema)) return schema.map((item) => compact(item, false));
26+
if (!isObject(schema)) return schema;
27+
const required = new Set(Array.isArray(schema.required) ? schema.required : []);
28+
let result: JsonObject = {};
29+
for (const [key, value] of Object.entries(schema)) {
30+
if (key === "additionalProperties" && value === true) continue;
31+
if (SAFE_INTEGER_BOUNDS[key] === value) continue;
32+
result[key] =
33+
key === "properties" && isObject(value)
34+
? Object.fromEntries(
35+
Object.entries(value).map(([name, property]) => [
36+
name,
37+
compact(property, !required.has(name)),
38+
]),
39+
)
40+
: compact(value, false);
41+
}
42+
if (Array.isArray(result.anyOf)) {
43+
const branches = result.anyOf
44+
.flatMap((branch) => (isBareAnyOf(branch) ? branch.anyOf : [branch]))
45+
.filter((branch) => !(optional && isNullSchema(branch)) && !isJsonStringSchema(branch));
46+
const { anyOf: _anyOf, ...rest } = result;
47+
const only = branches.length === 1 ? branches[0] : undefined;
48+
result = isObject(only) ? { ...only, ...rest } : { ...rest, anyOf: branches };
49+
}
50+
return result;
51+
};
52+
53+
/**
54+
* The input schema T3 advertises for a tool. Drops JSON noise that every thread pays for:
55+
* `additionalProperties: true`, safe-integer bounds, nested `anyOf`, JSON-string fallbacks, and
56+
* the `null` branch of optional properties. Decoding still uses the full schema.
57+
*/
58+
export const advertisedJsonSchema = (tool: Tool.Any) =>
59+
compact(Tool.getJsonSchema(tool), false) as ReturnType<typeof Tool.getJsonSchema>;

‎packages/contracts/src/scheduledTask.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ export const MAX_WEBHOOK_DELIVERY_AGE_MINUTES = 24 * 60;
6666
const WebhookMaxDeliveryAgeMinutes = Schema.Int.check(
6767
Schema.isBetween({ minimum: 1, maximum: MAX_WEBHOOK_DELIVERY_AGE_MINUTES }),
6868
).annotate({
69-
description: "Skip requests held offline over this many minutes. Null: run all.",
69+
description: "Skip requests held offline over this many minutes. Omit to run all.",
7070
});
7171

7272
export function isWebhookDedupeTemplate(template: string): boolean {
@@ -152,7 +152,7 @@ const ScheduledTaskUpsertWebhookSchedule = Schema.Struct({
152152
}),
153153
),
154154
).annotate({
155-
description: "Null or omitted: URL token only.",
155+
description: "Omit for URL token only.",
156156
}),
157157
maxDeliveryAgeMinutes: Schema.optional(Schema.NullOr(WebhookMaxDeliveryAgeMinutes)),
158158
dedupe: Schema.optional(ScheduledTaskWebhookDedupe),

0 commit comments

Comments
 (0)