Skip to content

Commit 5c04d74

Browse files
cliffhallclaude
andcommitted
fix(filesystem): declare JSON Schema 2020-12 on every tool schema (#4841)
The SDK 1.x tools/list handler renders each zod schema with zod's draft-07 target and stamps "$schema": draft-07 on it, which validators that accept only JSON Schema 2020-12 reject, so strict clients refused every filesystem tool. Each tool's input and output shape is now passed as a z.object whose root metadata sets $schema to the 2020-12 dialect, which overrides the stamp. No schema here uses a keyword whose draft-07 and 2020-12 renderings differ, so the label is the only change on the wire; a new test fails if a draft-07-only keyword ever appears under it. The KNOWN BUG #4841 pin in server-tools.test.ts now asserts 2020-12. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 571e2b3 commit 5c04d74

3 files changed

Lines changed: 88 additions & 36 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-filesystem": patch
3+
---
4+
5+
Every tool's input and output schema in `tools/list` now declares `"$schema": "https://json-schema.org/draft/2020-12/schema"` instead of draft-07, so clients that validate tool schemas strictly against JSON Schema 2020-12 no longer reject every tool. The schemas are otherwise unchanged.

‎src/filesystem/__tests__/server-tools.test.ts‎

Lines changed: 38 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -149,21 +149,53 @@ describe("server identity and tool list", () => {
149149
});
150150
});
151151

152-
// KNOWN BUG #4841: pins current (wrong) behavior; the fix changes this assertion.
153-
// #4841: every schema declares the draft-07 dialect, from the SDK's default
154-
// zod-to-JSON-Schema target. Strict 2020-12 validators reject it.
155-
it("declares the draft-07 $schema on every input and output schema (#4841)", async () => {
152+
// #4841: the SDK 1.x tools/list handler stamps draft-07 on every schema it
153+
// renders, which validators that accept only JSON Schema 2020-12 reject. The
154+
// server declares 2020-12 instead.
155+
it("declares the 2020-12 $schema on every input and output schema (#4841)", async () => {
156156
const { tools } = await client.listTools();
157+
expect(tools).toHaveLength(TOOL_NAMES.length);
157158
for (const tool of tools) {
158159
expect(tool.inputSchema.$schema).toBe(
159-
"http://json-schema.org/draft-07/schema#",
160+
"https://json-schema.org/draft/2020-12/schema",
160161
);
161162
expect(tool.outputSchema?.$schema).toBe(
162-
"http://json-schema.org/draft-07/schema#",
163+
"https://json-schema.org/draft/2020-12/schema",
163164
);
164165
}
165166
});
166167

168+
// #4841: the schemas are still rendered with zod's draft-07 rules, so the
169+
// 2020-12 label holds only while they use no keyword whose meaning differs
170+
// between the two dialects: array-form (tuple) items, additionalItems, and
171+
// definitions rather than $defs.
172+
it("advertises no draft-07-only keyword under the 2020-12 label (#4841)", async () => {
173+
const { tools } = await client.listTools();
174+
const draft07Only: string[] = [];
175+
const walk = (node: unknown, at: string): void => {
176+
if (Array.isArray(node)) {
177+
node.forEach((item, i) => walk(item, `${at}[${i}]`));
178+
return;
179+
}
180+
if (node === null || typeof node !== "object") return;
181+
for (const [key, value] of Object.entries(node)) {
182+
if (
183+
(key === "items" && Array.isArray(value)) ||
184+
key === "additionalItems" ||
185+
key === "definitions"
186+
) {
187+
draft07Only.push(`${at}.${key}`);
188+
}
189+
walk(value, `${at}.${key}`);
190+
}
191+
};
192+
for (const tool of tools) {
193+
walk(tool.inputSchema, `${tool.name}.inputSchema`);
194+
walk(tool.outputSchema, `${tool.name}.outputSchema`);
195+
}
196+
expect(draft07Only).toEqual([]);
197+
});
198+
167199
it("pins the input schemas a client is shown", async () => {
168200
const { tools } = await client.listTools();
169201
const byName = Object.fromEntries(tools.map((t) => [t.name, t]));

‎src/filesystem/server.ts‎

Lines changed: 45 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,21 @@ import {
3131
} from "./lib.js";
3232
import { SERVER_VERSION } from "./version.js";
3333

34+
// The JSON Schema dialect every advertised tool schema declares (#4841). The
35+
// SDK 1.x tools/list handler renders zod schemas with zod's draft-07 target and
36+
// stamps "$schema": draft-07 on each one, which validators that accept only
37+
// 2020-12 (the dialect MCP assumes for tool schemas) reject outright. Setting
38+
// $schema in the root object's zod metadata overrides that stamp. The schemas
39+
// below use nothing whose draft-07 and 2020-12 renderings differ (no tuples),
40+
// so the label is the only change; server-tools.test.ts fails if a draft-07-only
41+
// keyword ever appears under it.
42+
const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
43+
44+
/** A tool's input or output shape as an object schema declaring 2020-12. */
45+
function jsonSchema2020<Shape extends z.ZodRawShape>(shape: Shape) {
46+
return z.object(shape).meta({ $schema: JSON_SCHEMA_DIALECT });
47+
}
48+
3449
// Schema definitions
3550
const ReadTextFileArgsSchema = z.object({
3651
path: z.string(),
@@ -179,8 +194,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
179194
title: "Read File (Deprecated)",
180195
description:
181196
"Read the complete contents of a file as text. DEPRECATED: Use read_text_file instead.",
182-
inputSchema: ReadTextFileArgsSchema.shape,
183-
outputSchema: { content: z.string() },
197+
inputSchema: jsonSchema2020(ReadTextFileArgsSchema.shape),
198+
outputSchema: jsonSchema2020({ content: z.string() }),
184199
annotations: { readOnlyHint: true, openWorldHint: false },
185200
},
186201
readTextFileHandler,
@@ -198,7 +213,7 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
198213
"the first N lines of a file, or the 'tail' parameter to read only " +
199214
"the last N lines of a file. Operates on the file as text regardless of extension. " +
200215
"Only works within allowed directories.",
201-
inputSchema: {
216+
inputSchema: jsonSchema2020({
202217
path: z.string(),
203218
tail: z
204219
.number()
@@ -208,8 +223,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
208223
.number()
209224
.optional()
210225
.describe("If provided, returns only the first N lines of the file"),
211-
},
212-
outputSchema: { content: z.string() },
226+
}),
227+
outputSchema: jsonSchema2020({ content: z.string() }),
213228
annotations: { readOnlyHint: true, openWorldHint: false },
214229
},
215230
readTextFileHandler,
@@ -223,8 +238,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
223238
"Read a file and return it as a base64-encoded content block with its MIME type. " +
224239
"Image and audio files are returned as image/audio content; any other file type is " +
225240
"returned as an embedded resource. Only works within allowed directories.",
226-
inputSchema: ReadMediaFileArgsSchema.shape,
227-
outputSchema: {
241+
inputSchema: jsonSchema2020(ReadMediaFileArgsSchema.shape),
242+
outputSchema: jsonSchema2020({
228243
content: z.array(
229244
z.union([
230245
z.object({
@@ -243,7 +258,7 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
243258
}),
244259
]),
245260
),
246-
},
261+
}),
247262
annotations: { readOnlyHint: true, openWorldHint: false },
248263
},
249264
async (args: z.infer<typeof ReadMediaFileArgsSchema>) => {
@@ -298,8 +313,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
298313
"or compare multiple files. Each file's content is returned with its " +
299314
"path as a reference. Failed reads for individual files won't stop " +
300315
"the entire operation. Only works within allowed directories.",
301-
inputSchema: ReadMultipleFilesArgsSchema.shape,
302-
outputSchema: { content: z.string() },
316+
inputSchema: jsonSchema2020(ReadMultipleFilesArgsSchema.shape),
317+
outputSchema: jsonSchema2020({ content: z.string() }),
303318
annotations: { readOnlyHint: true, openWorldHint: false },
304319
},
305320
async (args: z.infer<typeof ReadMultipleFilesArgsSchema>) => {
@@ -332,8 +347,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
332347
"Create a new file or completely overwrite an existing file with new content. " +
333348
"Use with caution as it will overwrite existing files without warning. " +
334349
"Handles text content with proper encoding. Only works within allowed directories.",
335-
inputSchema: WriteFileArgsSchema.shape,
336-
outputSchema: { content: z.string() },
350+
inputSchema: jsonSchema2020(WriteFileArgsSchema.shape),
351+
outputSchema: jsonSchema2020({ content: z.string() }),
337352
annotations: {
338353
readOnlyHint: false,
339354
idempotentHint: true,
@@ -360,8 +375,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
360375
"Make line-based edits to a text file. Each edit replaces exact line sequences " +
361376
"with new content. Returns a git-style diff showing the changes made. " +
362377
"Only works within allowed directories.",
363-
inputSchema: EditFileArgsSchema.shape,
364-
outputSchema: { content: z.string() },
378+
inputSchema: jsonSchema2020(EditFileArgsSchema.shape),
379+
outputSchema: jsonSchema2020({ content: z.string() }),
365380
annotations: {
366381
readOnlyHint: false,
367382
idempotentHint: false,
@@ -388,8 +403,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
388403
"nested directories in one operation. If the directory already exists, " +
389404
"this operation will succeed silently. Perfect for setting up directory " +
390405
"structures for projects or ensuring required paths exist. Only works within allowed directories.",
391-
inputSchema: CreateDirectoryArgsSchema.shape,
392-
outputSchema: { content: z.string() },
406+
inputSchema: jsonSchema2020(CreateDirectoryArgsSchema.shape),
407+
outputSchema: jsonSchema2020({ content: z.string() }),
393408
annotations: {
394409
readOnlyHint: false,
395410
idempotentHint: true,
@@ -417,8 +432,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
417432
"Results clearly distinguish between files and directories with [FILE] and [DIR] " +
418433
"prefixes. This tool is essential for understanding directory structure and " +
419434
"finding specific files within a directory. Only works within allowed directories.",
420-
inputSchema: ListDirectoryArgsSchema.shape,
421-
outputSchema: { content: z.string() },
435+
inputSchema: jsonSchema2020(ListDirectoryArgsSchema.shape),
436+
outputSchema: jsonSchema2020({ content: z.string() }),
422437
annotations: { readOnlyHint: true, openWorldHint: false },
423438
},
424439
async (args: z.infer<typeof ListDirectoryArgsSchema>) => {
@@ -446,8 +461,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
446461
"Results clearly distinguish between files and directories with [FILE] and [DIR] " +
447462
"prefixes. This tool is useful for understanding directory structure and " +
448463
"finding specific files within a directory. Only works within allowed directories.",
449-
inputSchema: ListDirectoryWithSizesArgsSchema.shape,
450-
outputSchema: { content: z.string() },
464+
inputSchema: jsonSchema2020(ListDirectoryWithSizesArgsSchema.shape),
465+
outputSchema: jsonSchema2020({ content: z.string() }),
451466
annotations: { readOnlyHint: true, openWorldHint: false },
452467
},
453468
async (args: z.infer<typeof ListDirectoryWithSizesArgsSchema>) => {
@@ -526,8 +541,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
526541
"Each entry includes 'name', 'type' (file/directory), and 'children' for directories. " +
527542
"Files have no children array, while directories always have a children array (which may be empty). " +
528543
"The output is formatted with 2-space indentation for readability. Only works within allowed directories.",
529-
inputSchema: DirectoryTreeArgsSchema.shape,
530-
outputSchema: { content: z.string() },
544+
inputSchema: jsonSchema2020(DirectoryTreeArgsSchema.shape),
545+
outputSchema: jsonSchema2020({ content: z.string() }),
531546
annotations: { readOnlyHint: true, openWorldHint: false },
532547
},
533548
async (args: z.infer<typeof DirectoryTreeArgsSchema>) => {
@@ -600,8 +615,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
600615
"and rename them in a single operation. If the destination exists, the " +
601616
"operation will fail. Works across different directories and can be used " +
602617
"for simple renaming within the same directory. Both source and destination must be within allowed directories.",
603-
inputSchema: MoveFileArgsSchema.shape,
604-
outputSchema: { content: z.string() },
618+
inputSchema: jsonSchema2020(MoveFileArgsSchema.shape),
619+
outputSchema: jsonSchema2020({ content: z.string() }),
605620
annotations: {
606621
readOnlyHint: false,
607622
idempotentHint: false,
@@ -638,8 +653,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
638653
"Use pattern like '*.ext' to match files in current directory, and '**/*.ext' to match files in all subdirectories. " +
639654
"Returns full paths to all matching items. Great for finding files when you don't know their exact location. " +
640655
"Only searches within allowed directories.",
641-
inputSchema: SearchFilesArgsSchema.shape,
642-
outputSchema: { content: z.string() },
656+
inputSchema: jsonSchema2020(SearchFilesArgsSchema.shape),
657+
outputSchema: jsonSchema2020({ content: z.string() }),
643658
annotations: { readOnlyHint: true, openWorldHint: false },
644659
},
645660
async (args: z.infer<typeof SearchFilesArgsSchema>) => {
@@ -667,8 +682,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
667682
"information including size, creation time, last modified time, permissions, " +
668683
"and type. This tool is perfect for understanding file characteristics " +
669684
"without reading the actual content. Only works within allowed directories.",
670-
inputSchema: GetFileInfoArgsSchema.shape,
671-
outputSchema: { content: z.string() },
685+
inputSchema: jsonSchema2020(GetFileInfoArgsSchema.shape),
686+
outputSchema: jsonSchema2020({ content: z.string() }),
672687
annotations: { readOnlyHint: true, openWorldHint: false },
673688
},
674689
async (args: z.infer<typeof GetFileInfoArgsSchema>) => {
@@ -693,8 +708,8 @@ export function createServer(initialAllowedDirectories: string[]): McpServer {
693708
"Subdirectories within these allowed directories are also accessible. " +
694709
"Use this to understand which directories and their nested paths are available " +
695710
"before trying to access files.",
696-
inputSchema: {},
697-
outputSchema: { content: z.string() },
711+
inputSchema: jsonSchema2020({}),
712+
outputSchema: jsonSchema2020({ content: z.string() }),
698713
annotations: { readOnlyHint: true, openWorldHint: false },
699714
},
700715
async () => {

0 commit comments

Comments
 (0)