Fix $ref resolution in request schema properties before validation

[vincent0426]

Added $ref resolution for requestedSchema.properties before SDK validation. When incoming requests contain $ref references in their schema properties, they are automatically resolved before reaching the SDK's validation layer.

Before the fix

Error executing tool book_table: [
  {
    "code": "invalid_union",
    "unionErrors": [
      {
        "issues": [
          {
            "code": "invalid_literal",
            "expected": "boolean",
            "path": [
              "params",
              "requestedSchema",
              "properties",
              "fruit",
              "type"
            ],
            "message": "Invalid literal value, expected \"boolean\""
          },
          {
            "code": "invalid_type",
            "expected": "boolean",
            "received": "string",
            "path": [
              "params",
              "requestedSchema",
              "properties",
              "fruit",
              "default"
            ],
            "message": "Expected boolean, received string"
          }
        ],
        "name": "ZodError"
      },
      {
        "issues": [
          {
            "code": "invalid_literal",
            "expected": "string",
            "path": [
              "params",
              "requestedSchema",
              "properties",
              "fruit",
              "type"
            ],
            "message": "Invalid literal value, expected \"string\""
          }
        ],
        "name": "ZodError"
      },
      {
        "issues": [
          {
            "expected": "'number' | 'integer'",
            "received": "undefined",
            "code": "invalid_type",
            "path": [
              "params",
              "requestedSchema",
              "properties",
              "fruit",
              "type"
            ],
            "message": "Required"
          }
        ],
        "name": "ZodError"
      },
      {
        "issues": [
          {
            "code": "invalid_literal",
            "expected": "string",
            "path": [
              "params",
              "requestedSchema",
              "properties",
              "fruit",
              "type"
            ],
            "message": "Invalid literal value, expected \"string\""
          },
          {
            "code": "invalid_type",
            "expected": "array",
            "received": "undefined",
            "path": [
              "params",
              "requestedSchema",
              "properties",
              "fruit",
              "enum"
            ],
            "message": "Required"
          }
        ],
        "name": "ZodError"
      }
    ],
    "path": [
      "params",
      "requestedSchema",
      "properties",
      "fruit"
    ],
    "message": "Invalid input"
  }
]

After

Motivation and Context

While playing around with python enum elicitation requests, when MCP servers send elicitation requests (or any requests) with $ref references in requestedSchema.properties (e.g., { $ref: "#/properties/nameDef" }), the SDK attempts to validate these schemas before our handlers can process them. Unresolved $ref references can cause validation failures.

This change intercepts incoming messages at the transport level (before validation) and resolves all $ref references in requestedSchema.properties, ensuring the SDK receives fully resolved schemas that validate correctly.

How Has This Been Tested?

Added a new unit test:

• Creates a mock request with $ref in requestedSchema.properties
• Verifies the ref is resolved to actual schema values before reaching the protocol handler
• Confirms the resolved schema contains the expected values

Breaking Changes

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[cliffhall]

Hi @vincent0426 thanks for this, but we just merged a change #889 last week that addresses this specific issue.

[vincent0426]

Hi @cliffhall, thanks for the response, but I think they address different issues. This PR fixes request handling (e.g., schemas sent by elicitation), while #889 addresses tool rendering. I’m still seeing the error on the latest version which fails before the handler, during validation against ElicitRequestSchema.

inspector/client/src/lib/hooks/useConnection.ts

Line 759 in 9e6c9a2

client.setRequestHandler(ElicitRequestSchema, async (request) => {

[cliffhall]

Hoping we can avoid adding even more logic to useConnection by extracting the bulk of the change to schemaUtils.ts

[cliffhall]

Hoping we could extend this to cover refs in $defs

[cliffhall]

Could this also resolve $refs that point to $defs or definitions? Seems like a perfect place to do so.

[vincent0426]

I added a test resolves $ref references to $defs in requestedSchema to verify that resolveRef already handles this. I believe it uses a generic path that resolves defs as well.

[cliffhall]

That test seems to be failing at the moment. https://github.com/modelcontextprotocol/inspector/actions/runs/19337854835/job/55324774030?pr=902

[vincent0426]

ah yeah fixed

[cliffhall]

But is there a test that shows we can resolve $defs? Was this working before?

[vincent0426]

yes there is a test resolves $ref references to $defs in requestedSchema

...
$ref: "#/$defs/UserInput",
...