Fix: resolve complex OpenAPI reference chains with inline definitions

[shalarn1]

Background

FastMCP cannot resolve complex OpenApi reference chains (e.g., $ref → $defs → $ref) due to unreliable schema definition generation. See upstream issue: jlowin/fastmcp#1372. Related to #7.

Previously, complex $refs only appeared in output schemas (which we hide), so unresolved references weren't visible. Our customizer stripped $defs from tool schemas since they seemed unused.

However, the new PointInTimeMetrics tool has complex $refs in its input schema. With $defs stripped but references remaining, this causes "PointerToNowhere" errors since schema references can't resolve.

cortex-mcp is using a legacy OpenApi parser which will be deprecated. Supposedly the new parser will fix this issue but switching broke all existing tool registration in our setup (it will become the default though, so we will need figure that out eventually).

[09/25/25 09:43:36] INFO Using legacy OpenAPI parser. To use the new parser, set FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER=true. The new parser was introduced for testing in 2.11 and will become the default soon.

Solution

This PR adds openapi_resolver.py that recursively resolves all $ref chains by replacing them with inline schema definitions before FastMCP processing. This eliminates the need for $defs entirely and we can continue to drop it from the MCP tool schemas.

Result

• ✅ PointInTimeMetrics tool now works correctly
• ⚠️ Performance: Currently processes all ~800 OpenAPI endpoints, we only need it for the MCP-enabled endpoints (~20)