# Clone the repository
git clone https://github.com/david-strejc/sage-mcp
cd sage-mcp

# Install dependencies
pip install -r requirements.txt

# Configure your API keys
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"

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

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

// Analyze specific files
Use sage tool in analyze mode to review the architecture of ./src/api/

// With model selection
Use sage with model gpt-4o to analyze performance bottlenecks in server.py

// First turn
Use sage to help me design a caching system

// Continue the conversation (Claude will auto-continue)
Now let's implement the LRU cache we discussed

// Files are automatically deduplicated across turns

// For complex problems requiring deep reasoning
Use sage in think mode with thinking_mode="high" to solve this algorithmic challenge: [problem description]

// Token-efficient mode for large codebases
Use sage with file_handling_mode="summary" to review the entire project structure

// Reference mode for iterative work
Use sage with file_handling_mode="reference" to start refactoring the database layer

# Provider Configuration
DEFAULT_PROVIDER=openai          # Default: auto
DEFAULT_MODEL=gpt-4o            # Default: auto
FALLBACK_MODEL=gpt-4o-mini      # Fallback for errors

# Model Restrictions (optional)
ALLOWED_MODELS=gpt-4o,gpt-4o-mini,claude-3-5-sonnet
DISALLOWED_MODELS=o1-preview,o1  # Expensive models to exclude

# Feature Flags
WEBSEARCH_ENABLED=true          # Enable web search
FILE_SECURITY_CHECK=true        # Validate file paths
AUTO_MODEL_SELECTION=true       # Smart model selection

# Token Limits
MAX_TOKENS_GPT4O=128000
MAX_TOKENS_CLAUDE=200000
MAX_THINKING_TOKENS_O1=100000

# Start conversation
response = sage(mode="chat", prompt="Let's design a web app")
# Returns: continuation_id: abc123

# Continue in same mode
sage(mode="chat", prompt="What database should we use?", continuation_id="abc123")

# Switch modes seamlessly  
sage(mode="analyze", prompt="Review our database schema", 
     files=["/db/schema.sql"], continuation_id="abc123")

# Multiple modes available
sage(mode="review",
     files=["/src", "/tests"],           # Auto-expands directories
     file_handling_mode="embedded",      # Full content (default)
     prompt="Security review")

sage(mode="analyze",
     files=["/large/codebase"],
     file_handling_mode="summary",       # Summaries only (saves tokens)
     prompt="Architecture overview")

sage(mode="debug",
     files=["/logs"],
     file_handling_mode="reference",     # Store with IDs
     prompt="Analyze error patterns")

# Save analysis directly to file instead of returning in response
sage(mode="analyze",
     files=["/src"],
     prompt="Full codebase analysis",
     output_file="/tmp/analysis.md")
# Returns: "Output saved to /tmp/analysis.md (15.2KB)"

# Great for:
# - Large code reviews
# - Documentation generation
# - Analysis reports
# - Any output you want to process later

# Environment variables for cost control
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 mode requires model selection when restricted
DEFAULT_MODEL=auto  # Forces explicit model choice

sage-mcp/
├── server.py           # FastMCP server entry point
├── config.py           # Configuration management
├── tools/
│   └── sage.py        # Universal SAGE tool
├── modes/             # Specialized AI modes
│   ├── base.py        # Base mode handler
│   ├── chat.py        # Conversational mode
│   ├── analyze.py     # Code analysis mode
│   ├── debug.py       # Debugging mode
│   └── ...
├── providers/         # AI provider integrations
│   ├── openai.py
│   ├── anthropic.py
│   ├── gemini.py
│   └── openrouter.py
├── models/           # Model management
│   ├── manager.py    # Intelligent model selection
│   └── config.yaml   # Model capabilities
└── utils/            # Utilities
    ├── files.py      # File handling
    ├── memory.py     # Conversation memory
    ├── models.py     # Model restrictions
    └── security.py   # Security validation

# Allow only specific models
export ALLOWED_MODELS="gpt-4o-mini,claude-3-haiku"

# Exclude expensive models
export DISALLOWED_MODELS="o1-preview,claude-3-opus"

# Automatically continues conversations
# Previous context and files are preserved
# Smart deduplication prevents re-reading

class CustomProvider(BaseProvider):
    async def generate(self, messages, **kwargs):
        # Your implementation
        pass

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Format code
black .
ruff check .