@meldscience/mcp-tool-processor NPM

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

npm install @meldscience/mcp-tool-processor

Usage

Basic Setup with File Discovery

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

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:

{
  "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

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

Event Handling

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:

Discovery Consumer: Monitors server availability and configuration changes
- File-based discovery (watches a JSON file)
- Redis-based discovery (planned)
- Direct updates from ToolManager
Connection Pool: Manages server connections
- Maintains active connections
- Handles connection lifecycle
- Implements idle timeout
- Enforces max connection limits
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

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