superai-mcp

Table of contents

TOC

• ✨ Features
  • Multi-Model Broadcast
  • Chain Pipeline
  • Vote Consensus
  • Multi-Round Debate
  • Batch Processing
  • Auto-Retry Fallback
  • Response Cache
  • Streaming Output
  • Model Discovery & Validation
  • Cost Tracking & Quota
  • Security
• 📦 Getting Started
  • Prerequisites
  • Installation
• 🛠️ Tools Reference
• 🧪 Testing
• 🤝 Contributing
• 📝 License

✨ Features

🔀 Multi-Model Broadcast

Send the same prompt to Claude, Codex, and Gemini in parallel and get aggregated results in a single response. Perfect for multi-perspective code reviews, comparing model reasoning, or finding consensus across different AI engines.

• Per-target model and parameter overrides via models and overrides
• System prompt injection for consistent instructions across all targets
• Built-in prompt templates: review, refactor, explain, test, debug, optimize

🔗 Chain Pipeline

Build sequential multi-model pipelines where each step's output automatically flows into the next. Chain different models for tasks that benefit from staged processing — draft with one, refine with another, verify with a third.

• Output auto-injected as <previous_output> tags between steps
• Stops on first failure with partial results returned
• End-to-end timeout budget across all steps

🗳️ Vote Consensus

Run candidates in parallel, then have a judge model pick the best answer. Get the most reliable output by leveraging the strengths of multiple models simultaneously.

• Judge auto-excluded from candidate pool
• Only successful candidate outputs forwarded to judge
• Fully configurable candidate and judge selection

💬 Multi-Round Debate

Stage an alternating debate between two models over multiple rounds. Each round sees the opponent's previous response. Ideal for exploring trade-offs, stress-testing solutions, or generating balanced analysis.

• Configurable number of debate rounds
• Opponent output injected as <opponent_response> tags
• Any two CLIs as debate sides

More Features

⚡ Batch Processing

Run N prompts against the same CLI concurrently in a single tool call. Bypasses stdio serialization bottleneck with server-side dispatch via asyncio.Semaphore. Up to 20 tasks with configurable concurrency.

🔁 Auto-Retry Fallback

Automatic cascading degradation on rate-limit, server error, or timeout. Retryable patterns include RESOURCE_EXHAUSTED, overloaded_error, 429, 5xx, timed out, etc.

CLI	Fallback Strategy	Example
Gemini	Switch to flash model	pro → flash
Claude	Model downgrade	current → sonnet → haiku
Codex	Reduce reasoning effort	high → medium → low

🗄️ Response Cache

Opt-in LRU+TTL in-memory cache (use_cache=True). Identical requests (same cli+cd+prompt+model) return cached results instantly. Configure via SUPERAI_MCP_CACHE_TTL (default 300s) and SUPERAI_MCP_CACHE_MAXSIZE (default 128).

📡 Streaming Output

Real-time push of AI response chunks via MCP ctx.info() notifications (stream=True). Get immediate visibility into long-running tasks while the final complete response is still returned as the tool result.

🔍 Model Discovery & Validation