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

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

1. send-message

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

1. list-conversations

typescript { 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}
2. Access specific conversation details
3. View message history

4. Check conversation metadata

5. conversation://list

6. List all active conversations
7. Filter conversations by criteria
8. Sort by recent activity

Development

Building

npm run build

Running Tests

npm test

Debugging

The server provides several debugging features:

1. Error Logging
2. All errors are logged with stack traces
3. Token usage tracking

4. Rate limit monitoring

5. MCP Inspector

bash npm run inspector

Use the MCP Inspector to: - Test tool execution - View resource contents - Monitor message flow - Validate protocol compliance

1. Provider Validation

typescript await server.providerManager.validateProviders();

Validates: - API key validity - Model availability - Rate limit status

Troubleshooting

Common issues and solutions:

1. OpenRouter Connection Issues
2. Verify your API key is valid
3. Check rate limits on OpenRouter's dashboard
4. Ensure the model ID is correct

5. Monitor credit usage

6. Message Streaming Errors

7. Verify model streaming support
8. Check connection stability
9. Monitor token limits

10. Handle timeout settings

11. File System Errors

12. Check directory permissions
13. Verify path configuration
14. Monitor disk space
15. 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