Populate $defs with referenced schemas to produce valid JSON Schema

[asseti6]

Problem

The OpenAPI-to-MCP converter was generating invalid JSON Schema that caused MCP clients to fail with schema validation errors:

API Error: 400 - Invalid $ref in schema: '#/$defs/FilterExpression' does not exist. Ensure all $ref targets are defined in the schema's definitions or $defs.

This affected any MCP client that validates tool schemas against JSON Schema spec in some cases.

Root Cause

When converting OpenAPI schemas to JSON Schema, the converter:

1. Converted $ref paths from #/components/schemas/* → #/$defs/*
2. Left $defs empty with comments stating: // Omit this.convertComponentsToJsonSchema() to reduce definition size

This created dangling references—the $ref pointers existed but their targets didn't.

The issue occurred in two code paths in src/openapi/parser.ts:

• When resolveRefs=false (explicit non-resolution)
• When ref resolution fails (cyclic references, missing schemas)

Both paths emitted $ref: "#/$defs/*" but never populated $defs.

Solution

Track which schemas are actually referenced during conversion, then populate $defs with only those schemas. This maintains the original size optimization goal while producing valid JSON Schema.

Worth Noting

• Maintains size optimization (only referenced schemas included, not all components)
• No breaking changes to public API

[asseti6]

@jmetrikat I saw the update mentioned in #21 (comment). Looks like that does resolve the issue, but returns an empty {} on def type. I'll leave this up in case you want a proper definition returned without compromising schema minimization. Thanks for the awesome package!