mnehmos.trace.mcp 1.0.0

package/dist/adapters/openapi/parser.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 🔗 OpenAPI Ref Parser
+ * Parses and builds SchemaRef ID strings for the OpenAPI adapter
+ *
+ * The OpenAPI adapter uses structured reference IDs to identify
+ * specific parts of an OpenAPI specification. This module provides
+ * utilities to parse these IDs and reconstruct them from components.
+ *
+ * @module adapters/openapi/parser
+ */
+/**
+ * Parsed components of an OpenAPI reference ID.
+ *
+ * Reference IDs encode the type, location, and spec path:
+ * - `file` - Entire spec file
+ * - `endpoint` - Full endpoint (request + responses)
+ * - `request` - Request body schema only
+ * - `response` - Specific response by status code
+ * - `schema` - Named component schema
+ */
+export interface OpenAPIRef {
+    /** The type of reference being accessed */
+    type: 'file' | 'endpoint' | 'request' | 'response' | 'schema';
+    /** HTTP method (GET, POST, etc.) - for endpoint/request/response types */
+    method?: string;
+    /** API path (e.g., /users/{id}) - for endpoint/request/response types */
+    path?: string;
+    /** Response status code (e.g., 200, 404) - for response type only */
+    statusCode?: string;
+    /** Component schema name - for schema type only */
+    schemaName?: string;
+    /** Path to the OpenAPI specification file */
+    specPath: string;
+}
+/**
+ * Parse an OpenAPI SchemaRef ID string into its components.
+ *
+ * ID formats by type:
+ * - `endpoint:METHOD:/path@specPath` - Full endpoint
+ * - `request:METHOD:/path@specPath` - Request body only
+ * - `response:METHOD:/path:statusCode@specPath` - Specific response
+ * - `schema:SchemaName@specPath` - Component schema
+ * - `file:specPath` - Entire spec file
+ *
+ * @param refId - The reference ID string to parse
+ * @returns Parsed reference object, or null if the ID is invalid
+ *
+ * @example
+ * ```typescript
+ * // Parse an endpoint reference
+ * const ref = parseOpenAPIRef('endpoint:GET:/users/{id}@./api.yaml');
+ * // { type: 'endpoint', method: 'GET', path: '/users/{id}', specPath: './api.yaml' }
+ *
+ * // Parse a response reference
+ * const ref = parseOpenAPIRef('response:POST:/users:201@./api.yaml');
+ * // { type: 'response', method: 'POST', path: '/users', statusCode: '201', specPath: './api.yaml' }
+ *
+ * // Parse a component schema reference
+ * const ref = parseOpenAPIRef('schema:User@./api.yaml');
+ * // { type: 'schema', schemaName: 'User', specPath: './api.yaml' }
+ * ```
+ */
+export declare function parseOpenAPIRef(refId: string): OpenAPIRef | null;
+/**
+ * Build an OpenAPI SchemaRef ID string from its components.
+ *
+ * This is the inverse of `parseOpenAPIRef` - it takes parsed
+ * components and constructs a valid reference ID string.
+ *
+ * @param ref - The OpenAPIRef components to encode
+ * @returns The formatted ID string
+ * @throws {Error} If the ref type is unknown
+ *
+ * @example
+ * ```typescript
+ * // Build an endpoint reference
+ * const id = buildOpenAPIRefId({
+ *   type: 'endpoint',
+ *   method: 'GET',
+ *   path: '/users/{id}',
+ *   specPath: './api.yaml'
+ * });
+ * // 'endpoint:GET:/users/{id}@./api.yaml'
+ *
+ * // Build a schema reference
+ * const id = buildOpenAPIRefId({
+ *   type: 'schema',
+ *   schemaName: 'User',
+ *   specPath: './api.yaml'
+ * });
+ * // 'schema:User@./api.yaml'
+ * ```
+ */
+export declare function buildOpenAPIRefId(ref: OpenAPIRef): string;
+//# sourceMappingURL=parser.d.ts.map

package/dist/adapters/openapi/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/adapters/openapi/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IAE9D,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAmGhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAoBzD"}

package/dist/adapters/openapi/parser.js

@@ -0,0 +1,171 @@
+/**
+ * 🔗 OpenAPI Ref Parser
+ * Parses and builds SchemaRef ID strings for the OpenAPI adapter
+ *
+ * The OpenAPI adapter uses structured reference IDs to identify
+ * specific parts of an OpenAPI specification. This module provides
+ * utilities to parse these IDs and reconstruct them from components.
+ *
+ * @module adapters/openapi/parser
+ */
+/** Valid reference type identifiers */
+const VALID_TYPES = ['file', 'endpoint', 'request', 'response', 'schema'];
+/**
+ * Parse an OpenAPI SchemaRef ID string into its components.
+ *
+ * ID formats by type:
+ * - `endpoint:METHOD:/path@specPath` - Full endpoint
+ * - `request:METHOD:/path@specPath` - Request body only
+ * - `response:METHOD:/path:statusCode@specPath` - Specific response
+ * - `schema:SchemaName@specPath` - Component schema
+ * - `file:specPath` - Entire spec file
+ *
+ * @param refId - The reference ID string to parse
+ * @returns Parsed reference object, or null if the ID is invalid
+ *
+ * @example
+ * ```typescript
+ * // Parse an endpoint reference
+ * const ref = parseOpenAPIRef('endpoint:GET:/users/{id}@./api.yaml');
+ * // { type: 'endpoint', method: 'GET', path: '/users/{id}', specPath: './api.yaml' }
+ *
+ * // Parse a response reference
+ * const ref = parseOpenAPIRef('response:POST:/users:201@./api.yaml');
+ * // { type: 'response', method: 'POST', path: '/users', statusCode: '201', specPath: './api.yaml' }
+ *
+ * // Parse a component schema reference
+ * const ref = parseOpenAPIRef('schema:User@./api.yaml');
+ * // { type: 'schema', schemaName: 'User', specPath: './api.yaml' }
+ * ```
+ */
+export function parseOpenAPIRef(refId) {
+    if (!refId || refId.length === 0) {
+        return null;
+    }
+    // Find the @ separator (last occurrence for spec path)
+    const atIndex = refId.lastIndexOf('@');
+    // Find the first colon (type separator)
+    const colonIndex = refId.indexOf(':');
+    if (colonIndex === -1) {
+        return null;
+    }
+    const type = refId.slice(0, colonIndex);
+    if (!VALID_TYPES.includes(type)) {
+        return null;
+    }
+    // Handle file type specially (format: file:path)
+    if (type === 'file') {
+        const specPath = refId.slice(colonIndex + 1);
+        if (!specPath) {
+            return null;
+        }
+        return { type: 'file', specPath };
+    }
+    // All other types require @ separator for spec path
+    if (atIndex === -1) {
+        return null;
+    }
+    const specPath = refId.slice(atIndex + 1);
+    const identifier = refId.slice(colonIndex + 1, atIndex);
+    if (!specPath) {
+        return null;
+    }
+    switch (type) {
+        case 'schema': {
+            // Format: schema:SchemaName@specPath
+            return {
+                type: 'schema',
+                schemaName: identifier,
+                specPath,
+            };
+        }
+        case 'endpoint':
+        case 'request': {
+            // Format: type:METHOD:/path@specPath
+            const methodEnd = identifier.indexOf(':');
+            if (methodEnd === -1) {
+                return null;
+            }
+            const method = identifier.slice(0, methodEnd);
+            const path = decodeURIComponent(identifier.slice(methodEnd + 1));
+            return {
+                type,
+                method,
+                path,
+                specPath,
+            };
+        }
+        case 'response': {
+            // Format: response:METHOD:/path:statusCode@specPath
+            const methodEnd = identifier.indexOf(':');
+            if (methodEnd === -1) {
+                return null;
+            }
+            const method = identifier.slice(0, methodEnd);
+            const restPart = identifier.slice(methodEnd + 1);
+            // Find the last colon for status code
+            const lastColon = restPart.lastIndexOf(':');
+            if (lastColon === -1) {
+                return null;
+            }
+            const path = decodeURIComponent(restPart.slice(0, lastColon));
+            const statusCode = restPart.slice(lastColon + 1);
+            return {
+                type: 'response',
+                method,
+                path,
+                statusCode,
+                specPath,
+            };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Build an OpenAPI SchemaRef ID string from its components.
+ *
+ * This is the inverse of `parseOpenAPIRef` - it takes parsed
+ * components and constructs a valid reference ID string.
+ *
+ * @param ref - The OpenAPIRef components to encode
+ * @returns The formatted ID string
+ * @throws {Error} If the ref type is unknown
+ *
+ * @example
+ * ```typescript
+ * // Build an endpoint reference
+ * const id = buildOpenAPIRefId({
+ *   type: 'endpoint',
+ *   method: 'GET',
+ *   path: '/users/{id}',
+ *   specPath: './api.yaml'
+ * });
+ * // 'endpoint:GET:/users/{id}@./api.yaml'
+ *
+ * // Build a schema reference
+ * const id = buildOpenAPIRefId({
+ *   type: 'schema',
+ *   schemaName: 'User',
+ *   specPath: './api.yaml'
+ * });
+ * // 'schema:User@./api.yaml'
+ * ```
+ */
+export function buildOpenAPIRefId(ref) {
+    const { type, method, path, statusCode, schemaName, specPath } = ref;
+    switch (type) {
+        case 'file':
+            return `file:${specPath}`;
+        case 'schema':
+            return `schema:${schemaName}@${specPath}`;
+        case 'endpoint':
+        case 'request':
+            return `${type}:${method}:${path}@${specPath}`;
+        case 'response':
+            return `response:${method}:${path}:${statusCode}@${specPath}`;
+        default:
+            throw new Error(`Unknown OpenAPI ref type: ${type}`);
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/adapters/openapi/parser.js.map

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

package/dist/adapters/registry.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 📦 Adapter Registry
+ * Central registry for managing schema adapters with validation and lookup
+ *
+ * @module adapters/registry
+ */
+import type { SchemaAdapter, SchemaRef, NormalizedSchema, SchemaSourceKind } from '../core/types.js';
+/**
+ * Register a schema adapter.
+ *
+ * The adapter is validated before registration. If an adapter for
+ * the same kind already exists, it is replaced (last-wins semantics).
+ *
+ * @param adapter - The schema adapter to register
+ * @throws {AdapterValidationError} If the adapter is invalid
+ *
+ * @example
+ * ```typescript
+ * registerAdapter(new MCPAdapter());
+ * ```
+ */
+export declare function registerAdapter(adapter: SchemaAdapter): void;
+/**
+ * Get a registered adapter by kind.
+ *
+ * @param kind - The schema source kind to look up
+ * @returns The registered adapter
+ * @throws {AdapterNotFoundError} If no adapter is registered for the kind
+ *
+ * @example
+ * ```typescript
+ * const adapter = getAdapter('mcp');
+ * ```
+ */
+export declare function getAdapter(kind: SchemaSourceKind): SchemaAdapter;
+/**
+ * Check if an adapter is registered for a kind.
+ *
+ * @param kind - The schema source kind to check
+ * @returns True if an adapter is registered
+ *
+ * @example
+ * ```typescript
+ * if (hasAdapter('mcp')) {
+ *   console.log('MCP adapter available');
+ * }
+ * ```
+ */
+export declare function hasAdapter(kind: SchemaSourceKind): boolean;
+/**
+ * List all registered adapter kinds.
+ *
+ * @returns Array of registered schema source kinds
+ *
+ * @example
+ * ```typescript
+ * const kinds = listAdapters();
+ * console.log('Available:', kinds.join(', '));
+ * ```
+ */
+export declare function listAdapters(): SchemaSourceKind[];
+/**
+ * Get an adapter that supports a given schema ref.
+ *
+ * @param ref - The schema reference to find an adapter for
+ * @returns The adapter that supports the ref
+ * @throws {AdapterNotFoundError} If no adapter supports the ref
+ *
+ * @example
+ * ```typescript
+ * const ref: SchemaRef = { source: 'mcp', id: 'tool:get_weather' };
+ * const adapter = getAdapterForRef(ref);
+ * ```
+ */
+export declare function getAdapterForRef(ref: SchemaRef): SchemaAdapter;
+/**
+ * Extract a schema using the appropriate adapter.
+ *
+ * Automatically selects the adapter based on the ref's source kind
+ * and delegates extraction to that adapter.
+ *
+ * @param ref - The schema reference to extract
+ * @returns Promise resolving to the normalized schema
+ * @throws {AdapterNotFoundError} If no adapter supports the ref
+ *
+ * @example
+ * ```typescript
+ * const schema = await extractSchema({
+ *   source: 'mcp',
+ *   id: 'tool:get_weather'
+ * });
+ * ```
+ */
+export declare function extractSchema(ref: SchemaRef): Promise<NormalizedSchema>;
+/**
+ * List available schemas using the appropriate adapter.
+ *
+ * Not all adapters support listing. This function throws if
+ * the adapter doesn't implement the list() method.
+ *
+ * @param kind - The schema source kind
+ * @param basePath - Base path to search for schemas
+ * @returns Promise resolving to array of schema refs
+ * @throws {AdapterNotFoundError} If no adapter is registered for the kind
+ * @throws {Error} If the adapter doesn't support listing
+ *
+ * @example
+ * ```typescript
+ * const refs = await listSchemas('mcp', './src');
+ * for (const ref of refs) {
+ *   console.log(`Found: ${ref.id}`);
+ * }
+ * ```
+ */
+export declare function listSchemas(kind: SchemaSourceKind, basePath: string): Promise<SchemaRef[]>;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/adapters/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AA4HrG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAE5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa,CAEhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,gBAAgB,EAAE,CAEjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,aAAa,CAE9D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQ7E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAYhG"}

package/dist/adapters/registry.js

@@ -0,0 +1,246 @@
+/**
+ * 📦 Adapter Registry
+ * Central registry for managing schema adapters with validation and lookup
+ *
+ * @module adapters/registry
+ */
+import { AdapterNotFoundError, AdapterValidationError } from './errors.js';
+/**
+ * Internal registry class that manages schema adapters.
+ *
+ * Provides validated registration, lookup by kind, and ref-based
+ * adapter resolution. Uses last-wins semantics for replacement.
+ */
+class AdapterRegistry {
+    adapters = new Map();
+    /**
+     * Register an adapter with validation.
+     *
+     * Validates the adapter interface before registration.
+     * If an adapter for the same kind exists, it is replaced (last-wins).
+     *
+     * @param adapter - The schema adapter to register
+     * @throws {AdapterValidationError} If the adapter is missing required properties
+     */
+    register(adapter) {
+        this.validateAdapter(adapter);
+        if (this.adapters.has(adapter.kind) && process.env.DEBUG_TRACE_MCP) {
+            console.error(`[AdapterRegistry] Overwriting adapter for kind: ${adapter.kind}`);
+        }
+        this.adapters.set(adapter.kind, adapter);
+        if (process.env.DEBUG_TRACE_MCP) {
+            console.error(`[AdapterRegistry] Registered adapter: ${adapter.kind}`);
+        }
+    }
+    /**
+     * Get an adapter by its kind.
+     *
+     * @param kind - The schema source kind to look up
+     * @returns The registered adapter for the kind
+     * @throws {AdapterNotFoundError} If no adapter is registered for the kind
+     */
+    get(kind) {
+        const adapter = this.adapters.get(kind);
+        if (!adapter) {
+            throw new AdapterNotFoundError(kind, this.list());
+        }
+        return adapter;
+    }
+    /**
+     * Check if an adapter is registered for a kind.
+     *
+     * @param kind - The schema source kind to check
+     * @returns True if an adapter is registered
+     */
+    has(kind) {
+        return this.adapters.has(kind);
+    }
+    /**
+     * List all registered adapter kinds.
+     *
+     * @returns Array of registered schema source kinds
+     */
+    list() {
+        return Array.from(this.adapters.keys());
+    }
+    /**
+     * Get an adapter that supports a given schema ref.
+     *
+     * Looks up the adapter by the ref's source kind and verifies
+     * that the adapter supports the specific ref.
+     *
+     * @param ref - The schema reference to find an adapter for
+     * @returns The adapter that supports the ref
+     * @throws {AdapterNotFoundError} If no adapter supports the ref
+     */
+    getForRef(ref) {
+        const adapter = this.adapters.get(ref.source);
+        if (adapter && adapter.supports(ref)) {
+            return adapter;
+        }
+        throw new AdapterNotFoundError(ref.source, this.list());
+    }
+    /**
+     * Validate adapter before registration.
+     *
+     * Ensures the adapter has all required properties and methods:
+     * - kind: string identifier
+     * - supports(): function to check ref compatibility
+     * - extract(): function to extract schemas
+     * - list() (optional): function to list available refs
+     *
+     * @param adapter - The adapter to validate
+     * @throws {AdapterValidationError} If validation fails
+     */
+    validateAdapter(adapter) {
+        const partial = adapter;
+        if (!partial.kind || typeof partial.kind !== 'string') {
+            throw new AdapterValidationError(partial, 'kind is required and must be a string');
+        }
+        if (typeof partial.supports !== 'function') {
+            throw new AdapterValidationError(partial, 'supports() must be a function');
+        }
+        if (typeof partial.extract !== 'function') {
+            throw new AdapterValidationError(partial, 'extract() must be a function');
+        }
+        if (partial.list !== undefined && typeof partial.list !== 'function') {
+            throw new AdapterValidationError(partial, 'list() must be a function if defined');
+        }
+    }
+}
+// Singleton instance
+const registry = new AdapterRegistry();
+/**
+ * Register a schema adapter.
+ *
+ * The adapter is validated before registration. If an adapter for
+ * the same kind already exists, it is replaced (last-wins semantics).
+ *
+ * @param adapter - The schema adapter to register
+ * @throws {AdapterValidationError} If the adapter is invalid
+ *
+ * @example
+ * ```typescript
+ * registerAdapter(new MCPAdapter());
+ * ```
+ */
+export function registerAdapter(adapter) {
+    registry.register(adapter);
+}
+/**
+ * Get a registered adapter by kind.
+ *
+ * @param kind - The schema source kind to look up
+ * @returns The registered adapter
+ * @throws {AdapterNotFoundError} If no adapter is registered for the kind
+ *
+ * @example
+ * ```typescript
+ * const adapter = getAdapter('mcp');
+ * ```
+ */
+export function getAdapter(kind) {
+    return registry.get(kind);
+}
+/**
+ * Check if an adapter is registered for a kind.
+ *
+ * @param kind - The schema source kind to check
+ * @returns True if an adapter is registered
+ *
+ * @example
+ * ```typescript
+ * if (hasAdapter('mcp')) {
+ *   console.log('MCP adapter available');
+ * }
+ * ```
+ */
+export function hasAdapter(kind) {
+    return registry.has(kind);
+}
+/**
+ * List all registered adapter kinds.
+ *
+ * @returns Array of registered schema source kinds
+ *
+ * @example
+ * ```typescript
+ * const kinds = listAdapters();
+ * console.log('Available:', kinds.join(', '));
+ * ```
+ */
+export function listAdapters() {
+    return registry.list();
+}
+/**
+ * Get an adapter that supports a given schema ref.
+ *
+ * @param ref - The schema reference to find an adapter for
+ * @returns The adapter that supports the ref
+ * @throws {AdapterNotFoundError} If no adapter supports the ref
+ *
+ * @example
+ * ```typescript
+ * const ref: SchemaRef = { source: 'mcp', id: 'tool:get_weather' };
+ * const adapter = getAdapterForRef(ref);
+ * ```
+ */
+export function getAdapterForRef(ref) {
+    return registry.getForRef(ref);
+}
+/**
+ * Extract a schema using the appropriate adapter.
+ *
+ * Automatically selects the adapter based on the ref's source kind
+ * and delegates extraction to that adapter.
+ *
+ * @param ref - The schema reference to extract
+ * @returns Promise resolving to the normalized schema
+ * @throws {AdapterNotFoundError} If no adapter supports the ref
+ *
+ * @example
+ * ```typescript
+ * const schema = await extractSchema({
+ *   source: 'mcp',
+ *   id: 'tool:get_weather'
+ * });
+ * ```
+ */
+export async function extractSchema(ref) {
+    const adapter = getAdapterForRef(ref);
+    if (process.env.DEBUG_TRACE_MCP) {
+        console.error(`[AdapterRegistry] Extracting schema: ${ref.id} via ${adapter.kind}`);
+    }
+    return adapter.extract(ref);
+}
+/**
+ * List available schemas using the appropriate adapter.
+ *
+ * Not all adapters support listing. This function throws if
+ * the adapter doesn't implement the list() method.
+ *
+ * @param kind - The schema source kind
+ * @param basePath - Base path to search for schemas
+ * @returns Promise resolving to array of schema refs
+ * @throws {AdapterNotFoundError} If no adapter is registered for the kind
+ * @throws {Error} If the adapter doesn't support listing
+ *
+ * @example
+ * ```typescript
+ * const refs = await listSchemas('mcp', './src');
+ * for (const ref of refs) {
+ *   console.log(`Found: ${ref.id}`);
+ * }
+ * ```
+ */
+export async function listSchemas(kind, basePath) {
+    const adapter = getAdapter(kind);
+    if (!adapter.list) {
+        throw new Error(`Adapter for kind "${kind}" does not support list() method`);
+    }
+    if (process.env.DEBUG_TRACE_MCP) {
+        console.error(`[AdapterRegistry] Listing schemas via ${kind} in ${basePath}`);
+    }
+    return adapter.list(basePath);
+}
+//# sourceMappingURL=registry.js.map

package/dist/adapters/registry.js.map

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