brainy/src/mcp/README.md

# 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.