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

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:

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
}

send-message

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

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:

conversation://{id}
- Access specific conversation details
- View message history
- Check conversation metadata
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:

Error Logging
- All errors are logged with stack traces
- Token usage tracking
- Rate limit monitoring
MCP Inspector
```
npm run inspector
```
Use the MCP Inspector to:
- Test tool execution
- View resource contents
- Monitor message flow
- Validate protocol compliance
Provider Validation
```
await server.providerManager.validateProviders();
```
Validates:
- API key validity
- Model availability
- Rate limit status

Troubleshooting

Common issues and solutions:

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
Message Streaming Errors
- Verify model streaming support
- Check connection stability
- Monitor token limits
- Handle timeout settings
File System Errors
- Check directory permissions
- Verify path configuration
- Monitor disk space
- Handle concurrent access

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

ISC License