hive-mind-mcp 1.0.12

MCP Server for orchestrating LLM interactions

🧠 Hive Mind MCP - LLM Orchestrator

A powerful Model Context Protocol (MCP) server that enables advanced Multi-LLM collaboration workflows.

Transform simple chat interactions into sophisticated "Council of Experts" sessions. This orchestrator connects OpenAI, Anthropic, DeepSeek, Google Gemini, and Local models (Ollama) to debate, refine, and validate code and content autonomously.

✨ Key Features

• 🏰 Round Table: Run a full Round Table — Independent generation from 3+ models, cross-critique, and final consensus synthesis.

• 👥 Collaborative Refine: A "Drafter" model writes code, while a "Council" of critics (Claude + DeepSeek) reviews it iteratively.

• ✈️ Auto-Pilot (Adaptive Selection): Intelligent analysis of request complexity to automatically route tasks.

  graph LR
      Req[User Request] --> Analyzer{Complexity Analyzer}
      Analyzer -->|High Complexity| SOTA["SOTA Tier (GPT-4o)"]
      Analyzer -->|Medium| ADV["Advanced Tier (GPT-4o-mini)"]
      Analyzer -->|Low| BASIC["Basic Tier (Llama 3)"]
      SOTA --> Result
      ADV --> Result
      BASIC --> Result
  

• 🧠 Intelligence Tiers: Abstracted model selection using SOTA, ADVANCED, and BASIC tiers managed via config.yaml.

• 🏗️ Workflow Pipelines: Define complex sequential tasks.

  graph TD
      Start((Start)) --> Input[/Input/]
      Input --> Step1[Process]
      Step1 --> Decision{Check Condition}
      Decision -->|True| Step2[Step A]
      Decision -->|False| Step3[Step B]
      Step2 --> Final((End))
      Step3 --> Final
  

• 🛡️ Secure Sandbox: "Tool Agents" execute code in a controlled environment with strict validation using ToolAwareProvider.

  graph TD
      User[User Query] --> Moderator
      Moderator -->|Ask| A[Model A]
      Moderator -->|Ask| B[Model B]
      Moderator -->|Ask| C[Model C]
      A -->|Draft| XT[Cross-Critique]
      B -->|Draft| XT
      C -->|Draft| XT
      XT -->|Feedback| Moderator
      Moderator -->|Synthesize| Final[Consensus Answer]
  

• 📊 Observability Dashboard: Real-time Streamlit dashboard to track costs, sessions, and artifacts.

• 🌍 Global Configuration: Centralized config with easy overrides for models and API keys.

• 🔌 Dynamic Plugins: Drop-in .py files to add new LLM providers instantly without restarting.

---

🛠️ Installation

Option A: The "Pro" Way (Recommended)

Use pipx to install Hive Mind globally in an isolated environment. This keeps your system clean and makes the command available everywhere.

# 1. Install
pipx install hive-mind-mcp

# 2. Auto-Configure your Environment
hive-mind install

The installer will detect your setup and help you configure:

• Google Antigravity
• Claude Desktop
• VS Code

Option B: Standard Pip

pip install hive-mind-mcp

---

⚙️ Configuration

The hive-mind install command handles most configuration for you.

Global API Keys

The installer will prompt you to set up your API keys in a central location (~/.hive_mind/.env). This means you only need to configure them once, and they work for all your projects.

Manual Setup (Reference)

If you prefer manual configuration, the server details are:

• Command: hive-mind (or path to your venv python)
• Args: ['run']

---

🤖 Agentic IDE Integration

The Hive Mind MCP server is designed to be the "brain" behind your favorite editor. It is fully compatible with any environment that supports the Model Context Protocol (MCP) or can run terminal commands.

Supported Environments:

• VS Code: Via standard MCP extensions (e.g., Cline, Roo Code).
• Cursor: Use the "Composer" mode to run hive-mind commands directly.
• Windsurf: Integrate via its "Cascade" flows.
• Trae: Compatible with its "Builder" mode.
• Claude Desktop: Native support for MCP servers.
• Replit: Usable via the integrated shell.

How to Use

You can run these workflows directly inside your AI coding assistant without touching the terminal:

1. Slash Commands (if supported)

Simply type the command in the chat:

• /round_table "Topic" - Runs a full consensus session.
• /debate "Topic" - Runs a collaborative refinement.
• /review "Content" - Checks code/text for safety and logic errors.
• /analyze - Analyzes the project.

2. Natural Language

You can just ask your agent:

"Run a round table to decide the best database for this project."

User Request:

"Run the round table now on the review of the ARCHITECTURE.md document. Send them the source code for context with map-reduce"

Agent Execution:

hive-mind round_table "Review the attached ARCHITECTURE.md file. Does it accurately reflect the codebase structure in src/? Identify any missing features or inconsistencies." --context src/ ARCHITECTURE.md --map-reduce

---

🚀 CLI Usage Guide

The logic is built into the hive-mind command (formerly aliased as mcp).

⚡ Quick Guide: Which Command to Use?

Command	Goal	Best For	Example
round_table	Consensus	Big decisions, architecture, ambiguity.	"What DB should we use?"
debate	Refinement	Writing complex code, fixing tough bugs.	"Write a thread-safe Queue"
review	Verification	Auditing code, security checks, sanity checks.	"Check this file for bugs"
analyze	Understanding	Learning large codebases, finding patterns.	"Explain how auth works"
models	Discovery	Listing/Searching available models.	"List all GPT models"

---

1. Dashboard & Observability

Visualize your costs and session history in real-time.

Budget & Overview	Analytics & Insights

New Features:

• 🗓️ Date Filtering: Filter costs and analytics by custom date ranges.
• 🏷️ Provider & Type Filters: Drill down into specific providers (OpenAI, Anthropic) or session types (Round Table, Debate).
• 📉 Clean Visuals: Interactive charts with dual-axis cost tracking and responsive layouts.

Session Explorer (Audit Traces) > Deep dive into every decision made by the Council.

Model Catalog & Discovery > Dynamic discovery of every model available across all configured providers.

• Unified List: See all models from OpenAI, Anthropic, DeepSeek, Google, etc. in one place.
• Search & Filter: Quickly find specific models by name or provider.
• Live Status: Confirms which providers are correctly configured and active.

# Launch the dashboard
hive-mind dashboard

• 💰 Budget: Track daily spend limit vs actuals with granular provider filtering.
• 📊 Analytics: See which models are winning debates and analyze session trends.
• 🗂️ Explorer: Browse artifacts and metadata from previous Round Tables.

2. Round Table (hive-mind round_table)

Consensus Engine: Simulates a council of 3 diversity models (e.g., GPT-4, Claude, DeepSeek) debating a problem.

• Best for: Architecture decisions, ambiguous questions, strategy.
• Workflow: Independent Generation -> Cross-Critique -> Synthesis.

hive-mind round_table "What is the best architecture for this app?" --context README.md

3. Debate (hive-mind debate)

Refinement Engine: An iterative loop where a "Drafter" writes and "Reviewers" critique.

• Best for: Writing complex code, refactoring, fixing bugs.
• Workflow: Draft -> Critique -> Refine -> Critique -> Final.

hive-mind debate "Write a thread-safe Singleton" --max-turns 5

4. Review (hive-mind review)

Evaluation Engine: Submits existing content/code to the Council for a "Safety & Logic Check".

• Best for: Security audits, code review, checking generated content.
• Workflow: Reviewer 1 -> Pass/Fail + Reviewer 2 -> Pass/Fail -> Aggregated Report.

hive-mind review src/security.py --reviewers openai:gpt-4o anthropic:claude-3-opus

5. Analyze (hive-mind analyze)

Map-Reduce Engine: Summarizes large codebases file-by-file before answering.

• Best for: "How does this project work?", "Find security flaws in src/".
• Workflow: Chunk Files -> Summarize Each -> Aggregate -> Final Answer.

hive-mind analyze src "Explain the auth flow"

---

🔌 Plugins System

Expand the orchestrator with custom providers without modifying core code.

1. Create a plugins/ directory in your current folder.
2. Add a python file (e.g., plugins/my_custom_llm.py).
3. Define a class inheriting from LLMProvider with PROVIDER_NAME.

The orchestrator will automatically discover and load it!

---

❓ Troubleshooting

Issue	Cause	Fix
NotFoundError (Anthropic)	Model ID deprecated or invalid.	Update ANTHROPIC_MODELS in .env with new IDs (e.g., claude-sonnet-4-5...).
SettingsError / JSON	Env var has spaces or bad format.	Ensure lists in .env are comma-separated without brackets: MODEL_A,MODEL_B.
401 Unauthorized	Invalid API Key.	check hive-mind config and verify keys.
Dashboard Empty	No artifacts found.	Run a round_table command first to generate data.

---

🤝 Contributing

Contributions are welcome! Please see ARCHITECTURE.md for system design details.