fix: update changeset for graceful degradation, document boolean schema limitation

Author: gogakoreli

.changeset/inline-ref-in-tool-schema.md

@@ -2,4 +2,4 @@
 '@modelcontextprotocol/core': patch
 ---
 
-Inline local `$ref` pointers in tool `inputSchema` so schemas are self-contained and LLM-consumable. LLMs cannot resolve JSON Schema `$ref` — they serialize referenced parameters as strings instead of objects. Recursive schemas now throw at `tools/list` time instead of silently degrading.
+Inline local `$ref` pointers in tool `inputSchema` so schemas are self-contained and LLM-consumable. LLMs cannot resolve JSON Schema `$ref` — they serialize referenced parameters as strings instead of objects. Recursive schemas are handled gracefully — cyclic `$ref` pointers are left in place with only their `$defs` entries preserved, while all non-cyclic refs are fully inlined.

packages/core/src/util/schema.ts

@@ -101,7 +101,10 @@ export function dereferenceLocalRefs(schema: Record<string, unknown>): Record<st
                 resolvedDefs.set(defName, resolved);
             }
 
-            // Merge sibling keywords onto the resolved definition
+            // Merge sibling keywords onto the resolved definition.
+            // Note: boolean JSON Schemas (true/false) skip this merge — siblings are dropped.
+            // This is acceptable: the SDK's JsonSchemaType excludes boolean schemas by design,
+            // and no schema library (Zod v4, ArkType, Valibot) produces boolean $defs entries.
             if (hasSiblings && resolved !== null && typeof resolved === 'object' && !Array.isArray(resolved)) {
                 const resolvedSiblings = Object.fromEntries(Object.entries(siblings).map(([k, v]) => [k, inlineRefs(v, stack)]));
                 return { ...(resolved as Record<string, unknown>), ...resolvedSiblings };

packages/core/test/schema.test.ts

@@ -269,6 +269,25 @@ describe('dereferenceLocalRefs', () => {
         });
     });
 
+    test('boolean $defs entry resolves without sibling merge (SDK excludes boolean schemas by design)', () => {
+        // JSON Schema allows boolean schemas (true = accept all, false = reject all) in $defs.
+        // When a $ref resolves to a boolean, sibling keywords (description, title, etc.) are
+        // dropped because the merge guard requires an object. This test documents that behavior.
+        // No schema library produces boolean $defs — Zod: z.any() → {}, z.never() → {not:{}},
+        // and the SDK's JsonSchemaType explicitly excludes boolean schemas (validators/types.ts).
+        const schema = {
+            type: 'object',
+            properties: {
+                x: { $ref: '#/$defs/AlwaysValid', description: 'Any value' }
+            },
+            $defs: { AlwaysValid: true }
+        };
+        expect(dereferenceLocalRefs(schema)).toEqual({
+            type: 'object',
+            properties: { x: true }
+        });
+    });
+
     test('$ref inlined from real $defs while properties named "$defs" and "definitions" are preserved', () => {
         const schema = {
             type: 'object',