From 094a38a3d4565d46efb52e426125d44b77023882 Mon Sep 17 00:00:00 2001
From: William Swannell <will@hirespace.com>
Date: Mon, 1 Sep 2025 08:10:44 +0100
Subject: [PATCH 1/3] Add configurable JSON Schema target specification

- Add jsonSchemaSpec option to ServerOptions for OpenAI compatibility
- Support for specifying JSON Schema target (e.g., 'jsonSchema7')
- Use configured target in zodToJsonSchema calls in McpServer
- Defaults to 'jsonSchema7' for backward compatibility
---
 src/server/index.ts | 8 ++++++++
 src/server/mcp.ts   | 1 +
 2 files changed, 9 insertions(+)

diff --git a/src/server/index.ts b/src/server/index.ts
index b1f71ea28..5743db2c7 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -37,6 +37,7 @@ import {
   LoggingLevelSchema
 } from "../types.js";
 import Ajv from "ajv";
+import type { Target } from "zod-to-json-schema";
 
 export type ServerOptions = ProtocolOptions & {
   /**
@@ -48,6 +49,11 @@ export type ServerOptions = ProtocolOptions & {
    * Optional instructions describing how to use the server and its features.
    */
   instructions?: string;
+
+  /**
+   * Optional spec for JSON Schema to allow fully compatible use with OpenAI endpoints.
+   */
+  jsonSchemaSpec?: Target;
 };
 
 /**
@@ -88,6 +94,7 @@ export class Server<
   private _clientVersion?: Implementation;
   private _capabilities: ServerCapabilities;
   private _instructions?: string;
+  public _jsonSchemaSpec?: Target = 'jsonSchema7';
 
   /**
    * Callback for when initialization has fully completed (i.e., the client has sent an `initialized` notification).
@@ -104,6 +111,7 @@ export class Server<
     super(options);
     this._capabilities = options?.capabilities ?? {};
     this._instructions = options?.instructions;
+    this._jsonSchemaSpec = options?.jsonSchemaSpec;
 
     this.setRequestHandler(InitializeRequestSchema, (request) =>
       this._oninitialize(request),
diff --git a/src/server/mcp.ts b/src/server/mcp.ts
index fb797a8b4..fc45d05ae 100644
--- a/src/server/mcp.ts
+++ b/src/server/mcp.ts
@@ -119,6 +119,7 @@ export class McpServer {
               description: tool.description,
               inputSchema: tool.inputSchema
                 ? (zodToJsonSchema(tool.inputSchema, {
+                  target: this.server._jsonSchemaSpec,
                   strictUnions: true,
                 }) as Tool["inputSchema"])
                 : EMPTY_OBJECT_JSON_SCHEMA,

From bd86c2186b439915a323172a2bd1868a977b5c09 Mon Sep 17 00:00:00 2001
From: William Swannell <will@hirespace.com>
Date: Mon, 1 Sep 2025 08:14:40 +0100
Subject: [PATCH 2/3] docs: Add documentation for jsonSchemaSpec configuration
 option

- Add section explaining jsonSchemaSpec option in Server documentation
- Document supported values (jsonSchema7, openApi3, etc.)
- Explain use case for OpenAI compatibility
- Provide usage examples
---
 README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/README.md b/README.md
index cee7eb855..1fe3000aa 100644
--- a/README.md
+++ b/README.md
@@ -117,6 +117,27 @@ const server = new McpServer({
 });
 ```
 
+#### JSON Schema Specification
+
+You can configure the JSON Schema target specification for better compatibility with different systems, particularly OpenAI endpoints:
+
+```typescript
+const server = new McpServer({
+  name: "my-app",
+  version: "1.0.0"
+}, {
+  jsonSchemaSpec: 'openApi3'  // For OpenAI compatibility
+});
+```
+
+Supported values include:
+- `'jsonSchema7'` (default) - JSON Schema Draft 7
+- `'openApi3'` - OpenAPI 3.0 specification (recommended for OpenAI compatibility)
+- `'jsonSchema4'` - JSON Schema Draft 4
+- `'jsonSchema2019-09'` - JSON Schema Draft 2019-09
+
+This setting affects how tool input schemas are generated from Zod schemas, ensuring they match the expected format for your target system.
+
 ### Resources
 
 Resources are how you expose data to LLMs. They're similar to GET endpoints in a REST API - they provide data but shouldn't perform significant computation or have side effects:

From e9e8e41888e633ce1927d23e2faba369b70f3a18 Mon Sep 17 00:00:00 2001
From: ashburnham <will@hirespace.com>
Date: Fri, 5 Sep 2025 14:18:11 +0100
Subject: [PATCH 3/3] Update index.ts

Correct `Targets` import
---
 src/server/index.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/server/index.ts b/src/server/index.ts
index 5743db2c7..c62a8fd05 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -37,7 +37,7 @@ import {
   LoggingLevelSchema
 } from "../types.js";
 import Ajv from "ajv";
-import type { Target } from "zod-to-json-schema";
+import type { Targets } from "zod-to-json-schema";
 
 export type ServerOptions = ProtocolOptions & {
   /**
@@ -53,7 +53,7 @@ export type ServerOptions = ProtocolOptions & {
   /**
    * Optional spec for JSON Schema to allow fully compatible use with OpenAI endpoints.
    */
-  jsonSchemaSpec?: Target;
+  jsonSchemaSpec?: Targets;
 };
 
 /**
@@ -94,7 +94,7 @@ export class Server<
   private _clientVersion?: Implementation;
   private _capabilities: ServerCapabilities;
   private _instructions?: string;
-  public _jsonSchemaSpec?: Target = 'jsonSchema7';
+  public _jsonSchemaSpec?: Targets = 'jsonSchema7';
 
   /**
    * Callback for when initialization has fully completed (i.e., the client has sent an `initialized` notification).