mirror of
https://github.com/samanhappy/mcphub.git
synced 2026-01-01 04:08:52 -05:00
b67111219d
- Add output-compression.mdx with comprehensive feature documentation - Add feature to navigation in docs.json Co-authored-by: samanhappy <2755122+samanhappy@users.noreply.github.com>
110 lines
3.9 KiB
Plaintext
110 lines
3.9 KiB
Plaintext
---
|
|
title: 'Output Compression'
|
|
description: 'Reduce token consumption by compressing MCP tool outputs'
|
|
---
|
|
|
|
# Output Compression
|
|
|
|
MCPHub provides an AI-powered compression mechanism to reduce token consumption from MCP tool outputs. This feature is particularly useful when dealing with large outputs that can significantly impact system efficiency and scalability.
|
|
|
|
## Overview
|
|
|
|
The compression feature uses a lightweight AI model (by default, `gpt-4o-mini`) to intelligently compress MCP tool outputs while preserving all essential information. This can help:
|
|
|
|
- **Reduce token overhead** by compressing verbose tool information
|
|
- **Lower operational costs** associated with token consumption
|
|
- **Improve performance** for downstream processing
|
|
- **Better resource utilization** in resource-constrained environments
|
|
|
|
## Configuration
|
|
|
|
Add the compression configuration to your `systemConfig` section in `mcp_settings.json`:
|
|
|
|
```json
|
|
{
|
|
"systemConfig": {
|
|
"compression": {
|
|
"enabled": true,
|
|
"model": "gpt-4o-mini",
|
|
"maxInputTokens": 100000,
|
|
"targetReductionRatio": 0.5
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `enabled` | boolean | `false` | Enable or disable output compression |
|
|
| `model` | string | `"gpt-4o-mini"` | AI model to use for compression |
|
|
| `maxInputTokens` | number | `100000` | Maximum input tokens for compression |
|
|
| `targetReductionRatio` | number | `0.5` | Target size reduction ratio (0.0-1.0) |
|
|
|
|
## Requirements
|
|
|
|
Output compression requires:
|
|
|
|
1. An OpenAI API key configured in the smart routing settings
|
|
2. The compression feature must be explicitly enabled
|
|
|
|
### Setting up OpenAI API Key
|
|
|
|
Configure your OpenAI API key using environment variables or system configuration:
|
|
|
|
**Environment Variable:**
|
|
```bash
|
|
export OPENAI_API_KEY=your-api-key
|
|
```
|
|
|
|
**Or in systemConfig:**
|
|
```json
|
|
{
|
|
"systemConfig": {
|
|
"smartRouting": {
|
|
"openaiApiKey": "your-api-key",
|
|
"openaiApiBaseUrl": "https://api.openai.com/v1"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **Content Size Check**: When a tool call completes, the compression service checks if the output is large enough to benefit from compression (threshold is 10% of `maxInputTokens` or 1000 tokens, whichever is smaller)
|
|
|
|
2. **AI Compression**: If the content exceeds the threshold, it's sent to the configured AI model with instructions to compress while preserving essential information
|
|
|
|
3. **Size Validation**: The compressed result is compared with the original; if compression didn't reduce the size, the original content is used
|
|
|
|
4. **Error Handling**: If compression fails for any reason, the original content is returned unchanged
|
|
|
|
## Fallback Mechanism
|
|
|
|
The compression feature includes graceful degradation for several scenarios:
|
|
|
|
- **Compression disabled**: Original content is returned
|
|
- **No API key**: Original content is returned with a warning
|
|
- **Small content**: Content below threshold is not compressed
|
|
- **API errors**: Original content is returned on any API failure
|
|
- **Error responses**: Tool error responses are never compressed
|
|
- **Non-text content**: Images and other media types are preserved as-is
|
|
|
|
## Best Practices
|
|
|
|
1. **Start with defaults**: The default configuration provides a good balance between compression and quality
|
|
|
|
2. **Monitor results**: Review compressed outputs to ensure important information isn't lost
|
|
|
|
3. **Adjust threshold**: If you have consistently large outputs, consider lowering `targetReductionRatio` for more aggressive compression
|
|
|
|
4. **Use efficient models**: The default `gpt-4o-mini` provides a good balance of cost and quality; switch to `gpt-4o` if you need higher quality compression
|
|
|
|
## Limitations
|
|
|
|
- Compression adds latency due to the AI API call
|
|
- API costs apply for each compression operation
|
|
- Very short outputs won't be compressed (below threshold)
|
|
- Binary/non-text content is not compressed
|