Fix OpenAI Agent SDK schema compatibility issues (resolves #27) #41
Conversation
- Add `additionalProperties: false` to all tool schemas for OpenAI compatibility - Remove non-standard `"optional": true` properties (use proper JSON Schema patterns) - Ensure all array schemas have proper `items` definitions - Maintain backward compatibility by keeping optional parameters in correct `required` arrays Schema fixes for all 22 MCP tools: * Connection tools: get-connection-settings, update-connection-settings * Index tools: create-index, list-indexes, delete-index, get-index-metrics * Document tools: get-documents, add-documents * Search tools: search * Settings tools: get-settings, update-settings * Task tools: get-task, get-tasks, cancel-tasks * Key tools: get-keys, create-key, delete-key * Monitoring tools: health-check, get-version, get-stats, get-health-status, get-system-info Add comprehensive test suite (5 new tests) verifying: - All schemas include additionalProperties: false - Array schemas have proper items property - No non-standard optional properties used - Specific add-documents schema compliance - Full OpenAI function calling format compatibility Fixes OpenAI Agent SDK error: "array schema missing items" and related schema validation issues. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
WalkthroughThe changes enforce stricter JSON schema validation for tool input schemas by disallowing undeclared properties, removing the non-standard "optional" property, and ensuring proper specification of required fields and nested object schemas. Additionally, new tests verify schema compliance and compatibility with the OpenAI Agent SDK, focusing on the "add-documents" tool. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant MCPServer
Client->>MCPServer: Request list of tools
MCPServer-->>Client: Return tool schemas with strict validation (additionalProperties: false, required fields, etc.)
Note over MCPServer: Input schemas now strictly validated before tool execution
Assessment against linked issues
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
🔇 Additional comments (14)
✨ Finishing Touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Summary
Fixes OpenAI Agent SDK compatibility issues reported in #27 by updating all MCP tool schemas to follow OpenAI's strict JSON Schema requirements.
Issue Description
User reported error when using the MCP server with OpenAI Agent SDK:
Root Cause Analysis
OpenAI's Agent SDK requires stricter JSON Schema compliance than the MCP standard:
additionalProperties: false- OpenAI requires this property for object schemas"optional": true- OpenAI doesn't recognize this custom propertyitemswere present, the overall schema structure needed improvementChanges Made
🔧 Schema Standardization
Fixed all 22 MCP tool schemas:
"additionalProperties": falseto every object schema"optional": trueproperties"required"array usage for optional parameters"items"definitions📋 Tools Updated
Connection Management (2 tools)
get-connection-settings,update-connection-settingsIndex Management (4 tools)
create-index,list-indexes,delete-index,get-index-metricsDocument Operations (2 tools)
get-documents,add-documentsSearch Functionality (1 tool)
searchSettings Management (2 tools)
get-settings,update-settingsTask Management (3 tools)
get-task,get-tasks,cancel-tasksAPI Key Management (3 tools)
get-keys,create-key,delete-keySystem Monitoring (5 tools)
health-check,get-version,get-stats,get-health-status,get-system-info🧪 Comprehensive Test Coverage
Added 5 new test methods in
TestIssue27OpenAISchemaCompatibility:test_all_schemas_have_additional_properties_false- Verifies every tool schema includesadditionalProperties: falsetest_array_schemas_have_items_property- Ensures all array properties have properitemsdefinitionstest_no_custom_optional_properties- Confirms no non-standard"optional"properties existtest_specific_add_documents_schema_compliance- Validates the specific tool mentioned in the issuetest_openai_compatible_tool_schema_format- Verifies overall OpenAI function calling format complianceBackward Compatibility
✅ Fully backward compatible - All existing MCP functionality preserved:
requiredarraysExample Schema Improvement
Before (non-compliant):
{ "type": "object", "properties": { "indexUid": {"type": "string"}, "offset": {"type": "integer", "optional": true}, "limit": {"type": "integer", "optional": true} }, "required": ["indexUid"] }After (OpenAI compliant):
{ "type": "object", "properties": { "indexUid": {"type": "string"}, "offset": {"type": "integer"}, "limit": {"type": "integer"} }, "required": ["indexUid"], "additionalProperties": false }Testing Results
Impact
For OpenAI Agent SDK users:
For MCP users:
Closes #27
🤖 Generated with Claude Code
Summary by CodeRabbit