fix: emit JSON Schema draft 2020-12 for tools/list (#32)

Claude's API rejects the default draft-07 output from the MCP SDK's
Zod→JSON Schema converter with:

  tools.N.custom.input_schema: JSON schema is invalid.
  It must match JSON Schema draft 2020-12

Bypass the SDK's auto-registered tools/list handler with one that
pre-generates schemas via zod-to-json-schema (targeting
jsonSchema2019-09), strips any nested $schema keys, and sets the
top-level $schema to https://json-schema.org/draft/2020-12/schema.

The per-tool CallTool dispatch registered by server.tool() is
untouched; only the schema serialization path changes.

Author: kk-michael

package.json

@@ -50,7 +50,8 @@
     "@modelcontextprotocol/sdk": "^1.12.0",
     "axios": "^1.9.0",
     "hono": "^4.12.12",
-    "zod": "^3.25.28"
+    "zod": "^3.25.28",
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",

pnpm-lock.yaml

@@ -1,10 +1,15 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import type { ZodObject, ZodRawShape } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
 import { generatedTools } from "./generated/tools.js";
 import { createHandler } from "./handler.js";
 import { createLogger } from "./utils/logger.js";
 
 const logger = createLogger("MCP-Server");
 
+const JSON_SCHEMA_2020_12 = "https://json-schema.org/draft/2020-12/schema";
+
 function getEnabledTools() {
   const enabledTags = process.env.DOKPLOY_ENABLED_TAGS;
 
@@ -30,6 +35,38 @@ function getEnabledTools() {
   return filtered;
 }
 
+function stripNestedSchemaKeys(value: unknown): void {
+  if (value === null || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    for (const item of value) stripNestedSchemaKeys(item);
+    return;
+  }
+  const record = value as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    if (key === "$schema") {
+      delete record[key];
+    } else {
+      stripNestedSchemaKeys(record[key]);
+    }
+  }
+}
+
+// Claude's API requires JSON Schema draft 2020-12. The MCP SDK's built-in
+// Zod→JSON Schema converter emits draft-07 by default, which causes a 400
+// error on tools/list. We bypass the SDK's auto-generated handler by
+// registering our own with pre-converted draft-2020-12 schemas.
+// See https://github.com/Dokploy/mcp/issues/32
+function toDraft2020_12JsonSchema(schema: ZodObject<ZodRawShape>): Record<string, unknown> {
+  const result = zodToJsonSchema(schema, {
+    target: "jsonSchema2019-09",
+    strictUnions: true,
+  }) as Record<string, unknown>;
+
+  stripNestedSchemaKeys(result);
+  result.$schema = JSON_SCHEMA_2020_12;
+  return result;
+}
+
 export function createServer() {
   const server = new McpServer({
     name: "dokploy",
@@ -48,5 +85,16 @@ export function createServer() {
     );
   }
 
+  const toolList = tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: toDraft2020_12JsonSchema(tool.schema),
+    annotations: tool.annotations,
+  }));
+
+  server.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: toolList,
+  }));
+
   return server;
 }