MCP Conversation Server

A Model Context Protocol (MCP) server implementation for managing conversations with OpenRouter's language models. This server provides a standardized interface for applications to interact with various language models through a unified conversation management system.

Features

• MCP Protocol Support
• Full MCP protocol compliance
• Resource management and discovery
• Tool-based interaction model
• Streaming response support
• Error handling and recovery

• OpenRouter Integration
• Support for all OpenRouter models
• Real-time streaming responses
• Automatic token counting
• Model context window management
• Available models include:
• Claude 3 Opus
• Claude 3 Sonnet
• Llama 2 70B
• And many more from OpenRouter's catalog

• Conversation Management
• Create and manage multiple conversations
• Support for system messages
• Message history tracking
• Token usage monitoring
• Conversation filtering and search

• Streaming Support
• Real-time message streaming
• Chunked response handling
• Token counting

• File System Persistence
• Conversation state persistence
• Configurable storage location
• Automatic state management

Installation

npm install mcp-conversation-server

Configuration

Configuration

All configuration for the MCP Conversation Server is now provided via YAML. Please update the config/models.yaml file with your settings. For example:

# MCP Server Configuration
openRouter:
  apiKey: "YOUR_OPENROUTER_API_KEY"  # Replace with your actual OpenRouter API key.

persistence:
  path: "./conversations"  # Directory for storing conversation data.

models:
  # Define your models here
  'provider/model-name':
    id: 'provider/model-name'
    contextWindow: 123456
    streaming: true
    temperature: 0.7
    description: 'Model description'

# Default model to use if none specified
defaultModel: 'provider/model-name'

Server Configuration

The MCP Conversation Server now loads all its configuration from the YAML file. In your application, you can load the configuration as follows:

const config = await loadModelsConfig(); // Loads openRouter, persistence, models, and defaultModel settings from 'config/models.yaml'

*Note: Environment variables are no longer required as all configuration is provided via the YAML file.*

Usage

Basic Server Setup

import { ConversationServer } from 'mcp-conversation-server';

const server = new ConversationServer(config);
server.run().catch(console.error);

Available Tools

The server exposes several MCP tools:

1. create-conversation

{
       provider: 'openrouter',    // Provider is always 'openrouter'
       model: string,             // OpenRouter model ID (e.g., 'anthropic/claude-3-opus-20240229')
       title?: string;            // Optional conversation title
   }

2. send-message

{
       conversationId: string;  // Conversation ID
       content: string;         // Message content
       stream?: boolean;        // Enable streaming responses
   }

3. list-conversations

{
       filter?: {
           model?: string;      // Filter by model
           startDate?: string;  // Filter by start date
           endDate?: string;    // Filter by end date
       }
   }

Resources

The server provides access to several resources:

1. conversation://{id}

• Access specific conversation details
• View message history
• Check conversation metadata

2. conversation://list

• List all active conversations
• Filter conversations by criteria
• Sort by recent activity

Development

Building

npm run build

Running Tests

npm test

Debugging

The server provides several debugging features:

1. Error Logging

• All errors are logged with stack traces
• Token usage tracking
• Rate limit monitoring

2. MCP Inspector

npm run inspector

Use the MCP Inspector to:

• Test tool execution
• View resource contents
• Monitor message flow
• Validate protocol compliance

3. Provider Validation

await server.providerManager.validateProviders();

Validates:

• API key validity
• Model availability
• Rate limit status

Troubleshooting

Common issues and solutions:

1. OpenRouter Connection Issues

• Verify your API key is valid
• Check rate limits on OpenRouter's dashboard
• Ensure the model ID is correct
• Monitor credit usage

2. Message Streaming Errors

• Verify model streaming support
• Check connection stability
• Monitor token limits
• Handle timeout settings

3. File System Errors

• Check directory permissions
• Verify path configuration
• Monitor disk space
• Handle concurrent access

Contributing

1. Fork the repository

2. Create a feature branch

3. Commit your changes

4. Push to the branch

5. Create a Pull Request

License

ISC License