@blueberrybytes/webmcp 0.1.0

package/dist/mcp-server.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * MCP Server - Implementation of MCP protocol for WebMCP
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPServer = void 0;
+const json_rpc_2_0_1 = require("json-rpc-2.0");
+const model_context_1 = require("./model-context");
+/**
+ * MCP Server that handles JSON-RPC communication for WebMCP tools
+ */
+class MCPServer {
+    constructor(modelContext) {
+        this.clients = new Map();
+        this.server = new json_rpc_2_0_1.JSONRPCServer();
+        this.modelContext = modelContext || new model_context_1.ModelContext();
+        this.setupMethods();
+    }
+    /**
+     * Sets up the JSON-RPC methods for the MCP server
+     */
+    setupMethods() {
+        // List available tools
+        this.server.addMethod('tools/list', () => {
+            const tools = this.modelContext.getAllTools();
+            return {
+                tools: tools.map(tool => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema
+                }))
+            };
+        });
+        // Execute a tool
+        this.server.addMethod('tools/call', async (params) => {
+            const { name, arguments: args } = params;
+            const client = this.getDefaultClient();
+            try {
+                const result = await this.modelContext.executeTool(name, args || {}, client);
+                return this.formatToolResult(result);
+            }
+            catch (error) {
+                throw {
+                    code: -32603,
+                    message: error instanceof Error ? error.message : 'Internal error',
+                    data: error
+                };
+            }
+        });
+        // Get tool by name
+        this.server.addMethod('tools/get', (params) => {
+            const { name } = params;
+            const tool = this.modelContext.getTool(name);
+            if (!tool) {
+                throw {
+                    code: -32601,
+                    message: `Tool '${name}' not found`
+                };
+            }
+            return {
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema
+            };
+        });
+    }
+    /**
+     * Handles incoming JSON-RPC requests
+     * @param request - The JSON-RPC request
+     * @param clientId - Optional client ID
+     * @returns Promise that resolves with the JSON-RPC response
+     */
+    async receive(request, clientId) {
+        return await this.server.receive(request);
+    }
+    /**
+     * Adds a tool to the model context
+     * @param tool - The tool to add
+     */
+    addTool(tool) {
+        this.modelContext.registerTool(tool);
+    }
+    /**
+     * Removes a tool from the model context
+     * @param name - The name of the tool to remove
+     */
+    removeTool(name) {
+        this.modelContext.unregisterTool(name);
+    }
+    /**
+     * Gets all registered tools
+     * @returns Array of all registered tools
+     */
+    getTools() {
+        return this.modelContext.getAllTools();
+    }
+    /**
+     * Gets the model context
+     * @returns The model context
+     */
+    getModelContext() {
+        return this.modelContext;
+    }
+    /**
+     * Adds a client to the server
+     * @param clientId - The client ID
+     * @param client - The client to add
+     */
+    addClient(clientId, client) {
+        this.clients.set(clientId, client);
+    }
+    /**
+     * Removes a client from the server
+     * @param clientId - The client ID to remove
+     */
+    removeClient(clientId) {
+        this.clients.delete(clientId);
+    }
+    /**
+     * Gets a client by ID
+     * @param clientId - The client ID
+     * @returns The client or undefined if not found
+     */
+    getClient(clientId) {
+        return this.clients.get(clientId);
+    }
+    /**
+     * Gets the default client
+     * @returns The default client
+     */
+    getDefaultClient() {
+        return {
+            requestUserInteraction: async (callback) => {
+                // In a real implementation, this would handle user interaction
+                // For now, we'll just execute the callback
+                return await callback();
+            }
+        };
+    }
+    /**
+     * Formats a tool result for MCP protocol
+     * @param result - The tool result
+     * @returns Formatted result
+     */
+    formatToolResult(result) {
+        // If result is already in the correct format, return it
+        if (result && typeof result === 'object' && (result.content || result.type)) {
+            return result;
+        }
+        // If result is a string, wrap it in the appropriate format
+        if (typeof result === 'string') {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: result
+                    }
+                ]
+            };
+        }
+        // If result is an object, try to convert it to a string representation
+        if (typeof result === 'object' && result !== null) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2)
+                    }
+                ]
+            };
+        }
+        // For other types, convert to string
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: String(result)
+                }
+            ]
+        };
+    }
+}
+exports.MCPServer = MCPServer;

package/dist/model-context.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ModelContext - Implementation of the WebMCP API
+ */
+import { ModelContextTool, ModelContextOptions, ModelContextClient } from './types';
+/**
+ * ModelContext provides methods for web applications to register and manage tools
+ * that can be invoked by AI agents
+ */
+export declare class ModelContext {
+    private tools;
+    private sessionId;
+    constructor();
+    /**
+     * Registers the provided context (tools) with the browser
+     * This method clears any pre-existing tools and other context before registering the new ones
+     * @param options - Options containing tools to register
+     */
+    provideContext(options?: ModelContextOptions): void;
+    /**
+     * Unregisters all context (tools) with the browser
+     */
+    clearContext(): void;
+    /**
+     * Registers a single tool without clearing the existing set of tools
+     * @param tool - The tool to register
+     * @throws Error if a tool with the same name already exists
+     */
+    registerTool(tool: ModelContextTool): void;
+    /**
+     * Removes the tool with the specified name from the registered set
+     * @param name - The name of the tool to unregister
+     */
+    unregisterTool(name: string): void;
+    /**
+     * Gets a tool by name
+     * @param name - The name of the tool to retrieve
+     * @returns The tool or undefined if not found
+     */
+    getTool(name: string): ModelContextTool | undefined;
+    /**
+     * Gets all registered tools
+     * @returns Array of all registered tools
+     */
+    getAllTools(): ModelContextTool[];
+    /**
+     * Executes a tool by name with the provided input
+     * @param name - The name of the tool to execute
+     * @param input - The input parameters for the tool
+     * @param client - The client executing the tool
+     * @returns Promise that resolves with the tool result
+     */
+    executeTool(name: string, input: Record<string, any>, client: ModelContextClient): Promise<any>;
+    /**
+     * Gets tools filtered by category
+     * @param category - The category to filter by
+     * @returns Array of tools in the specified category
+     */
+    getToolsByCategory(category: string): ModelContextTool[];
+    /**
+     * Gets tools filtered by tags
+     * @param tags - The tags to filter by
+     * @returns Array of tools with the specified tags
+     */
+    getToolsByTags(tags: string[]): ModelContextTool[];
+    /**
+     * Gets the session ID for this context
+     * @returns The session ID
+     */
+    getSessionId(): string;
+    /**
+     * Validates input against a JSON schema
+     * @param input - The input to validate
+     * @param schema - The schema to validate against
+     */
+    private validateInput;
+    /**
+     * Checks if a value is of the correct type
+     * @param value - The value to check
+     * @param expectedType - The expected type
+     * @returns True if the value is of the correct type
+     */
+    private isCorrectType;
+    /**
+     * Validates a JSON schema
+     * @param schema - The schema to validate
+     * @returns True if the schema is valid
+     */
+    private isValidSchema;
+    /**
+     * Generates a unique session ID
+     * @returns A unique session ID
+     */
+    private generateSessionId;
+}

package/dist/model-context.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * ModelContext - Implementation of the WebMCP API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelContext = void 0;
+/**
+ * ModelContext provides methods for web applications to register and manage tools
+ * that can be invoked by AI agents
+ */
+class ModelContext {
+    constructor() {
+        this.tools = new Map();
+        // Generate a unique session ID for this context
+        this.sessionId = this.generateSessionId();
+    }
+    /**
+     * Registers the provided context (tools) with the browser
+     * This method clears any pre-existing tools and other context before registering the new ones
+     * @param options - Options containing tools to register
+     */
+    provideContext(options = {}) {
+        // Clear existing tools
+        this.clearContext();
+        // Register new tools if provided
+        if (options.tools && options.tools.length > 0) {
+            for (const tool of options.tools) {
+                this.registerTool(tool);
+            }
+        }
+    }
+    /**
+     * Unregisters all context (tools) with the browser
+     */
+    clearContext() {
+        this.tools.clear();
+    }
+    /**
+     * Registers a single tool without clearing the existing set of tools
+     * @param tool - The tool to register
+     * @throws Error if a tool with the same name already exists
+     */
+    registerTool(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`Tool with name '${tool.name}' already exists`);
+        }
+        // Validate input schema if provided
+        if (tool.inputSchema && !this.isValidSchema(tool.inputSchema)) {
+            throw new Error(`Invalid input schema for tool '${tool.name}'`);
+        }
+        this.tools.set(tool.name, tool);
+    }
+    /**
+     * Removes the tool with the specified name from the registered set
+     * @param name - The name of the tool to unregister
+     */
+    unregisterTool(name) {
+        this.tools.delete(name);
+    }
+    /**
+     * Gets a tool by name
+     * @param name - The name of the tool to retrieve
+     * @returns The tool or undefined if not found
+     */
+    getTool(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Gets all registered tools
+     * @returns Array of all registered tools
+     */
+    getAllTools() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Executes a tool by name with the provided input
+     * @param name - The name of the tool to execute
+     * @param input - The input parameters for the tool
+     * @param client - The client executing the tool
+     * @returns Promise that resolves with the tool result
+     */
+    async executeTool(name, input, client) {
+        const tool = this.getTool(name);
+        if (!tool) {
+            throw new Error(`Tool '${name}' not found`);
+        }
+        // Validate input against schema if provided
+        if (tool.inputSchema) {
+            this.validateInput(input, tool.inputSchema);
+        }
+        // Execute the tool
+        return await tool.execute(input, client);
+    }
+    /**
+     * Gets tools filtered by category
+     * @param category - The category to filter by
+     * @returns Array of tools in the specified category
+     */
+    getToolsByCategory(category) {
+        return Array.from(this.tools.values()).filter(tool => tool.annotations?.category === category);
+    }
+    /**
+     * Gets tools filtered by tags
+     * @param tags - The tags to filter by
+     * @returns Array of tools with the specified tags
+     */
+    getToolsByTags(tags) {
+        return Array.from(this.tools.values()).filter(tool => {
+            const toolTags = tool.annotations?.tags || [];
+            return tags.some(tag => toolTags.includes(tag));
+        });
+    }
+    /**
+     * Gets the session ID for this context
+     * @returns The session ID
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Validates input against a JSON schema
+     * @param input - The input to validate
+     * @param schema - The schema to validate against
+     */
+    validateInput(input, schema) {
+        // Check required properties
+        if (schema.required && Array.isArray(schema.required)) {
+            for (const requiredProp of schema.required) {
+                if (!(requiredProp in input)) {
+                    throw new Error(`Missing required property: ${requiredProp}`);
+                }
+            }
+        }
+        // Check property types if schema defines them
+        if (schema.properties) {
+            for (const [propName, propSchema] of Object.entries(schema.properties)) {
+                if (propName in input) {
+                    const value = input[propName];
+                    const expectedType = propSchema.type;
+                    if (expectedType) {
+                        if (!this.isCorrectType(value, expectedType)) {
+                            throw new Error(`Property '${propName}' should be of type '${expectedType}'`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Checks if a value is of the correct type
+     * @param value - The value to check
+     * @param expectedType - The expected type
+     * @returns True if the value is of the correct type
+     */
+    isCorrectType(value, expectedType) {
+        switch (expectedType) {
+            case 'string':
+                return typeof value === 'string';
+            case 'number':
+                return typeof value === 'number';
+            case 'boolean':
+                return typeof value === 'boolean';
+            case 'object':
+                return typeof value === 'object' && value !== null && !Array.isArray(value);
+            case 'array':
+                return Array.isArray(value);
+            default:
+                return true; // Allow any type if not specifically checked
+        }
+    }
+    /**
+     * Validates a JSON schema
+     * @param schema - The schema to validate
+     * @returns True if the schema is valid
+     */
+    isValidSchema(schema) {
+        // Basic validation - check that it's an object
+        if (typeof schema !== 'object' || schema === null) {
+            return false;
+        }
+        // If properties are defined, they should be an object
+        if (schema.properties && typeof schema.properties !== 'object') {
+            return false;
+        }
+        // If required is defined, it should be an array
+        if (schema.required && !Array.isArray(schema.required)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Generates a unique session ID
+     * @returns A unique session ID
+     */
+    generateSessionId() {
+        return 'session_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9);
+    }
+}
+exports.ModelContext = ModelContext;

package/dist/tool-manager.d.ts

@@ -0,0 +1,108 @@
+/**
+ * ToolManager - Utility class for managing WebMCP tools
+ */
+import { ModelContextTool, JSONSchema, ToolAnnotations } from './types';
+import { ModelContext } from './model-context';
+/**
+ * ToolManager provides utilities for registering and managing WebMCP tools
+ */
+export declare class ToolManager {
+    private modelContext;
+    constructor(modelContext: ModelContext);
+    /**
+     * Creates a new tool with the specified parameters
+     * @param name - The name of the tool
+     * @param description - The description of the tool
+     * @param execute - The execute function for the tool
+     * @param options - Additional options for the tool
+     * @returns The created tool
+     */
+    createTool(name: string, description: string, execute: (input: Record<string, any>, client: any) => Promise<any>, options?: {
+        inputSchema?: JSONSchema;
+        annotations?: ToolAnnotations;
+    }): ModelContextTool;
+    /**
+     * Registers a tool with the model context
+     * @param tool - The tool to register
+     * @returns The registered tool
+     */
+    registerTool(tool: ModelContextTool): ModelContextTool;
+    /**
+     * Unregisters a tool from the model context
+     * @param name - The name of the tool to unregister
+     */
+    unregisterTool(name: string): void;
+    /**
+     * Gets a tool by name
+     * @param name - The name of the tool to retrieve
+     * @returns The tool or undefined if not found
+     */
+    getTool(name: string): ModelContextTool | undefined;
+    /**
+     * Gets all registered tools
+     * @returns Array of all registered tools
+     */
+    getAllTools(): ModelContextTool[];
+    /**
+     * Gets tools filtered by category
+     * @param category - The category to filter by
+     * @returns Array of tools in the specified category
+     */
+    getToolsByCategory(category: string): ModelContextTool[];
+    /**
+     * Gets tools filtered by tags
+     * @param tags - The tags to filter by
+     * @returns Array of tools with the specified tags
+     */
+    getToolsByTags(tags: string[]): ModelContextTool[];
+    /**
+     * Creates a tool with category annotation
+     * @param name - The name of the tool
+     * @param description - The description of the tool
+     * @param category - The category of the tool
+     * @param execute - The execute function for the tool
+     * @param options - Additional options for the tool
+     * @returns The created tool
+     */
+    createCategorizedTool(name: string, description: string, category: string, execute: (input: Record<string, any>, client: any) => Promise<any>, options?: {
+        inputSchema?: JSONSchema;
+        tags?: string[];
+    }): ModelContextTool;
+    /**
+     * Creates a tool with authentication requirements
+     * @param name - The name of the tool
+     * @param description - The description of the tool
+     * @param execute - The execute function for the tool
+     * @param options - Additional options for the tool
+     * @returns The created tool
+     */
+    createAuthenticatedTool(name: string, description: string, execute: (input: Record<string, any>, client: any) => Promise<any>, options?: {
+        inputSchema?: JSONSchema;
+        scopes?: string[];
+        tags?: string[];
+    }): ModelContextTool;
+    /**
+     * Creates a read-only tool
+     * @param name - The name of the tool
+     * @param description - The description of the tool
+     * @param execute - The execute function for the tool
+     * @param options - Additional options for the tool
+     * @returns The created tool
+     */
+    createReadOnlyTool(name: string, description: string, execute: (input: Record<string, any>, client: any) => Promise<any>, options?: {
+        inputSchema?: JSONSchema;
+        tags?: string[];
+    }): ModelContextTool;
+    /**
+     * Batch registers multiple tools
+     * @param tools - Array of tools to register
+     * @returns Array of successfully registered tools
+     */
+    registerTools(tools: ModelContextTool[]): ModelContextTool[];
+    /**
+     * Validates a tool before registration
+     * @param tool - The tool to validate
+     * @returns True if the tool is valid, false otherwise
+     */
+    validateTool(tool: ModelContextTool): boolean;
+}