@feniix/bridgekit 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to `@feniix/bridgekit` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.4] - 2026-05-27
+
+### Fixed
+
+- `isObjectSchema` now short-circuits on `$ref` before checking
+  `type === "object"`, closing a hole where a hybrid `{type: "object", $ref:
+  "..."}` schema would bypass the construction-time `$ref` rejection
+  introduced in 0.9.3. The hybrid shape is not produced by TypeBox today;
+  the fix guards against future schema producers (including hand-crafted
+  JSON Schema). Existing `Type.Object` (no `$ref`), `Type.Cyclic` (`$ref`
+  without `type`), and `Type.Intersect` (`allOf` at root, no `$ref`)
+  behavior is unchanged. Resolves [#51](https://github.com/feniix/bridgekit/issues/51).
+
+## [0.9.3] - 2026-05-27
+
+### Fixed
+
+- `createMcpServer` construction errors now recognize top-level `$ref` /
+  `Type.Cyclic` / `Type.Recursive` schemas as a distinct rejection class with
+  `$ref`-specific guidance (inline the referenced shape or split recursive
+  shapes into multiple non-recursive tools), instead of falling through to
+  the misdirecting "wrap with `Type.Object`" recipe. New stable error code
+  `BRIDGEKIT_MCP_REF_PARAMETERS` for consumer branching. Existing
+  `BRIDGEKIT_MCP_NON_OBJECT_PARAMETERS` and `BRIDGEKIT_MCP_DUPLICATE_TOOL_NAME`
+  codes are unchanged. Resolves [#44](https://github.com/feniix/bridgekit/issues/44).
+
 ## [0.9.2] - 2026-05-26
 
 ### Fixed

package/dist/src/adapters/mcp.js

@@ -24,6 +24,12 @@ function isObjectSchema(schema) {
     if (typeof schema !== "object" || schema === null)
         return false;
     const candidate = schema;
+    // $ref takes structural precedence: a hybrid {type: "object", $ref: "..."}
+    // is not an inlined object schema — it's a reference, and
+    // assertObjectShapedParameters owns the rejection recipe. Return false so
+    // the $ref branch runs.
+    if (typeof candidate.$ref === "string")
+        return false;
     if (candidate.type === "object")
         return true;
     if (Array.isArray(candidate.allOf) && candidate.allOf.length > 0) {
@@ -37,11 +43,19 @@ function isObjectSchema(schema) {
  * branches and surface the first non-object branch by index — a bare `"allOf"`
  * label is misleading because the rejection is owned by one specific branch,
  * not the composition itself.
+ *
+ * The `$ref` check is first because `Type.Cyclic` produces
+ * `{ $defs: {...}, $ref: "..." }` at the root; the `$ref` is the load-bearing
+ * structural signal regardless of what else is set, and the recipe for that
+ * shape (inline or split) is different from the generic `Type.Object(...)`
+ * wrap recipe.
  */
 function schemaTypeLabel(schema) {
     if (typeof schema !== "object" || schema === null)
         return "unknown";
     const candidate = schema;
+    if (typeof candidate.$ref === "string")
+        return "$ref";
     if (typeof candidate.type === "string")
         return candidate.type;
     if (Array.isArray(candidate.anyOf))
@@ -83,6 +97,7 @@ function toInputSchema(parameters) {
  * recipe-shaped and may evolve; the code is part of the public contract).
  */
 const ERROR_CODE_NON_OBJECT_PARAMETERS = "BRIDGEKIT_MCP_NON_OBJECT_PARAMETERS";
+const ERROR_CODE_REF_PARAMETERS = "BRIDGEKIT_MCP_REF_PARAMETERS";
 const ERROR_CODE_DUPLICATE_TOOL_NAME = "BRIDGEKIT_MCP_DUPLICATE_TOOL_NAME";
 function throwWithCode(message, code) {
     const error = new Error(message);
@@ -93,6 +108,19 @@ function assertObjectShapedParameters(tools) {
     for (const tool of tools) {
         if (!isObjectSchema(tool.parameters)) {
             const typeLabel = schemaTypeLabel(tool.parameters);
+            // Top-level $ref (TypeBox's `Type.Cyclic` lowering, or a bare `Type.Ref`)
+            // gets its own branch and code. The generic "wrap with Type.Object(...)"
+            // recipe is the wrong fix for a recursive schema — the user wants to
+            // express recursion, not wrap a primitive — so a $ref shape needs
+            // $ref-specific guidance (inline or split) before the generic branch
+            // can run.
+            if (typeLabel === "$ref") {
+                throwWithCode(`createMcpServer: tool "${tool.name}" has a top-level $ref schema (type="$ref"). ` +
+                    "Top-level $ref / Type.Cyclic schemas are not currently supported by the MCP wire layer " +
+                    "because tools/list ships inputSchema by value and the SDK client does not resolve $refs. " +
+                    "Inline the referenced schema (wrap the target shape directly with Type.Object(...)) " +
+                    "or split recursive shapes into multiple non-recursive tools.", ERROR_CODE_REF_PARAMETERS);
+            }
             let message = `createMcpServer: tool "${tool.name}" has a non-object parameters schema (type="${typeLabel}"). ` +
                 "MCP requires Type.Object(...) at the top level; use Type.Object({ value: Type.String() }) " +
                 "to wrap a single-field schema, or Type.Intersect([Type.Object(...), Type.Object(...)]) for " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",