@supernal/interface 1.0.1 → 1.0.3

package/dist/esm/src/mcp/server.js

@@ -0,0 +1,276 @@
+/**
+ * Supernal MCP Server
+ *
+ * MCP (Model Context Protocol) server that exposes Supernal Interface tools
+ * to external AI agents like Claude Desktop, Cursor, and custom MCP clients.
+ *
+ * Usage:
+ * ```typescript
+ * import { createSupernalMCPServer } from '@supernal/interface';
+ *
+ * const server = createSupernalMCPServer({
+ *   name: 'my-app-tools',
+ *   version: '1.0.0'
+ * });
+ *
+ * await server.start();
+ * ```
+ */
+import { ToolRegistry } from '../background/registry/ToolRegistry.js';
+import { ToolExecutor } from '../ai/ToolExecutor.js';
+import { MCPErrorCode } from './types.js';
+/**
+ * Default server configuration
+ */
+const DEFAULT_CONFIG = {
+    name: 'supernal-interface',
+    version: '1.0.0',
+    description: 'MCP server for Supernal Interface tools',
+    capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {}
+    }
+};
+/**
+ * Supernal MCP Server implementation
+ */
+export class SupernalMCPServer {
+    constructor(config = {}) {
+        this.running = false;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.executor = new ToolExecutor();
+    }
+    /**
+     * Start the MCP server with given transport
+     */
+    async start(transport) {
+        if (this.running) {
+            throw new Error('Server is already running');
+        }
+        this.transport = transport;
+        this.running = true;
+        console.error(`[MCP Server] Starting: ${this.config.name} v${this.config.version}`);
+        // Message processing loop
+        while (this.running) {
+            try {
+                const request = await this.transport.receive();
+                const response = await this.handle(request);
+                // Only send response if not null (notifications return null)
+                if (response !== null) {
+                    await this.transport.send(response);
+                }
+            }
+            catch (error) {
+                if (!this.running)
+                    break; // Transport closed
+                console.error('[MCP Server] Error processing message:', error);
+                // Send error response
+                if (this.transport) {
+                    await this.transport.send({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: MCPErrorCode.INTERNAL_ERROR,
+                            message: error instanceof Error ? error.message : 'Internal server error',
+                            data: error
+                        }
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Stop the MCP server
+     */
+    async stop() {
+        this.running = false;
+        if (this.transport) {
+            await this.transport.close();
+            this.transport = undefined;
+        }
+        console.error('[MCP Server] Stopped');
+    }
+    /**
+     * Handle incoming MCP request
+     */
+    async handle(request) {
+        const { method, params, id } = request;
+        try {
+            // Handle notifications (no response needed)
+            if (method.startsWith('notifications/')) {
+                console.error(`[MCP Server] Received notification: ${method}`);
+                return null; // No response for notifications
+            }
+            switch (method) {
+                case 'tools/list':
+                    return this.handleToolsList(id);
+                case 'tools/call':
+                    return await this.handleToolCall(id, params);
+                case 'initialize':
+                    return this.handleInitialize(id);
+                default:
+                    return this.errorResponse(id, MCPErrorCode.METHOD_NOT_FOUND, `Method not found: ${method}`);
+            }
+        }
+        catch (error) {
+            return this.errorResponse(id, MCPErrorCode.INTERNAL_ERROR, error instanceof Error ? error.message : 'Internal error', error);
+        }
+    }
+    /**
+     * Handle tools/list request
+     *
+     * Returns location-filtered tools based on LocationContext.getCurrent()
+     * Uses @LocationScope decorators to determine tool availability
+     */
+    handleToolsList(id) {
+        const toolsByContainer = ToolRegistry.getToolsGroupedByContainerForLocation();
+        const mcpTools = [];
+        for (const [container, containerTools] of Object.entries(toolsByContainer)) {
+            for (const tool of containerTools) {
+                mcpTools.push(this.convertToMCPTool(container, tool));
+            }
+        }
+        const response = {
+            tools: mcpTools
+        };
+        return {
+            jsonrpc: '2.0',
+            id,
+            result: response
+        };
+    }
+    /**
+     * Handle tools/call request
+     */
+    async handleToolCall(id, params) {
+        const { name, arguments: args } = params;
+        if (!name) {
+            return this.errorResponse(id, MCPErrorCode.INVALID_PARAMS, 'Missing tool name');
+        }
+        // Parse tool name (format: container.toolName)
+        const [container, toolName] = name.split('.');
+        if (!container || !toolName) {
+            return this.errorResponse(id, MCPErrorCode.INVALID_PARAMS, `Invalid tool name format: ${name}. Expected: container.toolName`);
+        }
+        // Find tool by containerId and tool name
+        // The tool may be registered with its class name, but exposed with containerId
+        // Handle undefined containerId (treat as matching the container name used in MCP)
+        const tool = Array.from(ToolRegistry.getAllTools().values()).find(t => {
+            const toolContainer = t.containerId || 'global'; // undefined becomes 'global'
+            return toolContainer === container && t.name === toolName;
+        });
+        if (!tool) {
+            return this.errorResponse(id, MCPErrorCode.TOOL_NOT_FOUND, `Tool not found: ${name}`);
+        }
+        // Execute tool
+        try {
+            // Convert args object to array format expected by ToolExecutor
+            const argsArray = Object.values(args || {});
+            const result = await this.executor.execute(tool, argsArray);
+            if (!result.success) {
+                return this.errorResponse(id, MCPErrorCode.TOOL_EXECUTION_FAILED, result.message || 'Tool execution failed', { error: result.error, timing: result.timing });
+            }
+            // Format success response
+            const response = {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            result: result.data,
+                            timing: result.timing,
+                            message: result.message
+                        }, null, 2)
+                    }
+                ]
+            };
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: response
+            };
+        }
+        catch (error) {
+            return this.errorResponse(id, MCPErrorCode.TOOL_EXECUTION_FAILED, error instanceof Error ? error.message : 'Tool execution failed', error);
+        }
+    }
+    /**
+     * Handle initialize request
+     */
+    handleInitialize(id) {
+        return {
+            jsonrpc: '2.0',
+            id,
+            result: {
+                protocolVersion: '2024-11-05',
+                serverInfo: {
+                    name: this.config.name,
+                    version: this.config.version
+                },
+                capabilities: this.config.capabilities
+            }
+        };
+    }
+    /**
+     * Convert Supernal tool to MCP tool format
+     */
+    convertToMCPTool(container, tool) {
+        // tool.inputSchema is already a full schema object {type, properties, required}
+        // Use it directly, or create a default if missing
+        const inputSchema = tool.inputSchema || {
+            type: 'object',
+            properties: {},
+            required: []
+        };
+        return {
+            name: `${container}.${tool.name}`,
+            description: tool.description || `Tool: ${tool.name}`,
+            inputSchema,
+            annotations: {
+                container,
+                category: tool.category,
+                elementId: tool.elementId,
+                componentName: tool.componentName,
+                toolType: tool.toolType,
+                aiEnabled: tool.aiEnabled
+            }
+        };
+    }
+    /**
+     * Create error response
+     */
+    errorResponse(id, code, message, data) {
+        const error = {
+            code,
+            message,
+            data
+        };
+        return {
+            jsonrpc: '2.0',
+            id,
+            error
+        };
+    }
+}
+/**
+ * Create and configure a Supernal MCP server
+ *
+ * @param config - Server configuration
+ * @returns Configured MCP server instance
+ *
+ * @example
+ * ```typescript
+ * const server = createSupernalMCPServer({
+ *   name: 'my-app-tools',
+ *   version: '1.0.0'
+ * });
+ *
+ * // Start with stdio transport
+ * const transport = new StdioTransport();
+ * await server.start(transport);
+ * ```
+ */
+export function createSupernalMCPServer(config) {
+    return new SupernalMCPServer(config);
+}
+//# sourceMappingURL=server.js.map

package/dist/esm/src/mcp/server.js.map

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

package/dist/esm/src/mcp/transport.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Stdio Transport for MCP
+ *
+ * Implements MCP transport over stdin/stdout for integration with
+ * Claude Desktop, Cursor, and other MCP clients.
+ */
+import type { MCPTransport, MCPRequest, MCPResponse } from './types';
+/**
+ * Stdio transport implementation
+ *
+ * Reads JSON-RPC messages from stdin (one per line)
+ * Writes JSON-RPC responses to stdout (one per line)
+ */
+export declare class StdioTransport implements MCPTransport {
+    private readline?;
+    private messageQueue;
+    private waitingResolvers;
+    private closed;
+    constructor();
+    /**
+     * Setup readline interface for stdin
+     */
+    private setupReadline;
+    /**
+     * Send message to client (write to stdout)
+     */
+    send(message: MCPResponse): Promise<void>;
+    /**
+     * Receive message from client (read from stdin)
+     */
+    receive(): Promise<MCPRequest>;
+    /**
+     * Close transport
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create stdio transport
+ *
+ * @returns Stdio transport instance
+ *
+ * @example
+ * ```typescript
+ * import { createSupernalMCPServer, createStdioTransport } from '@supernal/interface';
+ *
+ * const server = createSupernalMCPServer();
+ * const transport = createStdioTransport();
+ *
+ * await server.start(transport);
+ * ```
+ */
+export declare function createStdioTransport(): StdioTransport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/esm/src/mcp/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../src/mcp/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAErE;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,YAAY;IACjD,OAAO,CAAC,QAAQ,CAAC,CAAoB;IACrC,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,gBAAgB,CAA4C;IACpE,OAAO,CAAC,MAAM,CAAkB;;IAMhC;;OAEG;IACH,OAAO,CAAC,aAAa;IAuCrB;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IAgBpC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAoB7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAErD"}

package/dist/esm/src/mcp/transport.js

@@ -0,0 +1,126 @@
+/**
+ * Stdio Transport for MCP
+ *
+ * Implements MCP transport over stdin/stdout for integration with
+ * Claude Desktop, Cursor, and other MCP clients.
+ */
+import { createInterface } from 'readline';
+/**
+ * Stdio transport implementation
+ *
+ * Reads JSON-RPC messages from stdin (one per line)
+ * Writes JSON-RPC responses to stdout (one per line)
+ */
+export class StdioTransport {
+    constructor() {
+        this.messageQueue = [];
+        this.waitingResolvers = [];
+        this.closed = false;
+        this.setupReadline();
+    }
+    /**
+     * Setup readline interface for stdin
+     */
+    setupReadline() {
+        this.readline = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: false
+        });
+        this.readline.on('line', (line) => {
+            try {
+                const message = JSON.parse(line);
+                // If someone is waiting for a message, give it to them immediately
+                if (this.waitingResolvers.length > 0) {
+                    const resolve = this.waitingResolvers.shift();
+                    resolve(message);
+                }
+                else {
+                    // Otherwise queue it
+                    this.messageQueue.push(message);
+                }
+            }
+            catch (error) {
+                console.error('[Stdio Transport] Failed to parse message:', error);
+                console.error('[Stdio Transport] Line:', line);
+            }
+        });
+        this.readline.on('close', () => {
+            this.closed = true;
+            // Reject all waiting resolvers
+            for (const resolve of this.waitingResolvers) {
+                resolve({
+                    jsonrpc: '2.0',
+                    method: '__transport_closed__'
+                });
+            }
+            this.waitingResolvers = [];
+        });
+    }
+    /**
+     * Send message to client (write to stdout)
+     */
+    async send(message) {
+        if (this.closed) {
+            throw new Error('Transport is closed');
+        }
+        const json = JSON.stringify(message);
+        process.stdout.write(json + '\n');
+    }
+    /**
+     * Receive message from client (read from stdin)
+     */
+    async receive() {
+        if (this.closed) {
+            throw new Error('Transport is closed');
+        }
+        // If we have queued messages, return the first one
+        if (this.messageQueue.length > 0) {
+            return this.messageQueue.shift();
+        }
+        // Otherwise wait for the next message
+        return new Promise((resolve) => {
+            this.waitingResolvers.push(resolve);
+        });
+    }
+    /**
+     * Close transport
+     */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.readline) {
+            this.readline.close();
+            this.readline = undefined;
+        }
+        // Reject all waiting resolvers
+        for (const resolve of this.waitingResolvers) {
+            resolve({
+                jsonrpc: '2.0',
+                method: '__transport_closed__'
+            });
+        }
+        this.waitingResolvers = [];
+        this.messageQueue = [];
+    }
+}
+/**
+ * Create stdio transport
+ *
+ * @returns Stdio transport instance
+ *
+ * @example
+ * ```typescript
+ * import { createSupernalMCPServer, createStdioTransport } from '@supernal/interface';
+ *
+ * const server = createSupernalMCPServer();
+ * const transport = createStdioTransport();
+ *
+ * await server.start(transport);
+ * ```
+ */
+export function createStdioTransport() {
+    return new StdioTransport();
+}
+//# sourceMappingURL=transport.js.map

package/dist/esm/src/mcp/transport.js.map

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

package/dist/esm/src/mcp/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * MCP Protocol Types
+ *
+ * Type definitions for Model Context Protocol (MCP) integration.
+ * Based on @ai-sdk/mcp specification.
+ */
+/**
+ * MCP tool parameter schema
+ */
+export interface MCPToolParameter {
+    type: string;
+    description?: string;
+    required?: boolean;
+    properties?: Record<string, MCPToolParameter>;
+    items?: MCPToolParameter;
+    enum?: string[];
+    default?: any;
+}
+/**
+ * MCP tool definition
+ */
+export interface MCPTool {
+    /** Unique tool identifier (container.toolName format) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** JSON Schema for tool parameters */
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, MCPToolParameter>;
+        required?: string[];
+    };
+    /** Optional annotations for additional metadata */
+    annotations?: {
+        container?: string;
+        category?: string;
+        elementId?: string;
+        componentName?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * MCP tools/list response
+ */
+export interface MCPToolsListResponse {
+    tools: MCPTool[];
+}
+/**
+ * MCP tools/call request
+ */
+export interface MCPToolCallRequest {
+    name: string;
+    arguments: Record<string, any>;
+}
+/**
+ * MCP content types
+ */
+export type MCPContentType = 'text' | 'image' | 'resource';
+/**
+ * MCP text content
+ */
+export interface MCPTextContent {
+    type: 'text';
+    text: string;
+}
+/**
+ * MCP image content
+ */
+export interface MCPImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+/**
+ * MCP resource content
+ */
+export interface MCPResourceContent {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+    };
+}
+/**
+ * Union of all MCP content types
+ */
+export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
+/**
+ * MCP tools/call response
+ */
+export interface MCPToolCallResponse {
+    content: MCPContent[];
+    isError?: boolean;
+}
+/**
+ * MCP server configuration
+ */
+export interface MCPServerConfig {
+    /** Server name */
+    name: string;
+    /** Server version */
+    version: string;
+    /** Optional description */
+    description?: string;
+    /** Optional capabilities */
+    capabilities?: {
+        tools?: {};
+        resources?: {};
+        prompts?: {};
+    };
+}
+/**
+ * MCP error codes
+ */
+export declare enum MCPErrorCode {
+    PARSE_ERROR = -32700,
+    INVALID_REQUEST = -32600,
+    METHOD_NOT_FOUND = -32601,
+    INVALID_PARAMS = -32602,
+    INTERNAL_ERROR = -32603,
+    TOOL_NOT_FOUND = -1,
+    TOOL_EXECUTION_FAILED = -2
+}
+/**
+ * MCP error
+ */
+export interface MCPError {
+    code: MCPErrorCode;
+    message: string;
+    data?: any;
+}
+/**
+ * MCP request
+ */
+export interface MCPRequest {
+    jsonrpc: '2.0';
+    id?: string | number;
+    method: string;
+    params?: any;
+}
+/**
+ * MCP response
+ */
+export interface MCPResponse {
+    jsonrpc: '2.0';
+    id?: string | number;
+    result?: any;
+    error?: MCPError;
+}
+/**
+ * MCP transport interface
+ */
+export interface MCPTransport {
+    /** Send message to client */
+    send(message: MCPResponse): Promise<void>;
+    /** Receive message from client */
+    receive(): Promise<MCPRequest>;
+    /** Close transport */
+    close(): Promise<void>;
+}
+/**
+ * MCP server interface
+ */
+export interface MCPServer {
+    /** Server configuration */
+    config: MCPServerConfig;
+    /** Start server (transport provided externally) */
+    start(transport: MCPTransport): Promise<void>;
+    /** Stop server */
+    stop(): Promise<void>;
+    /** Handle incoming request */
+    handle(request: MCPRequest): Promise<MCPResponse | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/src/mcp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/mcp/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IAEb,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IAEpB,sCAAsC;IACtC,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAC7C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IAEF,mDAAmD;IACnD,WAAW,CAAC,EAAE;QACZ,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IAEb,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAEhB,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,4BAA4B;IAC5B,YAAY,CAAC,EAAE;QACb,KAAK,CAAC,EAAE,EAAE,CAAC;QACX,SAAS,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,CAAC,EAAE,EAAE,CAAC;KACd,CAAC;CACH;AAED;;GAEG;AACH,oBAAY,YAAY;IACtB,WAAW,SAAS;IACpB,eAAe,SAAS;IACxB,gBAAgB,SAAS;IACzB,cAAc,SAAS;IACvB,cAAc,SAAS;IACvB,cAAc,KAAK;IACnB,qBAAqB,KAAK;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,GAAG,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,GAAG,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C,kCAAkC;IAClC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAE/B,sBAAsB;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,2BAA2B;IAC3B,MAAM,EAAE,eAAe,CAAC;IAExB,mDAAmD;IACnD,KAAK,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C,kBAAkB;IAClB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,8BAA8B;IAC9B,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC1D"}

package/dist/esm/src/mcp/types.js

@@ -0,0 +1,20 @@
+/**
+ * MCP Protocol Types
+ *
+ * Type definitions for Model Context Protocol (MCP) integration.
+ * Based on @ai-sdk/mcp specification.
+ */
+/**
+ * MCP error codes
+ */
+export var MCPErrorCode;
+(function (MCPErrorCode) {
+    MCPErrorCode[MCPErrorCode["PARSE_ERROR"] = -32700] = "PARSE_ERROR";
+    MCPErrorCode[MCPErrorCode["INVALID_REQUEST"] = -32600] = "INVALID_REQUEST";
+    MCPErrorCode[MCPErrorCode["METHOD_NOT_FOUND"] = -32601] = "METHOD_NOT_FOUND";
+    MCPErrorCode[MCPErrorCode["INVALID_PARAMS"] = -32602] = "INVALID_PARAMS";
+    MCPErrorCode[MCPErrorCode["INTERNAL_ERROR"] = -32603] = "INTERNAL_ERROR";
+    MCPErrorCode[MCPErrorCode["TOOL_NOT_FOUND"] = -1] = "TOOL_NOT_FOUND";
+    MCPErrorCode[MCPErrorCode["TOOL_EXECUTION_FAILED"] = -2] = "TOOL_EXECUTION_FAILED";
+})(MCPErrorCode || (MCPErrorCode = {}));
+//# sourceMappingURL=types.js.map

package/dist/esm/src/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/mcp/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6HH;;GAEG;AACH,MAAM,CAAN,IAAY,YAQX;AARD,WAAY,YAAY;IACtB,kEAAoB,CAAA;IACpB,0EAAwB,CAAA;IACxB,4EAAyB,CAAA;IACzB,wEAAuB,CAAA;IACvB,wEAAuB,CAAA;IACvB,oEAAmB,CAAA;IACnB,kFAA0B,CAAA;AAC5B,CAAC,EARW,YAAY,KAAZ,YAAY,QAQvB"}