Fix $ref output schema object detection regression by jlowin · Pull Request #3420 · PrefectHQ/fastmcp

jlowin · 2026-03-06T22:31:05Z

Motivation

A recent simplification treated any schema containing both $ref and $defs as an object, which causes non-object referenced schemas (for example Pydantic alias/enums) to be misclassified and skip wrapping. This can lead to ToolResult runtime ValueError because structured_content must be a dict.
The goal is to preserve wrapping for non-object referenced schemas by resolving local #/$defs/... targets before deciding whether a schema is object-shaped.

Description

Update _is_object_schema in src/fastmcp/tools/function_parsing.py to accept optional _root_schema and _seen_refs parameters and resolve local #/$defs/... references recursively instead of assuming $ref + $defs means an object.
Add cycle protection when resolving references so recursive definitions do not loop infinitely.
Add a focused regression test test_output_schema_wraps_non_object_ref_schema in tests/server/providers/local_provider_tools/test_output_schema.py which uses a TypeAliasType/Literal alias to ensure non-object $ref schemas are wrapped (x-fastmcp-wrap-result) and runtime structured_content is a dict.
Small test import updates to support the new test (Literal, TypeAliasType).

Testing

Ran uv sync successfully to install dependencies.
Ran the full test suite with uv run pytest -n auto, which completed but reported unrelated failures in the container run (12 failed, 1 error) that appear environment/timeout related and not caused by this change.
Ran the focused tests for this change with uv run pytest tests/server/providers/local_provider_tools/test_output_schema.py, and all 20 tests passed. prek static hook run uv run prek run --all-files failed to initialize due to a network/git clone error (403) and could not complete.

Codex Task

🤖 Generated with GPT-5.2-Codex

jlowin · 2026-03-06T22:32:28Z

/marvin fix static analysis

marvin-context-protocol · 2026-03-06T22:33:01Z

Claude finished @jlowin's task in 1m 17s —— View job

Fixed static analysis

Install dependencies
Run static analysis to identify issues
Fix issues
Verify fixes

The ty checker flagged one error: invalid-type-alias-type at test_output_schema.py:289 — the TypeAliasType name "AliasType" didn't match the variable alias_type. Renamed the variable to AliasType to match. All checks pass and all 20 tests in the file still pass.

Marvin Context Protocol | Type /marvin to interact further

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

marvin-context-protocol · 2026-03-06T22:33:07Z

Test Failure Analysis

Summary: The static_analysis job failed due to a ty (type checker) error in the new test code — a TypeAliasType name doesn't match its variable name.

Root Cause: In tests/server/providers/local_provider_tools/test_output_schema.py:289, the TypeAliasType is constructed with a name string ("AliasType") that doesn't match the variable it's assigned to (alias_type). The ty type checker enforces that these must match:

# line 289 — invalid
alias_type = TypeAliasType("AliasType", Literal["foo", "bar"])
#  variable: alias_type      ^ name: AliasType  (mismatch!)

Suggested Solution: Fix the variable name to match the TypeAliasType name string (or vice versa). Since the string "AliasType" is used for the type name, rename the variable to match:

In tests/server/providers/local_provider_tools/test_output_schema.py:289, change:

alias_type = TypeAliasType("AliasType", Literal["foo", "bar"])

to:

AliasType = TypeAliasType("AliasType", Literal["foo", "bar"])

and update any references to alias_type in the same test to use AliasType instead.

Detailed Analysis

Failing check

ty check.................................................................[Failed]
- hook id: ty
- exit code: 1

error[invalid-type-alias-type]: The name of a `TypeAliasType` (`AliasType`) must match the name of the variable it is assigned to (`alias_type`)
  --> tests/server/providers/local_provider_tools/test_output_schema.py:289:9
    |
287 |         """Root $ref schemas should only skip wrapping when they resolve to objects."""
288 |         mcp = FastMCP()
289 |         alias_type = TypeAliasType("AliasType", Literal["foo", "bar"])
    |         ^^^^^^^^^^
    |
info: rule `invalid-type-alias-type` is enabled by default

Found 1 diagnostic

Other checks

ruff check, ruff format, prettier, validate pyproject.toml, and codespell all passed.
The loq (file size limits) check reported 7 violations but explicitly states they are "not enforced... yet!" — this did not cause the failure.

Related Files

tests/server/providers/local_provider_tools/test_output_schema.py:289 — the test file containing the mismatched TypeAliasType name, introduced in this PR

Co-authored-by: Jeremiah Lowin <[email protected]> 🤖 Generated with Claude Code

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5257deeaa4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-07T15:43:21Z

+    definition_name = ref.removeprefix("#/$defs/")
+    definitions = root_schema.get("$defs")
+    if not isinstance(definitions, dict):
+        return False
+
+    target_schema = definitions.get(definition_name)


Resolve escaped JSON-pointer tokens in $defs refs

The new $ref resolver assumes the definition key is the raw suffix after #/$defs/, but JSON Pointer escapes / and ~ as ~1/~0 (and can include deeper paths), so refs like #/$defs/A~1B or #/$defs/Outer/$defs/Inner won’t resolve even when they point to object schemas. In those cases _is_object_schema returns False, which causes FastMCP to wrap an already-object output and change structured_content shape unexpectedly for valid schemas that previously passed object checks.

Useful? React with 👍 / 👎.

jlowin · 2026-03-07T17:09:53Z

Auto-reviewed: all CI checks green, review comments addressed. Merging.

@tool

Co-authored-by: Claude Opus 4.6 <[email protected]> Co-authored-by: Jeremiah Lowin <[email protected]> Co-authored-by: Marvin Context Protocol <41898282+Marvin Context [email protected]> Co-authored-by: voidborne-d <[email protected]> Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com> Co-authored-by: Claude <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: d 🔹 <[email protected]> Co-authored-by: Jeremiah Lowin <[email protected]> Co-authored-by: nightcityblade <[email protected]> Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]> Co-authored-by: Claude Sonnet 4.6 <[email protected]> Co-authored-by: Bill Easton <[email protected]> Co-authored-by: Sumanshu Nankana <[email protected]> Co-authored-by: Eric Robinson <[email protected]> Co-authored-by: Martim Santos <[email protected]> Co-authored-by: d 🔹 <[email protected]> Co-authored-by: Matthieu B <[email protected]> Co-authored-by: Sascha Buehrle <[email protected]> Co-authored-by: Hakancan <[email protected]> Co-authored-by: nightcityblade <[email protected]> Co-authored-by: Matt Hallowell <[email protected]> Co-authored-by: nate nowack <[email protected]> Co-authored-by: Bill Easton <[email protected]> Co-authored-by: Marcus Shu <[email protected]> Co-authored-by: Rushabh Doshi <[email protected]> Co-authored-by: AIKAWA Shigechika <[email protected]> Co-authored-by: Jeremy Simon <[email protected]> Co-authored-by: Miguel Miranda Dias <[email protected]> Co-authored-by: Anthony James Padavano <[email protected]> Co-authored-by: Mostafa Kamal <[email protected]> Fix auto-close MRE script posting comment without closing (#3386) Fix WorkOS token scope verification bypass 🤖 Generated with Codex (#3407) Fix initialize McpError fallthrough 🤖 Generated with Codex (#3413) Fix transform arg collisions with passthrough params (#3431) Fix get_* returning None when latest version is disabled (#3439) Fix get_* returning None when latest version is disabled (#3421) Fix server lifespan overlap teardown (#3415) Fix $ref output schema object detection regression (#3420) resolved annotations (#3429) Fix async partial callables rejected by iscoroutinefunction (#3438) Fix async partial callables rejected by iscoroutinefunction (#3423) fix: add version to components (#3458) fix: use intent-based flag for OIDC scope patch in load_access_token (#3465) Fixes #3461 fix: normalize Google scope shorthands and surface valid_scopes (#3477) fix: resolve ty 0.0.23 type-checking errors and bump pin (#3481) fix: shield lifespan teardown from cancellation (#3480) fix: forward custom_route endpoints from mounted servers (#3462) fix updates _get_additional_http_routes() to traverse providers, Fixes #3457 fix: remove hardcoded version from CLI help text (#3456) fix: monty 0.0.8 compatibility, drop external_functions from constructor (#3468) fix: task test teardown hanging 5s per test (#3499) Closes #3498 fix: validate workspace path is a directory before cursor install (#3440) Fixes #3426 fix: handle re.error from malformed URI templates in build_regex (#3501) fix: reject empty/OIDC-only required_scopes in AzureProvider (#3503) fix: restrict $ref resolution to local refs only (SSRF/LFI) (#3502) fix warnings and timeouts (#3504) close upgrade check issue when build passes (#3505) Closes #3484 fix: URL-encode path params to prevent SSRF/path traversal (GHSA-vv7q-7jx5-f767) (#3507) fix: prevent path traversal in skill download (#3493) fix: prefer IdP-granted scopes over client-requested scopes in OAuthProxy (#3492) fix: remove unrelated transform and http.py changes from PR scope fix: remove forced follow_redirects from httpx_client_factory calls (#3496) fix: stop passing follow_redirects to httpx_client_factory fix: restore follow_redirects=True for custom httpx client factories Closes #3509 fix: CSRF double-submit cookie check in consent flow (#3519) fix: validate server names in install commands (#3522) fix: use raw strings for regex in pytest.raises match (#3523) fix: reject refresh tokens used as Bearer access tokens (#3524) fix: route ResourcesAsTools/PromptsAsTools through server middleware (#3495) fix: resolve Pyright "Module is not callable" on @tool, @resource, @prompt decorators (#3540) fix: filter warnings by message in KEY_PREFIX test (#3549) fix: suppress output schema for ToolResult subclass annotations (#3548) fix: increase sleep duration in proxy cache tests (#3567) fix: store absolute token expiry to prevent stale expires_in on reload (#3572) fix: preserve tool properties named 'title' during schema compression (#3582) Fix loopback redirect URI port matching per RFC 8252 §7.3 (#3589) Fix app tool routing: visibility check and middleware propagation (#3591) Fix query parameter serialization to respect OpenAPI explode/style settings (#3595) Fix dev apps form: union types, textarea support, JSON parsing (#3597) fix(google): replace deprecated /oauth2/v1/tokeninfo with /oauth2/v3/userinfo (#3603) fix: resolve EntraOBOToken dependency injection through MultiAuth (#3609) fix(docs): correct misleading stateless_http header (#3622) fix: filesystem provider import machinery (#3626) Closes #3625 (issues 2, 3, 6) fix: recover StdioTransport after subprocess exits (#3630) fix(server): preserve mounted tool task metadata (#3632) fix: scope deprecation warning filter to FastMCPDeprecationWarning (#3649) fix imports, add PrefabAppConfig (#3650) fix: resolve CurrentFastMCP/ctx.fastmcp to child server in mounted background tasks (#3651) Fix blocking docs issues: chart imports, Select API, Rx consistency (#3652) closed by default (#3657) Fix prompt caching middleware missing wrap/unwrap round-trip (#3666) fix: serialize object query params per OpenAPI style/explode rules (#3662) Fixes #2857 fix: HTTP request headers not accessible in background task workers (#3631) fix: restore HTTP headers in worker execution path for background tasks (#3681) fix: strip discriminator after dereferencing schemas (#3682) fix: remove stale ty:ignore directives for ty 0.0.26 (#3684) Fix docs gaps in app provider pages (#3690) fix: dev apps log panel UX improvements (#3698) fix dev server empty string args (#3700)

Fix output schema object detection

26240b9

🤖 Generated with GPT-5.2-Codex

jlowin added aardvark codex labels Mar 6, 2026 — with ChatGPT Codex Connector

marvin-context-protocol Bot added bug Something isn't working. Reports of errors, unexpected behavior, or broken functionality. server Related to FastMCP server implementation or server-side functionality. labels Mar 6, 2026

Marvin Context Protocol and others added 2 commits March 6, 2026 22:34

Fix ty invalid-type-alias-type error

d8de3bc

Co-authored-by: Jeremiah Lowin <[email protected]> 🤖 Generated with Claude Code

Merge branch 'main' into codex/fix-ref-output-schemas-misclassification

5257dee

chatgpt-codex-connector Bot reviewed Mar 7, 2026

View reviewed changes

Fix $ref resolution to handle JSON Pointer escaping and nested paths

f6b0d63

jlowin merged commit ceb8ff1 into main Mar 7, 2026
7 checks passed

jlowin deleted the codex/fix-ref-output-schemas-misclassification branch March 7, 2026 17:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix $ref output schema object detection regression#3420

Fix $ref output schema object detection regression#3420
jlowin merged 4 commits intomainfrom
codex/fix-ref-output-schemas-misclassification

jlowin commented Mar 6, 2026

Uh oh!

jlowin commented Mar 6, 2026

Uh oh!

marvin-context-protocol Bot commented Mar 6, 2026 •

edited

Loading

Uh oh!

marvin-context-protocol Bot commented Mar 6, 2026

Failing check

Other checks

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Mar 7, 2026

Uh oh!

jlowin commented Mar 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jlowin commented Mar 6, 2026

Motivation

Description

Testing

Uh oh!

jlowin commented Mar 6, 2026

Uh oh!

marvin-context-protocol Bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fixed static analysis

Uh oh!

marvin-context-protocol Bot commented Mar 6, 2026

Test Failure Analysis

Failing check

Other checks

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

jlowin commented Mar 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

marvin-context-protocol Bot commented Mar 6, 2026 •

edited

Loading