npm package: @meldscience/mcp-tool-processor
Description: Tool processor for Model Context Protocol (MCP)
Author: MeldScience
Latest version: 0.3.0

# MCP Tool Processor

The MCP Tool Processor is a component of the Model Context Protocol (MCP) system that handles dynamic discovery and connection to tool servers. It provides a flexible way to discover, connect to, and manage tool servers in a distributed environment.

## Features

- Dynamic server discovery using file-based or Redis-based discovery mechanisms
- Direct server updates from ToolManager for local development
- Automatic server connection management with circuit breaker pattern
- Connection pooling with idle timeout and max connection limits
- Event-driven architecture for server status updates
- Graceful error handling and server failure recovery
- Hot-reloading of server configurations

## Installation

```bash
npm install @meldscience/mcp-tool-processor
```

## Usage

### Basic Setup with File Discovery

```typescript
import { ToolProcessor } from '@meldscience/mcp-tool-processor';

const processor = new ToolProcessor({
  discovery: {
    type: 'file',
    options: {
      path: '/path/to/discovery.json',
      watchInterval: 1000 // milliseconds
    }
  },
  connectionPool: {
    maxConnections: 10,
    idleTimeout: 300000 // 5 minutes
  }
});

// Start the processor
await processor.start();

// Get available tools
const tools = await processor.getAvailableTools();

// Validate a tool call
const validation = await processor.validateToolCall({
  function_name: 'my-tool',
  parameters: { /* ... */ }
});

// Clean up when done
await processor.stop();
```

### Setup with ToolManager for Local Development

```typescript
import { ToolProcessor } from '@meldscience/mcp-tool-processor';
import { ToolManager } from '@meldscience/mcp-tool-manager';

// Create a tool manager instance
const manager = new ToolManager(/* ... */);

// Create processor with both file discovery and tool manager
const processor = new ToolProcessor({
  discovery: {
    type: 'file',
    options: {
      path: './mcp-discovery.json'
    }
  }
}, manager);

// The processor will now receive server updates from both
// the discovery file and the tool manager
```

### Discovery File Format

The discovery file should contain a JSON object mapping server names to their configuration:

```json
{
  "server-1": {
    "name": "server-1",
    "url": "ws://localhost:3000",
    "status": "running",
    "capabilities": {
      "tools": ["tool1", "tool2"]
    },
    "metadata": {
      "lastSeen": "2024-01-20T12:00:00Z"
    }
  }
}
```

### Connection Pool Configuration

```typescript
const processor = new ToolProcessor({
  discovery: { /* ... */ },
  connectionPool: {
    maxConnections: 10,
    idleTimeout: 300000,
    circuitBreaker: {
      failureThreshold: 3,
      resetTimeout: 30000,
      maxRetries: 3
    }
  }
});
```

### Event Handling

```typescript
processor.on('serverAdded', (serverName: string) => {
  console.log(`Server ${serverName} added`);
});

processor.on('serverRemoved', (serverName: string) => {
  console.log(`Server ${serverName} removed`);
});

processor.on('error', (error: {
  type: string;
  serverName?: string;
  error: Error;
}) => {
  console.error('Error:', error);
});
```

## Architecture

The tool processor consists of several key components:

1. **Discovery Consumer**: Monitors server availability and configuration changes
   - File-based discovery (watches a JSON file)
   - Redis-based discovery (planned)
   - Direct updates from ToolManager

2. **Connection Pool**: Manages server connections
   - Maintains active connections
   - Handles connection lifecycle
   - Implements idle timeout
   - Enforces max connection limits

3. **Circuit Breaker**: Provides resilient server connections
   - Prevents cascading failures
   - Implements retry logic
   - Supports automatic recovery

## Error Handling

The processor implements comprehensive error handling:

- Discovery errors (file not found, invalid JSON)
- Connection errors (server unreachable, timeout)
- Tool validation errors
- Circuit breaker events (open, half-open, closed)

All errors are emitted as events with detailed context information.

## API Reference

### ToolProcessor

#### Constructor Options

```typescript
interface ToolProcessorConfig {
  discovery: {
    type: 'file' | 'redis';
    options: FileDiscoveryOptions | RedisDiscoveryOptions;
  };
  connectionPool?: {
    maxConnections?: number;
    idleTimeout?: number;
    circuitBreaker?: CircuitBreakerOptions;
  };
}

// Optional second parameter
constructor(config: ToolProcessorConfig, toolManager?: ToolManager)
```

#### Methods

- `start(): Promise<void>` - Start the processor
- `stop(): Promise<void>` - Stop the processor
- `getAvailableTools(): Promise<string[]>` - Get list of available tools
- `validateToolCall(call: ToolCall): Promise<ValidationResult>` - Validate a tool call

#### Events

- `'serverAdded'` - Emitted when a new server is discovered
- `'serverRemoved'` - Emitted when a server is removed
- `'error'` - Emitted on any error with context

## License

MIT