Test Failure Analysis

Summary: The integration test test_github_api_schema_performance timed out (>10s) — not during OpenAPI parsing (which completed in 3.46s), but during the subsequent await mcp_server.list_tools() call, which triggers the DereferenceRefsMiddleware introduced in commit 35bbf48.

Root Cause: The DereferenceRefsMiddleware calls dereference_refs(tool.output_schema) for every tool on each list_tools() call. For the GitHub API schema (500+ tools), each tool's output_schema contains $defs and $ref entries inherited from the OpenAPI component schemas. The jsonref.replace_refs function gets stuck in deeply recursive _walk_refs traversal across these complex schemas — repeated 500+ times — causing the total list_tools() call to blow past the 10s test timeout.

This failure is not caused by the PR changes (docs-only). It's a pre-existing regression introduced when the dereference middleware was added.

Suggested Solution: The dereferencing middleware is re-running expensive schema resolution on every list_tools() call with no caching. A few options:

1. Cache at the middleware level — memoize _dereference_tool by tool identity so repeated list_tools() calls don't redo work.
2. Pre-compute at tool creation — apply dereference_refs eagerly in the OpenAPI parser or tool builder, so the tool carries an already-resolved schema.
3. Fix the test — the test's 10s timeout was sized for parsing only. The list_tools() verification (line 65) should either move to a separate test without the tight timeout, or the timeout needs to account for dereferencing 500+ tools. Though this is the least desirable option since it would just paper over a real performance issue.

Option 1 or 2 is the right fix — list_tools() for a 500-tool server shouldn't require re-dereferencing every schema on every call.

tests/server/providers/openapi/test_openapi_performance.py:65: 
    tools = await mcp_server.list_tools()

src/fastmcp/server/middleware/dereference.py:30: in on_list_tools
    return [_dereference_tool(tool) for tool in tools]

src/fastmcp/server/middleware/dereference.py:52: in _dereference_tool
    updates["output_schema"] = dereference_refs(tool.output_schema)

src/fastmcp/utilities/json_schema.py:42: in dereference_refs
    dereferenced = replace_refs(schema, proxies=False, lazy_load=False)

# _walk_refs called 6+ levels deep, processing enormous _processed cache
E   Failed: Timeout (>10.0s) from pytest-timeout.

OpenAPI parsing took 3.46s

🤖 Generated with Claude Code