Skip to content

Commit cc356b3

Browse files
CaseyRonori-agent
andcommitted
Add ChatGPT MCP compatibility with schema transformations
ChatGPT's strict mode requires additional JSON Schema constraints that standard MCP schemas don't provide. This adds transformations that work for both n8n and ChatGPT clients without configuration. New transformations (in addition to existing anyOf flattening): - Add additionalProperties: false to all object schemas - Make all fields required with nullable types for optional fields Changes: - Add _add_additional_properties_false() for ChatGPT strict mode - Add _make_all_fields_required() for ChatGPT strict mode - Rename middleware to ClientCompatibilityMiddleware - Rename _patch_tool_serialization_for_n8n to _patch_tool_serialization - Add unit tests for new transformation functions - Add docs/chatgpt-fastmcp-compatibility.md - Update n8n docs to reference ChatGPT docs Refs: - PrefectHQ/fastmcp#855 - github/github-mcp-server#376 🤖 Generated with [Nori](https://nori.ai) Co-Authored-By: Nori <[email protected]>
1 parent e858767 commit cc356b3

9 files changed

Lines changed: 804 additions & 33 deletions

File tree

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# ChatGPT + FastMCP 3.0 Compatibility Guide
2+
3+
This document describes the compatibility issues between ChatGPT's MCP integration and FastMCP 3.0 servers, along with the solutions implemented in this project.
4+
5+
## Background
6+
7+
ChatGPT adopted MCP in March 2025. However, ChatGPT uses "strict mode" for function calling, which has stricter JSON Schema requirements than the base MCP specification.
8+
9+
## Issue 1: Missing `additionalProperties: false`
10+
11+
**GitHub Issues:**
12+
- [github-mcp-server #376](https://github.com/github/github-mcp-server/issues/376)
13+
- [FastMCP #855](https://github.com/jlowin/fastmcp/issues/855)
14+
15+
**Problem:** ChatGPT strict mode requires `additionalProperties: false` on every object in the schema. Standard MCP schemas (and Pydantic-generated schemas) don't include this.
16+
17+
**Error:**
18+
```
19+
Invalid schema for function 'add_issue_comment': In context=(), 'additionalProperties' is required to be supplied and to be false.
20+
```
21+
22+
**Solution:** Recursively add `additionalProperties: false` to all object schemas.
23+
24+
```python
25+
def _add_additional_properties_false(schema: dict) -> dict:
26+
"""Recursively add additionalProperties: false to all objects."""
27+
if not isinstance(schema, dict):
28+
return schema
29+
30+
result = dict(schema)
31+
32+
# If this is an object with properties, add additionalProperties: false
33+
if result.get("type") == "object" or "properties" in result:
34+
if "additionalProperties" not in result:
35+
result["additionalProperties"] = False
36+
37+
# Recurse into properties
38+
if "properties" in result:
39+
result["properties"] = {
40+
k: _add_additional_properties_false(v)
41+
for k, v in result["properties"].items()
42+
}
43+
44+
# Recurse into items (for arrays)
45+
if "items" in result and isinstance(result["items"], dict):
46+
result["items"] = _add_additional_properties_false(result["items"])
47+
48+
return result
49+
```
50+
51+
## Issue 2: Optional Fields Must Be in `required` Array
52+
53+
**Problem:** ChatGPT strict mode requires ALL properties to be listed in the `required` array. Optional fields should use type arrays like `["string", "null"]` instead of being omitted from `required`.
54+
55+
**ChatGPT Documentation:**
56+
> "If you turn on `strict: true` in the function calling schema, then you have to list all of your fields under `required`."
57+
58+
**Before (Standard JSON Schema):**
59+
```json
60+
{
61+
"type": "object",
62+
"properties": {
63+
"title": {"type": "string"},
64+
"notes": {"type": "string"}
65+
},
66+
"required": ["title"]
67+
}
68+
```
69+
70+
**After (ChatGPT Strict Mode):**
71+
```json
72+
{
73+
"type": "object",
74+
"properties": {
75+
"title": {"type": "string"},
76+
"notes": {"type": ["string", "null"]}
77+
},
78+
"required": ["title", "notes"],
79+
"additionalProperties": false
80+
}
81+
```
82+
83+
**Solution:** Add all properties to `required` and use type arrays for optional fields.
84+
85+
```python
86+
def _make_all_fields_required(schema: dict) -> dict:
87+
"""Add all properties to required array, using type arrays for optional fields."""
88+
if not isinstance(schema, dict):
89+
return schema
90+
91+
result = dict(schema)
92+
93+
if "properties" in result:
94+
all_props = list(result["properties"].keys())
95+
current_required = set(result.get("required", []))
96+
97+
# For fields not currently required, make them nullable
98+
new_properties = {}
99+
for prop_name, prop_schema in result["properties"].items():
100+
prop_schema = _make_all_fields_required(prop_schema) # Recurse first
101+
102+
if prop_name not in current_required:
103+
# Add null to type for optional fields
104+
prop_schema = dict(prop_schema)
105+
if "type" in prop_schema:
106+
current_type = prop_schema["type"]
107+
if isinstance(current_type, str) and current_type != "null":
108+
prop_schema["type"] = [current_type, "null"]
109+
elif isinstance(current_type, list) and "null" not in current_type:
110+
prop_schema["type"] = current_type + ["null"]
111+
112+
new_properties[prop_name] = prop_schema
113+
114+
result["properties"] = new_properties
115+
result["required"] = all_props
116+
117+
# Recurse into items
118+
if "items" in result and isinstance(result["items"], dict):
119+
result["items"] = _make_all_fields_required(result["items"])
120+
121+
return result
122+
```
123+
124+
## Issue 3: `anyOf` Not Supported
125+
126+
**Problem:** ChatGPT strict mode doesn't support `anyOf`, `oneOf`, or `allOf` constructs. Pydantic generates `anyOf` for `Optional[T]` types.
127+
128+
**Error:**
129+
```
130+
Invalid schema: anyOf is not supported in strict mode
131+
```
132+
133+
**Solution:** Flatten `anyOf` constructs to JSON Schema type arrays. This is the same solution we use for n8n compatibility - see `docs/n8n-fastmcp-compatibility.md`.
134+
135+
## Complete Transformation Pipeline
136+
137+
We apply all transformations to all requests (ChatGPT requirements are a superset of n8n):
138+
139+
```python
140+
def _transform_schema_for_clients(schema: dict) -> dict:
141+
"""Apply all client compatibility transformations."""
142+
# Step 1: Flatten anyOf (needed for both n8n and ChatGPT)
143+
schema = _flatten_anyof_for_n8n(schema)
144+
145+
# Step 2: Add additionalProperties: false (ChatGPT)
146+
schema = _add_additional_properties_false(schema)
147+
148+
# Step 3: Make all fields required (ChatGPT)
149+
schema = _make_all_fields_required(schema)
150+
151+
return schema
152+
```
153+
154+
## Why This Works for Both n8n and ChatGPT
155+
156+
| Transformation | n8n needs? | ChatGPT needs? | Breaks either? |
157+
|----------------|------------|----------------|----------------|
158+
| Flatten `anyOf` | Yes | Yes | No |
159+
| `additionalProperties: false` | No | Yes | No (n8n ignores) |
160+
| All fields in `required` | No | Yes | No (n8n ignores) |
161+
| Strip extra params | Yes | No | No (ChatGPT doesn't send them) |
162+
163+
## Testing ChatGPT Compatibility
164+
165+
1. **Enable debug logging:**
166+
```bash
167+
export THINGS_MCP_DEBUG_SCHEMA=1
168+
```
169+
170+
2. **Use ngrok for HTTPS** (ChatGPT requires HTTPS):
171+
```bash
172+
ngrok http 127.0.0.1:8009
173+
```
174+
175+
3. **Connect ChatGPT to the ngrok HTTPS URL**
176+
177+
4. **Verify tools are listed and callable**
178+
179+
## Recommendations for FastMCP Team
180+
181+
### 1. Built-in Schema Transformations
182+
183+
Consider adding built-in schema transformation for common clients:
184+
185+
```python
186+
server = FastMCP(
187+
"MyServer",
188+
schema_compat="strict" # Applies ChatGPT-compatible transformations
189+
)
190+
```
191+
192+
### 2. Pydantic Model Configuration
193+
194+
Consider Pydantic configuration that generates strict-mode-compatible schemas:
195+
196+
```python
197+
class ToolInput(BaseModel):
198+
model_config = ConfigDict(
199+
json_schema_extra={"additionalProperties": False}
200+
)
201+
```
202+
203+
### 3. Documentation
204+
205+
Document the differences between MCP spec schemas and what various clients actually require.
206+
207+
## References
208+
209+
- [FastMCP Issue #855 - OpenAI Responses API](https://github.com/jlowin/fastmcp/issues/855)
210+
- [github-mcp-server Issue #376 - additionalProperties](https://github.com/github/github-mcp-server/issues/376)
211+
- [OpenAI Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs)
212+
- [OpenAI Community: Schema additionalProperties](https://community.openai.com/t/schema-additionalproperties-must-be-false-when-strict-is-true/929996)
213+
214+
## See Also
215+
216+
- `docs/n8n-fastmcp-compatibility.md` - n8n-specific compatibility (anyOf flattening, parameter stripping)

‎docs/n8n-fastmcp-compatibility.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -217,3 +217,7 @@ See `src/things_mcp/server_core.py` for the complete implementation including:
217217
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
218218
- [JSON Schema Type Arrays](https://json-schema.org/understanding-json-schema/reference/type.html)
219219
- [MCP Specification](https://spec.modelcontextprotocol.io/)
220+
221+
## See Also
222+
223+
- `docs/chatgpt-fastmcp-compatibility.md` - ChatGPT-specific compatibility (additionalProperties, required fields)
Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Design: ChatGPT MCP Compatibility
2+
3+
## Context
4+
5+
ChatGPT's MCP integration uses "strict mode" for function calling, which has stricter JSON Schema requirements than the base MCP specification:
6+
7+
1. `additionalProperties: false` on every object
8+
2. All properties listed in `required` array
9+
3. No `anyOf`/`oneOf`/`allOf` constructs (we already handle this for n8n)
10+
11+
## Decision: Single Transformation Pipeline
12+
13+
**What:** Apply all transformations (n8n + ChatGPT) to all requests.
14+
15+
**Why:** ChatGPT's requirements are a superset of n8n's. Applying the stricter transformations works for both clients:
16+
17+
| Transformation | n8n | ChatGPT | Breaks either? |
18+
|----------------|-----|---------|----------------|
19+
| Flatten `anyOf` | Needs | Needs | No |
20+
| `additionalProperties: false` | Ignores | Needs | No |
21+
| All fields in `required` | Ignores | Needs | No |
22+
| Strip extra params | Needs | Ignores | No |
23+
24+
This avoids configuration complexity and "just works" for all clients.
25+
26+
## Schema Transformation Pipeline
27+
28+
### Order of Operations
29+
30+
```python
31+
def transform_schema(schema: dict) -> dict:
32+
# Step 1: Flatten anyOf (existing - for n8n and ChatGPT)
33+
schema = _flatten_anyof_for_n8n(schema)
34+
35+
# Step 2: Add additionalProperties: false (new - for ChatGPT)
36+
schema = _add_additional_properties_false(schema)
37+
38+
# Step 3: Make all fields required (new - for ChatGPT)
39+
schema = _make_all_fields_required(schema)
40+
41+
return schema
42+
```
43+
44+
### Example Transformation
45+
46+
**Input (Pydantic-generated):**
47+
```json
48+
{
49+
"type": "object",
50+
"properties": {
51+
"title": {"type": "string"},
52+
"notes": {"anyOf": [{"type": "string"}, {"type": "null"}]}
53+
},
54+
"required": ["title"]
55+
}
56+
```
57+
58+
**Output (ChatGPT-compatible):**
59+
```json
60+
{
61+
"type": "object",
62+
"properties": {
63+
"title": {"type": "string"},
64+
"notes": {"type": ["string", "null"]}
65+
},
66+
"required": ["title", "notes"],
67+
"additionalProperties": false
68+
}
69+
```
70+
71+
## Implementation Notes
72+
73+
### `_add_additional_properties_false()`
74+
75+
Recursively traverse the schema and add `additionalProperties: false` to any object that has `properties` defined.
76+
77+
### `_make_all_fields_required()`
78+
79+
1. Get all property names from `properties`
80+
2. For properties not already in `required`, add `null` to their type
81+
3. Set `required` to include all property names
82+
4. Recurse into nested objects
83+
84+
## Risks
85+
86+
### Risk: Transformation breaks edge case schemas
87+
88+
**Mitigation:** Unit tests with various schema structures. Existing n8n tests serve as regression tests.
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Change: Add OpenAI/ChatGPT MCP Compatibility
2+
3+
## Why
4+
5+
OpenAI's MCP integration (ChatGPT) has stricter JSON Schema requirements than the MCP specification. When connecting Things MCP to ChatGPT, tool schemas are rejected with validation errors because OpenAI requires `strict` mode compliance that standard MCP schemas don't provide.
6+
7+
This is a known issue affecting all MCP servers trying to integrate with OpenAI - see [FastMCP #855](https://github.com/jlowin/fastmcp/issues/855) and [github-mcp-server #376](https://github.com/github/github-mcp-server/issues/376).
8+
9+
## What Changes
10+
11+
- **Extend schema transformation pipeline** - Add OpenAI strict mode transformations alongside existing n8n fixes
12+
- **Single code path** - Apply all transformations for all clients (OpenAI requirements are a superset of n8n)
13+
- **Documentation** - Document ChatGPT compatibility patterns (like we did for n8n)
14+
15+
### OpenAI Strict Mode Requirements (in addition to n8n)
16+
17+
1. **`additionalProperties: false`** - Must be set on every object in the schema
18+
2. **All fields in `required`** - Every property must be listed in `required` array
19+
20+
We already handle:
21+
- `anyOf` flattening (works for both n8n and OpenAI)
22+
- Null value stripping in middleware (harmless for OpenAI)
23+
24+
### Why One Path Works for Both
25+
26+
| Transformation | n8n needs? | OpenAI needs? | Apply to all? |
27+
|----------------|------------|---------------|---------------|
28+
| Flatten `anyOf` | Yes | Yes | Yes |
29+
| `additionalProperties: false` | No (but harmless) | Yes | Yes |
30+
| All fields in `required` | No (but harmless) | Yes | Yes |
31+
| Strip extra params | Yes | No (but harmless) | Yes |
32+
33+
## Impact
34+
35+
- Affected specs: `client-compatibility` (new capability)
36+
- Affected code: `src/things_mcp/server_core.py` - Schema transformation functions
37+
- No configuration needed - works automatically for both n8n and ChatGPT
38+
- No breaking changes
39+
40+
## References
41+
42+
- [FastMCP Issue #855](https://github.com/jlowin/fastmcp/issues/855)
43+
- [github-mcp-server Issue #376](https://github.com/github/github-mcp-server/issues/376)

0 commit comments

Comments
 (0)