Slimcontext MCP Server

🚀 SlimContext MCP Server

A Model Context Protocol (MCP) server that wraps the SlimContext library, providing AI chat history compression tools for MCP-compatible clients.

🚀 Quick Start

SlimContext MCP Server is a powerful tool that exposes two compression strategies as MCP tools. It can effectively compress AI chat history for MCP-compatible clients.

✨ Features

SlimContext MCP Server offers two robust compression strategies:

1. trim_messages: Token-based compression that removes the oldest messages when the token threshold is exceeded.
2. summarize_messages: AI-powered compression using OpenAI to generate concise summaries.

📦 Installation

You can install the SlimContext MCP Server using either npm or pnpm:

npm install -g slimcontext-mcp-server
# or
pnpm add -g slimcontext-mcp-server

🛠️ Development

Setup

# Clone and setup
git clone <repository>
cd slimcontext-mcp-server
pnpm install

Build

pnpm build

Run in Development

pnpm dev

Type Checking

pnpm typecheck

⚙️ Configuration

MCP Client Setup

Add the following to your MCP client configuration:

{
  "mcpServers": {
    "slimcontext": {
      "command": "npx",
      "args": ["-y", "slimcontext-mcp-server"]
    }
  }
}

Environment Variables

• OPENAI_API_KEY: OpenAI API key for summarization (optional, can be passed as a tool parameter)

💻 Usage Examples

trim_messages

Basic Usage

Compresses chat history using a token-based trimming strategy.

Parameters:

Example:

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" },
    { "role": "assistant", "content": "Hi there! How can I help you today?" },
    { "role": "user", "content": "Tell me about AI." }
  ],
  "maxModelTokens": 4000,
  "thresholdPercent": 0.8,
  "minRecentMessages": 2
}

Response:

{
  "success": true,
  "original_message_count": 4,
  "compressed_message_count": 3,
  "messages_removed": 1,
  "compression_ratio": 0.75,
  "compressed_messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "assistant", "content": "Hi there! How can I help you today?" },
    { "role": "user", "content": "Tell me about AI." }
  ]
}

summarize_messages

Basic Usage

Compresses chat history using an AI-powered summarization strategy.

Parameters:

Example:

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "I want to build a web scraper." },
    {
      "role": "assistant",
      "content": "I can help you build a web scraper! What programming language would you prefer?"
    },
    { "role": "user", "content": "Python please." },
    {
      "role": "assistant",
      "content": "Great choice! For Python web scraping, I recommend using requests and BeautifulSoup..."
    },
    { "role": "user", "content": "Can you show me a simple example?" }
  ],
  "maxModelTokens": 4000,
  "thresholdPercent": 0.6,
  "minRecentMessages": 2,
  "openaiModel": "gpt-4o-mini"
}

Response:

{
  "success": true,
  "original_message_count": 6,
  "compressed_message_count": 4,
  "messages_removed": 2,
  "summary_generated": true,
  "compression_ratio": 0.67,
  "compressed_messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    {
      "role": "system",
      "content": "The user expressed interest in building a web scraper and requested help with Python. The assistant recommended using requests and BeautifulSoup libraries for Python web scraping."
    },
    {
      "role": "assistant",
      "content": "Great choice! For Python web scraping, I recommend using requests and BeautifulSoup..."
    },
    { "role": "user", "content": "Can you show me a simple example?" }
  ]
}

📚 Documentation

Message Format

Both tools expect messages in SlimContext format:

interface SlimContextMessage {
  role: 'system' | 'user' | 'assistant' | 'tool' | 'human';
  content: string;
}

Error Handling

All tools return structured error responses:

{
  "success": false,
  "error": "Error message description",
  "error_type": "SlimContextError" | "OpenAIError" | "UnknownError"
}

Common error scenarios include:

• Missing OpenAI API key for summarization
• Invalid message format
• OpenAI API rate limits or errors
• Invalid parameter values

Token Estimation

SlimContext uses a simple heuristic for token estimation: Math.ceil(content.length / 4) + 2. This provides a reasonable approximation for most use cases. For more accurate token counting, you would need to implement a custom token estimator in your client application.

Compression Strategies

Trimming Strategy

• Preserves all system messages.
• Preserves the most recent N messages.
• Removes the oldest non-system messages until under the token threshold.
• Fast and deterministic.
• No external API dependencies.

Summarization Strategy

• Preserves all system messages.
• Preserves the most recent N messages.
• Summarizes the middle portion of the conversation using AI.
• Creates contextually rich summaries.
• Requires OpenAI API access.

📄 License

This project is licensed under the MIT License.

👥 Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add tests for new functionality.
5. Submit a pull request.

📎 Related

• SlimContext - The underlying compression library.
• Model Context Protocol - The protocol specification.
• MCP SDK - TypeScript SDK for MCP.