Sage MCP

🚀 🧙 SAGE-MCP: 面向Claude的簡易AI引導引擎

SAGE-MCP將Claude轉變為一位多才多藝的開發助手，可滿足你的各種需求。無論你是在調試代碼、規劃架構、編寫測試，還是進行技術討論，SAGE都能自動選擇合適的方法和模型，以達到最佳效果。

🚀 快速開始

安裝

# 克隆倉庫
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桌面端配置

在你的Claude桌面端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 mode） - 根據任務複雜度智能選擇模型
• 支持多個提供商：OpenAI、Anthropic、Google、OpenRouter
• 通過環境變量限制模型使用，以控制成本
• 思考深度控制：最低（0.5%）、低（8%）、中（33%）、高（67%）、最高（100%）

📁 智能文件處理

• 嵌入（embedded） - 在上下文中包含完整文件內容（默認）
• 摘要（summary） - 針對大型代碼庫的高效令牌摘要
• 引用（reference） - 使用ID引用的文件存儲
• 自動目錄擴展和智能去重
• 所有文件操作均進行安全驗證

🌐 網絡搜索集成

• 即時文檔查找
• 最佳實踐和當前標準查詢
• 框架和庫研究
• 錯誤和問題調查

🎨 模式特性

💻 使用示例

基礎聊天

// 在Claude中：
使用sage工具解釋Python中async/await的工作原理

帶文件的代碼分析

// 分析特定文件
使用sage工具的分析模式評審./src/api/的架構

// 選擇模型
使用sage搭配gpt-4o模型分析server.py中的性能瓶頸

多輪對話

// 第一輪
使用sage幫助我設計一個緩存系統

// 繼續對話（Claude會自動延續）
現在讓我們實現我們討論過的LRU緩存

// 文件會在各輪對話中自動去重

深度思考模式

// 用於需要深度推理的複雜問題
使用sage的思考模式，設置thinking_mode="high"來解決這個算法挑戰：[問題描述]

智能文件處理

// 針對大型代碼庫的高效令牌模式
使用sage搭配file_handling_mode="summary"評審整個項目結構

// 用於迭代工作的引用模式
使用sage搭配file_handling_mode="reference"開始重構數據庫層

📚 詳細文檔

配置

環境變量

# 提供商配置
DEFAULT_PROVIDER=openai          # 默認：自動
DEFAULT_MODEL=gpt-4o            # 默認：自動
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="讓我們設計一個Web應用")
# 返回：continuation_id: abc123

# 在同一模式下繼續
sage(mode="chat", prompt="我們應該使用什麼數據庫？", continuation_id="abc123")

# 無縫切換模式
sage(mode="analyze", prompt="評審我們的數據庫架構", 
     files=["/db/schema.sql"], continuation_id="abc123")

智能文件處理

# 多種模式可用
sage(mode="review", 
     files=["/src", "/tests"],           # 自動擴展目錄
     file_handling_mode="embedded",      # 完整內容（默認）
     prompt="安全評審")

sage(mode="analyze",
     files=["/large/codebase"], 
     file_handling_mode="summary",       # 僅摘要（節省令牌）
     prompt="架構概述")

sage(mode="debug",
     files=["/logs"],
     file_handling_mode="reference",     # 使用ID存儲
     prompt="分析錯誤模式") 

模型限制

# 用於成本控制的環境變量
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

# 自動模式在受限情況下需要選擇模型
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助手 🧙✨