CC-MCP

🧠 CC-MCP（Context Consistent MCP Server）

🌐 言語 / 言語 / 语言

• English（現在の表示）
• 日本語 - 日本語版
• 中文 - 中国語版

⚠️ 重要：適切な使用ガイドをご確認ください

• 📚 English Guide - セッション管理に必要な知識
• 📚 日本語ガイド - セッション管理の必須知識
• 📚 中文指南 - 会话管理必备知识

🌟 革新的な AI コンテキスト管理：長時間の会話における LLM の記憶喪失を解決

LLM を活用した AI エージェントのための、長期的な会話の一貫性管理システム

---

🚀 解決する課題

従来の LLM は、長時間の会話で「意図を忘れる」問題に悩まされています：

• ❌ 数回のやり取りの後、当初の目標を見失う
• ❌ 重要な制約や決定事項を忘れる
• ❌ 対話セッション間で一貫性のない回答をする
• ❌ ユーザーが AI にコンテキストを繰り返し伝える必要がある

CC-MCP は、LLM が一貫性を維持できるよう支援する、インテリジェントなコンテキスト管理ツールを提供します。

---

これを 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 を使用する場合： OpenAI の代わりに Ollama を使用する場合は、環境変数を次のように変更してください：

• CLASSIFIER_API_URL を Ollama サーバーの URL に変更します（例：http://localhost:11434/v1/chat/completions）
• CLASSIFIER_MODEL を使用する Ollama モデルに変更します（例：llama3.2）
• Ollama では不要なため、CLASSIFIER_API_KEY を削除するか、空欄にします

Ollama の設定例：

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

前提条件：

• Python 3.13+
• uv パッケージマネージャー
• LLM API へのアクセス（Azure OpenAI、OpenAI など）、または Ollama などのローカル LLM
• 環境を設定済みであること（クイックスタートを参照）

---

✨ 主な機能

🏗️ 階層型コンテキストアーキテクチャ

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 で定義）：

分類ロジックは、ユーザーのメッセージを分析し、次のいずれかのラベルを 1 つ以上割り当てるよう LLM に指示するプロンプトに基づいています：

• PROBLEM_DEFINITION：ユーザーが解決したい中心的な課題を定義しています。

  • プロンプトの例：「AI で議事録を自動的に要約したいのですが、何か良い方法はありますか？」

• CONSTRAINT_ADDITION：予算やスケジュールなどの制約や条件を追加しています。

  • プロンプトの例：「いいですね。ただし、使用するモデルはオープンソースのものに限定してください。」

• REFINEMENT：既存の要件をより具体的にする、または変更しています。

• QUESTION：簡単な質問をしています。

• UNCLEAR：メッセージを上記のいずれのカテゴリにも明確に分類できません。

🔧 インテリジェントなコンテキスト管理

• コンテキスト認識型：3 つの階層レベルにまたがるコンテキストを自動的に整理します
• 目的重視型：中核となる課題と目標を把握します
• 制約準拠型：蓄積された制約や決定事項を追跡し、適用します

メモリ管理の実装方法：

「インテリジェントなコンテキストの枝刈りと最適化」は、HierarchicalContextStore（context_store.py）内で多面的なアプローチによって実現されています。

1. 階層型コンテキストストレージ：システムは情報を3つの階層に分類し、コンテキストの劣化を防ぎます。

   • コアコンテキスト：主要な問題の定義を保持し、主な目標が失われないようにします。
   • 進化するコンテキスト：制約と改良点のリストを保存し、解決策の範囲を段階的に絞り込めるようにします。
   • ターンコンテキスト：直近の会話の流れを維持するため、会話の直近数ターンを保持する短期メモリです。

2. ターンコンテキストの自動的な枝刈り：メモリの肥大化を防ぐため、turn_contextは自動的に整理されます。_trim_turn_context()メソッドにより、最新のメッセージ（デフォルト：6件）のみが保持され、古く関連性の低いターンは破棄されます。

3. キーワードベースの最適化：システムは全文履歴に依存する代わりに、CoreおよびEvolvingコンテキストの重み付きキーワードを抽出して保存します。次に、get_context_summary()メソッドが、キーワードを活用した簡潔な要約をLLMに提供します。これは、生の会話履歴よりもはるかに効率的に処理できます。

この構造化されたルールベースのアプローチにより、メモリを効率的かつインテリジェントに管理し、LLMに過剰な負荷をかけずに、最も重要な情報へアクセスできるようにします。

📊 統計的キーワード抽出

• TF-IDFを活用：TF-IDFアルゴリズムを使用して、会話から最も重要なキーワードを特定し、抽出します。
• コンテキストの要約：主要な問題と進化する制約をキーワードベースで簡潔に要約します。これにより、LLMがより効率的に処理できます。
• 動的コーパス：キーワード抽出エンジンは、新しい会話ごとに文書コーパスを継続的に更新し、時間とともに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]

コンポーネントの説明：

このサーバーは、コンテキストを考慮した応答を実現するために連携する、3 つの中核コンポーネントで構成されています。

1. Intent Classifier (intent_classifier.py)：

   • 機能：ユーザーのメッセージを分析し、その根底にある目的を判断します。
   • 実装：慎重に作成されたプロンプトを使用して、ユーザーのメッセージを外部 LLM（GPT やローカルの Ollama モデルなど）に送信します。このプロンプトは、メッセージを PROBLEM_DEFINITION、CONSTRAINT_ADDITION、REFINEMENT、QUESTION、UNCLEAR の 5 つのインテントのいずれかに分類するよう LLM に求めます。

2. Context Store (context_store.py)：

   • 機能：システムの「メモリ」です。会話のコンテキストを階層構造で整理し、保存します。
   • 実装：3 層構造を採用しています。主な問題には 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 です。直接 HTTP 通信するための SSE（Server-Sent Events）もサポートしており、エンドポイントには http://127.0.0.1:8001/sse/ を使用します。

---

📦 クイックスタート

前提条件

• Python 3.13+
• uv package manager
• LLM API へのアクセス（Azure OpenAI、OpenAI など）、または Ollama などのローカル LLM。
• 環境設定（クイックスタートを参照）

インストール

# 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（ローカル LLM）の使用

CC-MCP は、API コストなしでローカル LLM を利用できるよう、Ollama をサポートするようになりました。この機能は最近のコミットで追加されました。

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. Context Management

# 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. Multi-Session Management

# 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']}")

---

🔧 Advanced Configuration

Custom Intent Labels

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

Context Storage Optimization

# 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 Parameter Tuning

# 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
}

---

🌍 International Support

CC-MCP is designed with internationalization in mind:

• Japanese-Optimized: Native Japanese intent classification
• English Support: Full English documentation and examples
• Extensible: Easy to add support for additional languages
• Unicode-Safe: Handles all character encodings properly

---

🤝 Contributing

We welcome contributions from the global community!

How to Contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup:

# 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

---

📚 Documentation

Usage Guides (Essential Reading!)

• 📚 English Usage Guide - Complete guide for proper usage
• 📚 日本語使用ガイド - 正しい使い方の完全ガイド
• 📚 中文使用指南 - 正确使用的完整指南

---

🛟 Support & Community

• 🐛 Report Issues - Bug reports and feature requests
• 💬 Discussions - Community Q&A
• 📧 Contact - Direct support

---

🏆 Recognition

CC-MCP represents a breakthrough in AI conversation management:

• 🥇 First Production-Ready Solution for LLM intent forgetting
• ⚡ Sub-300ms Performance with enterprise-grade reliability
• 🔬 Research-Backed architecture with proven effectiveness
• 🌐 Open Source commitment to advancing AI technology

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• MCP Protocol Team - For the excellent Model Context Protocol
• OpenAI & Azure OpenAI - For powerful LLM APIs
• FastAPI Community - For the robust web framework
• UV Team - For the lightning-fast Python package manager

---