moinsen-dev/mcp-hive

MCP-Hive 🐝

Collective Intelligence for AI Agents

Transform isolated AI agents into a collaborative intelligence network

🎯 Revolutionary AI Agent Collaboration

MCP-Hive is a Model Context Protocol (MCP) server that solves the critical problem of isolated agent operations. Instead of agents working in silos, MCP-Hive creates a shared intelligence network where agents can:

• 🧠 Share Knowledge - Solutions and insights flow between agents
• 🎯 Coordinate Tasks - Hierarchical goal and task management
• 📊 Learn Collectively - Past experiences inform future decisions
• 🔍 Find Experts - Locate agents with specific domain expertise
• 📈 Track Decisions - Maintain architectural decision history

✨ Enterprise-Grade Features

🗄️ Dual-Level Knowledge Management

• Global Repository: ~/.hive/ for cross-project patterns and learnings
• Project Context: .hive/ for project-specific knowledge and decisions
• Semantic Search: Advanced embedding-based knowledge retrieval
• Auto-categorization: Intelligent knowledge classification and tagging

🚀 Professional CLI Suite

• Interactive Init: mcp-hive init with guided configuration
• Real-time Status: mcp-hive status with comprehensive system overview
• Knowledge Operations: remember, recall, search commands
• Task Management: Complete task lifecycle management
• Data Operations: Export/import with backup and restore capabilities

📊 Web Dashboard

• Real-time Monitoring: Live agent activity and system metrics
• Visual Analytics: Knowledge graphs and task dependency visualization
• Interactive Management: Point-and-click knowledge and task operations
• System Health: Performance metrics and diagnostic tools

🔧 Developer Experience

• Zero-config Setup: One-command project initialization
• Hot Reload: Development server with automatic restarts
• TypeScript Native: Full type safety and IntelliSense support
• Extensive Testing: Unit, integration, and performance test suites

🚀 Installation & Quick Start

📦 NPX (Recommended - Zero Installation)

# Initialize your project
npx mcp-hive init

# Start the MCP server  
npx mcp-hive start

# Launch web dashboard
npx mcp-hive dashboard

# Check system status
npx mcp-hive status

🌍 Global Installation

# Install globally
npm install -g mcp-hive

# Use commands directly
mcp-hive init
mcp-hive start
mcp-hive dashboard

📁 Local Project Setup

# Add to your project
npm install mcp-hive --save-dev

# Configure package.json scripts
{
  "scripts": {
    "hive:start": "mcp-hive start",
    "hive:dashboard": "mcp-hive dashboard",
    "hive:status": "mcp-hive status"
  }
}

🐳 Docker Support

# Pull and run
docker run -p 8080:8080 -p 8081:8081 mcp-hive

# Or with docker-compose
docker-compose up -d

🛠️ Comprehensive MCP Tools Suite

MCP-Hive provides 22 powerful tools for sophisticated agent collaboration through the Goals→Plans→Tasks hierarchy:

🎯 Goals & Project Management (7 tools)

📋 Task & Workflow Management (4 tools)

📄 Plan Management & Approval (4 tools)

🧠 Knowledge Management (5 tools)

👥 Agent Coordination (3 tools)

🏛️ Decision Tracking (3 tools)

🔍 Discovery Tools (2 tools)

💻 CLI Command Reference

Core Operations

# Project setup
mcp-hive init [--name <project>] [--yes]

# Server management  
mcp-hive start [--port <port>] [--debug]
mcp-hive status [--json] [--watch]

# Knowledge operations
mcp-hive remember "Solution insight" --tags backend,auth
mcp-hive recall "authentication patterns"
mcp-hive search --query "database" --scope global

# Task management
mcp-hive tasks list [--filter active]
mcp-hive tasks add "Implement feature X" --parent <id>
mcp-hive tasks update <id> --status done

# Data operations
mcp-hive export backup.json --include knowledge,tasks
mcp-hive import backup.json --merge
mcp-hive clear --scope knowledge --backup

Dashboard & Monitoring

# Launch web interface
mcp-hive dashboard [--port 8080] [--open]

# System diagnostics
mcp-hive status --verbose
mcp-hive status --health-check

🏗️ Architecture & Technology Stack

System Architecture

graph TB
    A[AI Agents] --> B[MCP Protocol]
    B --> C[MCP-Hive Server]
    C --> D[SQLite Database]
    C --> E[Vectra Embeddings]
    C --> F[WebSocket Server]
    C --> G[REST API]
    F --> H[Web Dashboard]
    G --> I[CLI Tools]
    
    style C fill:#e1f5fe
    style D fill:#f3e5f5
    style E fill:#e8f5e8

Goals→Plans→Tasks Workflow

graph LR
    subgraph "🎯 Goals Layer"
        G1[High Priority Goal]
        G2[Medium Priority Goal]
        G3[Low Priority Goal]
    end
    
    subgraph "📄 Plans Layer"
        P1[Technical Plan]
        P2[Design Document]
        P3[Implementation Plan]
        
        P1_STATUS{Plan Status}
        P1_STATUS -->|Draft| P1_EDIT[💬 Comments & Review]
        P1_STATUS -->|In Review| P1_APPROVE[✅ Approval Process]
        P1_STATUS -->|Approved| P1_TASKS[⚙️ Generate Tasks]
    end
    
    subgraph "📋 Tasks Layer"
        T1[Sequence 0: Parallel Setup]
        T2[Sequence 1: Core Development]
        T3[Sequence 2: Integration & Testing]
        
        T1 --> T1A[Task A] & T1B[Task B] & T1C[Task C]
        T2 --> T2A[Task D] & T2B[Task E]
        T3 --> T3A[Task F]
    end
    
    %% Hierarchy Flow
    G1 --> P1 --> P1_STATUS
    G2 --> P2
    G3 --> P3
    
    P1_TASKS --> T1
    T1 --> T2
    T2 --> T3
    
    %% Styling
    classDef goalStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef planStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef taskStyle fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    
    class G1,G2,G3 goalStyle
    class P1,P2,P3,P1_STATUS,P1_EDIT,P1_APPROVE,P1_TASKS planStyle
    class T1,T2,T3,T1A,T1B,T1C,T2A,T2B,T3A taskStyle

📊 Data Model & Architecture

MCP-Hive uses a sophisticated Goals→Plans→Tasks hierarchy with comprehensive agent intelligence:

🎯 Core Workflow Entities

• Goals - High-level project objectives with priority management and target dates
• Planning Documents - Structured plans with approval workflows and collaborative commenting
• Tasks - Hierarchical task breakdown with sequence-based parallel execution
• Plan Comments - Threaded discussions for collaborative plan development
• Approval History - Complete audit trail of plan approval decisions

🧠 Knowledge & Intelligence

• Knowledge Base - Semantic knowledge with embeddings and type categorization
• Decisions - Architectural decision records with alternatives and implementation details
• Agent Expertise - Dynamic expertise scoring per topic and technology
• Agent Reputation - Performance metrics and reliability tracking

🔄 Coordination & Workflow

• Dependencies - Task dependency graph with blocking relationships
• Human Tasks - Human-in-the-loop coordination for approvals and decisions
• Activity Logs - Comprehensive system audit trail and performance analytics
• Parallel Execution - Sequence-based task coordination for concurrent work

📖 - Detailed entity relationships, workflows, and database schema

🔧 Technology Stack

• Runtime: Node.js 18+ with ES Modules
• Language: TypeScript with strict mode
• Database: SQLite with better-sqlite3 (synchronous)
• Embeddings: Vectra for local vector operations
• Protocol: MCP SDK for agent communication
• Web UI: Vanilla JS with WebSocket real-time updates
• Testing: Vitest with comprehensive test suites

📊 Performance Characteristics

• Query Response: < 100ms for knowledge recall
• Write Operations: < 50ms for knowledge storage
• Semantic Search: < 200ms for similarity matching
• Server Startup: < 500ms initialization time
• Memory Usage: < 50MB baseline consumption

🔌 API Documentation

REST API Endpoints

WebSocket Events

// Connect to real-time updates
const ws = new WebSocket('ws://localhost:8080');

// Available events
ws.on('knowledge_added', (data) => {});
ws.on('task_updated', (data) => {});  
ws.on('agent_activity', (data) => {});
ws.on('system_stats', (data) => {});

⚙️ Configuration

Automatic Setup

# Interactive configuration wizard
npx mcp-hive init

The initialization creates optimal configurations based on your setup:

NPX Configuration

{
  "mcpServers": {
    "mcp-hive": {
      "command": "npx",
      "args": ["mcp-hive-server"],
      "description": "MCP-Hive: Collective Intelligence Platform",
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Advanced Configuration

{
  "mcpServers": {
    "mcp-hive": {
      "command": "npx", 
      "args": ["mcp-hive-server"],
      "env": {
        "LOG_LEVEL": "debug",
        "HIVE_DB_PATH": ".hive/custom.db",
        "HIVE_GLOBAL_ENABLED": "true",
        "HIVE_EMBEDDINGS_MODEL": "all-MiniLM-L6-v2"
      }
    }
  }
}

🎭 Agent Ecosystems

MCP-Hive supports sophisticated multi-agent workflows:

🏢 Enterprise Development Team

• 🎯 Project Lead - Strategic planning and coordination
• 💻 Backend Developer - Server-side implementation
• 🎨 Frontend Developer - User interface development
• 🗄️ Database Architect - Data modeling and optimization
• 🔒 Security Engineer - Security implementation and auditing
• ☁️ DevOps Engineer - Infrastructure and deployment
• 🧪 QA Engineer - Testing and quality assurance

🔄 Collaborative Workflows

• Knowledge Sharing - Solutions propagate across team members
• Code Review - Automated pattern matching and best practices
• Decision Tracking - Architectural decisions with full context
• Progress Monitoring - Real-time task and milestone tracking

🧪 Development & Testing

Local Development Setup

# Clone repository
git clone https://github.com/moinsen-dev/mcp-hive.git
cd mcp-hive

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Run in separate terminal
pnpm cli dashboard

Testing Suite

# Run all tests
pnpm test

# Unit tests only
pnpm test:unit

# Integration tests
pnpm test:integration  

# Performance benchmarks
pnpm test:performance

# Coverage report
pnpm coverage

Build Process

# Production build
pnpm build

# Lint and format
pnpm lint
pnpm format

# Package verification  
pnpm pack --dry-run

📊 Performance Metrics & Benchmarks

🚀 Response Times

• Knowledge recall: < 100ms average
• Task operations: < 50ms average
• Dashboard load: < 2s initial load
• WebSocket latency: < 10ms real-time updates

💾 Resource Usage

• Memory footprint: 45MB average
• Disk usage: ~100MB with full knowledge base
• CPU usage: < 5% during normal operations
• Database growth: ~1MB per 1000 knowledge entries

📈 Scalability

• Concurrent agents: Tested with 50+ simultaneous connections
• Knowledge entries: Handles 100,000+ entries efficiently
• Task hierarchy: Supports 10+ levels of nested tasks
• Search performance: Sub-second semantic search across large datasets

🔧 Troubleshooting

Common Issues

NPX Installation Problems

# Update Node.js to latest LTS
node --version  # Should be >= 18.0.0

# Clear NPX cache
npx clear-npx-cache

# Force latest version
npx mcp-hive@latest init

MCP Server Connection Issues

# Verify server status
npx mcp-hive status

# Check logs with debug mode
npx mcp-hive start --debug

# Reset database if corrupted
npx mcp-hive clear --scope all --backup

Claude Code Integration

1. Ensure .mcp.json exists in project root
2. Restart Claude Code after configuration changes
3. Check Claude Code logs for connection errors
4. Verify MCP server is running: npx mcp-hive status

Performance Optimization

Large Knowledge Bases

# Optimize database
npx mcp-hive optimize

# Backup and compact
npx mcp-hive export backup.json
npx mcp-hive clear --scope all
npx mcp-hive import backup.json

Memory Usage

# Monitor resource usage
npx mcp-hive status --resources

# Restart server to clear memory
npx mcp-hive restart

📚 Documentation & Resources

📖 Complete Guides

• - Detailed setup instructions
• - Complete API reference
• - Command-line interface guide
• - Development contribution guidelines

🔄 Updates & Changes

• - Version history and updates
• - Version upgrade instructions
• - Important compatibility notes

🎯 Project Information

• - Original vision and requirements
• - Technical decision history
• - Planned features

🤝 Community & Support

💬 Get Help

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Community Q&A
• Documentation - Complete usage guides

🚀 Contributing

We welcome contributions! Please see our for details.

📜 License

This project is licensed under the MIT License - see the file for details.

🏆 Credits

Built with ❤️ by Moinsen Development for the AI agent community.