MCP server providing multi-advisor AI consultations via OpenRouter API with advanced caching, rate limiting, and security features
npm install mcp-smartA powerful MCP (Model Context Protocol) server that provides intelligent AI routing and multi-advisor consultations through OpenRouter API. Get expert coding advice from 6 premium AI models with smart routing, advanced caching, rate limiting, and security features.
- 🧠 Smart Routing System - Intelligent provider selection based on task requirements
- 🎲 Random Mode - NEW! Randomly selects from all available providers for unpredictable results
- 🤖 6 Premium AI Providers - Claude Sonnet 4.5, OpenAI GPT-5 Pro, xAI Grok 4, Google Gemini 3 Pro, DeepSeek v3.2, Moonshot Kimi-K2 Thinking
- ⚡ Intelligent Caching - LRU cache with configurable TTL to reduce API costs
- 🛡️ Security First - Input validation, prompt injection detection, and rate limiting
- 📊 Comprehensive Logging - Structured logging with cache metrics and health monitoring
- ⚙️ Fully Configurable - Environment variables for all settings
- 🔄 Retry Logic - Exponential backoff with Promise.allSettled for resilient API calls
- 🔄 Circuit Breakers - Individual provider protection with automatic failover
bash
npx mcp-smart@1.5.7
`$3
bash
npm install -g mcp-smart@1.5.7
`$3
bash
mcp-smart
`$3
bash
Install and test the new random routing feature
npx mcp-smart@1.5.7In your MCP client, try:
model: "random" - for unpredictable AI provider selection
`🔧 Configuration
Set your OpenRouter API key and configure the server:
bash
export OPENROUTER_API_KEY="your-api-key-here"
export MAX_RETRIES=3
export REQUEST_TIMEOUT=30000
export CACHE_TTL=300000
export MAX_TOKENS=4000
export MAX_CACHE_SIZE=100
export RATE_LIMIT_REQUESTS=10
export RATE_LIMIT_WINDOW=60000
Circuit Breaker Configuration
export CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
export CIRCUIT_BREAKER_RECOVERY_TIMEOUT=60000
export CIRCUIT_BREAKER_MONITORING_PERIOD=300000
export CIRCUIT_BREAKER_HALF_OPEN_MAX_CALLS=3
`$3
| Variable | Default | Description |
|----------|---------|-------------|
|
| Required | Your OpenRouter API key |
| MAX_RETRIES | 3 | Maximum retry attempts for failed requests |
| REQUEST_TIMEOUT | 30000 | Request timeout in milliseconds |
| CACHE_TTL | 300000 | Cache time-to-live in milliseconds (5 min) |
| MAX_TOKENS | 4000 | Maximum tokens per API request |
| MAX_CACHE_SIZE | 100 | Maximum number of cached responses |
| MAX_TASK_LENGTH | 10000 | Maximum task input length |
| MAX_CONTEXT_LENGTH | 20000 | Maximum context input length |
| RATE_LIMIT_REQUESTS | 10 | Requests per rate limit window |
| RATE_LIMIT_WINDOW | 60000 | Rate limit window in milliseconds (1 min) |
| CIRCUIT_BREAKER_FAILURE_THRESHOLD | 5 | Consecutive failures before opening circuit breaker |
| CIRCUIT_BREAKER_RECOVERY_TIMEOUT | 60000 | Time to wait before attempting recovery (ms) |
| CIRCUIT_BREAKER_MONITORING_PERIOD | 300000 | Circuit breaker monitoring window (ms) |
| CIRCUIT_BREAKER_HALF_OPEN_MAX_CALLS | 3 | Max calls allowed in half-open state |🎯 Usage with Claude Code
Add to your
claude-code-config.json:`json
{
"mcpServers": {
"smart-advisor": {
"command": "npx",
"args": ["mcp-smart@1.5.7"],
"env": {
"OPENROUTER_API_KEY": "your-openrouter-api-key-here"
}
}
}
}
`$3
To enable automatic Smart advisor access in Claude Code, add this to your
file (or local project CLAUDE.md). This hooks the MCP server with Claude's agent system:`markdown
When facing uncertainty and needing advice, you have exclusive access to L7 Google programmer named Smart. Ask him when appropriate using these terms: smart_advisor, code_review, get_advice, expert_opinion, smart_llm. You can specify what you're looking for, these are the modes available:
- auto - GPT-5 Mini intelligently selects the best provider
- intelligence - Routes to Claude Sonnet 4.5 (ultimate reasoning)
- premium - Routes to OpenAI GPT-5 Pro (high-end reasoning)
- speed - Routes to xAI Grok 4 (fast responses)
- balance - Routes to Google Gemini 3 Pro (cost/performance balance)
- cost - Routes to DeepSeek v3.2 (budget-friendly)
- all - Multi-provider consultation (all providers)
`This integration allows Claude Code to automatically consult the Smart advisor when encountering complex coding problems or needing expert opinions.
🤖 AI Providers & Intelligence Ranking
$3
| Provider | Intelligence | Cost | Speed | Context | Strengths |
|----------|-------------|------|-------|---------|-----------|
| Claude Sonnet 4.5 | 🔥 Ultimate | High | Medium | Very High | Supreme reasoning, ethical coding, comprehensive solutions |
| OpenAI GPT-5 Pro | 🏆 Highest | Very High | Slow | Medium | Complex reasoning, creativity, advanced coding |
| xAI Grok 4 | ⭐ Very High | Medium | Fast | High | Real-time data, creative thinking, fast responses |
| Google Gemini 3 Pro | ⭐ Very High | Low | Fast | Highest (2M) | Multimodal, research, long-context, speed |
| DeepSeek v3.2 | ✅ High | Low | Fast | Medium | Cost-effective, coding/logic/math, analysis |
| Moonshot Kimi-K2 Thinking | ⭐ Very High | Medium | Fast | Highest (2M) | Chinese language, reasoning, coding, long-context |
🎛️ Smart Routing Strategies
$3
| Strategy | Provider | Use Case | Description |
|----------|----------|----------|-------------|
|
⚡ | GPT-5 Mini decides | Default smart routing | Intelligent provider selection based on task |
| intelligence 🔥 | Claude Sonnet 4.5 | Ultimate reasoning | Most capable model for complex problems |
| premium 🏆 | OpenAI GPT-5 Pro | Premium alternative | High-end reasoning and creativity |
| speed 🚀 | xAI Grok 4 | Fast responses | Quick turnaround with real-time data |
| balance ⚖️ | Google Gemini 3 Pro | Cost/performance | Optimal balance of speed, cost, and capability |
| cost 💰 | DeepSeek v3.2 | Budget-friendly | Maximum cost efficiency |
| random 🎲 | Random provider | Unpredictable | Randomly selects from all available providers |
| all 🌟 | All providers | Comprehensive | Multi-provider consultation |$3
- claude - Force Claude Sonnet 4.5
- openai - Force OpenAI GPT-5 Pro
- xai - Force xAI Grok 4
- google - Force Google Gemini 3 Pro
- deepseek - Force DeepSeek v3.2
- moonshot - Force Moonshot Kimi-K2 Thinking💡 Example Usage
$3
`typescript
// Let GPT-4o-mini choose the best provider
await smart_advisor({
model: "auto",
task: "Optimize this React component for performance",
context: "Component renders 10,000+ items with complex state"
});
`$3
typescript
// Maximum intelligence for complex problems
await smart_advisor({
model: "intelligence", // Routes to Claude Sonnet 4.5
task: "Design a fault-tolerant distributed system architecture",
context: "Microservices with 99.99% uptime requirement"
});// Speed-optimized responses
await smart_advisor({
model: "speed", // Routes to xAI Grok 4
task: "Quick debugging help for this JavaScript error",
context: "TypeError in production, need fast solution"
});
// Cost-effective solutions
await smart_advisor({
model: "cost", // Routes to DeepSeek v3.2
task: "Write a simple sorting algorithm",
context: "Basic coding task for learning"
});
// Random provider selection
await smart_advisor({
model: "random", // Randomly selects from all providers
task: "Refactor this function for better readability",
context: "Legacy code that needs modernization"
});
`$3
The random routing strategy offers unique advantages:
- 🔍 Provider Testing - Compare different AI approaches to the same problem
- ⚖️ Load Balancing - Distribute requests across providers automatically
- 🎯 Bias Reduction - Avoid over-reliance on a single provider
- 🚀 Discovery - Uncover unexpected solutions from different AI models
- 🔄 Experimentation - Perfect for A/B testing AI provider performance
typescript
// Great for testing different perspectives
for (let i = 0; i < 5; i++) {
const result = await smart_advisor({
model: "random",
task: "Explain this complex algorithm",
context: "University-level computer science"
});
console.log(Attempt ${i + 1}: Different AI perspective);
}
`$3
typescript
// Get perspectives from all providers
await smart_advisor({
model: "all",
task: "Review this security-critical authentication system",
context: "OAuth2 implementation handling sensitive user data"
});
`$3
typescript
// Use specific provider directly
await smart_advisor({
model: "claude",
task: "Ethical considerations for AI system design",
context: "Building recommendation engine for social media"
});
`🏗️ Architecture
The server implements a structured 4-persona prompt system:
1. Manager - Defines clear requirements and ensures understanding
2. Smart Technical Advisor - Creates detailed technical architecture with deep insights
3. QA - Implements comprehensive tests covering edge cases and bottlenecks
4. Engineer - Provides production-ready, secure, and efficient code
$3
User Request → GPT-4o-mini Analysis → Provider Selection → Response
↓
[Task Complexity Assessment]
↓
[Cost/Performance/Speed Requirements]
↓
[Optimal Provider Routing]
🛡️ Security Features
- Prompt Injection Detection - Advanced pattern recognition for malicious inputs
- Script Injection Prevention - Blocks XSS and code injection attempts
- Input Validation - Length limits and comprehensive sanitization
- Rate Limiting - Configurable request limits per time window
- Security Logging - Detailed audit trail for security events
🔄 Resilience & Fault Tolerance
$3
- Provider Protection - Individual circuit breakers for each AI provider
- Automatic Failover - Smart fallback to healthy providers when others fail
- Self-Healing - Automatic recovery testing with configurable timeouts
- State Management - CLOSED, OPEN, and HALF_OPEN states with proper transitions
- Failure Thresholds - Configurable consecutive failure limits before opening
- Monitoring - Real-time circuit breaker status and metrics tracking📈 Performance & Monitoring
$3
- LRU Caching - Intelligent cache eviction based on usage patterns
- Cache Metrics - Real-time hit/miss ratios and performance tracking
- TTL Management - Configurable cache expiration$3
- Circuit Breakers - Individual protection for each AI provider with automatic failover
- Promise.allSettled - Graceful handling of provider failures
- Intelligent Fallback - Hierarchical fallback to healthy providers based on capability ranking
- Exponential Backoff - Smart retry logic for transient failures
- Health Monitoring - Comprehensive system health checks including circuit breaker status
- Provider Recovery - Automatic testing and recovery of failed providers$3
typescript
// Access real-time metrics
const health = server.getHealthCheck();
const cacheMetrics = server.getCacheMetrics();
`🔍 Advanced Features
$3
- System uptime tracking
- Cache performance metrics
- Rate limit monitoring
- Provider failure tracking
- Version information$3
- Hit/miss ratio tracking
- Eviction monitoring
- Size management
- Performance optimization$3
- Injection attempt detection
- Rate limit violations
- Input validation failures
- Security event logging🛠️ Development
bash
Clone the repository
git clone https://github.com/sliday/mcp-smart.git
cd mcp-smartInstall dependencies
npm installBuild the project
npm run buildRun in development mode
npm run devRun tests (44/45 passing)
npm testRun tests with coverage
npm run test:coverage
`🧪 Testing
The project maintains high test coverage with 44/45 tests passing:
- Unit tests for all providers and routing strategies
- Integration tests for end-to-end workflows
- Security tests for injection detection
- Performance tests for caching and rate limiting
- Error handling and fallback testing
📊 Version History
$3
- 🚀 Major Model Updates - All providers upgraded to latest versions
- ✨ Claude Sonnet 4 → Claude Sonnet 4.5 (enhanced reasoning)
- ✨ OpenAI o3 → OpenAI GPT-5 Pro (next-generation intelligence)
- ✨ xAI Grok-3-beta → xAI Grok 4 (improved speed and accuracy)
- ✨ Google Gemini Flash → Google Gemini 3 Pro (enhanced capabilities)
- ✨ DeepSeek v3-0324 → DeepSeek v3.2 (improved coding performance)
- ✨ Moonshot Kimi-K2 → Moonshot Kimi-K2 Thinking (reasoning enhancement)
- ✨ Router: GPT-4o-mini → GPT-5 Mini (smarter routing decisions)
- 📚 Updated all documentation with new model names
- 🎯 Improved routing prompts with latest model capabilities$3
- ✨ Added random routing strategy for unpredictable provider selection
- 🎲 New MIT License - see LICENSE file for details.
Contributions are welcome! Please read our contributing guidelines and submit pull requests.
Report bugs and request features at GitHub Issues.
If you find this project helpful, please give it a star on GitHub!
---
Built with ❤️ for the MCP ecosystem
Powered by Claude Sonnet 4.5, OpenAI GPT-5 Pro, xAI Grok 4, Google Gemini 3 Pro, DeepSeek v3.2, and Moonshot Kimi-K2 Thinking