# SlimContext MCP Server

A Model Context Protocol (MCP) server that wraps the [SlimContext](https://www.npmjs.com/package/slimcontext) library, providing AI chat history compression tools for MCP-compatible clients.

## Overview

SlimContext MCP Server exposes two powerful compression strategies as MCP tools:

1. **`trim_messages`** - Token-based compression that removes oldest messages when exceeding token thresholds
2. **`summarize_messages`** - AI-powered compression using OpenAI to create concise summaries

## Installation

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

## Development

```bash
# 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 to your MCP client configuration:

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

### Environment Variables

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

## Tools

### trim_messages

Compresses chat history using token-based trimming strategy.

**Parameters:**

- `messages` (required): Array of chat messages
- `maxModelTokens` (optional): Maximum model token context window (default: 8192)
- `thresholdPercent` (optional): Percentage threshold to trigger compression 0-1 (default: 0.7)
- `minRecentMessages` (optional): Minimum recent messages to preserve (default: 2)

**Example:**

```json
{
  "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:**

```json
{
  "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

Compresses chat history using AI-powered summarization strategy.

**Parameters:**

- `messages` (required): Array of chat messages
- `maxModelTokens` (optional): Maximum model token context window (default: 8192)
- `thresholdPercent` (optional): Percentage threshold to trigger compression 0-1 (default: 0.7)
- `minRecentMessages` (optional): Minimum recent messages to preserve (default: 4)
- `openaiApiKey` (optional): OpenAI API key (can also use OPENAI_API_KEY env var)
- `openaiModel` (optional): OpenAI model for summarization (default: 'gpt-4o-mini')
- `customPrompt` (optional): Custom summarization prompt

**Example:**

```json
{
  "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:**

```json
{
  "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?" }
  ]
}
```

## Message Format

Both tools expect messages in SlimContext format:

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

## Error Handling

All tools return structured error responses:

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

Common error scenarios:

- 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 oldest non-system messages until under token threshold
- Fast and deterministic
- No external API dependencies

### Summarization Strategy

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

## License

MIT

## 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](https://www.npmjs.com/package/slimcontext) - The underlying compression library
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) - TypeScript SDK for MCP