CC-MCP

🧠 CC-MCP（Context Consistent MCP Server）

🌐 语言 / 言語 / 语言

• 英语（当前）
• 日本語 - 日语版本
• 中文 - 中文版本

⚠️ 重要：请查阅正确的使用指南

• 📚 英文指南 - 会话管理必备知识
• 📚 日语指南 - 会话管理必备知识
• 📚 中文指南 - 会话管理必备知识

🌟 革命性的 AI 上下文管理：解决长对话中的大模型记忆丢失问题

面向大模型驱动的 AI Agent 的长期对话一致性管理系统

---

🚀 我们要解决的问题

传统大模型在长对话中会出现“意图遗忘”：

• ❌ 几轮对话后就忘记最初的目标
• ❌ 忘记重要的限制条件和决策
• ❌ 在不同对话会话中给出不一致的回复
• ❌ 用户必须不断提醒 AI 上下文信息

CC-MCP 提供智能上下文管理工具，帮助大模型保持一致性。

---

将以下内容添加到 MCP 客户端设置中（例如 Cline 的 cline_mcp_settings.json）：

{
  "mcpServers": {
    "cc-mcp": {
      "autoApprove": [
        "process_user_message",
        "start_session",
        "get_debug_info", 
        "list_sessions",
        "get_session_stats",
        "export_context",
        "import_context"
      ],
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/cc-mcp",
        "main.py"
      ],
      "env": {
        "CLASSIFIER_API_URL": "https://api.openai.com/v1/chat/completions",
        "CLASSIFIER_API_KEY": "your_openai_api_key_here",
        "CLASSIFIER_MODEL": "gpt-4o-mini"
      }
    }
  }
}

• 已配置环境（请参阅快速入门） 将 /path/to/your/cc-mcp 替换为实际的仓库路径。

Ollama 用户须知： 使用 Ollama 而不是 OpenAI 时，请按如下方式修改环境变量：

• 将 CLASSIFIER_API_URL 更改为 Ollama 服务 URL（例如，http://localhost:11434/v1/chat/completions）
• 将 CLASSIFIER_MODEL 更改为首选的 Ollama 模型（例如，llama3.2）
• 移除 CLASSIFIER_API_KEY 或将其留空，因为 Ollama 不需要此变量

Ollama 配置示例：

"env": {
  "CLASSIFIER_API_URL": "http://localhost:11434/v1/chat/completions",
  "CLASSIFIER_MODEL": "llama3.2"
}

先决条件：

• Python 3.13+
• uv 包管理器
• 大模型 API 访问权限（Azure OpenAI、OpenAI 等）或 Ollama 等本地大模型。
• 已配置环境（请参阅快速入门）

---

✨ 主要功能

🏗️ 分层上下文架构

Core Context (Long-term)    ──► Problem definitions & core objectives
    ↓
Evolving Context (Mid-term) ──► Constraints, decisions & refinements  
    ↓
Turn Context (Short-term)   ──► Recent conversation flow

🧠 智能意图分类

• 5 种意图类别：PROBLEM_DEFINITION、CONSTRAINT_ADDITION、REFINEMENT、QUESTION、UNCLEAR

详细意图说明（定义于 intent_classifier.py）：

分类逻辑基于一条提示词，用于指示大模型分析用户消息并分配以下一个或多个标签：

• PROBLEM_DEFINITION：用户正在定义希望解决的核心问题。

  • 提示词中的示例：“我想用 AI 自动总结会议纪要，有什么好办法吗？”

• CONSTRAINT_ADDITION：用户正在添加限制或条件，例如预算或时间安排。

  • 提示词中的示例：“听起来不错。不过，请将使用的模型限制为开源模型。”

• REFINEMENT：用户正在细化现有需求，或对其进行修改。

• QUESTION：用户在提出一个简单的问题。

• UNCLEAR：无法将消息明确归入上述任何类别。

🔧 智能上下文管理

• 感知上下文：自动整理三个层级的上下文
• 目标驱动：持续掌握核心问题和目标
• 遵循约束：跟踪并应用累积的限制条件和决策

记忆管理的实现方式：

“智能上下文剪枝与优化”通过 HierarchicalContextStore（context_store.py）中的多层机制实现：

1. 分层上下文存储：系统将信息分为三个层级，以防止上下文退化：

   • 核心上下文：保存主要问题定义，确保不会丢失核心目标。
   • 演进上下文：保存约束条件和细化内容的列表，以便逐步缩小解决方案空间。
   • 轮次上下文：短期记忆，保存最近几轮对话，以维持对话的即时连贯性。

2. 自动剪枝轮次上下文：为防止记忆膨胀，系统会自动裁剪 turn_context。_trim_turn_context() 方法确保只保留最近的消息（默认：6 条），并丢弃较早且相关性较低的轮次。

3. 基于关键词的优化：系统不会依赖完整文本历史，而是提取并存储 Core 和 Evolving 上下文的加权关键词。随后，get_context_summary() 方法会向大模型提供精简的关键词摘要，相比原始对话历史，处理效率高得多。

这种结构化、基于规则的方法可确保高效且智能地管理记忆，让最关键的信息随时可用，同时避免给大模型造成过重负担。

📊 统计关键词提取

• 由 TF-IDF 驱动：使用 TF-IDF 算法识别并提取对话中最重要的关键词。
• 上下文摘要：提供核心问题和演进约束的精简关键词摘要，让大模型能够更高效地处理。
• 动态语料库：关键词提取引擎会在每次新对话后持续更新文档语料库，随着时间推移提升 IDF 计算的准确性。

关键词提取的实现方式（如 keyword_extraction.py 中所定义）：

统计关键词提取采用了经过多项优化的精细 TF-IDF 实现：

1. 词频（TF）计算：_calculate_tf() 方法根据某个词在特定消息中的出现频率与该消息总词数的比值，计算每个词的出现频率。这能识别当前上下文中被强调的词语。

2. 逆文档频率（IDF）计算：_calculate_idf() 方法计算一个词在整个语料库的所有对话中有多罕见。所用公式为 IDF = log(total_documents / documents_containing_term)，因此罕见词更有价值。

3. TF-IDF 评分：extract_keywords() 方法结合 TF 和 IDF 评分（TF-IDF = TF × IDF），以识别在当前消息中频繁出现、但在所有对话中较为罕见的词语，从而体现其对特定主题的重要性。

4. 多语言分词：_tokenize() 方法使用正则表达式提取日语（平假名、片假名、汉字）和英语单词，同时过滤两种语言中的常见停用词。

5. 语料库管理：系统维护一个不断增长的文档语料库，以逐步提高 IDF 的准确性。每条新消息都会更新 _document_frequency 字典和 _total_documents 计数，使未来的提取结果更加精确。

这种方法可确保提取的关键词能代表上下文中最相关的词语，同时过滤掉常见且意义较弱的词语。

⚡ 卓越性能

• 超快：可与 gpt-3.5-tubo、gpt-4o-mini 或 gemma3:4b 等能力较弱的模型配合使用
• 可扩展：支持处理多个并发会话
• 高效利用内存：智能上下文剪枝与优化

💾 会话持久化

• 有状态运行：所有对话会话和关键词统计信息都会自动保存到 persistence/ 目录，并在启动时恢复，确保服务器重启后不会丢失数据。
• 稳健性：这让服务器更具韧性，即使服务器崩溃或重启，也能保留上下文。

---

🎯 实际影响

使用 CC-MCP 之前：

User: "I want to build an AI assistant app"
AI: "Sure! Here are some general approaches..."

[10 messages later]
User: "Remember, budget is 500K yen, 3 months timeline"
AI: "What project are we talking about?" ❌

使用 CC-MCP 之后：

User: "I want to build an AI assistant app"
AI: "Great! Let me help you design this system..."

[10 messages later] 
User: "What about deployment options?"
AI: "For your AI assistant app (budget: 500K yen, 3-month timeline, security priority), here are deployment strategies that fit your constraints..." ✅

---

🛠️ 技术架构

graph TD
    subgraph CC-MCP Server
        direction LR
        C[Intent Classifier]
        D[Context Store]
        E[Keyword Extractor]
    end

    A[MCP Client Application] -- MCP Tools --> B((main.py))
    B -- Manages --> C
    B -- Manages --> D
    B -- Manages --> E
    C -- Calls --> G[External LLM API]

组件说明：

此服务器基于三个核心组件构建，它们协同工作以提供感知上下文的响应：

1. Intent Classifier（intent_classifier.py）：

   • 功能：此组件会分析用户的消息，以确定其潜在目的。
   • 实现方式：它会使用精心设计的提示词，将用户的消息发送给外部大模型（如 GPT 或本地 Ollama 模型），让大模型将消息归类为五种意图之一：PROBLEM_DEFINITION、CONSTRAINT_ADDITION、REFINEMENT、QUESTION 或 UNCLEAR。

2. Context Store（context_store.py）：

   • 功能：这是系统的“记忆”，用于以分层结构组织和存储对话上下文。
   • 实现方式：它采用三层系统：用于主要问题的 core_context、用于约束和细化内容的 evolving_context，以及用于最新消息的 turn_context。它会自动精简短期 turn_context，以高效管理记忆。

3. Keyword Extractor（keyword_extraction.py）：

   • 功能：此引擎会从存储在 core 和 evolving 上下文中的用户消息里识别最重要的词语。
   • 实现方式：它使用经典的 **TF-IDF（词频－逆文档频率）**算法，计算一个词在消息中出现的频率（TF），以及该词在所有对话中的稀有程度（IDF）。结合这两项得分，它可以找出对当前主题特别重要的关键词。

可用的 MCP 工具：

• process_user_message - 使用上下文管理处理核心消息
• export_context - 将对话状态导出为 JSON
• import_context - 恢复对话状态
• clear_context - 重置所有上下文数据
• get_debug_info - 获取详细的调试信息
• start_session / end_session - 管理会话生命周期
• list_sessions - 监控活跃会话
• get_session_stats - 获取性能分析数据

传输协议：

默认传输协议为 stdio。也支持 SSE（服务器发送事件），可通过端点 http://127.0.0.1:8001/sse/ 直接进行 HTTP 通信。

---

📦 快速开始

前置条件

• Python 3.13+
• uv 包管理器
• 大模型 API 访问权限（Azure OpenAI、OpenAI 等）或本地大模型（如 Ollama）。
• 已配置环境（参见快速开始）

安装

# Clone the repository
git clone https://github.com/Beginnersguide138/cc-mcp.git
cd cc-mcp

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your API credentials

更新仓库

克隆仓库后，如需获取最新更新，请使用以下 Git 命令：

# Fetch the latest changes from the remote repository
git fetch origin

# Pull the latest changes from the main branch
git pull origin main

# Update dependencies (if they have changed)
uv sync

建议定期更新本地仓库，以便：

• 获取最新功能
• 获得错误修复
• 确保与最新版本兼容

环境配置

# .env file example - Only 3 variables needed!
CLASSIFIER_API_URL=https://api.openai.com/v1/chat/completions
CLASSIFIER_API_KEY=sk-your_openai_api_key_here
CLASSIFIER_MODEL=gpt-3.5-turbo

# Alternative providers (see .env.example for full list):
# Azure OpenAI, Anthropic Claude, Google Gemini, Ollama supported

# For Ollama (Local LLM):
# CLASSIFIER_API_URL=http://localhost:11434/v1/chat/completions
# CLASSIFIER_API_KEY=not_required  # Ollama doesn't need auth; leave empty with the latest version
# CLASSIFIER_MODEL=llama3

启动服务器

# Start CC-MCP server with stdio transport (default for clients like Cline)
uv run main.py

🦙 使用 Ollama（本地大模型）

CC-MCP 现已支持使用 Ollama 运行本地大模型，无需支付 API 费用。此功能是在最近一次提交中添加的。

1. 安装并运行 Ollama：

# Install Ollama from https://ollama.com/
# Download and run a model
ollama run llama3

2. 在 .env 中为 Ollama 配置 CC-MCP：

CLASSIFIER_API_URL=http://localhost:11434/v1/chat/completions
CLASSIFIER_API_KEY=not_required  # Ollama doesn't need auth; leave empty
CLASSIFIER_MODEL=llama3  # Or: mistral, gemma, phi, qwen, etc.

3. 更新 MCP 客户端配置： 只需更改现有 cc-mcp 配置中的 env 部分：

"env": {
  "CLASSIFIER_API_URL": "http://localhost:11434/v1/chat/completions",
  "CLASSIFIER_API_KEY": "not_required",
  "CLASSIFIER_MODEL": "llama3"
}

完成！CC-MCP 现在将使用本地 Ollama 模型进行意图分类。

---

💡 使用示例

1. 基本消息处理

import asyncio
from cc_mcp import process_user_message

async def demo():
    # Define core problem
    result = await process_user_message(
        "I want to build an AI assistant for customer support"
    )
    print("Intent:", result["metadata"]["intent_classification"]["intent"])
    # Expected: ["PROBLEM_DEFINITION"]
    
    # Add constraints
    result = await process_user_message(
        "Budget is $50,000 and must be completed in 2 months"
    )
    print("Intent:", result["metadata"]["intent_classification"]["intent"])
    # Expected: ["CONSTRAINT_ADDITION"]
    
    # Ask unrelated question - context still preserved!
    result = await process_user_message(
        "What's the weather like today?"
    )
    # AI response will still maintain awareness of the support system project!

asyncio.run(demo())

2. 上下文管理

# Export current conversation state
context_data = await export_context(session_id="my-session")
print(f"Core Problem: {context_data['core_problem']}")
print(f"Active Constraints: {len(context_data['constraints'])}")

# Clear context for fresh start
await clear_context(session_id="my-session")

# Import previously saved context
await import_context(json_state=context_data, session_id="my-session")

3. 多会话管理

# Start new session
session_info = await start_session()
session_id = session_info["session_id"]

# Process messages in specific session
await process_user_message(
    message="Design a mobile app",
    session_id=session_id
)

# Check session statistics
stats = await get_session_stats(session_id=session_id)
print(f"Messages: {stats['total_messages']}")
print(f"Active Constraints: {stats['active_constraints']}")

---

🔧 高级配置

自定义意图标签

# Extend intent classification in intent_classifier.py
CUSTOM_INTENTS = {
    "TECHNICAL_SPEC": "User is providing technical specifications",
    "BUDGET_CHANGE": "User is modifying budget constraints",
    "TIMELINE_UPDATE": "User is adjusting project timeline"
}

上下文存储优化

# Configure in context_store.py
CONTEXT_CONFIG = {
    "max_core_contexts": 3,      # Maximum core problems per session
    "max_evolving_items": 10,    # Maximum constraints/refinements
    "turn_history_limit": 5,     # Recent conversation turns to keep
    "auto_cleanup": True         # Automatic memory optimization
}

API 参数调优

# Optimize for your use case
CLASSIFIER_PARAMS = {
    "temperature": 0.1,          # Lower for consistency
    "max_tokens": 150,          # Sufficient for classification
    "top_p": 0.9               # Focus on high-probability responses
}

MAIN_LLM_PARAMS = {
    "temperature": 0.7,          # Higher for creativity
    "max_tokens": 2000,         # Generous for detailed responses
    "presence_penalty": 0.1     # Encourage diverse vocabulary
}

---

🌍 国际化支持

CC-MCP 在设计时充分考虑了国际化：

• 针对日语优化：原生日语意图分类
• 支持英语：完整的英文文档和示例
• 可扩展：轻松添加对其他语言的支持
• Unicode 安全：妥善处理所有字符编码

---

🤝 参与贡献

我们欢迎全球社区参与贡献！

如何参与贡献：

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

开发环境设置：

# Clone your fork
git clone https://github.com/YOUR-USERNAME/cc-mcp.git
cd cc-mcp

# Install development dependencies
uv sync --group dev

# Run pre-commit hooks
pre-commit install

# Run the full test suite
uv run pytest

---

📚 文档

使用指南（必读！）

• 📚 英文使用指南 - 完整的正确使用指南
• 📚 日本語使用ガイド - 正しい使い方の完全ガイド
• 📚 中文使用指南 - 正确使用的完整指南

---

🛟 支持与社区

• 🐛 报告问题 - Bug 报告和功能请求
• 💬 讨论 - 社区问答
• 📧 联系 - 直接支持

---

🏆 荣誉

CC-MCP 代表了 AI 对话管理领域的一项突破：

• 🥇 首个可用于生产环境的解决方案，解决大模型意图遗忘问题
• ⚡ 低于 300 ms 的性能，具备企业级可靠性
• 🔬 以研究为基础的架构，效果经过验证
• 🌐 开源，致力于推动 AI 技术发展

---

📄 许可证

此项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

---

🙏 致谢

• MCP Protocol Team - 感谢他们打造出色的 Model Context Protocol
• OpenAI & Azure OpenAI - 感谢他们提供强大的大模型 API
• FastAPI Community - 感谢他们提供稳健的 Web 框架
• UV Team - 感谢他们提供极速的 Python 包管理器

---