Slimcontext MCP Server

🚀 SlimContext MCP Server

SlimContext MCP Server是一个模型上下文协议（MCP）服务器，它封装了 SlimContext 库，为兼容MCP的客户端提供AI聊天历史压缩工具。

🚀 快速开始

SlimContext MCP Server将两种强大的压缩策略作为MCP工具公开：

1. trim_messages - 基于令牌的压缩，当超过令牌阈值时移除最旧的消息。
2. summarize_messages - 由OpenAI提供支持的AI压缩，用于创建简洁的摘要。

📦 安装指南

npm install -g slimcontext-mcp-server
# 或者
pnpm add -g slimcontext-mcp-server

🔧 开发步骤

# 克隆并设置
git clone <repository>
cd slimcontext-mcp-server
pnpm install

# 构建
pnpm build

# 开发环境运行
pnpm dev

# 类型检查
pnpm typecheck

🛠️ 配置说明

MCP客户端设置

在您的MCP客户端配置中添加以下内容：

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

环境变量

• OPENAI_API_KEY：用于摘要生成的OpenAI API密钥（可选，可以作为工具参数传递）。

💻 使用示例

trim_messages

使用基于令牌的修剪策略压缩聊天历史。

参数：

• messages（必需）：聊天消息数组。
• maxModelTokens（可选）：模型的最大令牌上下文窗口（默认值：8192）。
• thresholdPercent（可选）：触发压缩的百分比阈值，范围为0 - 1（默认值：0.7）。
• minRecentMessages（可选）：要保留的最近消息的最小数量（默认值：2）。

示例：

{
  "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
}

响应：

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

使用基于AI的摘要策略压缩聊天历史。

参数：

• messages（必需）：聊天消息数组。
• maxModelTokens（可选）：模型的最大令牌上下文窗口（默认值：8192）。
• thresholdPercent（可选）：触发压缩的百分比阈值，范围为0 - 1（默认值：0.7）。
• minRecentMessages（可选）：要保留的最近消息的最小数量（默认值：4）。
• openaiApiKey（可选）：OpenAI API密钥（也可以使用 OPENAI_API_KEY 环境变量）。
• openaiModel（可选）：用于摘要生成的OpenAI模型（默认值：'gpt - 4o - mini'）。
• customPrompt（可选）：自定义摘要提示。

示例：

{
  "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"
}

响应：

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

📚 详细文档

消息格式

两个工具都期望消息采用SlimContext格式：

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

错误处理

所有工具都返回结构化的错误响应：

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

常见的错误场景：

• 摘要生成时缺少OpenAI API密钥。
• 消息格式无效。
• OpenAI API速率限制或错误。
• 参数值无效。

令牌估计

SlimContext使用一个简单的启发式方法进行令牌估计：Math.ceil(content.length / 4) + 2。这为大多数用例提供了合理的近似值。对于更准确的令牌计数，您需要在客户端应用程序中实现自定义令牌估计器。

压缩策略

修剪策略

• 保留所有系统消息。
• 保留最近的N条消息。
• 移除最旧的非系统消息，直到低于令牌阈值。
• 快速且确定性强。
• 无需外部API依赖。

摘要策略

• 保留所有系统消息。
• 保留最近的N条消息。
• 使用AI对对话的中间部分进行摘要。
• 创建上下文丰富的摘要。
• 需要OpenAI API访问权限。

📄 许可证

本项目采用MIT许可证。

👥 贡献指南

1. 分叉仓库。
2. 创建功能分支。
3. 进行更改。
4. 为新功能添加测试。
5. 提交拉取请求。

🔗 相关项目

• SlimContext - 底层压缩库。
• Model Context Protocol - 协议规范。
• MCP SDK - MCP的TypeScript SDK。