apcore-mcp 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/aipartnerup/apcore-mcp/main/apcore-mcp-logo.svg" alt="apcore-mcp logo" width="200"/>
+</div>
+
+# apcore-mcp
+
+Automatic MCP Server & OpenAI Tools Bridge for [apcore](https://github.com/aipartnerup/apcore).
+
+Converts apcore module registries into [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tool definitions and [OpenAI-compatible function calling](https://platform.openai.com/docs/guides/function-calling) formats — zero boilerplate required.
+
+## Features
+
+- **MCP Server** — Expose apcore modules as MCP tools over stdio, Streamable HTTP, or SSE
+- **OpenAI Tools** — Convert modules to OpenAI function calling format with strict mode support
+- **Schema Conversion** — Inline `$defs`/`$ref` from Pydantic-generated JSON Schema
+- **Annotation Mapping** — Map module annotations to MCP hints and OpenAI description suffixes
+- **Error Mapping** — Sanitize internal errors for safe client-facing responses
+- **Dynamic Registration** — Listen for registry changes and update tools at runtime
+- **CLI** — Launch an MCP server from the command line
+
+## Requirements
+
+- Node.js >= 18.0.0
+- apcore (peer dependency)
+
+## Installation
+
+```bash
+npm install apcore-mcp
+```
+
+## Quick Start
+
+### Programmatic API
+
+```typescript
+import { serve, toOpenaiTools } from "apcore-mcp";
+
+// Launch MCP server over stdio
+await serve(executor);
+
+// Launch over Streamable HTTP
+await serve(executor, {
+  transport: "streamable-http",
+  host: "127.0.0.1",
+  port: 8000,
+});
+
+// Export OpenAI tool definitions
+const tools = toOpenaiTools(registry, {
+  embedAnnotations: true,
+  strict: true,
+});
+```
+
+### CLI
+
+```bash
+# stdio (default)
+npx apcore-mcp --extensions-dir ./extensions
+
+# Streamable HTTP
+npx apcore-mcp --extensions-dir ./extensions --transport streamable-http --port 8000
+
+# SSE
+npx apcore-mcp --extensions-dir ./extensions --transport sse --port 8000
+```
+
+#### CLI Arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `--extensions-dir` | *(required)* | Path to apcore extensions directory |
+| `--transport` | `stdio` | `stdio`, `streamable-http`, or `sse` |
+| `--host` | `127.0.0.1` | Host for HTTP transports |
+| `--port` | `8000` | Port for HTTP transports (1-65535) |
+| `--name` | `apcore-mcp` | MCP server name |
+| `--version` | package version | MCP server version |
+| `--log-level` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+
+## API Reference
+
+### `serve(registryOrExecutor, options?)`
+
+Launch an MCP Server that exposes all apcore modules as tools.
+
+```typescript
+function serve(
+  registryOrExecutor: Registry | Executor,
+  options?: {
+    transport?: "stdio" | "streamable-http" | "sse";
+    host?: string;
+    port?: number;
+    name?: string;
+    version?: string;
+  }
+): Promise<void>;
+```
+
+### `toOpenaiTools(registryOrExecutor, options?)`
+
+Export apcore modules as OpenAI-compatible tool definitions.
+
+```typescript
+function toOpenaiTools(
+  registryOrExecutor: Registry | Executor,
+  options?: {
+    embedAnnotations?: boolean;
+    strict?: boolean;
+    tags?: string[];
+    prefix?: string;
+  }
+): OpenAIToolDef[];
+```
+
+**Options:**
+
+- `embedAnnotations` — Append annotation metadata to tool descriptions (default: `false`)
+- `strict` — Enable OpenAI strict mode: adds `additionalProperties: false`, makes all properties required, wraps optional properties with nullable (default: `false`)
+- `tags` — Filter modules by tags
+- `prefix` — Filter modules by ID prefix
+
+## Architecture
+
+```
+src/
+├── index.ts              # Public API: serve(), toOpenaiTools()
+├── cli.ts                # CLI entry point
+├── types.ts              # TypeScript interfaces
+├── adapters/
+│   ├── schema.ts         # JSON Schema $ref inlining
+│   ├── annotations.ts    # Module annotations -> MCP hints
+│   ├── errors.ts         # Error sanitization
+│   └── idNormalizer.ts   # Dot-notation <-> dash-notation
+├── converters/
+│   └── openai.ts         # OpenAI tool definition converter
+└── server/
+    ├── factory.ts        # MCP Server creation & handler registration
+    ├── router.ts         # Tool call execution routing
+    ├── transport.ts      # Transport lifecycle (stdio/HTTP/SSE)
+    └── listener.ts       # Dynamic registry event listener
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+```
+
+## Testing
+
+100 tests across 10 test suites with 96%+ line coverage:
+
+| Module | Coverage |
+|---|---|
+| annotations.ts | 100% |
+| idNormalizer.ts | 100% |
+| factory.ts | 100% |
+| router.ts | 100% |
+| errors.ts | 98.8% |
+| schema.ts | 97.0% |
+| openai.ts | 91.7% |
+| listener.ts | 89.7% |
+
+## License
+
+Apache-2.0

package/dist/adapters/annotations.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AnnotationMapper - Maps apcore module annotations to MCP tool annotations.
+ *
+ * Converts between apcore's annotation format and the MCP protocol's
+ * hint-based annotation system. Also provides description suffix generation
+ * and approval requirement checking.
+ */
+import type { ModuleAnnotations, McpAnnotationsDict } from "../types.js";
+export declare class AnnotationMapper {
+    /**
+     * Convert apcore module annotations to MCP annotations dict.
+     *
+     * Returns default values when annotations are null:
+     * - read_only_hint: false
+     * - destructive_hint: false
+     * - idempotent_hint: false
+     * - open_world_hint: true
+     * - title: null
+     */
+    toMcpAnnotations(annotations: ModuleAnnotations | null): McpAnnotationsDict;
+    /**
+     * Generate a description suffix string from annotations.
+     *
+     * Returns a formatted string like:
+     *   `\n\n[Annotations: readonly=true, destructive=false, ...]`
+     *
+     * Returns an empty string if annotations are null.
+     */
+    toDescriptionSuffix(annotations: ModuleAnnotations | null): string;
+    /**
+     * Check whether the annotations indicate the module requires approval.
+     *
+     * Returns false if annotations are null.
+     */
+    hasRequiresApproval(annotations: ModuleAnnotations | null): boolean;
+}
+//# sourceMappingURL=annotations.d.ts.map

package/dist/adapters/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEzE,qBAAa,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,kBAAkB;IAoB3E;;;;;;;OAOG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM;IAgBlE;;;;OAIG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO;CAOpE"}

package/dist/adapters/annotations.js

@@ -0,0 +1,70 @@
+/**
+ * AnnotationMapper - Maps apcore module annotations to MCP tool annotations.
+ *
+ * Converts between apcore's annotation format and the MCP protocol's
+ * hint-based annotation system. Also provides description suffix generation
+ * and approval requirement checking.
+ */
+export class AnnotationMapper {
+    /**
+     * Convert apcore module annotations to MCP annotations dict.
+     *
+     * Returns default values when annotations are null:
+     * - read_only_hint: false
+     * - destructive_hint: false
+     * - idempotent_hint: false
+     * - open_world_hint: true
+     * - title: null
+     */
+    toMcpAnnotations(annotations) {
+        if (annotations === null) {
+            return {
+                read_only_hint: false,
+                destructive_hint: false,
+                idempotent_hint: false,
+                open_world_hint: true,
+                title: null,
+            };
+        }
+        return {
+            read_only_hint: annotations.readonly,
+            destructive_hint: annotations.destructive,
+            idempotent_hint: annotations.idempotent,
+            open_world_hint: annotations.open_world,
+            title: null,
+        };
+    }
+    /**
+     * Generate a description suffix string from annotations.
+     *
+     * Returns a formatted string like:
+     *   `\n\n[Annotations: readonly=true, destructive=false, ...]`
+     *
+     * Returns an empty string if annotations are null.
+     */
+    toDescriptionSuffix(annotations) {
+        if (annotations === null) {
+            return "";
+        }
+        const parts = [
+            `readonly=${annotations.readonly}`,
+            `destructive=${annotations.destructive}`,
+            `idempotent=${annotations.idempotent}`,
+            `requires_approval=${annotations.requires_approval}`,
+            `open_world=${annotations.open_world}`,
+        ];
+        return `\n\n[Annotations: ${parts.join(", ")}]`;
+    }
+    /**
+     * Check whether the annotations indicate the module requires approval.
+     *
+     * Returns false if annotations are null.
+     */
+    hasRequiresApproval(annotations) {
+        if (annotations === null) {
+            return false;
+        }
+        return annotations.requires_approval;
+    }
+}
+//# sourceMappingURL=annotations.js.map

package/dist/adapters/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,OAAO,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAqC;QACpD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO;gBACL,cAAc,EAAE,KAAK;gBACrB,gBAAgB,EAAE,KAAK;gBACvB,eAAe,EAAE,KAAK;gBACtB,eAAe,EAAE,IAAI;gBACrB,KAAK,EAAE,IAAI;aACZ,CAAC;QACJ,CAAC;QAED,OAAO;YACL,cAAc,EAAE,WAAW,CAAC,QAAQ;YACpC,gBAAgB,EAAE,WAAW,CAAC,WAAW;YACzC,eAAe,EAAE,WAAW,CAAC,UAAU;YACvC,eAAe,EAAE,WAAW,CAAC,UAAU;YACvC,KAAK,EAAE,IAAI;SACZ,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,mBAAmB,CAAC,WAAqC;QACvD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,KAAK,GAAa;YACtB,YAAY,WAAW,CAAC,QAAQ,EAAE;YAClC,eAAe,WAAW,CAAC,WAAW,EAAE;YACxC,cAAc,WAAW,CAAC,UAAU,EAAE;YACtC,qBAAqB,WAAW,CAAC,iBAAiB,EAAE;YACpD,cAAc,WAAW,CAAC,UAAU,EAAE;SACvC,CAAC;QAEF,OAAO,qBAAqB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,WAAqC;QACvD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,WAAW,CAAC,iBAAiB,CAAC;IACvC,CAAC;CACF"}

package/dist/adapters/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ErrorMapper - Maps apcore errors to MCP-compatible error responses.
+ *
+ * Handles ModuleError instances with specific error codes, sanitizes
+ * internal error details, and formats schema validation errors with
+ * field-level detail.
+ */
+import type { McpErrorResponse } from "../types.js";
+export declare class ErrorMapper {
+    /**
+     * Convert an error to an MCP error response.
+     *
+     * Duck-types the error to check for ModuleError properties (code, message, details).
+     * Applies sanitization and formatting rules based on the error code.
+     */
+    toMcpError(error: unknown): McpErrorResponse;
+    /**
+     * Duck-type check for ModuleError-like objects.
+     *
+     * Checks for `code` (string), `message` (string), and `details` properties.
+     */
+    private _isModuleError;
+    /**
+     * Format a schema validation error message with field-level details.
+     *
+     * Extracts the `errors` array from details and formats each entry
+     * as "field: message" lines appended to the base message.
+     */
+    private _formatValidationError;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/adapters/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AASpD,qBAAa,WAAW;IACtB;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB;IAuD5C;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAetB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;CA4B/B"}

package/dist/adapters/errors.js

@@ -0,0 +1,113 @@
+/**
+ * ErrorMapper - Maps apcore errors to MCP-compatible error responses.
+ *
+ * Handles ModuleError instances with specific error codes, sanitizes
+ * internal error details, and formats schema validation errors with
+ * field-level detail.
+ */
+/** Internal error codes that should be sanitized to a generic message. */
+const INTERNAL_ERROR_CODES = new Set([
+    "CALL_DEPTH_EXCEEDED",
+    "CIRCULAR_CALL",
+    "CALL_FREQUENCY_EXCEEDED",
+]);
+export class ErrorMapper {
+    /**
+     * Convert an error to an MCP error response.
+     *
+     * Duck-types the error to check for ModuleError properties (code, message, details).
+     * Applies sanitization and formatting rules based on the error code.
+     */
+    toMcpError(error) {
+        // Duck-type check for ModuleError-like objects
+        if (this._isModuleError(error)) {
+            const code = error.code;
+            const details = error.details;
+            // Internal error codes -> generic message
+            if (INTERNAL_ERROR_CODES.has(code)) {
+                return {
+                    is_error: true,
+                    error_type: code,
+                    message: "Internal error occurred",
+                    details: null,
+                };
+            }
+            // ACL denied -> sanitized access denied
+            if (code === "ACL_DENIED") {
+                return {
+                    is_error: true,
+                    error_type: "ACL_DENIED",
+                    message: "Access denied",
+                    details: null,
+                };
+            }
+            // Schema validation error -> formatted with field-level details
+            if (code === "SCHEMA_VALIDATION_ERROR") {
+                const message = this._formatValidationError(details);
+                return {
+                    is_error: true,
+                    error_type: "SCHEMA_VALIDATION_ERROR",
+                    message,
+                    details,
+                };
+            }
+            // Other known ModuleError codes -> pass through
+            return {
+                is_error: true,
+                error_type: code,
+                message: error.message,
+                details,
+            };
+        }
+        // Unknown/unexpected exceptions -> generic error
+        return {
+            is_error: true,
+            error_type: "INTERNAL_ERROR",
+            message: "Internal error occurred",
+            details: null,
+        };
+    }
+    /**
+     * Duck-type check for ModuleError-like objects.
+     *
+     * Checks for `code` (string), `message` (string), and `details` properties.
+     */
+    _isModuleError(error) {
+        if (error === null || typeof error !== "object") {
+            return false;
+        }
+        const obj = error;
+        return (typeof obj["code"] === "string" &&
+            typeof obj["message"] === "string" &&
+            "details" in obj);
+    }
+    /**
+     * Format a schema validation error message with field-level details.
+     *
+     * Extracts the `errors` array from details and formats each entry
+     * as "field: message" lines appended to the base message.
+     */
+    _formatValidationError(details) {
+        const baseMessage = "Schema validation failed";
+        if (details === null) {
+            return baseMessage;
+        }
+        const errors = details["errors"];
+        if (!Array.isArray(errors) || errors.length === 0) {
+            return baseMessage;
+        }
+        const fieldErrors = errors
+            .map((err) => {
+            if (err !== null && typeof err === "object") {
+                const entry = err;
+                const field = entry["field"] ?? "unknown";
+                const message = entry["message"] ?? "validation error";
+                return `  ${String(field)}: ${String(message)}`;
+            }
+            return `  ${String(err)}`;
+        })
+            .join("\n");
+        return `${baseMessage}:\n${fieldErrors}`;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/adapters/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"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"}

package/dist/adapters/idNormalizer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ModuleIDNormalizer - Converts between apcore module IDs and MCP tool names.
+ *
+ * apcore uses dot-separated module IDs (e.g. "myorg.tools.search")
+ * while MCP tool names use hyphens (e.g. "myorg-tools-search").
+ */
+export declare class ModuleIDNormalizer {
+    /**
+     * Normalize an apcore module ID to an MCP-compatible tool name.
+     *
+     * Replaces dots (`.`) with hyphens (`-`).
+     */
+    normalize(moduleId: string): string;
+    /**
+     * Denormalize an MCP tool name back to an apcore module ID.
+     *
+     * Replaces hyphens (`-`) with dots (`.`).
+     */
+    denormalize(toolName: string): string;
+}
+//# sourceMappingURL=idNormalizer.d.ts.map

package/dist/adapters/idNormalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idNormalizer.d.ts","sourceRoot":"","sources":["../../src/adapters/idNormalizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qBAAa,kBAAkB;IAC7B;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAGtC"}

package/dist/adapters/idNormalizer.js

@@ -0,0 +1,25 @@
+/**
+ * ModuleIDNormalizer - Converts between apcore module IDs and MCP tool names.
+ *
+ * apcore uses dot-separated module IDs (e.g. "myorg.tools.search")
+ * while MCP tool names use hyphens (e.g. "myorg-tools-search").
+ */
+export class ModuleIDNormalizer {
+    /**
+     * Normalize an apcore module ID to an MCP-compatible tool name.
+     *
+     * Replaces dots (`.`) with hyphens (`-`).
+     */
+    normalize(moduleId) {
+        return moduleId.replaceAll(".", "-");
+    }
+    /**
+     * Denormalize an MCP tool name back to an apcore module ID.
+     *
+     * Replaces hyphens (`-`) with dots (`.`).
+     */
+    denormalize(toolName) {
+        return toolName.replaceAll("-", ".");
+    }
+}
+//# sourceMappingURL=idNormalizer.js.map

package/dist/adapters/idNormalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idNormalizer.js","sourceRoot":"","sources":["../../src/adapters/idNormalizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,OAAO,kBAAkB;IAC7B;;;;OAIG;IACH,SAAS,CAAC,QAAgB;QACxB,OAAO,QAAQ,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,QAAgB;QAC1B,OAAO,QAAQ,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/adapters/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Adapter classes for converting between apcore and MCP/OpenAI formats.
+ */
+export { SchemaConverter } from "./schema.js";
+export { AnnotationMapper } from "./annotations.js";
+export { ErrorMapper } from "./errors.js";
+export { ModuleIDNormalizer } from "./idNormalizer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,8 @@
+/**
+ * Adapter classes for converting between apcore and MCP/OpenAI formats.
+ */
+export { SchemaConverter } from "./schema.js";
+export { AnnotationMapper } from "./annotations.js";
+export { ErrorMapper } from "./errors.js";
+export { ModuleIDNormalizer } from "./idNormalizer.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/adapters/schema.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SchemaConverter - Converts apcore module schemas to MCP-compatible JSON Schema.
+ *
+ * Handles deep copying, inlining $ref references, and ensuring schemas
+ * have the required `type: "object"` for MCP tool input/output schemas.
+ */
+import type { JsonSchema, ModuleDescriptor } from "../types.js";
+export declare class SchemaConverter {
+    /**
+     * Convert a module descriptor's input_schema to an MCP-compatible schema.
+     */
+    convertInputSchema(descriptor: ModuleDescriptor): JsonSchema;
+    /**
+     * Convert a module descriptor's output_schema to an MCP-compatible schema.
+     */
+    convertOutputSchema(descriptor: ModuleDescriptor): JsonSchema;
+    /**
+     * Apply all schema transformations: deep copy, inline $ref, ensure object type.
+     */
+    _convertSchema(schema: JsonSchema): JsonSchema;
+    /**
+     * Recursively inline `$ref` references using the provided $defs map.
+     *
+     * Handles dicts (objects), arrays, and primitive values.
+     * Skips the `$defs` key itself during traversal.
+     */
+    _inlineRefs(node: unknown, defs: Record<string, JsonSchema>): unknown;
+    /**
+     * Resolve a `$ref` path (e.g. `#/$defs/MyType`) against the $defs map.
+     *
+     * Returns a deep copy of the resolved definition to avoid mutation.
+     * Throws Error if the ref format is invalid or the definition is not found.
+     */
+    _resolveRef(refPath: string, defs: Record<string, JsonSchema>): JsonSchema;
+    /**
+     * Ensure the schema has `type: "object"`.
+     *
+     * - Empty schema -> `{ type: "object", properties: {} }`
+     * - Schema without `type` -> adds `type: "object"`
+     */
+    _ensureObjectType(schema: JsonSchema): JsonSchema;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/adapters/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/adapters/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEhE,qBAAa,eAAe;IAC1B;;OAEG;IACH,kBAAkB,CAAC,UAAU,EAAE,gBAAgB,GAAG,UAAU;IAI5D;;OAEG;IACH,mBAAmB,CAAC,UAAU,EAAE,gBAAgB,GAAG,UAAU;IAI7D;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU;IAe9C;;;;;OAKG;IACH,WAAW,CACT,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAC/B,OAAO;IA8BV;;;;;OAKG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAC/B,UAAU;IAoBb;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU;CAclD"}