Sage MCP

🚀 🧙 SAGE-MCP: Simple AI Guidance Engine for Claude

SAGE-MCPは、Claudeをあなたのニーズに合わせた多機能な開発アシスタントに変えます。コードのデバッグ、アーキテクチャの計画、テストの作成、技術的な議論など、どのような作業でも、SAGEは最適な結果を得るために適切なアプローチとモデルを自動的に選択します。

インテリジェントなモード選択、会話の継続性、スマートなファイル処理を備えた汎用AIアシスタントMCPサーバー

🚀 クイックスタート

インストール

# リポジトリをクローンする
git clone https://github.com/david-strejc/sage-mcp
cd sage-mcp

# 依存関係をインストールする
pip install -r requirements.txt

# APIキーを設定する
export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"
export GOOGLE_API_KEY="your-key-here"
export OPENROUTER_API_KEY="your-key-here"

Claude Desktopの設定

Claude DesktopのMCP設定に以下を追加します。

{
  "mcpServers": {
    "sage": {
      "command": "python",
      "args": ["/path/to/sage-mcp/server.py"],
      "env": {
        "OPENAI_API_KEY": "your-key",
        "ANTHROPIC_API_KEY": "your-key",
        "DEFAULT_MODEL": "gpt-4o",
        "DEFAULT_PROVIDER": "openai"
      }
    }
  }
}

✨ 主な機能

🎯 インテリジェントモードシステム

• chat - コンテキストを考慮した自然な会話
• analyze - 深いコード分析とパターン認識
• review - 実行可能なフィードバックを伴う包括的なコードレビュー
• debug - 体系的なデバッグと根本原因分析
• plan - 戦略的なプロジェクト計画とアーキテクチャ設計
• test - カバレッジ分析を伴うテスト生成
• refactor - コードの改善と近代化
• think - 思考深度を調整可能な深い推論

🔄 会話の継続性

• 異なるモード間でのシームレスな複数ターンの会話
• ツール呼び出し間での自動コンテキスト保存
• スマートなファイル重複排除 - 同じファイルを再読み込みすることはありません
• 長時間実行されるタスクのためのスレッドベースのメモリシステム

🤖 スマートモデル選択

• Autoモード - タスクの複雑性に基づくインテリジェントなモデル選択
• 複数のプロバイダーをサポート: OpenAI、Anthropic、Google、OpenRouter
• コスト管理のための環境変数によるモデル制限
• 思考深度の制御: 最小 (0.5%)、低 (8%)、中 (33%)、高 (67%)、最大 (100%)

📁 インテリジェントファイル処理

• embedded - コンテキスト内の完全なファイル内容 (デフォルト)
• summary - 大規模なコードベースのためのトークン効率の良い要約
• reference - ID参照によるファイル保存
• 自動ディレクトリ展開とスマートな重複排除
• すべてのファイル操作のセキュリティ検証

🌐 ウェブ検索統合

• リアルタイムのドキュメント検索
• ベストプラクティスと最新の標準
• フレームワークとライブラリの調査
• エラーと問題の調査

🎨 モードの特化

💻 使用例

基本的なチャット

// Claudeで:
Use sage tool to explain how async/await works in Python

ファイルを使用したコード分析

// 特定のファイルを分析する
Use sage tool in analyze mode to review the architecture of ./src/api/

// モデル選択を伴う
Use sage with model gpt-4o to analyze performance bottlenecks in server.py

複数ターンの会話

// 最初のターン
Use sage to help me design a caching system

// 会話を続ける (Claudeが自動的に続けます)
Now let's implement the LRU cache we discussed

// ターン間でファイルは自動的に重複排除されます

深い思考モード

// 深い推論を必要とする複雑な問題の場合
Use sage in think mode with thinking_mode="high" to solve this algorithmic challenge: [problem description]

スマートファイル処理

// 大規模なコードベースのためのトークン効率の良いモード
Use sage with file_handling_mode="summary" to review the entire project structure

// 反復作業のための参照モード
Use sage with file_handling_mode="reference" to start refactoring the database layer

⚙️ 設定

環境変数

# プロバイダー設定
DEFAULT_PROVIDER=openai          # デフォルト: auto
DEFAULT_MODEL=gpt-4o            # デフォルト: auto
FALLBACK_MODEL=gpt-4o-mini      # エラー時のフォールバック

# モデル制限 (オプション)
ALLOWED_MODELS=gpt-4o,gpt-4o-mini,claude-3-5-sonnet
DISALLOWED_MODELS=o1-preview,o1  # 高価なモデルを除外

# 機能フラグ
WEBSEARCH_ENABLED=true          # ウェブ検索を有効にする
FILE_SECURITY_CHECK=true        # ファイルパスを検証する
AUTO_MODEL_SELECTION=true       # スマートモデル選択を有効にする

# トークン制限
MAX_TOKENS_GPT4O=128000
MAX_TOKENS_CLAUDE=200000
MAX_THINKING_TOKENS_O1=100000

モード固有の温度

各モードに最適化されたデフォルトの温度:

• chat: 0.5 - バランスの取れた創造性
• analyze: 0.2 - 集中的な精度
• review: 0.3 - 体系的な評価
• debug: 0.1 - 決定論的な分析
• plan: 0.4 - 戦略的な思考
• test: 0.2 - 正確なテスト生成
• refactor: 0.3 - 慎重な改善
• think: 0.7 - 創造的な問題解決

🔧 高度な機能

会話の継続

# 会話を開始する
response = sage(mode="chat", prompt="Let's design a web app")
# 返り値: continuation_id: abc123

# 同じモードで会話を続ける
sage(mode="chat", prompt="What database should we use?", continuation_id="abc123")

# シームレスにモードを切り替える
sage(mode="analyze", prompt="Review our database schema", 
     files=["/db/schema.sql"], continuation_id="abc123")

スマートファイル処理

# 複数のモードが利用可能
sage(mode="review", 
     files=["/src", "/tests"],           # ディレクトリを自動的に展開する
     file_handling_mode="embedded",      # 完全な内容 (デフォルト)
     prompt="Security review")

sage(mode="analyze",
     files=["/large/codebase"], 
     file_handling_mode="summary",       # 要約のみ (トークンを節約する)
     prompt="Architecture overview")

sage(mode="debug",
     files=["/logs"],
     file_handling_mode="reference",     # IDで保存する
     prompt="Analyze error patterns") 

モデル制限

# コスト管理のための環境変数
OPENAI_ALLOWED_MODELS=o3-mini,gpt-4o-mini
GOOGLE_ALLOWED_MODELS=gemini-2.0-flash-exp,gemini-1.5-pro
BLOCKED_MODELS=gpt-4,claude-opus
DISABLED_MODEL_PATTERNS=expensive,legacy

# 制限された場合、Autoモードでは明示的なモデル選択が必要
DEFAULT_MODEL=auto  # 明示的なモデル選択を強制する

サポートされるモデル

完全な設定リファレンス

🏗️ アーキテクチャ

sage-mcp/
├── server.py           # FastMCPサーバーのエントリポイント
├── config.py           # 設定管理
├── tools/
│   └── sage.py        # 汎用SAGEツール
├── modes/             # 特化したAIモード
│   ├── base.py        # 基本モードハンドラー
│   ├── chat.py        # 会話モード
│   ├── analyze.py     # コード分析モード
│   ├── debug.py       # デバッグモード
│   └── ...
├── providers/         # AIプロバイダーの統合
│   ├── openai.py
│   ├── anthropic.py
│   ├── gemini.py
│   └── openrouter.py
├── models/           # モデル管理
│   ├── manager.py    # インテリジェントモデル選択
│   └── config.yaml   # モデルの機能
└── utils/            # ユーティリティ
    ├── files.py      # ファイル処理
    ├── memory.py     # 会話メモリ
    ├── models.py     # モデル制限
    └── security.py   # セキュリティ検証

🧪 高度な機能

モデル制限

コストを管理するために使用できるモデルを制御します。

# 特定のモデルのみを許可する
export ALLOWED_MODELS="gpt-4o-mini,claude-3-haiku"

# 高価なモデルを除外する
export DISALLOWED_MODELS="o1-preview,claude-3-opus"

会話メモリ

SAGEはツール呼び出し間で会話コンテキストを維持します。

# 自動的に会話を続けます
# 以前のコンテキストとファイルは保存されます
# スマートな重複排除により再読み込みを防ぎます

カスタムプロバイダー

基本プロバイダーインターフェースを実装することで、カスタムAIプロバイダーを追加できます。

class CustomProvider(BaseProvider):
    async def generate(self, messages, **kwargs):
        # あなたの実装
        pass

🤝 コントリビューション

コントリビューションを歓迎します！ガイドラインについては CONTRIBUTING.md を参照してください。

開発環境のセットアップ

# 開発用の依存関係をインストールする
pip install -r requirements-dev.txt

# テストを実行する
pytest

# コードをフォーマットする
black .
ruff check .

📄 ライセンス

MITライセンス - 詳細については LICENSE を参照してください。

🙏 謝辞

• FastMCP フレームワークをベースに構築されています
• zen-mcp-server からインスピレーションを得ています
• Claude MCPプロトコルを使用しています

🔗 リンク

• GitHubリポジトリ
• イシュートラッカー
• MCPドキュメント

SAGE-MCP - あなたの作業スタイルに適応するインテリジェントなAIアシスタント 🧙✨