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

Related MCP server: Linear MCP Server

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