Skip to content

Commit 1710680

Browse files
committed
add zDateRangeInclude and zFlexibleDate as factory functions
zod-to-json-schema emits $ref pointers when a Zod schema instance is reused across multiple fields. Several LLM providers (e.g. Moonshot/Kimi K3) reject $ref values that don't start with "#/$defs/", 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 $ref 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
1 parent 5c428a8 commit 1710680

3 files changed

Lines changed: 88 additions & 0 deletions

File tree

‎src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,5 @@ export type {
1616
PromptFactory,
1717
ResourceFactory,
1818
} from './types.js';
19+
export { zDateRangeInclude, zFlexibleDate } from './schemas.js';
20+
export type { DateRangeInclude } from './schemas.js';

‎src/schemas.spec.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import { describe, expect, it } from 'bun:test';
2+
import { z } from 'zod';
3+
import { zodToJsonSchema } from 'zod-to-json-schema';
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+
// zod-to-json-schema's types target Zod 3; the runtime works correctly with
21+
// Zod 4. The cast avoids a type-only mismatch between Zod 3/4 ZodType shapes.
22+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
23+
const jsonSchema = zodToJsonSchema(z.object(inputSchema) as any);
24+
25+
it('contains zero $ref references (LLM provider compatibility)', () => {
26+
const serialized = JSON.stringify(jsonSchema);
27+
const matches = [...serialized.matchAll(/"\$ref"/g)];
28+
expect(matches.length).toBe(0);
29+
});
30+
31+
it('each call returns a distinct instance (no shared identity)', () => {
32+
const a = zDateRangeInclude();
33+
const b = zDateRangeInclude();
34+
expect(a).not.toBe(b);
35+
});
36+
});

‎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)