Skip to content

Commit 1b6147b

Browse files
LeeHamptonclaude
andauthored
add zDateRangeInclude and zFlexibleDate as factory functions (#48)
zod-to-json-schema emits pointers when a Zod schema instance is reused across multiple fields. Several LLM providers (e.g. Moonshot/Kimi K3) reject values that don't start with "#/\/", breaking tool use for any MCP server that shares a Zod singleton across parameters. These factory functions return a fresh instance on every call so the generated JSON Schema is always inlined — zero references. Downstream MCP servers can import them instead of defining their own, avoiding a class of compatibility bugs that are hard to diagnose. See: modelcontextprotocol/typescript-sdk#1563 modelcontextprotocol/typescript-sdk#2100 We initially took at a stab at fixing a very specific issue we saw around the billing MCP in this PR timescale/tiger-billing-mcp-server#7 But changing it here will get ahead of any other MCPs that end up implementing a similar pattern. This does not however change any future schema changes that result in references. If it becomes an issue we might have to think of a broader fix. --------- Co-authored-by: Claude Fable 5 <[email protected]>
1 parent 5c428a8 commit 1b6147b

3 files changed

Lines changed: 85 additions & 0 deletions

File tree

‎src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ export { log } from './logger.js';
44
export type { AdditionalSetupArgs } from './mcpServer.js';
55
export { registerExitHandlers } from './registerExitHandlers.js';
66
export { StatusError } from './StatusError.js';
7+
export type { DateRangeInclude } from './schemas.js';
8+
export { zDateRangeInclude, zFlexibleDate } from './schemas.js';
79
export { stdioServerFactory } from './stdio.js';
810
export { ArrayStore, Store } from './store.js';
911
export { addAiResultToSpan, withSpan } from './tracing.js';

‎src/schemas.spec.ts‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
import { describe, expect, it } from 'bun:test';
2+
import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
3+
import { z } from 'zod';
4+
import { zDateRangeInclude } from './schemas.js';
5+
6+
/**
7+
* Verify that zDateRangeInclude (a factory function) produces JSON Schema
8+
* with zero $ref references. Several LLM providers (e.g. Moonshot/Kimi K3)
9+
* reject $ref pointers that don't start with "#/$defs/", so this is a hard
10+
* compatibility requirement.
11+
*/
12+
describe('zDateRangeInclude JSON Schema', () => {
13+
const inputSchema = {
14+
includeInvoices: zDateRangeInclude().describe('include invoices'),
15+
includeStripePayments: zDateRangeInclude().describe(
16+
'include stripe payments',
17+
),
18+
};
19+
20+
const jsonSchema = toJsonSchemaCompat(z.object(inputSchema));
21+
22+
it('contains zero $ref references (LLM provider compatibility)', () => {
23+
const serialized = JSON.stringify(jsonSchema);
24+
const matches = [...serialized.matchAll(/"\$ref"/g)];
25+
expect(matches.length).toBe(0);
26+
});
27+
28+
it('each call returns a distinct instance (no shared identity)', () => {
29+
const a = zDateRangeInclude();
30+
const b = zDateRangeInclude();
31+
expect(a).not.toBe(b);
32+
});
33+
});

‎src/schemas.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
import { z } from 'zod';
2+
3+
/**
4+
* Accept any date string that `new Date(...)` can parse (ISO 8601, RFC 2822,
5+
* "YYYY-MM-DD", etc.), then normalize to an ISO 8601 string. This is friendlier
6+
* than z.string().datetime(), which rejects common shapes like "2024-01-01".
7+
*
8+
* Returns a fresh Zod type instance on every call so that zod-to-json-schema
9+
* never emits a $ref pointer — several LLM providers (e.g. Moonshot/Kimi K3)
10+
* reject JSON Schema $ref references that don't start with "#/$defs/".
11+
*/
12+
export const zFlexibleDate = () =>
13+
z.string().transform((s, ctx) => {
14+
const d = new Date(s);
15+
if (Number.isNaN(d.getTime())) {
16+
ctx.addIssue({
17+
code: z.ZodIssueCode.custom,
18+
message: `Invalid date: "${s}"`,
19+
});
20+
return z.NEVER;
21+
}
22+
return d.toISOString();
23+
});
24+
25+
/**
26+
* A nullable date-range object with `rangeStart` and `rangeEnd`, each
27+
* accepting any parseable date string (see {@link zFlexibleDate}).
28+
*
29+
* Returns a fresh Zod type instance on every call so that zod-to-json-schema
30+
* never emits a $ref pointer — several LLM providers (e.g. Moonshot/Kimi K3)
31+
* reject JSON Schema $ref references that don't start with "#/$defs/".
32+
*/
33+
export const zDateRangeInclude = () =>
34+
z
35+
.object({
36+
rangeStart: zFlexibleDate()
37+
.nullable()
38+
.describe(
39+
'Inclusive start of the range. Accepts any parseable date string (e.g. "2024-01-01" or "2024-01-01T00:00:00Z"). Null to use the default window.',
40+
),
41+
rangeEnd: zFlexibleDate()
42+
.nullable()
43+
.describe(
44+
'Inclusive end of the range. Accepts any parseable date string (e.g. "2024-01-01" or "2024-01-01T00:00:00Z"). Null for "up to now".',
45+
),
46+
})
47+
.nullable();
48+
49+
/** The TypeScript type for a {@link zDateRangeInclude} value. */
50+
export type DateRangeInclude = z.infer<ReturnType<typeof zDateRangeInclude>>;

0 commit comments

Comments
 (0)