Schema mutation: _prune_param and _convert_nullable_field modify input in place

[strawgate]

Two functions that claim to return new schemas actually mutate their input.

1. _prune_param (utilities/json_schema.py)

Docstring says "Return a new schema with param removed" but uses .pop() and .remove() on the input dict:

import copy
from fastmcp.utilities.json_schema import _prune_param

schema = {'properties': {'a': {'type': 'string'}, 'b': {'type': 'int'}}, 'required': ['a', 'b']}
backup = copy.deepcopy(schema)
_prune_param(schema, 'a')
assert schema == backup  # FAILS — 'a' was removed from the original

2. _convert_nullable_field (utilities/openapi/json_schema_converter.py)

Uses schema.copy() (shallow) then .append() on the shared anyOf list:

from fastmcp.utilities.openapi.json_schema_converter import _convert_nullable_field

schema = {"anyOf": [{"type": "string"}], "nullable": True}
original_len = len(schema["anyOf"])
_convert_nullable_field(schema)
assert len(schema["anyOf"]) == original_len  # FAILS — null type appended to original list

Both can corrupt shared schema objects when the same schema dict is referenced from multiple places (common with $ref resolution).

[marvin-context-protocol]

Claude finished @strawgate's task in 2m 14s —— View job

---

Recommendation

Both bugs are real and easy to fix. They should be fixed together — same class of bug (shared-reference mutation), both in schema-processing helpers, both callable on user/$ref-shared dicts.

• _prune_param is the more serious one: its contract promises a new schema ("Return a new schema"), callers in compress_schema chain it expecting pure behavior, and it currently mutates the input's properties dict and required list.
• _convert_nullable_field has a narrower failure: it correctly .copy()s the top-level dict but shares the nested anyOf list with the input, so .append(...) on line 176 corrupts the original. (The type/oneOf/allOf/enum branches already use list-spread or reassignment and are safe.)

The fix in each case is to copy the nested container before mutating it. No deepcopy needed — only the containers actually written to need copying.

Findings

Bug 1: src/fastmcp/utilities/json_schema.py:286-304

def _prune_param(schema: dict[str, Any], param: str) -> dict[str, Any]:
    props = schema.get("properties", {})          # ← reference, not copy
    removed = props.pop(param, None)              # ← mutates input
    if removed is None:
        return schema

    schema["properties"] = props                  # ← assigns same ref back (no-op)
    if param in schema.get("required", []):
        schema["required"].remove(param)          # ← mutates input's required list
        ...
    return schema

The docstring says "Return a new schema with param removed" but the function mutates in place and returns the same object.

Bug 2: src/fastmcp/utilities/openapi/json_schema_converter.py:152-185

def _convert_nullable_field(schema: dict[str, Any]) -> dict[str, Any]:
    ...
    result = schema.copy()                        # shallow
    ...
    elif "anyOf" in result:
        if not any(item.get("type") == "null" for item in result["anyOf"]):
            result["anyOf"].append({"type": "null"})   # ← mutates shared list

schema.copy() is shallow, so result["anyOf"] is the same list object as schema["anyOf"]. append() corrupts the original.

The other branches are fine by accident:

• type branch uses [*current_type, "null"] — new list.
• oneOf branch uses [*result.pop("oneOf"), {"type": "null"}] — new list; pop acts on the shallow-copy dict only.
• allOf branch wraps in a fresh list literal.
• enum branch uses result["enum"] + [None] — new list.

Only the anyOf .append leaks.

Blast radius. In normal compress_schema flow the input often isn't shared, so these bugs are latent. They bite when:

• The same schema dict is reached through multiple paths (e.g. $ref resolution that produces structural sharing — common with jsonref.replace_refs(proxies=False) and with Pydantic's $defs).
• A caller holds a reference to the input and expects it unchanged after compression.
• An OpenAPI parser reuses definition dicts across routes (exactly the scenario _convert_nullable_field runs in).

Verification

Reproduced both bugs directly against this checkout:

[_prune_param] mutated input? True
  input after call: {'properties': {'b': {'type': 'int'}}, 'required': ['b']}
  result is input dict? True

[_convert_nullable_field] mutated shared anyOf list? True
  original anyOf list now: [{'type': 'string'}, {'type': 'null'}]

Both reports are accurate.

Detailed Action Plan

1. Fix _prune_param in src/fastmcp/utilities/json_schema.py:286:

def _prune_param(schema: dict[str, Any], param: str) -> dict[str, Any]:
    """Return a new schema with *param* removed from `properties`, `required`,
    and (if no longer referenced) `$defs`.
    """
    props = schema.get("properties", {})
    if param not in props:
        return schema  # unchanged — safe to return as-is

    new_schema = dict(schema)
    new_props = dict(props)
    new_props.pop(param)
    new_schema["properties"] = new_props

    required = schema.get("required")
    if required is not None and param in required:
        new_required = [r for r in required if r != param]
        if new_required:
            new_schema["required"] = new_required
        else:
            new_schema.pop("required", None)

    return new_schema

Key changes: top-level shallow copy, copy properties before mutating, rebuild required with a comprehension instead of .remove().

2. Fix _convert_nullable_field in src/fastmcp/utilities/openapi/json_schema_converter.py:173-176:

elif "anyOf" in result:
    # Add null to anyOf if not present
    if not any(item.get("type") == "null" for item in result["anyOf"]):
        result["anyOf"] = [*result["anyOf"], {"type": "null"}]

One-line change from .append(...) to list-spread. Matches the style already used in the sibling oneOf/type branches.

3. Add regression tests in tests/utilities/test_json_schema.py (the TestPruneParam class) and a new test file/section for _convert_nullable_field:

# tests/utilities/test_json_schema.py (TestPruneParam)
def test_does_not_mutate_input(self):
    """_prune_param must not mutate its input schema."""
    schema = {
        "properties": {"foo": {"type": "string"}, "bar": {"type": "integer"}},
        "required": ["foo", "bar"],
    }
    snapshot = copy.deepcopy(schema)
    _prune_param(schema, "bar")
    assert schema == snapshot

# tests/utilities/openapi/test_json_schema_converter.py (or similar)
def test_convert_nullable_does_not_mutate_shared_anyof():
    schema = {"anyOf": [{"type": "string"}], "nullable": True}
    shared_list = schema["anyOf"]
    _convert_nullable_field(schema)
    assert shared_list == [{"type": "string"}]

4. Check callers. Both helpers' existing public callers (compress_schema and convert_openapi_schema_to_json_schema) already treat results as new values, so no API changes are required. The existing tests in tests/utilities/test_json_schema.py::TestPruneParam should all still pass unchanged (they only assert on result, not input identity).

5. Run the suite. uv run pytest -n auto and uv run prek run --all-files per CLAUDE.md.

Related Files

Repository	File	Relevance	Lines
PrefectHQ/fastmcp	src/fastmcp/utilities/json_schema.py	_prune_param is here, mutates input via .pop() and .remove().	286-304
PrefectHQ/fastmcp	src/fastmcp/utilities/openapi/json_schema_converter.py	_convert_nullable_field — shallow .copy() followed by .append on shared anyOf list.	152-185
PrefectHQ/fastmcp	tests/utilities/test_json_schema.py	Existing TestPruneParam — regression test for input-mutation should be added here.	14-52

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.