Initial commit

src/mcp/README.md

@@ -0,0 +1,180 @@
+# Model Control Protocol (MCP) for Brainy
+
+This document provides information about the Model Control Protocol (MCP) implementation in Brainy, which allows external models to access Brainy data and use the augmentation pipeline as tools.
+
+## Components
+
+The MCP implementation consists of three main components:
+
+1. **BrainyMCPAdapter**: Provides access to Brainy data through MCP
+2. **MCPAugmentationToolset**: Exposes the augmentation pipeline as tools
+3. **BrainyMCPService**: Integrates the adapter and toolset, providing WebSocket and REST server implementations for external model access
+
+## Environment Compatibility
+
+### BrainyMCPAdapter
+
+The `BrainyMCPAdapter` has no environment-specific dependencies and can run in any environment where Brainy itself runs, including:
+
+- Browser environments
+- Node.js environments
+- Server environments
+
+### MCPAugmentationToolset
+
+The `MCPAugmentationToolset` also has no environment-specific dependencies and can run in any environment where Brainy itself runs, including:
+
+- Browser environments
+- Node.js environments
+- Server environments
+
+### BrainyMCPService
+
+The `BrainyMCPService` has been refactored to separate the core functionality from the Node.js-specific server functionality:
+
+1. **Core Functionality**: The core request handling functionality (`handleMCPRequest`) can run in any environment where Brainy itself runs. This is what remains in the main Brainy package.
+
+2. **Server Functionality**: The WebSocket and REST server functionality has been moved to the cloud-wrapper project to avoid including Node.js-specific dependencies in the browser bundle:
+   - `ws` for WebSocket server
+   - `express` for REST API
+   - `cors` for Cross-Origin Resource Sharing
+
+This separation ensures that the browser bundle remains lightweight and doesn't include unnecessary Node.js-specific dependencies. In browser or other environments, you can still use the core functionality through the `handleMCPRequest` method.
+
+## Usage
+
+### In Any Environment (Browser, Node.js, Server)
+
+```typescript
+import { BrainyData, BrainyMCPAdapter, MCPAugmentationToolset } from '@soulcraft/brainy'
+
+// Create a BrainyData instance
+const brainyData = new BrainyData()
+await brainyData.init()
+
+// Create an MCP adapter
+const adapter = new BrainyMCPAdapter(brainyData)
+
+// Create a toolset
+const toolset = new MCPAugmentationToolset()
+
+// Use the adapter to access Brainy data
+const response = await adapter.handleRequest({
+  type: 'data_access',
+  operation: 'search',
+  requestId: adapter.generateRequestId(),
+  version: '1.0.0',
+  parameters: {
+    query: 'example query',
+    k: 5
+  }
+})
+
+// Use the toolset to execute augmentation pipeline tools
+const toolResponse = await toolset.handleRequest({
+  type: 'tool_execution',
+  toolName: 'brainy_memory_storeData',
+  requestId: toolset.generateRequestId(),
+  version: '1.0.0',
+  parameters: {
+    args: ['key1', { some: 'data' }]
+  }
+})
+```
+
+### In Node.js Environment with Server Functionality
+
+To use the MCP service with WebSocket and REST server functionality, you should use the cloud-wrapper project:
+
+```typescript
+import { BrainyData } from '@soulcraft/brainy'
+import { initializeBrainy } from './services/brainyService.js'
+import { initializeMCPService } from './services/mcpService.js'
+
+// Initialize Brainy
+const brainyData = await initializeBrainy()
+
+// Initialize MCP service with WebSocket and REST server functionality
+const mcpService = initializeMCPService(brainyData, {
+  wsPort: 8080,
+  restPort: 3000,
+  enableAuth: true,
+  apiKeys: ['your-api-key'],
+  rateLimit: {
+    maxRequests: 100,
+    windowMs: 60000 // 1 minute
+  },
+  cors: {
+    origin: '*',
+    credentials: true
+  }
+})
+```
+
+Alternatively, you can configure the MCP service using environment variables in the cloud-wrapper:
+
+```
+# MCP configuration
+MCP_WS_PORT=8080
+MCP_REST_PORT=3000
+MCP_ENABLE_AUTH=true
+MCP_API_KEYS=your-api-key,another-key
+MCP_RATE_LIMIT_REQUESTS=100
+MCP_RATE_LIMIT_WINDOW_MS=60000
+MCP_ENABLE_CORS=true
+```
+
+### In Browser Environment (Core Functionality Only)
+
+```typescript
+import { BrainyData, BrainyMCPService } from '@soulcraft/brainy'
+
+// Create a BrainyData instance
+const brainyData = new BrainyData()
+await brainyData.init()
+
+// Create an MCP service (server functionality will be disabled in browser)
+const mcpService = new BrainyMCPService(brainyData)
+
+// Use the core functionality
+const response = await mcpService.handleMCPRequest({
+  type: 'data_access',
+  operation: 'search',
+  requestId: mcpService.generateRequestId(),
+  version: '1.0.0',
+  parameters: {
+    query: 'example query',
+    k: 5
+  }
+})
+```
+
+## Cloud Wrapper Integration
+
+The MCP service's server functionality has been integrated directly into the cloud-wrapper project. The cloud-wrapper automatically initializes the MCP service if the appropriate environment variables are set:
+
+```
+# MCP configuration
+MCP_WS_PORT=8080
+MCP_REST_PORT=3000
+MCP_ENABLE_AUTH=true
+MCP_API_KEYS=your-api-key,another-key
+MCP_RATE_LIMIT_REQUESTS=100
+MCP_RATE_LIMIT_WINDOW_MS=60000
+MCP_ENABLE_CORS=true
+```
+
+You can deploy the cloud wrapper to various cloud platforms using the npm scripts from the root directory:
+
+```bash
+# Deploy to AWS Lambda and API Gateway
+npm run deploy:cloud:aws
+
+# Deploy to Google Cloud Run
+npm run deploy:cloud:gcp
+
+# Deploy to Cloudflare Workers
+npm run deploy:cloud:cloudflare
+```
+
+The cloud wrapper is specifically designed for server environments and includes additional features like logging, security headers, and deployment scripts for various cloud providers. See the [Cloud Wrapper README](../../cloud-wrapper/README.md) for detailed configuration instructions and API documentation.