schemashim 0.1.0__py3-none-any.whl

schemashim/__init__.py

@@ -0,0 +1,12 @@
+"""schemashim: make MCP and agent tool schemas work on Gemini and OpenAI strict mode."""
+
+from .core import GEMINI, OPENAI_STRICT, TARGETS, Change, Shim, adapt, check
+from .names import tool_name
+from .tools import AdaptedTool, ToolKit, adapt_tool, adapt_tools
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GEMINI", "OPENAI_STRICT", "TARGETS", "Change", "Shim", "adapt", "check", "tool_name",
+    "AdaptedTool", "ToolKit", "adapt_tool", "adapt_tools", "__version__",
+]

schemashim/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

schemashim/cli.py

@@ -0,0 +1,97 @@
+"""schemashim check / fix: find and fix tool schemas a provider would reject."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, List, Optional
+
+from . import __version__
+from .core import TARGETS, adapt
+from .tools import ToolKit
+
+
+def _load(path: str) -> Any:
+    try:
+        if path == "-":
+            return json.load(sys.stdin)
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except OSError as exc:
+        raise SystemExit(f"schemashim: can't read {path}: {exc.strerror or exc}")
+    except ValueError as exc:
+        raise SystemExit(f"schemashim: {path} is not valid JSON: {exc}")
+
+
+def _tools(data: Any) -> Optional[list]:
+    """The list of tools in ``data``, or None when ``data`` is a bare schema."""
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        result = data.get("result") if isinstance(data.get("result"), dict) else data
+        if isinstance(result.get("tools"), list):
+            return result["tools"]
+        if isinstance(result.get("tools"), dict):  # mcptest snapshot: {"tools": {name: tool}}
+            return [{"name": k, **v} for k, v in result["tools"].items() if isinstance(v, dict)]
+        if "name" in data and ("inputSchema" in data or "input_schema" in data):
+            return [data]
+    return None
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="schemashim",
+        description="Find and fix JSON Schemas that Gemini or OpenAI strict mode reject. "
+                    "FILE is a schema, a tool, a list of tools or a tools/list result "
+                    "('-' reads stdin).")
+    parser.add_argument("--version", action="version", version=f"schemashim {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    c = sub.add_parser("check", help="list what each target would reject; exit 1 if anything")
+    c.add_argument("file")
+    c.add_argument("--target", choices=TARGETS + ("all",), default="all")
+    c.add_argument("--json", action="store_true", help="print the findings as JSON")
+    f = sub.add_parser("fix", help="print the adapted schema or tool declarations")
+    f.add_argument("file")
+    f.add_argument("--target", choices=TARGETS, required=True)
+    args = parser.parse_args(argv)
+
+    data = _load(args.file)
+    tools = _tools(data)
+    try:
+        if args.command == "fix":
+            if tools is None:
+                out: Any = adapt(data, args.target).schema
+            else:
+                out = ToolKit(tools, args.target).declarations
+            json.dump(out, sys.stdout, indent=2)
+            sys.stdout.write("\n")
+            return 0
+
+        targets = TARGETS if args.target == "all" else (args.target,)
+        findings = []
+        for target in targets:
+            if tools is None:
+                findings += [{"target": target, "tool": None, "path": c.path,
+                              "message": c.message} for c in adapt(data, target).changes]
+            else:
+                for tool in ToolKit(tools, target):
+                    findings += [{"target": target, "tool": tool.original_name, "path": c.path,
+                                  "message": c.message} for c in tool.changes]
+    except (TypeError, ValueError) as exc:
+        print(f"schemashim: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        json.dump(findings, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        for item in findings:
+            where = f"{item['tool']}: " if item["tool"] else ""
+            print(f"[{item['target']}] {where}{item['path'] or '(root)'}: {item['message']}")
+        if findings:
+            n = len(findings)
+            print(f"{n} problem{'s' if n != 1 else ''} found; `schemashim fix` rewrites them.")
+        else:
+            print("OK: accepted as is by " + ", ".join(targets))
+    return 1 if findings else 0

schemashim/core.py

@@ -0,0 +1,609 @@
+"""Rewrite a JSON Schema so a model provider accepts it, and undo the rewrite on the arguments."""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+GEMINI = "gemini"
+OPENAI_STRICT = "openai-strict"
+TARGETS = (GEMINI, OPENAI_STRICT)
+
+# Keywords each target accepts on a schema node. Anything else is removed, and constraints the
+# model should still know about are written into the description instead.
+_GEMINI_KEYS = {
+    "type", "format", "title", "description", "nullable", "enum", "maxItems", "minItems",
+    "properties", "required", "minProperties", "maxProperties", "minLength", "maxLength",
+    "pattern", "example", "anyOf", "propertyOrdering", "default", "items", "minimum", "maximum",
+}
+_OPENAI_KEYS = {
+    "type", "title", "description", "enum", "const", "properties", "required",
+    "additionalProperties", "items", "anyOf", "pattern", "format", "minimum", "maximum",
+    "exclusiveMinimum", "exclusiveMaximum", "multipleOf", "minItems", "maxItems",
+}
+_GEMINI_STRING_FORMATS = {"enum", "date-time"}
+_GEMINI_NUMBER_FORMATS = {"int32", "int64", "float", "double"}
+_OPENAI_FORMATS = {"date-time", "time", "date", "duration", "email", "hostname", "ipv4",
+                   "ipv6", "uuid"}
+# Keys dropped without a note: they carry no meaning for the model.
+_SILENT = {"$schema", "$id", "$comment", "$anchor", "readOnly", "writeOnly", "deprecated",
+           "contentMediaType", "contentEncoding"}
+_STRUCTURAL = {"$ref", "$defs", "definitions", "allOf", "anyOf", "oneOf", "type", "properties",
+               "required", "items", "prefixItems", "additionalProperties", "nullable", "const",
+               "enum"}
+_LOOKAROUND = re.compile(r"\(\?<?[=!]|\\[1-9]|\\k<")
+
+_PHRASES = {
+    "minLength": "at least {} character(s)",
+    "maxLength": "at most {} character(s)",
+    "pattern": "must match the regex {}",
+    "format": "format: {}",
+    "minimum": "at least {}",
+    "maximum": "at most {}",
+    "exclusiveMinimum": "greater than {}",
+    "exclusiveMaximum": "less than {}",
+    "multipleOf": "a multiple of {}",
+    "minItems": "at least {} item(s)",
+    "maxItems": "at most {} item(s)",
+    "uniqueItems": "items must be unique",
+    "minProperties": "at least {} key(s)",
+    "maxProperties": "at most {} key(s)",
+    "default": "default: {}",
+    "examples": "examples: {}",
+    "example": "example: {}",
+}
+
+
+@dataclass(frozen=True)
+class Change:
+    """One thing the original schema had that the target would reject or ignore."""
+
+    path: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path or '(root)'}: {self.message}"
+
+
+@dataclass
+class _Restore:
+    json: bool = False
+    drop_null: bool = False
+    integer: bool = False
+    props: Dict[str, "_Restore"] = field(default_factory=dict)
+    items: Optional["_Restore"] = None
+
+    def empty(self) -> bool:
+        return not (self.json or self.drop_null or self.integer or self.props or self.items)
+
+
+@dataclass
+class Shim:
+    """The adapted schema, what changed, and how to turn model arguments back."""
+
+    target: str
+    schema: Dict[str, Any]
+    changes: List[Change]
+    _restore: _Restore = field(repr=False, default_factory=_Restore)
+
+    @property
+    def ok(self) -> bool:
+        """True when the original schema was already accepted as it was."""
+        return not self.changes
+
+    def restore(self, args: Any) -> Any:
+        """Turn arguments the model sent for the adapted schema into arguments for the original.
+
+        Decodes values that were sent as JSON strings, drops the nulls strict mode forces the
+        model to send for optional fields, and turns 5.0 back into 5 for integer fields.
+        """
+        if args is None:
+            return {}
+        return _apply(args, self._restore)
+
+
+def _apply(value: Any, node: Optional[_Restore]) -> Any:
+    if node is None or node.empty():
+        return value
+    if node.json:
+        if isinstance(value, str):
+            try:
+                return json.loads(value)
+            except ValueError:
+                return value
+        return value
+    if node.integer and isinstance(value, float) and value.is_integer():
+        return int(value)
+    if node.props and isinstance(value, dict):
+        out = {}
+        for key, val in value.items():
+            child = node.props.get(key)
+            if child is not None and child.drop_null and val is None:
+                continue
+            out[key] = _apply(val, child)
+        return out
+    if node.items is not None and isinstance(value, list):
+        return [_apply(v, node.items) for v in value]
+    return value
+
+
+def adapt(schema: Any, target: str, *, max_depth: int = 10) -> Shim:
+    """Rewrite ``schema`` (a tool's input schema) so ``target`` accepts it.
+
+    ``target`` is ``"gemini"`` (Gemini API / Vertex AI function declarations) or
+    ``"openai-strict"`` (OpenAI function calling with ``strict: true``). The input is not
+    modified. Nested objects deeper than ``max_depth`` are passed as JSON strings.
+    """
+    if target not in TARGETS:
+        raise ValueError(f"unknown target {target!r}; use one of {', '.join(TARGETS)}")
+    if not isinstance(max_depth, int) or max_depth < 1:
+        raise ValueError("max_depth must be a positive integer")
+    return _Adapter(target, max_depth).run(schema)
+
+
+def check(schema: Any, target: str) -> List[Change]:
+    """List what ``target`` would reject in ``schema``. Empty means it is accepted as is."""
+    return adapt(schema, target).changes
+
+
+def _fmt(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, sort_keys=True)
+
+
+def _join(path: str, key: str) -> str:
+    return f"{path}.{key}" if path else key
+
+
+class _Adapter:
+    def __init__(self, target: str, max_depth: int) -> None:
+        self.target = target
+        self.gemini = target == GEMINI
+        self.max_depth = max_depth
+        self.changes: List[Change] = []
+        self.defs: Dict[str, Any] = {}
+
+    def note(self, path: str, message: str) -> None:
+        change = Change(path, message)
+        if change not in self.changes:
+            self.changes.append(change)
+
+    # entry point -------------------------------------------------------------------------
+    def run(self, schema: Any) -> Shim:
+        if schema is None or schema is True or schema == {}:
+            schema = {"type": "object", "properties": {}}
+        if not isinstance(schema, dict):
+            raise TypeError("schema must be a JSON object (dict)")
+        schema = copy.deepcopy(schema)
+        for key in ("$defs", "definitions"):
+            defs = schema.get(key)
+            if isinstance(defs, dict):
+                for name, sub in defs.items():
+                    self.defs[f"#/{key}/{name}"] = sub
+        root, stack = self.resolve(schema, "", ())
+        if not isinstance(root, dict) or root.get("__free__"):
+            self.note("", "the root schema can't be resolved: the tool gets no arguments")
+            root, stack = {"type": "object", "properties": {}}, ()
+        root = self.root_object(root)
+        out, restore = self.convert(root, "", stack, 0, root=True)
+        return Shim(self.target, out, self.changes, restore)
+
+    def root_object(self, s: Dict[str, Any]) -> Dict[str, Any]:
+        branches = s.get("anyOf") or s.get("oneOf")
+        if s.get("type") in (None, "object") and isinstance(branches, list) and branches:
+            objects = []
+            for b in branches:
+                b, _ = self.resolve(b, "", ())
+                if isinstance(b, dict) and (b.get("type") == "object" or "properties" in b):
+                    objects.append(b)
+            if len(objects) == len(branches):
+                props: Dict[str, Any] = dict(s.get("properties") or {})
+                required = None
+                for b in objects:
+                    for k, v in (b.get("properties") or {}).items():
+                        props.setdefault(k, v)
+                    r = set(b.get("required") or [])
+                    required = r if required is None else required & r
+                merged = {k: v for k, v in s.items() if k not in ("anyOf", "oneOf")}
+                merged["type"] = "object"
+                merged["properties"] = props
+                merged["required"] = sorted((required or set()) | set(s.get("required") or []))
+                self.note("", "the root is a choice of objects, which tools can't use: merged "
+                              "into one object (fields not in every choice became optional)")
+                return merged
+        if s.get("type") not in (None, "object") or (
+                "type" not in s and "properties" not in s and not branches):
+            if s.get("type") is not None:
+                self.note("", f"the root must be an object, not {_fmt(s.get('type'))}")
+            elif s:
+                self.note("", "the root has no type: made it an object")
+            keep = {k: v for k, v in s.items() if k in ("description", "title")}
+            return {"type": "object", "properties": {}, **keep}
+        return s
+
+    # $ref and allOf ----------------------------------------------------------------------
+    def resolve(self, s: Any, path: str, stack: Tuple[str, ...]):
+        """Follow $ref and merge allOf. Returns (schema, stack) or (None, stack) on a loop."""
+        if not isinstance(s, dict):
+            return s, stack
+        seen = 0
+        while isinstance(s, dict) and "$ref" in s:
+            ref = s["$ref"]
+            if ref in stack:
+                return None, stack + (ref,)
+            target = self.defs.get(ref) if isinstance(ref, str) else None
+            if target is None:
+                self.note(path, f"can't resolve $ref {_fmt(ref)}: passed as a JSON string")
+                return {"__free__": True, **{k: v for k, v in s.items() if k == "description"}}, stack
+            if self.gemini:
+                self.note(path, f"inlined $ref {ref} (references are not supported)")
+            siblings = {k: v for k, v in s.items() if k != "$ref"}
+            s = {**copy.deepcopy(target), **siblings}
+            stack = stack + (ref,)
+            seen += 1
+            if seen > 64:
+                return None, stack
+        if isinstance(s, dict) and isinstance(s.get("allOf"), list):
+            parts = []
+            for part in s["allOf"]:
+                part, stack2 = self.resolve(part, path, stack)
+                if part is None:
+                    return None, stack2
+                if isinstance(part, dict):
+                    parts.append(part)
+            merged = {k: v for k, v in s.items() if k != "allOf"}
+            for part in parts:
+                for k, v in part.items():
+                    if k == "properties" and isinstance(v, dict):
+                        merged.setdefault("properties", {})
+                        for pk, pv in v.items():
+                            merged["properties"].setdefault(pk, pv)
+                    elif k == "required" and isinstance(v, list):
+                        merged["required"] = list(dict.fromkeys((merged.get("required") or []) + v))
+                    else:
+                        merged.setdefault(k, v)
+            self.note(path, "merged allOf into one schema")
+            return self.resolve(merged, path, stack)
+        return s, stack
+
+    # one node ----------------------------------------------------------------------------
+    def json_string(self, s: Any, path: str, why: str) -> Tuple[Dict[str, Any], _Restore]:
+        self.note(path, f"{why}: passed as a JSON string")
+        desc = s.get("description") if isinstance(s, dict) else None
+        text = "JSON-encoded value"
+        out: Dict[str, Any] = {"type": "string",
+                               "description": f"{desc} ({text})" if desc else text}
+        return out, _Restore(json=True)
+
+    def convert(self, s: Any, path: str, stack: Tuple[str, ...], depth: int,
+                root: bool = False, nullable: bool = False) -> Tuple[Dict[str, Any], _Restore]:
+        s, stack = self.resolve(s, path, stack)
+        if s is None:
+            return self.json_string({}, path, "recursive schema")
+        if s is True or s == {} or not isinstance(s, dict):
+            return self.json_string({}, path, "any value is allowed")
+        if s.get("__free__"):
+            return self.json_string(s, path, "unresolved reference")
+        if depth > self.max_depth:
+            return self.json_string(s, path, f"nested deeper than {self.max_depth} levels")
+
+        s = dict(s)
+        if "nullable" in s:
+            if s.pop("nullable") is True:
+                nullable = True
+                if not self.gemini:
+                    self.note(path, "nullable (OpenAPI) rewritten as a null type")
+
+        # "type": ["string", "null"] and friends.
+        t = s.get("type")
+        if isinstance(t, list):
+            types = [x for x in t if isinstance(x, str)]
+            if "null" in types:
+                nullable = True
+                types = [x for x in types if x != "null"]
+            if self.gemini:
+                self.note(path, f"type list {_fmt(t)} rewritten (not supported)")
+            if len(types) == 1:
+                s["type"] = types[0]
+            elif not types:
+                s.pop("type")
+                return self.json_string(s, path, "the only type is null")
+            else:
+                s.pop("type")
+                s["anyOf"] = [{"type": x} for x in types]
+        elif t == "null":
+            return self.json_string(s, path, "the only type is null")
+
+        # oneOf / anyOf: drop the null branch, collapse single branches.
+        if "oneOf" in s:
+            branches = s.pop("oneOf")
+            self.note(path, "oneOf changed to anyOf")
+            s["anyOf"] = branches if "anyOf" not in s else s["anyOf"]
+        if isinstance(s.get("anyOf"), list):
+            branches = []
+            for b in s["anyOf"]:
+                rb, _ = self.resolve(b, path, stack)
+                if isinstance(rb, dict) and rb.get("type") == "null" and not (
+                        set(rb) & (_STRUCTURAL - {"type"})):
+                    nullable = True
+                    if self.gemini:
+                        self.note(path, "null branch of anyOf changed to nullable")
+                    continue
+                branches.append(b)
+            if not branches:
+                s.pop("anyOf")
+                return self.json_string(s, path, "the only type is null")
+            if len(branches) == 1:
+                rest = {k: v for k, v in s.items() if k != "anyOf"}
+                inner, stack = self.resolve(branches[0], path, stack)
+                if inner is None:
+                    return self.json_string(rest, path, "recursive schema")
+                if not isinstance(inner, dict) or inner is True:
+                    return self.json_string(rest, path, "any value is allowed")
+                s = {**inner, **{k: v for k, v in rest.items() if k != "type"}}
+                s.pop("anyOf", None)
+                return self.convert(s, path, stack, depth, root=root, nullable=nullable)
+            s["anyOf"] = branches
+
+        if isinstance(s.get("anyOf"), list):
+            out, restore = self.convert_anyof(s, path, stack, depth)
+        else:
+            out, restore = self.convert_typed(s, path, stack, depth, root)
+        return self.nullable(out, nullable), restore
+
+    def nullable(self, out: Dict[str, Any], nullable: bool) -> Dict[str, Any]:
+        if not nullable:
+            return out
+        if self.gemini:
+            out["nullable"] = True
+            return out
+        return _openai_null(out)
+
+    def convert_anyof(self, s, path, stack, depth):
+        branches = []
+        for b in s["anyOf"]:
+            out, _ = self.convert(b, path, stack, depth + 1)
+            if out not in branches:
+                branches.append(out)
+        out: Dict[str, Any] = {"anyOf": branches}
+        extra = {k: v for k, v in s.items() if k != "anyOf"}
+        self.finish(extra, out, path)
+        return out, _Restore()
+
+    def convert_typed(self, s, path, stack, depth, root):
+        s = dict(s)
+        if "const" in s:
+            c = s["const"]
+            if self.gemini:
+                s.pop("const")
+                if isinstance(c, str):
+                    s["enum"] = [c]
+                    s.setdefault("type", "string")
+                    self.note(path, "const changed to a one-value enum")
+                else:
+                    self.add_note(s, f"must be {_fmt(c)}")
+                    self.note(path, "const moved to the description")
+        t = s.get("type")
+        if t is None:
+            t = _infer(s)
+            if t is None:
+                return self.json_string(s, path, "no type")
+            s["type"] = t
+            self.note(path, f"missing type: set to {t}")
+        if t == "object":
+            return self.convert_object(s, path, stack, depth, root)
+        if t == "array":
+            return self.convert_array(s, path, stack, depth)
+        if t not in ("string", "number", "integer", "boolean"):
+            return self.json_string(s, path, f"unknown type {_fmt(t)}")
+        out: Dict[str, Any] = {"type": t}
+        self.finish(s, out, path)
+        if "enum" in s:
+            self.enum(s, out, t, path)
+        return out, _Restore(integer=(t == "integer"))
+
+    def enum(self, s, out, t, path):
+        values = s.get("enum")
+        if not isinstance(values, list):
+            s.pop("enum", None)
+            return
+        if self.gemini:
+            if t != "string":
+                s.pop("enum")
+                self.add_note(out, "one of: " + ", ".join(_fmt(v) for v in values))
+                self.note(path, f"{t} enum moved to the description (Gemini only "
+                                "allows enums on strings)")
+                return
+            strings = [v for v in values if isinstance(v, str) and v != ""]
+            if len(strings) != len(values):
+                self.note(path, "removed empty or non-string enum values")
+            if strings:
+                out["enum"] = strings
+            s.pop("enum")
+            return
+        out["enum"] = values
+        s.pop("enum")
+
+    def convert_object(self, s, path, stack, depth, root):
+        props = s.get("properties")
+        props = props if isinstance(props, dict) else {}
+        required_in = s.get("required")
+        required = [r for r in required_in if isinstance(r, str)] \
+            if isinstance(required_in, list) else []
+        if required_in is not None and not isinstance(required_in, list):
+            self.note(path, "required must be a list of names: ignored")
+
+        # FastAPI / OpenAPI 2 style "required": true on the property itself.
+        cleaned = {}
+        for name, ps in props.items():
+            if isinstance(ps, dict) and isinstance(ps.get("required"), bool):
+                ps = dict(ps)
+                flag = ps.pop("required")
+                self.note(_join(path, name), "boolean required flag moved into the parent's "
+                                             "required list")
+                if flag and name not in required:
+                    required.append(name)
+            cleaned[name] = ps
+        props = cleaned
+
+        missing = [r for r in required if r not in props]
+        if missing:
+            self.note(path, "required lists undefined properties: " + ", ".join(missing))
+            required = [r for r in required if r in props]
+
+        extra = s.get("additionalProperties")
+        if not props:
+            if root:
+                out: Dict[str, Any] = {"type": "object", "properties": {}}
+                if extra not in (None, False) or s.get("patternProperties"):
+                    self.note(path, "free-form arguments can't be described: the tool gets "
+                                    "no arguments")
+                if not self.gemini:
+                    out["required"] = []
+                    out["additionalProperties"] = False
+                self.finish(s, out, path, skip={"additionalProperties", "patternProperties",
+                                                "propertyNames"})
+                return out, _Restore()
+            return self.json_string(s, path, "object without fixed properties")
+
+        out = {"type": "object", "properties": {}}
+        restore = _Restore()
+        for name, ps in props.items():
+            child_path = _join(path, name)
+            child, child_restore = self.convert(ps, child_path, stack, depth + 1)
+            if not self.gemini and name not in required:
+                if not _is_nullable(child):
+                    child = _openai_null(child)
+                    child_restore.drop_null = True
+            out["properties"][name] = child
+            if not child_restore.empty():
+                restore.props[name] = child_restore
+        optional = [n for n in props if n not in required]
+        if self.gemini:
+            if required:
+                out["required"] = required
+            if "additionalProperties" in s:
+                if extra not in (False, None):
+                    self.note(path, "extra keys (additionalProperties) are not supported: "
+                                    "only the listed properties can be sent")
+                else:
+                    self.note(path, "removed additionalProperties (not supported)")
+        else:
+            out["required"] = list(props)
+            out["additionalProperties"] = False
+            if optional:
+                self.note(path, "strict mode needs every property required: optional "
+                                + ", ".join(optional) + " made nullable")
+            if extra is None:
+                self.note(path, "strict mode needs additionalProperties: false")
+            elif extra is not False:
+                self.note(path, "extra keys (additionalProperties) are not allowed in strict "
+                                "mode: only the listed properties can be sent")
+        self.finish(s, out, path, skip={"additionalProperties"})
+        return out, restore
+
+    def convert_array(self, s, path, stack, depth):
+        items = s.get("items")
+        if "prefixItems" in s or isinstance(items, list):
+            return self.json_string(s, path, "tuple arrays are not supported")
+        if items is None or items is True or items == {}:
+            return self.json_string(s, path, "array without an items type")
+        child, child_restore = self.convert(items, path + "[]", stack, depth + 1)
+        out = {"type": "array", "items": child}
+        self.finish(s, out, path)
+        return out, _Restore(items=None if child_restore.empty() else child_restore)
+
+    # keywords ----------------------------------------------------------------------------
+    def finish(self, s, out, path, skip=frozenset()):
+        """Copy the keywords the target accepts; describe or drop the rest."""
+        allowed = _GEMINI_KEYS if self.gemini else _OPENAI_KEYS
+        t = out.get("type")
+        moved = []
+        for k, v in s.items():
+            if k in out or k in skip or k == "__free__":
+                continue
+            if k in _STRUCTURAL and k not in ("const",):
+                continue
+            if k in _SILENT:
+                continue
+            if k == "default" and v is None:
+                continue
+            if k == "format":
+                if self.gemini:
+                    ok = (t == "string" and v in _GEMINI_STRING_FORMATS) or (
+                        t in ("number", "integer") and v in _GEMINI_NUMBER_FORMATS)
+                else:
+                    ok = t == "string" and v in _OPENAI_FORMATS
+                if ok:
+                    out[k] = v
+                else:
+                    moved.append((k, v))
+                continue
+            if k == "pattern" and not self.gemini and isinstance(v, str) and _LOOKAROUND.search(v):
+                moved.append((k, v))
+                continue
+            if k in allowed:
+                out[k] = v
+            elif k in _PHRASES:
+                moved.append((k, v))
+            elif k in ("description", "title"):
+                out[k] = v
+            else:
+                self.note(path, f"removed unsupported keyword {k}")
+        if moved:
+            self.add_note(out, "; ".join(_PHRASES[k].format(_fmt(v)) for k, v in moved))
+            self.note(path, "moved " + ", ".join(k for k, _ in moved) + " to the description "
+                            "(not supported)")
+
+    @staticmethod
+    def add_note(out, text):
+        desc = out.get("description")
+        out["description"] = f"{desc} ({text})" if desc else text[0].upper() + text[1:]
+
+
+def _infer(s: Dict[str, Any]) -> Optional[str]:
+    if "properties" in s or "additionalProperties" in s or "required" in s:
+        return "object"
+    if "items" in s or "prefixItems" in s:
+        return "array"
+    values = s.get("enum")
+    if isinstance(values, list) and values:
+        if all(isinstance(v, str) for v in values):
+            return "string"
+        if all(isinstance(v, bool) for v in values):
+            return "boolean"
+        if all(isinstance(v, int) and not isinstance(v, bool) for v in values):
+            return "integer"
+        if all(isinstance(v, (int, float)) and not isinstance(v, bool) for v in values):
+            return "number"
+    if any(k in s for k in ("minLength", "maxLength", "pattern")):
+        return "string"
+    if any(k in s for k in ("minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum")):
+        return "number"
+    return None
+
+
+def _is_nullable(out: Dict[str, Any]) -> bool:
+    t = out.get("type")
+    if isinstance(t, list) and "null" in t:
+        return True
+    return any(b.get("type") == "null" for b in out.get("anyOf") or [] if isinstance(b, dict))
+
+
+def _openai_null(out: Dict[str, Any]) -> Dict[str, Any]:
+    if _is_nullable(out):
+        return out
+    if "anyOf" in out:
+        out["anyOf"] = out["anyOf"] + [{"type": "null"}]
+        return out
+    t = out.get("type")
+    if isinstance(t, str):
+        out["type"] = [t, "null"]
+        if isinstance(out.get("enum"), list) and None not in out["enum"]:
+            out["enum"] = out["enum"] + [None]
+        return out
+    return {"anyOf": [out, {"type": "null"}]}

schemashim/names.py

@@ -0,0 +1,54 @@
+"""Tool names each provider accepts."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from .core import GEMINI, OPENAI_STRICT, TARGETS
+
+MAX_LEN = 64
+_BAD = {
+    OPENAI_STRICT: re.compile(r"[^A-Za-z0-9_-]"),
+    GEMINI: re.compile(r"[^A-Za-z0-9_.:-]"),
+}
+
+
+def _digest(name: str) -> str:
+    return hashlib.sha1(name.encode("utf-8")).hexdigest()[:8]
+
+
+def tool_name(name: str, target: str) -> str:
+    """Return ``name`` changed only as much as ``target`` needs.
+
+    OpenAI allows ``[A-Za-z0-9_-]{1,64}``; Gemini also allows ``.`` and ``:`` and the name must
+    start with a letter or underscore. Invalid characters become ``_``; names that had to change
+    in a lossy way (too long, or emptied) get a short hash of the original so two different
+    tools never end up with the same name.
+    """
+    if target not in TARGETS:
+        raise ValueError(f"unknown target {target!r}; use one of {', '.join(TARGETS)}")
+    if not isinstance(name, str):
+        raise TypeError("tool name must be a string")
+    out = _BAD[target].sub("_", name)
+    if target == GEMINI and not re.match(r"[A-Za-z_]", out[:1] or "0"):
+        out = "_" + out
+    if not out.strip("_"):
+        out = "tool_" + _digest(name)
+    if len(out) > MAX_LEN:
+        out = out[: MAX_LEN - 9] + "_" + _digest(name)
+    return out
+
+
+def unique_name(name: str, target: str, taken: set) -> str:
+    """Like :func:`tool_name`, but different from every name in ``taken``."""
+    out = tool_name(name, target)
+    if out not in taken:
+        return out
+    base = out[: MAX_LEN - 9]
+    candidate = f"{base}_{_digest(name)}"
+    n = 2
+    while candidate in taken:
+        candidate = f"{base}_{_digest(name + '#' + str(n))}"
+        n += 1
+    return candidate

schemashim/tools.py

@@ -0,0 +1,123 @@
+"""Adapt whole MCP tools (name, description, inputSchema) for a provider."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from .core import GEMINI, Change, Shim, adapt
+from .names import unique_name
+
+
+def _get(tool: Any, *keys: str) -> Any:
+    for key in keys:
+        if isinstance(tool, dict):
+            if key in tool:
+                return tool[key]
+        elif hasattr(tool, key):
+            return getattr(tool, key)
+    return None
+
+
+@dataclass
+class AdaptedTool:
+    """One tool, ready to send to the provider."""
+
+    name: str
+    original_name: str
+    description: str
+    target: str
+    shim: Shim
+    changes: List[Change] = field(default_factory=list)
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return self.shim.schema
+
+    @property
+    def function(self) -> Dict[str, Any]:
+        """``{"name", "description", "parameters"}`` (plus ``"strict": True`` for OpenAI).
+
+        For the OpenAI Responses API send ``{"type": "function", **tool.function}``.
+        """
+        out: Dict[str, Any] = {"name": self.name, "description": self.description}
+        if self.target == GEMINI:
+            if self.parameters.get("properties"):
+                out["parameters"] = self.parameters
+            return out
+        out["parameters"] = self.parameters
+        out["strict"] = True
+        return out
+
+    @property
+    def declaration(self) -> Dict[str, Any]:
+        """A Gemini ``functionDeclaration``, or an OpenAI Chat Completions ``tools`` entry."""
+        if self.target == GEMINI:
+            return self.function
+        return {"type": "function", "function": self.function}
+
+    def restore(self, args: Any) -> Any:
+        return self.shim.restore(args)
+
+
+def adapt_tool(tool: Any, target: str, *, name: Optional[str] = None,
+               taken: Optional[set] = None, max_depth: int = 10) -> AdaptedTool:
+    """Adapt one MCP tool: a ``tools/list`` entry as a dict, or an ``mcp.types.Tool``."""
+    original = _get(tool, "name")
+    if not isinstance(original, str) or not original:
+        raise ValueError("tool has no name")
+    schema = _get(tool, "inputSchema", "input_schema", "parameters")
+    description = _get(tool, "description") or ""
+    shim = adapt(schema, target, max_depth=max_depth)
+    provider_name = name or unique_name(original, target, taken or set())
+    changes = list(shim.changes)
+    if provider_name != original:
+        changes.insert(0, Change("(name)", f"renamed to {provider_name}"))
+    return AdaptedTool(provider_name, original, description, target, shim, changes)
+
+
+class ToolKit:
+    """A set of adapted tools that maps the model's calls back to the original tools."""
+
+    def __init__(self, tools: Iterable[Any], target: str, *, max_depth: int = 10) -> None:
+        if isinstance(tools, dict) and isinstance(tools.get("tools"), list):
+            tools = tools["tools"]
+        elif _get(tools, "tools") is not None and not isinstance(tools, (list, tuple)):
+            tools = _get(tools, "tools")
+        self.target = target
+        self.tools: List[AdaptedTool] = []
+        self._by_name: Dict[str, AdaptedTool] = {}
+        seen = set()
+        for tool in tools:
+            adapted = adapt_tool(tool, target, taken=set(self._by_name), max_depth=max_depth)
+            if adapted.original_name in seen:
+                raise ValueError(f"duplicate tool name {adapted.original_name!r}")
+            seen.add(adapted.original_name)
+            self.tools.append(adapted)
+            self._by_name[adapted.name] = adapted
+
+    def __iter__(self):
+        return iter(self.tools)
+
+    def __len__(self) -> int:
+        return len(self.tools)
+
+    @property
+    def declarations(self) -> List[Dict[str, Any]]:
+        return [t.declaration for t in self.tools]
+
+    def get(self, name: str) -> AdaptedTool:
+        try:
+            return self._by_name[name]
+        except KeyError:
+            raise KeyError(f"the model called an unknown tool {name!r}") from None
+
+    def restore(self, name: str, args: Any) -> Tuple[str, Any]:
+        """Map a call from the model to ``(original tool name, original-shaped arguments)``."""
+        tool = self.get(name)
+        return tool.original_name, tool.restore(args)
+
+
+def adapt_tools(tools: Iterable[Any], target: str, *, max_depth: int = 10) -> ToolKit:
+    """Adapt a list of MCP tools (or a ``tools/list`` result) for ``target``."""
+    return ToolKit(tools, target, max_depth=max_depth)

schemashim-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: schemashim
+Version: 0.1.0
+Summary: Fix MCP and agent tool JSON Schemas that Gemini and OpenAI strict mode reject ($ref, anyOf null, type lists, arrays without items, enums), and map the model's arguments back
+Project-URL: Homepage, https://github.com/srikrishnaL/kitforge/tree/main/packages/schemashim
+Project-URL: Source, https://github.com/srikrishnaL/kitforge
+Project-URL: Issues, https://github.com/srikrishnaL/kitforge/issues
+Project-URL: Changelog, https://github.com/srikrishnaL/kitforge/blob/main/packages/schemashim/CHANGELOG.md
+Author: Sri Krishna Lingamaneni
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,function calling,function declarations,gemini,invalid_argument,json schema,llm,mcp,model context protocol,openai,strict mode,structured outputs,tool calling,vertex ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pydantic>=2; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# schemashim
+
+Make MCP and agent tool schemas work on Gemini and OpenAI strict mode, then turn the model's
+arguments back into what the tool expects.
+
+Gemini and OpenAI's `strict: true` function calling accept only a subset of JSON Schema, so one
+ordinary tool (a pydantic `$ref`, `Optional[int]`, an array without `items`, an `enum` with `""`,
+an untyped field) makes **every** request fail with `400 INVALID_ARGUMENT` or `Invalid schema`.
+schemashim rewrites a schema into the subset each provider accepts, says what it changed, and
+undoes the changes on the arguments the model sends back.
+
+```bash
+pip install schemashim
+```
+
+Python 3.9+, no dependencies.
+
+## Fix one schema
+
+```python
+from schemashim import adapt
+
+schema = {
+    "type": "object",
+    "$defs": {"Point": {"type": "object", "required": ["lat", "lon"],
+                        "properties": {"lat": {"type": "number"}, "lon": {"type": "number"}}}},
+    "properties": {
+        "start": {"$ref": "#/$defs/Point"},
+        "limit": {"anyOf": [{"type": "integer"}, {"type": "null"}], "default": None},
+        "tags": {"type": "array"},
+    },
+    "required": ["start"],
+}
+
+shim = adapt(schema, "gemini")          # or "openai-strict"
+shim.schema      # send this as the function's parameters
+for change in shim.changes:
+    print(change)
+# start: inlined $ref #/$defs/Point (references are not supported)
+# limit: null branch of anyOf changed to nullable
+# tags: array without an items type: passed as a JSON string
+
+# When the model calls the tool, map its arguments back before calling the real tool:
+shim.restore({"start": {"lat": 1, "lon": 2}, "tags": '["a", "b"]'})
+# {'start': {'lat': 1, 'lon': 2}, 'tags': ['a', 'b']}
+```
+
+`shim.ok` is `True` when the original was already accepted as is; `check(schema, target)`
+returns only the list of changes.
+
+## Bridge MCP tools to Gemini or OpenAI
+
+```python
+from schemashim import adapt_tools
+
+tools = (await session.list_tools()).tools        # mcp.types.Tool objects, or dicts
+kit = adapt_tools(tools, "openai-strict")          # or "gemini"
+
+response = client.chat.completions.create(model=..., messages=..., tools=kit.declarations)
+for call in response.choices[0].message.tool_calls or []:
+    name, args = kit.restore(call.function.name, json.loads(call.function.arguments))
+    result = await session.call_tool(name, args)
+```
+
+For Gemini, `kit.declarations` are `functionDeclarations`:
+`types.Tool(function_declarations=kit.declarations)` in `google-genai`, or
+`{"functionDeclarations": kit.declarations}` over REST. For the OpenAI Responses API use
+`[{"type": "function", **t.function} for t in kit]`.
+
+Tool names are fixed too: `github/search_issues` becomes `github_search_issues`, names over 64
+characters get a short hash, and two tools never end up with the same name. `kit.restore` maps
+the name back.
+
+## What it changes
+
+| Problem in the schema | Gemini | OpenAI strict |
+| --- | --- | --- |
+| `$ref` / `$defs` / `definitions` | inlined | inlined |
+| Recursive `$ref` (a tree) | the recursive field is a JSON string | same |
+| `anyOf: [X, {type: null}]`, `type: [X, "null"]`, OpenAPI `nullable` | `nullable: true` | `type: [X, "null"]` |
+| `type: [A, B]`, `oneOf` | `anyOf` | `anyOf` |
+| `allOf` | merged | merged |
+| Optional properties | kept optional | made required and nullable (strict mode needs every property in `required`); `restore` drops the nulls |
+| `additionalProperties` | removed | set to `false` on every object |
+| Array without `items`, object without `properties`, untyped "any" field, tuple arrays | sent as a JSON string; `restore` decodes it | same |
+| `enum` with `""` or non-strings | `""` dropped; number enums move to the description | kept |
+| `const` | one-value `enum` | kept |
+| Missing `type` | inferred from `properties`, `items`, `enum`, bounds | same |
+| `required` naming undefined properties, `"required": true` on a property | fixed | fixed |
+| Root not an object, root `anyOf` of objects | made an object / merged | same |
+| `format`, `exclusiveMinimum`, `multipleOf`, `minLength`, `default`, regex lookarounds... that the target rejects | written into the description so the model still sees them | same |
+| `$schema`, `$id`, `not`, `if`/`then`, `patternProperties`... | removed | removed |
+
+`restore` also turns `5.0` back into `5` for integer fields (Gemini sends numbers as floats).
+
+## In CI
+
+```bash
+schemashim check tools.json                     # exit 1 if Gemini or OpenAI strict would reject a tool
+schemashim check tools.json --target gemini --json
+schemashim fix tools.json --target openai-strict > tools.openai.json
+```
+
+The file can be a schema, one tool, a list of tools, a `tools/list` response or an
+[mcptest](../mcptest/) snapshot, and `-` reads stdin. To check a running MCP server:
+
+```bash
+mcptest tools -- python my_server.py | schemashim check -
+```
+
+## Limits
+
+- A JSON-string field is a workaround: the model sees "JSON-encoded value" instead of the real
+  shape, so describe what goes in it. It only happens where the provider cannot express the
+  shape at all.
+- Strict mode can't express "optional": the model sends `null`, and `restore` removes it. If a
+  field was already nullable, a `null` is kept, because it may be meaningful.
+- Merging a root `anyOf` makes fields that are not in every choice optional; the tool must still
+  validate which combination is valid.
+- Gemini's newer `parametersJsonSchema` field accepts more of JSON Schema. schemashim targets the
+  classic `parameters` field that most clients and SDKs send, and its output is valid there too.
+- Only local `#/$defs/...` and `#/definitions/...` references are followed; remote ones become
+  JSON-string fields.
+- Provider rules change. If a schema still gets rejected, open an issue with the error text.
+
+## Why this exists
+
+Every MCP client and agent framework that talks to Gemini or OpenAI strict mode hits this and
+writes its own partial sanitizer. A few of the reports:
+
+- [google-gemini/gemini-cli#13326](https://github.com/google-gemini/gemini-cli/issues/13326): Gemini API rejects MCP tool schemas with `$defs` references
+- [modelcontextprotocol/servers#1624](https://github.com/modelcontextprotocol/servers/issues/1624): mcp-server-fetch's schema can't be used with Gemini 2.5 Pro
+- [Portkey-AI/gateway#1203](https://github.com/Portkey-AI/gateway/issues/1203): not converting JSON Schema to Gemini compatible tool definitions
+- [chatboxai/chatbox#2606](https://github.com/chatboxai/chatbox/issues/2606): Gemini tool integration fails with `INVALID_ARGUMENT`
+- [langchain-ai/langchain-google#535](https://github.com/langchain-ai/langchain-google/issues/535): "should be non-empty for OBJECT type"
+- [BerriAI/litellm#18442](https://github.com/BerriAI/litellm/issues/18442): "functionDeclaration parameters schema should be of type OBJECT"
+- [Kilo-Org/kilocode#15512](https://github.com/Kilo-Org/kilocode/issues/15512), [cline/cline#11162](https://github.com/cline/cline/issues/11162), [CherryHQ/cherry-studio#18890](https://github.com/CherryHQ/cherry-studio/issues/18890), [anomalyco/opencode#48073](https://github.com/anomalyco/opencode/issues/48073): empty enums, undefined required properties, arrays without items, nullable arrays
+- [openclaw/openclaw#166877](https://github.com/openclaw/openclaw/issues/166877), [NousResearch/hermes-agent#104796](https://github.com/NousResearch/hermes-agent/issues/104796), [cloudflare/mcp-server-cloudflare#378](https://github.com/cloudflare/mcp-server-cloudflare/issues/378): one MCP tool breaks every strict-mode request
+
+GitHub search finds over 300 issues titled "tool schema" + Gemini alone. The demand evidence
+is in [`demand/`](../../demand/) (idea `tool-schema-compat`).
+
+## License
+
+MIT

schemashim-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+schemashim/__init__.py,sha256=3N9JGFDBNo5a7vywMnq-ZcK71wEgot8GRTOVC_SHAYA,464
+schemashim/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+schemashim/cli.py,sha256=INmFXX4Se4iOO4S887Lcfrg_YeENtOs__vnqzuOb-4U,3963
+schemashim/core.py,sha256=cQeIWr4b2ETqHCnz8nFxo9Mm8L3ukg0q-c9ZrovHRVM,26328
+schemashim/names.py,sha256=xGkt_CWPc_8wYF4oo1wjWxzdIZfoRQ-xjfZlWSpwAAg,1746
+schemashim/tools.py,sha256=HS9u_fFfAi_aSL6nk5Tzxvkpg1BMVnSc-AHRAudndxk,4535
+schemashim-0.1.0.dist-info/METADATA,sha256=f8AmvHD4NhWi1RXIyyogcbT6_j2eoQWFDcBvxms56Z8,9076
+schemashim-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+schemashim-0.1.0.dist-info/entry_points.txt,sha256=NEut_u1MpvqnmaKffciSpMg_E91I5KVtL_H6C2LO-8Q,51
+schemashim-0.1.0.dist-info/licenses/LICENSE,sha256=fl9U1idgeyJw-8GWneEYxVzZM_C29cBR63IAlNv7KjE,1080
+schemashim-0.1.0.dist-info/RECORD,,

schemashim-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

schemashim-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+schemashim = schemashim.cli:main

schemashim-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sri Krishna Lingamaneni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.