context-compression-mcp-server

# 上下文压缩MCP服务器 MCP（模型上下文协议）服务器，通过在SQLite数据库中压缩和存储上下文数据，帮助AI代理管理上下文窗口限制。 使用FastMCP构建，该服务器为AI代理提供了高效存储、检索和管理压缩上下文信息的工具。 ## 功能特点 - **上下文压缩**：使用zlib自动压缩上下文数据以节省存储空间 - **持久化存储**：使用SQLite数据库进行可靠的数据持久化 - **搜索与检索**：按关键词查找存储的上下文或按ID检索 - **元数据管理**：存储标题、标签和时间戳与上下文数据 - **线程安全操作**：安全处理并发请求 - **MCP集成**：与任何MCP兼容的AI客户端无缝协作 ## 安装 ### 前置条件 - Python 3.10或更高版本 - pip或uv包管理器 ### 从PyPI安装（发布时） ```bash pip install context-compression-mcp ``` ### 从源码安装 ```bash git clone https://github.com/yourusername/context-compression-mcp.git cd context-compression-mcp pip install -e . ``` ### 使用uv（推荐） ```bash git clone https://github.com/yourusername/context-compression-mcp.git cd context-compression-mcp uv sync ``` ### 验证安装 安装后，您可以验证一切是否正常工作： ```bash uv run python test_installation.py ``` ## 快速入门 ### 1. 启动MCP服务器 #### 生产模式 ```bash uv run fastmcp run server.py ``` #### 开发模式（带有MCP检查器） ```bash uv run fastmcp dev server.py ``` 开发模式包括用于测试和调试MCP工具的MCP检查器Web界面。 服务器将启动并在当前目录中创建`context_data.db` SQLite数据库文件。 ### 2. 配置您的MCP客户端 将服务器添加到您的MCP客户端配置中。以下是热门客户端的示例： #### Claude Desktop 配置（开发） 在开发过程中，请添加到您的`claude_desktop_config.json`中： ```json { "mcpServers": { "context-compression": { "command": "uv", "args": ["--directory", "/path/to/context-compression-mcp", "run", "fastmcp", "run", "server.py"], "env": {} } } } ``` #### 使用uvx（生产 - 发布时） ```json { "mcpServers": { "context-compression": { "command": "uvx", "args": ["context-compression-mcp"], "env": {} } } } ``` ## 可用工具 服务器提供六种MCP工具用于上下文管理： ### store_context 存储带有可选元数据的上下文数据。 **参数：** - `data`（字符串，必填）：要存储的上下文数据 - `title`（字符串，可选）：上下文的描述性标题 - `tags`（字符串数组，可选）：分类标签 **返回：** ```json { "status": "success", "id": "ctx_1234567890", "original_size": 5000, "compressed_size": 1200, "compression_ratio": 0.24, "compression_method": "zlib" } ``` **示例用法：** ```python # 存储API文档 result = store_context( data="API endpoints: GET /users, POST /users...", title="User API Documentation", tags=["api", "documentation", "users"] ) ``` ### retrieve_context 按ID检索和解压上下文数据。 **参数：** - `context_id`（字符串，必填）：唯一的上下文标识符 **返回：** ```json { "status": "success", "id": "ctx_1234567890", "title": "User API Documentation", "data": "API endpoints: GET /users, POST /users...", "tags": ["api", "documentation", "users"], "metadata": { "original_size": 5000, "compressed_size": 1200, "compression_method": "zlib", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } } ``` ### search_contexts 搜索匹配查询字符串的上下文。 **参数：** - `query`（字符串，必填）：搜索查询字符串 - `limit`（整数，可选）：返回的最大结果数（默认：10，最大：100） **返回：** ```json { "status": "success", "query": "api documentation", "results": [ { "id": "ctx_1234567890", "title": "User API Documentation", "tags": ["api", "documentation", "users"], "created_at": "2024-01-15T10:30:00Z", "original_size": 5000, "compressed_size": 1200 } ], "count": 1 } ``` ### list_contexts 列出所有存储的上下文，并支持分页。 **参数：** - `limit`（整数，可选）：返回的最大结果数（默认：50，最大：100） - `offset`（整数，可选）：要跳过的结果数（默认：0） **返回：** ```json { "status": "success", "results": [ { "id": "ctx_1234567890", "title": "User API Documentation", "tags": ["api", "documentation"], "created_at": "2024-01-15T10:30:00Z", "original_size": 5000, "compressed_size": 1200 } ], "count": 1, "pagination": { "limit": 50, "offset": 0 } } ``` ### delete_context 按ID删除上下文。 **参数：** - `context_id`（字符串，必填）：唯一的上下文标识符 **返回：** ```json { "status": "success", "message": "Context 'ctx_1234567890' deleted successfully", "context_id": "ctx_1234567890" } ``` ### update_context 更新现有上下文的数据、标题或标签。 **参数：** - `context_id`（字符串，必填）：唯一的上下文标识符 - `data`（字符串，可选）：新的上下文数据（将被重新压缩） - `title`（字符串，可选）：新的标题 - `tags`（字符串数组，可选）：新的标签列表 **返回：** ```json { "status": "success", "message": "Context 'ctx_1234567890' updated successfully", "context_id": "ctx_1234567890", "updated_fields": { "data": true, "title": false, "tags": true }, "metadata": { "original_size": 6000, "compressed_size": 1400, "compression_method": "zlib", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T11:45:00Z" } } ``` ## 配置 ### 环境变量 - `CONTEXT_DB_PATH`：SQLite数据库文件路径（默认：`./context_data.db`） - `COMPRESSION_THRESHOLD`：应用压缩前的最小字节数（默认：1024） - `MAX_CONTEXT_SIZE`：上下文的最大字节数（默认：10485760 = 10MB） ### 数据库配置 服务器自动创建和管理SQLite数据库。除非通过`CONTEXT_DB_PATH`指定，否则数据库文件将在当前工作目录中创建。 ## 使用示例 ### 基本工作流程 ```python # 1. 存储一些上下文数据 store_result = store_context( data="Large API documentation content here...", title="API Docs v2.1", tags=["api", "v2.1", "documentation"] ) context_id = store_result["id"] # 2. 稍后检索 context = retrieve_context(context_id) print(context["data"]) # 原始未压缩数据 # 3. 搜索相关上下文 results = search_contexts("API documentation") for result in results["results"]: print(f"Found: {result['title']} (ID: {result['id']})") # 4. 更新上下文 update_context( context_id, title="API Docs v2.2", tags=["api", "v2.2", "documentation", "updated"] ) # 5. 列出所有上下文 all_contexts = list_contexts(limit=20) print(f"Total contexts: {all_contexts['count']}") ``` ## 高级用法 #### 批量操作 ```python # 存储多个相关上下文 contexts = [ {"data": "User model documentation", "title": "User Model", "tags": ["model", "user"]}, {"data": "Order model documentation", "title": "Order Model", "tags": ["model", "order"]}, {"data": "Payment model documentation", "title": "Payment Model", "tags": ["model", "payment"]} ] stored_ids = [] for ctx in contexts: result = store_context(**ctx) stored_ids.append(result["id"]) # 跨所有模型文档搜索 model_docs = search_contexts("model documentation", limit=50) ``` #### 处理大型上下文 ```python # 服务器自动压缩大型上下文 large_context = "Very large context data..." * 1000 # 大字符串 result = store_context( data=large_context, title="Large Context Example" ) print(f"Original size: {result['original_size']} bytes") print(f"Compressed size: {result['compressed_size']} bytes") print(f"Compression ratio: {result['compression_ratio']}") ``` ## 错误处理 所有工具在发生问题时都会返回结构化的错误响应： ```json { "status": "error", "error_code": "CONTEXT_NOT_FOUND", "message": "Context with ID 'ctx_invalid' not found", "details": { "context_id": "ctx_invalid" } } ``` ### 常见错误代码 - `INVALID_INPUT`：无效或缺少必填参数 - `INVALID_TAGS_TYPE`：为标签参数提供了无效类型 - `CONTEXT_NOT_FOUND`：请求的上下文ID不存在 - `VALIDATION_ERROR`：数据验证失败 - `STORAGE_ERROR`：数据库存储操作失败 - `RETRIEVAL_ERROR`：数据库检索操作失败 - `COMPRESSION_ERROR`：数据压缩/解压失败 - `INTERNAL_ERROR`：意外服务器错误 ### 标签参数验证 `store_context`和`update_context`工具的`tags`参数接受灵活的输入类型并执行自动类型转换： #### 有效的标签参数值 ```python # None（无标签） store_context(data="example", tags=None) # 空列表（无标签） store_context(data="example", tags=[]) # 字符串列表（标准用法） store_context(data="example", tags=["api", "documentation", "v1"]) # 单个字符串（自动转换为列表） store_context(data="example", tags="important") # 转换为["important"] ``` #### 无效的标签参数值 ```python # 数字、布尔值或其他非字符串/列表类型 store_context(data="example", tags=123) # 错误 store_context(data="example", tags=True) # 错误 store_context(data="example", tags={"key": "value"}) # 错误 # 包含非字符串项的列表 store_context(data="example", tags=["valid", 123, "also_valid"]) # 错误 store_context(data="example", tags=[None, "tag"]) # 错误 ``` #### 标签类型转换行为 - **单个字符串**：自动转换为单个项的列表 - 输入："important" → 输出：["important"] - **空字符串**：转换为包含空字符串的单个项列表 - 输入：" " → 输出：[""] - **None**：保持为None（无标签） - **空列表**：保持为空列表（无标签） - **有效的字符串列表**：按原样使用 #### 标签验证错误响应 当为标签参数提供无效类型时，您将收到详细的错误响应： ```json { "status": "error", "error_code": "INVALID_TAGS_TYPE", "message": "Invalid type for tags parameter", "details": { "received_type": "int", "expected_types": ["None", "list of strings", "string"], "received_value": 123, "parameter": "tags" } } ``` ### 排除标签参数问题 #### 问题：'tags'参数类型无效错误 **症状**： - MCP客户端接收到`INVALID_TAGS_TYPE`错误 - 错误消息指示标签参数的类型不正确 **常见原因和解决方案**: 1. **传递数字而不是字符串** ```python # ❌ 错误 store_context(data="example", tags=[1, 2, 3]) # ✅ 正确 store_context(data="example", tags=["1", "2", "3"]) ``` 2. **传递对象或复杂类型** ```python # ❌ 错误 store_context(data="example", tags={"category": "api"}) # ✅ 正确 store_context(data="example", tags=["category:api"]) ``` 3. **列表中包含非字符串项** ```python # ❌ 错误 store_context(data="example", tags=["valid", 123, True]) # ✅ 正确 store_context(data="example", tags=["valid", "123", "true"]) ``` 4. **MCP客户端序列化问题** - 某些MCP客户端可能以不同的方式序列化数据 - 尝试在客户端中将标签作为显式字符串数组传递 - 检查MCP客户端文档以获取正确的数组格式 #### 问题：标签未正确存储或检索 **症状**： - 标签似乎被接受，但不显示在搜索结果中 - 检索的上下文中缺少或不正确的标签 **解决方案**: 1. **存储后验证标签格式** ```python # 存储标签 result = store_context(data="example", tags=["test", "debug"]) # 检索和验证 context = retrieve_context(result["id"]) print(context["tags"]) # 应该显示["test", "debug"] ``` 2. **检查空或仅包含空格的标签** ```python # 有问题的 store_context(data="example", tags=["", " ", "valid"]) # 更好 store_context(data="example", tags=["valid"]) ``` 3. **使用一致的标签命名约定** ```python # ✅ 推荐模式 store_context(data="example", tags=["api-v1", "documentation", "user-guide"]) store_context(data="example", tags=["category:api", "version:1", "type:docs"]) ``` #### 问题：搜索未找到标记的上下文 **症状**： - 存储带有标签的上下文，但搜索结果不返回它们 - 标签在`retrieve_context`中可见，但在`search_contexts`中不可见 **解决方案**: 1. **搜索包含标签内容** ```python # 如果您存储了标签["api", "documentation"] search_contexts("api") # 应该找到 search_contexts("documentation") # 应该找到 search_contexts("api docs") # 根据标题/内容可能找到 ``` 2. **使用`list_contexts`验证标签** ```python # 列出所有上下文以查看其标签 all_contexts = list_contexts() for ctx in all_contexts["results"]: print(f"ID: {ctx['id']}, Tags: {ctx['tags']}") ``` #### 标签的最佳实践 1. **使用描述性、可搜索的标签** ```python # ✅ 好 tags=["rest-api", "authentication", "oauth2", "v2.1"] # ❌ 效果较差 tags=["a", "b", "c"] ``` 2. **建立一致的命名约定** ```python # ✅ 一致的模式 tags=["type:api", "version:2.1", "status:stable"] tags=["lang:python", "framework:fastapi", "feature:auth"] ``` 3. **保持标签简洁但有意义** ```python # ✅ 平衡 tags=["user-management", "crud-operations", "validation"] # ❌ 过于冗长 tags=["user-management-system-with-full-crud-operations"] ``` 4. **将标签用于分类和筛选** ```python # 存储相关上下文并使用一致的标签 store_context(data="User API docs", tags=["api", "users", "v2"]) store_context(data="Order API docs", tags=["api", "orders", "v2"]) store_context(data="Payment API docs", tags=["api", "payments", "v2"]) # 后续搜索所有v2 API文档 search_contexts("api v2") ``` #### 标签参数问题 **问题**: 在存储或更新上下文时出现 `INVALID_TAGS_TYPE` 错误 **解决方案**: 1. 确保标签参数为 None、字符串或字符串列表 2. 将数字转换为字符串：使用 `["1", "2"]` 而不是 `[1, 2]` 3. 检查您的 MCP 客户端的数组序列化格式 4. 参考上面的“标签参数验证”部分以获取详细示例 **问题**: 标签未出现在存储的上下文中 **解决方案**: 1. 验证标签参数格式是否与预期类型匹配 2. 检查您的 MCP 客户端是否正确序列化字符串数组 3. 使用 `retrieve_context` 验证标签是否正确存储 4. 确保标签不包含仅为空格或空字符串 **问题**: 单个字符串标签无法按预期工作 **解决方案**: 1. 单个字符串会自动转换为单个元素的列表 2. `tags="important"` 内部变为 `tags=["important"]` 3. 这是正常行为 - 如有需要，请使用 `retrieve_context` 验证 ## 常见问题 ### 一般问题 **问**: 什么类型的数据最适合此服务器？ **答**: 基于文本的数据压缩效果最佳（文档、代码、对话）。二进制数据或已经压缩的数据不会看到显著的压缩收益。 **问**: 存储的数据量有限制吗？ **答**: 默认情况下，单个上下文限制为 10MB（可配置）。SQLite 数据库可以处理数 GB 的数据，但对于非常大的数据集，性能可能会下降。 **问**: 多个客户端可以使用同一个服务器实例吗？ **答**: 是的，服务器设计为可以安全处理并发请求。每个客户端都可以独立存储和检索上下文。 **问**: 如果服务器崩溃了怎么办？ **答**: 所有数据都存储在 SQLite 数据库中。只需重启服务器，所有上下文都将可用。 ### 技术问题 **问**: 压缩是如何工作的？ **答**: 服务器使用 Python 的 zlib 库，默认压缩级别。对于小于 1KB 的数据或压缩效果不佳（减少不足 20%）的数据，将以未压缩状态存储。 **问**: 我可以备份我的上下文吗？ **答**: 是的，只需复制 `context_data.db` 文件。您还可以使用 `list_contexts` 和 `retrieve_context` 工具导出上下文。 **问**: 数据是否加密？ **答**: 否，数据存储时为压缩状态，但未加密。如果您需要加密，请考虑使用数据库级加密或在上下文中存储加密数据。 **问**: 我可以运行多个服务器实例吗？ **答**: 是的，但每个实例应使用单独的数据库文件（设置不同的 `CONTEXT_DB_PATH` 值）。 ### 集成问题 **问**: 如何将此服务器与现有的 MCP 设置集成？ **答**: 将服务器配置添加到您的 MCP 客户端的配置文件中。此服务器与其他 MCP 服务器一起工作。 **问**: 我可以将此服务器与非 Python MCP 客户端一起使用吗？ **答**: 是的，MCP 是语言无关的。任何 MCP 兼容的客户端都可以使用此服务器。 **问**: 如何从另一个上下文存储系统迁移数据？ **答**: 使用 `store_context` 工具导入现有数据。您可以编写一个简单的脚本来批量导入上下文。 **问**: 标签如何工作，支持哪些类型？ **答**: 标签可以是 None、单个字符串或字符串列表。单个字符串会自动转换为单个元素的列表。标签有助于分类和搜索上下文。有关详细示例和故障排除，请参阅“标签参数验证”部分。 ## 开发 ### 运行测试 ```bash # 安装开发依赖 uv sync --group dev # 运行所有测试 uv run pytest # 运行覆盖率测试 uv run pytest --cov=src # 运行特定测试文件 uv run pytest tests/test_context_manager.py # 验证安装 uv run python test_installation.py ``` ### 代码质量 ```bash # 格式化代码 uv run black . # 检查代码 uv run ruff check . # 类型检查 uv run mypy src/ ``` ### 贡献 1. 分叉仓库 2. 创建功能分支：`git checkout -b feature-name` 3. 进行更改并添加测试 4. 运行测试套件：`pytest` 5. 提交拉取请求 ## 许可证 MIT 许可证 - 参见 LICENSE 文件获取详细信息。 ## 支持 - GitHub 问题：[报告错误或请求功能](https://github.com/yourusername/context-compression-mcp/issues) - 文档：此 README 和内联代码文档 - MCP 协议：[模型上下文协议规范](https://modelcontextprotocol.io/) ## 更新日志 ### v0.1.0（初始版本） - 基本上下文存储和检索 - zlib 压缩支持 - SQLite 数据库后端 - 六个 MCP 工具：存储、检索、搜索、列表、删除、更新 - 线程安全操作 - 全面的测试套件