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助手 🧙✨