@blueberrybytes/webmcp 0.1.0

package/README.md

@@ -0,0 +1,196 @@
+# WebMCP TypeScript Library
+
+A TypeScript implementation of the Web Model Context Protocol (WebMCP) for creating MCP servers and tools.
+
+## Overview
+
+WebMCP (Web Model Context Protocol) is a JavaScript API that allows web developers to expose their web application functionality as "tools" - JavaScript functions with natural language descriptions and structured schemas that can be invoked by AI agents, browser assistants, and assistive technologies.
+
+This TypeScript library provides a complete implementation of the WebMCP specification, allowing you to:
+
+- Create and manage WebMCP tools
+- Implement an MCP server that can communicate with AI agents
+- Handle client connections and communication
+- Validate tool schemas and inputs
+
+## Installation
+
+```bash
+npm install @webmcp/core
+```
+
+## Quick Start
+
+### Creating a Simple Tool
+
+```typescript
+import { ModelContext, ToolManager } from "@webmcp/core";
+
+// Create a model context
+const modelContext = new ModelContext();
+
+// Create a tool manager
+const toolManager = new ToolManager(modelContext);
+
+// Create a simple tool
+const helloTool = toolManager.createTool(
+  "hello",
+  "Say hello to someone",
+  async (input: { name: string }) => {
+    return `Hello, ${input.name}!`;
+  },
+  {
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "The name of the person to greet",
+        },
+      },
+      required: ["name"],
+    },
+  },
+);
+
+// Register the tool
+toolManager.registerTool(helloTool);
+
+// Execute the tool
+const result = await modelContext.executeTool("hello", { name: "World" });
+console.log(result); // "Hello, World!"
+```
+
+### Creating an MCP Server
+
+```typescript
+import { MCPServer, ToolManager } from "@webmcp/core";
+
+// Create an MCP server
+const server = new MCPServer();
+
+// Create and register tools
+const toolManager = new ToolManager(server.getModelContext());
+
+const calculatorTool = toolManager.createTool(
+  "add",
+  "Add two numbers together",
+  async (input: { a: number; b: number }) => {
+    return { result: input.a + input.b };
+  },
+  {
+    inputSchema: {
+      type: "object",
+      properties: {
+        a: { type: "number", description: "First number" },
+        b: { type: "number", description: "Second number" },
+      },
+      required: ["a", "b"],
+    },
+  },
+);
+
+toolManager.registerTool(calculatorTool);
+
+// Handle incoming requests (example)
+const request = {
+  jsonrpc: "2.0",
+  id: 1,
+  method: "tools/call",
+  params: {
+    name: "add",
+    arguments: { a: 5, b: 3 },
+  },
+};
+
+const response = await server.receive(request);
+console.log(response); // { jsonrpc: '2.0', id: 1, result: { result: 8 } }
+```
+
+### Creating Categorized Tools
+
+```typescript
+import { ToolManager } from "@webmcp/core";
+
+const toolManager = new ToolManager(modelContext);
+
+// Create a categorized tool
+const searchTool = toolManager.createCategorizedTool(
+  "search-docs",
+  "Search documentation for specific terms",
+  "search",
+  async (input: { query: string }) => {
+    // Implementation here
+    return { results: [`Result for: ${input.query}`] };
+  },
+  {
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+      },
+      required: ["query"],
+    },
+    tags: ["documentation", "search"],
+  },
+);
+
+toolManager.registerTool(searchTool);
+```
+
+## API Reference
+
+### ModelContext
+
+The core class for managing WebMCP tools.
+
+#### Methods
+
+- `provideContext(options: ModelContextOptions)`: Registers tools with the browser
+- `clearContext()`: Unregisters all tools
+- `registerTool(tool: ModelContextTool)`: Registers a single tool
+- `unregisterTool(name: string)`: Removes a tool
+- `getTool(name: string)`: Gets a tool by name
+- `getAllTools()`: Gets all registered tools
+- `executeTool(name: string, input: Record<string, any>, client: ModelContextClient)`: Executes a tool
+
+### ToolManager
+
+Utility class for creating and managing tools.
+
+#### Methods
+
+- `createTool(...)`: Creates a new tool
+- `createCategorizedTool(...)`: Creates a tool with category annotation
+- `createAuthenticatedTool(...)`: Creates a tool with authentication requirements
+- `createReadOnlyTool(...)`: Creates a read-only tool
+- `registerTool(tool: ModelContextTool)`: Registers a tool
+- `registerTools(tools: ModelContextTool[])`: Batch registers tools
+
+### MCPServer
+
+MCP server implementation that handles JSON-RPC communication.
+
+#### Methods
+
+- `receive(request: JSONRPCRequest, clientId?: string)`: Handles incoming requests
+- `addTool(tool: ModelContextTool)`: Adds a tool
+- `removeTool(name: string)`: Removes a tool
+- `getTools()`: Gets all registered tools
+
+## Tool Categories
+
+The library supports categorizing tools for better organization and discovery:
+
+- `search`: Find/query information
+- `read`: Retrieve specific data
+- `create`: Create new resources
+- `update`: Modify existing resources
+- `delete`: Remove resources
+- `analysis`: Process/analyze data
+- `navigation`: Page/UI navigation
+- `media`: Images, audio, video
+
+## License
+
+MIT

package/dist/client-handler.d.ts

@@ -0,0 +1,121 @@
+/**
+ * ClientHandler - Handles client connections for WebMCP MCP server
+ */
+import { JSONRPCRequest, JSONRPCResponse } from 'json-rpc-2.0';
+import { MCPServer } from './mcp-server';
+/**
+ * ClientHandler manages client connections and communication for the MCP server
+ */
+export declare class ClientHandler {
+    private server;
+    private clients;
+    constructor(server: MCPServer);
+    /**
+     * Adds a new client connection
+     * @param clientId - Unique identifier for the client
+     * @param clientInfo - Information about the client
+     * @returns The connected client
+     */
+    addClient(clientId: string, clientInfo: ClientInfo): ConnectedClient;
+    /**
+     * Removes a client connection
+     * @param clientId - The client ID to remove
+     */
+    removeClient(clientId: string): void;
+    /**
+     * Gets a client by ID
+     * @param clientId - The client ID
+     * @returns The connected client or undefined if not found
+     */
+    getClient(clientId: string): ConnectedClient | undefined;
+    /**
+     * Gets all connected clients
+     * @returns Array of all connected clients
+     */
+    getClients(): ConnectedClient[];
+    /**
+     * Handles an incoming JSON-RPC request from a client
+     * @param clientId - The client ID
+     * @param request - The JSON-RPC request
+     * @returns Promise that resolves with the JSON-RPC response
+     */
+    handleRequest(clientId: string, request: JSONRPCRequest): Promise<JSONRPCResponse | null>;
+    /**
+     * Sends a notification to a client
+     * @param clientId - The client ID
+     * @param method - The method to call
+     * @param params - The parameters to pass
+     */
+    sendNotification(clientId: string, method: string, params: any): void;
+    /**
+     * Sends a request to a client
+     * @param clientId - The client ID
+     * @param method - The method to call
+     * @param params - The parameters to pass
+     * @returns Promise that resolves with the response
+     */
+    sendRequest(clientId: string, method: string, params: any): Promise<any>;
+    /**
+     * Gets the number of connected clients
+     * @returns The number of connected clients
+     */
+    getClientCount(): number;
+    /**
+     * Gets inactive clients older than the specified time
+     * @param minutes - The number of minutes to consider a client inactive
+     * @returns Array of inactive clients
+     */
+    getInactiveClients(minutes: number): ConnectedClient[];
+    /**
+     * Disconnects inactive clients
+     * @param minutes - The number of minutes to consider a client inactive
+     * @returns The number of clients disconnected
+     */
+    disconnectInactiveClients(minutes: number): number;
+}
+/**
+ * Information about a connected client
+ */
+export interface ClientInfo {
+    /**
+     * Client name or identifier
+     */
+    name: string;
+    /**
+     * Client version
+     */
+    version?: string;
+    /**
+     * Client type (e.g., 'browser', 'desktop', 'mobile')
+     */
+    type?: string;
+    /**
+     * Client capabilities
+     */
+    capabilities?: string[];
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Represents a connected client
+ */
+export interface ConnectedClient {
+    /**
+     * Client ID
+     */
+    id: string;
+    /**
+     * Client information
+     */
+    info: ClientInfo;
+    /**
+     * Connection timestamp
+     */
+    connectedAt: Date;
+    /**
+     * Last activity timestamp
+     */
+    lastActivity: Date;
+}

package/dist/client-handler.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * ClientHandler - Handles client connections for WebMCP MCP server
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientHandler = void 0;
+/**
+ * ClientHandler manages client connections and communication for the MCP server
+ */
+class ClientHandler {
+    constructor(server) {
+        this.clients = new Map();
+        this.server = server;
+    }
+    /**
+     * Adds a new client connection
+     * @param clientId - Unique identifier for the client
+     * @param clientInfo - Information about the client
+     * @returns The connected client
+     */
+    addClient(clientId, clientInfo) {
+        const client = {
+            id: clientId,
+            info: clientInfo,
+            connectedAt: new Date(),
+            lastActivity: new Date()
+        };
+        this.clients.set(clientId, client);
+        return client;
+    }
+    /**
+     * Removes a client connection
+     * @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 connected client or undefined if not found
+     */
+    getClient(clientId) {
+        return this.clients.get(clientId);
+    }
+    /**
+     * Gets all connected clients
+     * @returns Array of all connected clients
+     */
+    getClients() {
+        return Array.from(this.clients.values());
+    }
+    /**
+     * Handles an incoming JSON-RPC request from a client
+     * @param clientId - The client ID
+     * @param request - The JSON-RPC request
+     * @returns Promise that resolves with the JSON-RPC response
+     */
+    async handleRequest(clientId, request) {
+        // Update client activity
+        const client = this.getClient(clientId);
+        if (client) {
+            client.lastActivity = new Date();
+        }
+        // Process the request through the MCP server
+        return await this.server.receive(request, clientId);
+    }
+    /**
+     * Sends a notification to a client
+     * @param clientId - The client ID
+     * @param method - The method to call
+     * @param params - The parameters to pass
+     */
+    sendNotification(clientId, method, params) {
+        const client = this.getClient(clientId);
+        if (!client) {
+            throw new Error(`Client '${clientId}' not found`);
+        }
+        // In a real implementation, this would send the notification to the client
+        // For now, we'll just log it
+        console.log(`Sending notification to client ${clientId}: ${method}`, params);
+    }
+    /**
+     * Sends a request to a client
+     * @param clientId - The client ID
+     * @param method - The method to call
+     * @param params - The parameters to pass
+     * @returns Promise that resolves with the response
+     */
+    async sendRequest(clientId, method, params) {
+        const client = this.getClient(clientId);
+        if (!client) {
+            throw new Error(`Client '${clientId}' not found`);
+        }
+        // In a real implementation, this would send the request to the client
+        // For now, we'll just log it and return a mock response
+        console.log(`Sending request to client ${clientId}: ${method}`, params);
+        // Mock response for demonstration
+        return {
+            result: `Mock response for ${method}`,
+            client: clientId
+        };
+    }
+    /**
+     * Gets the number of connected clients
+     * @returns The number of connected clients
+     */
+    getClientCount() {
+        return this.clients.size;
+    }
+    /**
+     * Gets inactive clients older than the specified time
+     * @param minutes - The number of minutes to consider a client inactive
+     * @returns Array of inactive clients
+     */
+    getInactiveClients(minutes) {
+        const now = new Date();
+        const inactiveClients = [];
+        for (const client of this.clients.values()) {
+            const minutesSinceLastActivity = (now.getTime() - client.lastActivity.getTime()) / (1000 * 60);
+            if (minutesSinceLastActivity > minutes) {
+                inactiveClients.push(client);
+            }
+        }
+        return inactiveClients;
+    }
+    /**
+     * Disconnects inactive clients
+     * @param minutes - The number of minutes to consider a client inactive
+     * @returns The number of clients disconnected
+     */
+    disconnectInactiveClients(minutes) {
+        const inactiveClients = this.getInactiveClients(minutes);
+        const count = inactiveClients.length;
+        for (const client of inactiveClients) {
+            this.removeClient(client.id);
+        }
+        return count;
+    }
+}
+exports.ClientHandler = ClientHandler;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * WebMCP - Web Model Context Protocol
+ *
+ * A TypeScript library for implementing WebMCP servers and tools
+ */
+export { ModelContext } from './model-context';
+export { MCPServer, MCPClient } from './mcp-server';
+export { ToolManager } from './tool-manager';
+export { ClientHandler, ClientInfo, ConnectedClient } from './client-handler';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * WebMCP - Web Model Context Protocol
+ *
+ * A TypeScript library for implementing WebMCP servers and tools
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientHandler = exports.ToolManager = exports.MCPServer = exports.ModelContext = void 0;
+var model_context_1 = require("./model-context");
+Object.defineProperty(exports, "ModelContext", { enumerable: true, get: function () { return model_context_1.ModelContext; } });
+var mcp_server_1 = require("./mcp-server");
+Object.defineProperty(exports, "MCPServer", { enumerable: true, get: function () { return mcp_server_1.MCPServer; } });
+var tool_manager_1 = require("./tool-manager");
+Object.defineProperty(exports, "ToolManager", { enumerable: true, get: function () { return tool_manager_1.ToolManager; } });
+var client_handler_1 = require("./client-handler");
+Object.defineProperty(exports, "ClientHandler", { enumerable: true, get: function () { return client_handler_1.ClientHandler; } });
+__exportStar(require("./types"), exports);

package/dist/mcp-server.d.ts

@@ -0,0 +1,100 @@
+/**
+ * MCP Server - Implementation of MCP protocol for WebMCP
+ */
+import { JSONRPCRequest, JSONRPCResponse } from 'json-rpc-2.0';
+import { ModelContext } from './model-context';
+import { ModelContextTool } from './types';
+/**
+ * MCP Server that handles JSON-RPC communication for WebMCP tools
+ */
+export declare class MCPServer {
+    private server;
+    private modelContext;
+    private clients;
+    constructor(modelContext?: ModelContext);
+    /**
+     * Sets up the JSON-RPC methods for the MCP server
+     */
+    private setupMethods;
+    /**
+     * 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
+     */
+    receive(request: JSONRPCRequest, clientId?: string): Promise<JSONRPCResponse | null>;
+    /**
+     * Adds a tool to the model context
+     * @param tool - The tool to add
+     */
+    addTool(tool: ModelContextTool): void;
+    /**
+     * Removes a tool from the model context
+     * @param name - The name of the tool to remove
+     */
+    removeTool(name: string): void;
+    /**
+     * Gets all registered tools
+     * @returns Array of all registered tools
+     */
+    getTools(): ModelContextTool[];
+    /**
+     * Gets the model context
+     * @returns The model context
+     */
+    getModelContext(): ModelContext;
+    /**
+     * Adds a client to the server
+     * @param clientId - The client ID
+     * @param client - The client to add
+     */
+    addClient(clientId: string, client: MCPClient): void;
+    /**
+     * Removes a client from the server
+     * @param clientId - The client ID to remove
+     */
+    removeClient(clientId: string): void;
+    /**
+     * Gets a client by ID
+     * @param clientId - The client ID
+     * @returns The client or undefined if not found
+     */
+    getClient(clientId: string): MCPClient | undefined;
+    /**
+     * Gets the default client
+     * @returns The default client
+     */
+    private getDefaultClient;
+    /**
+     * Formats a tool result for MCP protocol
+     * @param result - The tool result
+     * @returns Formatted result
+     */
+    private formatToolResult;
+}
+/**
+ * Represents an MCP client
+ */
+export interface MCPClient {
+    /**
+     * Client ID
+     */
+    id: string;
+    /**
+     * Client name
+     */
+    name: string;
+    /**
+     * Send a notification to the client
+     * @param method - The method to call
+     * @param params - The parameters to pass
+     */
+    sendNotification(method: string, params: any): void;
+    /**
+     * Send a request to the client
+     * @param method - The method to call
+     * @param params - The parameters to pass
+     * @returns Promise that resolves with the response
+     */
+    sendRequest(method: string, params: any): Promise<any>;
+}