Skip to content

[provider] Codex-style sanitizeOpenAISchema for MCP tool schemas #805

Closed

Description

@ausard

What

Add a sanitizeOpenAISchema(schema) lowering pass in
src/providers/transform.ts and apply it to every MCP inputSchema
before tools are registered with an OpenAI-shaped SAP AI Core
deployment, so JSON Schema 2020-12 features that OpenAI rejects
(prefixItems, boolean schemas, unknown composition keywords) are
either dropped or rewritten to the closest legal shape.

This ports the algorithm sst/opencode shipped in #32489 (commit
213ff3f2, 2026-06-17, +95 -0 impl + +201 -0 tests) directly
ported from Codex.

Why

src/mcp/client.ts:124-150 (mapToolInfo) forwards MCP inputSchema
verbatim. When a session routes to a SAP AI Core OpenAI deployment
(gpt-*, o1-*, o3-*, or any deployment whose metadata reports
@ai-sdk/openai), the OpenAI function-tool registration path rejects
unknown / unsupported schema features with Invalid schema for function. The tool registers with a green checkmark but every
subsequent call rejects, so the user sees the tool listed in the
session and gets a runtime error each time the model calls it.

Two of three example MCP servers in our docs (filesystem, ast-grep)
use $ref-heavy schemas that today fail this way against OpenAI
deployments. opencode hit the exact same wall and ported the lowering
algorithm from Codex; the test fixtures cover the failure modes we
need.

Source: .github/research/2026-06-19-research.md Detailed Finding #1.

How

  1. Implement sanitizeOpenAISchema(schema: unknown): unknown in
    src/providers/transform.ts. The algorithm (mirroring opencode's
    lowering, in order):
    • If schema is true or false (boolean schema), return
      { type: 'object' } (open) or { not: {} } equivalent (closed)
      — match opencode's choice exactly.
    • If schema is not a non-null object, return {}.
    • Recurse into properties (preserve key order), items,
      prefixItems, $defs, definitions, anyOf, oneOf, allOf.
    • Drop type values not in the OpenAI-accepted set
      (['string','number','integer','boolean','object','array','null']).
    • Fold const: X into enum: [X] when both are absent.
    • Filter required to only string entries.
    • Infer type: 'object' when absent but properties,
      required, or additionalProperties are present.
    • Infer type: 'array' when absent but items or prefixItems
      are present.
    • Keep $ref and description as-is.
    • Drop unknown JSON Schema keywords (if/then/else,
      dependentSchemas, unevaluatedProperties, etc.) — opencode's
      allowlist is the authority, copy it verbatim.
  2. Detection: add a helper isOpenAIShapedModel(model: string, providerMeta?: { sdk?: string }): boolean that returns true for
    model ids matching /^(gpt-|o[13]-)/i OR when
    providerMeta?.sdk === '@ai-sdk/openai'. Place it next to
    sanitizeOpenAISchema in src/providers/transform.ts.
  3. Apply at the call site that ships MCP inputSchema to the
    provider tool registration. Search for where McpToolInfo.inputSchema
    is converted into the provider-facing tools payload (likely
    src/providers/sapAiCore.ts or wherever tools are assembled before
    chat.completions). When isOpenAIShapedModel returns true, run
    each tool's inputSchema through sanitizeOpenAISchema immediately
    before serialization. Do NOT mutate the cached McpToolInfo —
    produce a new object per request.
  4. Tests: port the opencode transform.test.ts fixtures into
    tests/providers/transform.test.ts (or src/providers/transform.test.ts
    if conventions prefer co-located tests). Cover at minimum:
    • boolean schemas (true / false)
    • $ref chains preserved
    • prefixItems lowered to legal shape
    • const -> enum
    • inferred type: 'object' from properties
    • inferred type: 'array' from items
    • non-string entries filtered out of required
    • unknown composition keywords dropped
    • description preserved verbatim
      The opencode test file is small (~200 LOC) — port the table of
      fixtures and assert deep equality with the lowered output.
  5. No behaviour change for non-OpenAI deployments. SAP AI Core
    Anthropic / Mistral / Gemini deployments must NOT see the lowered
    schema; they accept JSON Schema 2020-12 fine and the lowering would
    strip semantically meaningful constraints.
  6. Ship in its own PR separate from the smaller MCP fixes — this
    touches a 100+ LOC transform plus full test fixtures and benefits
    from independent review.

Done when

  • sanitizeOpenAISchema and isOpenAIShapedModel exported from
    src/providers/transform.ts.
  • OpenAI-shaped MCP tool registration runs every inputSchema
    through sanitizeOpenAISchema before serialization.
  • Non-OpenAI deployments are unaffected (assert via test that an
    Anthropic / SAP AI Core anthropic model id leaves the schema
    untouched).
  • Test suite covers the opencode fixture set listed above.
  • No mutation of cached McpToolInfo; the lowering produces a new
    object per request.
  • npm run lint && npm run typecheck && npm run format:check && npm run test:coverage && npm run build all green.

Activity

  1. github-actions commented on Jun 19, 2026

    @github-actions
    Contributor

    🤖 Kilo is starting to implement this feature automatically.

    • Branch: auto/805-provider-codex-style-sanitizeopenaischema-for-mcp-
    • Run: View workflow

    Implementation in progress...

  2. added a commit that references this issue on Jun 19, 2026
    21ed92d
  3. added a commit that references this issue on Jun 19, 2026
    4949be3
  4. github-actions commented on Jun 19, 2026

    @github-actions
    Contributor

    ❌ Kilo was unable to implement this feature automatically.

    The AI agent encountered issues during implementation.
    Manual implementation may be required.

    View workflow run

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    auto-implementAutomatically implementable by AI agentsenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions