Hive Mind MCP Server

Intelligent documentation system for codebases that creates living documentation as you build.

Hive Mind is an MCP (Model Context Protocol) server that automatically generates hivemind.md and hivemind.mmd at every directory level, creating a navigable spider-web of documentation that:

• Works in real-time as code is built
• Can retroactively document existing codebases
• Preserves user requirements and architectural decisions
• Enables AI navigation via anchor points
• Works with any context window size (8k to 200k tokens)
• Includes Auto-Context (reads file previews for you)
• Traces External Dependencies (e.g., react, aws-sdk)
• Generates SVG Diagrams automatically

Installation

Quick Start (Recommended)

You can run the server directly using uvx (no installation required):

{
  "mcpServers": {
    "hive-mind": {
      "command": "uvx",
      "args": ["mcp-hivemind-server"]
    }
  }
}

Install via pip

pip install mcp-hivemind-server

Install from Source (Development)

# Clone the repository
git clone https://github.com/Jahanzaib-Kaleem/hive-mind-mcp.git
cd hive-mind-mcp

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux

# Install dependencies
pip install -r requirements.txt

Requirements

• Python 3.11 or higher
• Dependencies: mcp, tree-sitter, tree-sitter-languages, aiofiles, pyyaml
• Optional: @mermaid-js/mermaid-cli (for SVG generation)

Configuration

For Antigravity / Claude Desktop

Edit your MCP configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Option 1: Using uvx (Easiest)

{
  "mcpServers": {
    "hive-mind": {
      "command": "uvx",
      "args": ["mcp-hivemind-server"]
    }
  }
}

Option 2: Using pip installation

{
  "mcpServers": {
    "hive-mind": {
      "command": "hive-mind",
      "args": []
    }
  }
}

Option 3: Using Source Code

{
  "mcpServers": {
    "hive-mind": {
      "command": "python",
      "args": ["C:/path/to/hive-mind-mcp/server.py"]
    }
  }
}

For Cursor

1. Open Cursor Settings
2. Navigate to Features → MCP Servers
3. Add new server:
   • Name: hive-mind
   • Type: stdio
   • Command: uvx
   • Args: mcp-hivemind-server

Usage

Real-time Documentation

While coding, ask your AI assistant:

"Document this code as we build it"

The AI will call document_current_work to capture:

• Code structure (functions, imports, exports)
• User requirements and constraints
• Warnings and gotchas
• Next steps and TODOs
• How the code works

Retroactive Documentation

For existing codebases, ask:

"Document my entire codebase with hive-mind"

The AI will call build_hive to:

• Walk the entire directory tree
• Parse all code files
• Generate documentation at each level
• Create connection graphs

Guided Hive Build (Recommended)

For AI-enriched documentation where YOU provide the context:

"Start a guided hive build on my codebase"

How it works:

1. MCP discovers all directories
2. For each directory, MCP shows you the structure (files, functions)
3. YOU read the actual code and understand what it does
4. YOU call continue_hive_build with your explanation
5. MCP writes hivemind.md with both structure AND your context
6. Repeat until all directories are documented

New: Auto-Context Preview The start_hive_build tool now automatically includes the first 100 lines of every file in the directory, so you don't have to manually call view_file to understand what to document. This speeds up the process by 3x.

This creates documentation with intelligent context from the AI (you!), not just dry parsing.

Navigation

Ask AI to navigate your codebase:

"Show me the auth system context"
"Find the validateSession function"
"Trace what uses the database module"

Tools

Core Tools

Guided Build Tools

Generated Files

hivemind.md

Each directory gets a hivemind.md file containing:

AI Context Sections (above the line):

• What This Does - Purpose and role
• User Requirements - Constraints and preferences
• Important Notes - Warnings and gotchas
• Next Steps - TODOs and planned work
• How It Works - Key patterns and logic

Dry Logic Sections (below the line):

• Files at This Level
• Functions Defined
• Dependencies
• Exports
• Connections
• Navigation
• Metrics

hivemind.mmd & hivemind.svg

Mermaid diagram (and generated SVG) showing:

• Current directory (purple center node)
• Parent directory (gray)
• Child directories (green)
• Upstream dependencies (orange)
• Downstream dependents (cyan)

Anchor Points

Navigate using anchor points in format: anchor://path/to/directory

Example:

anchor://project/src/components/auth

Testing

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_parser.py -v

# Run with coverage
python -m pytest tests/ --cov=. --cov-report=html

Project Structure

hive-mind-mcp/
├── server.py              # Main MCP server entry point
├── parser.py              # Code structure extraction (tree-sitter)
├── generator.py           # Markdown/Mermaid generation
├── enrichment.py          # AI context integration
├── navigator.py           # Anchor point navigation
├── config.py              # Configuration constants
├── utils.py               # Helper functions
├── requirements.txt       # Python dependencies
├── README.md              # This file
├── .gitignore
└── tests/
    ├── test_parser.py
    ├── test_generator.py
    └── test_integration.py

Supported Languages

• TypeScript (.ts, .tsx)
• JavaScript (.js, .jsx, .mjs, .cjs)
• Python (.py)

Optional AI Enrichment

Set ANTHROPIC_API_KEY environment variable to enable automatic AI-generated context:

export ANTHROPIC_API_KEY=your_key_here

Then use build_hive with enrich_with_ai: true.

License

MIT