JSON Schema $defs resolution fails with FastMCP servers (e.g., basic-memory)

[johnlindquist]

Description

When attempting to use code-mode with MCP servers built on FastMCP 2.0 (like basic-memory), tool discovery fails due to JSON Schema $defs references not being resolved.

Error

[McpCommunicationProtocol Error] MCP operation on 'basic-memory:stdio' failed: can't resolve reference #/$defs/ContextResult from id #
MissingRefError: can't resolve reference #/$defs/ContextResult from id #
    at Object.code (...node_modules/ajv/dist/vocabularies/core/ref.js:21:19)

Environment

• @utcp/code-mode-mcp: latest (1.0.9)
• basic-memory: 0.15.2 (uses FastMCP 2.12.4)
• MCP SDK: 1.17.0

Configuration

{
  "manual_call_templates": [
    {
      "name": "memory",
      "call_template_type": "mcp",
      "config": {
        "mcpServers": {
          "basic-memory": {
            "transport": "stdio",
            "command": "uvx",
            "args": ["basic-memory", "mcp", "--project", "memory"]
          }
        }
      }
    }
  ]
}

Root Cause

FastMCP 2.0 generates tool schemas that use $defs references (JSON Schema draft-2020-12 feature). The AJV validator in code-mode appears to not have these references pre-registered, causing the MissingRefError.

This is related to the broader MCP ecosystem issue: modelcontextprotocol/typescript-sdk#745

Potential Solutions

1. Configure AJV to handle $defs by pre-loading them before validation
2. Use a JSON Schema dereferencer to inline $defs before validation
3. Skip schema validation for MCP tools (trust the MCP server)

Workaround

Currently, there's no workaround - code-mode cannot be used with FastMCP-based MCP servers that use $defs in their schemas.

[edujuan]

Made e PR here: universal-tool-calling-protocol/typescript-utcp#12

@h3xxit pls tell me if PR is good and close

[h3xxit]

I merged it and it should now be fixed. If you still encounter problems, please reopen