garyblankenship/mcpbee

MCPBee

Simplified MCP Architecture for Claude Code

Clean, efficient AI orchestration without the complexity

"Built with simplicity as a feature"

What is MCPBee?

MCPBee is a lightweight MCP (Model Context Protocol) server that connects your codebase to Claude Code with intelligent pattern learning. Unlike complex enterprise orchestration systems, MCPBee focuses on what matters:

• 🧠 Knowledge Storage - Remembers solutions and patterns that work
• 🔗 Knowledge Graph - Entity-relation model for connected knowledge
• 🔌 Native MCP Integration - Works with Claude Code out of the box
• 🎯 Direct Architecture - No layers of abstraction, just clean Go code

Perfect for developers who want AI assistance without enterprise complexity.

Why MCPBee?

📊 See for detailed comparisons with other MCP memory solutions like mcp-memory

Installation

Option 1: Download Binary (Coming Soon)

# Binaries will be available with first release
# macOS/Linux
curl -L https://github.com/garyblankenship/mcpbee/releases/latest/download/mcpbee-$(uname -s)-$(uname -m) -o mcpbee
chmod +x mcpbee
./mcpbee mcp  # For MCP server mode

Option 2: Install with Go

go install github.com/garyblankenship/mcpbee/cmd/mcpbee@latest
mcpbee mcp  # For MCP server mode

Option 3: Build from Source

git clone https://github.com/garyblankenship/mcpbee.git
cd mcpbee
make build  # Or: go build -o bin/mcpbee ./cmd/mcpbee
./bin/mcpbee mcp  # For MCP server mode

Quick Start

# Prerequisites
docker run -d -p 6379:6379 redis:alpine  # Start Redis

# Build the unified binary
make build  # Or: go build -o bin/mcpbee ./cmd/mcpbee

# Run MCPBee in different modes:
./bin/mcpbee mcp         # MCP server mode (for Claude Code)
./bin/mcpbee serve-http  # HTTP API server mode
./bin/mcpbee memory      # Memory management commands
./bin/mcpbee config      # Configuration management

📚 See for detailed usage and to get involved!

Features

🚀 Core Capabilities

• MCP Server - Native Claude Code integration via Model Context Protocol
• Knowledge Store - Redis-backed pattern learning and memory with enhanced search
• Knowledge Graph - Entity extraction and relationship mapping from memories
• Smart Search - Case-insensitive, word-based, and metadata search capabilities
• Graph Traversal - Navigate connected knowledge with BFS/DFS algorithms
• Pattern Learning - Automatically remembers successful solutions
• Entity Recognition - Extract persons, organizations, locations, and technologies

⚡ Performance

• Fast Startup - Under 100ms to operational
• Low Memory - ~23MB runtime footprint
• Direct Architecture - No unnecessary abstraction layers
• Single Binary - Everything in one executable
• Simple Config - One YAML file controls everything

Architecture

Claude Code → MCP Server → Learning Engine → Knowledge Store (Redis)
                     ↓                              ↓
              Event Bus → Pattern Detection   Knowledge Graph
                                              (Entities & Relations)

Clean, direct communication with intelligent event-driven learning. Features an integrated learning engine for pattern recognition, proactive suggestions, and a knowledge graph layer for entity relationship mapping.

Project Structure

mcpbee/
├── cmd/
│   └── mcpbee/              # Unified binary with subcommands
│       ├── main.go          # Entry point
│       └── cmd/             # Cobra command implementations
│           ├── root.go      # Root command
│           ├── mcp.go       # MCP server mode
│           ├── serve.go     # HTTP API server mode
│           ├── memory.go    # Memory management
│           └── config.go    # Configuration management
├── internal/
│   ├── mcp/                 # MCP server and tools
│   │   └── graph_tools.go   # Knowledge graph MCP tools
│   ├── learning/            # Intelligence engine and pattern learning
│   │   └── calibration/     # Confidence calibration system
│   ├── knowledge/           # Knowledge storage and search
│   │   ├── entity.go        # Entity management
│   │   ├── relation.go      # Relationship management
│   │   ├── extractor.go     # Entity extraction
│   │   └── graph.go         # Graph traversal operations
│   ├── eventbus/            # Event-driven communication
│   ├── config/              # Configuration management
│   ├── shared/              # Shared utilities
│   ├── streaming/           # Stream processing (optional)
│   └── generalization/      # Pattern generalization (legacy)
├── .mcp.json                # Claude Code MCP configuration
└── config.yaml              # Server configuration

Unified Binary Architecture

MCPBee uses a single, unified binary with multiple subcommands for different operational modes. This approach:

• Simplifies distribution - One binary to download and manage
• Reduces complexity - No need to track multiple executables
• Enables code reuse - Shared components across all modes
• Improves maintainability - Single codebase to update

Available Commands

mcpbee mcp          # Start as MCP server (for Claude Code)
mcpbee serve-http   # Start as HTTP API server
mcpbee memory       # Memory management operations
mcpbee config       # Configuration management
mcpbee --help       # Show all available commands

Migration from Multiple Binaries

If you're upgrading from an older version with separate binaries:

# Run the migration script
./scripts/migrate-to-unified.sh

# Or manually:
make build symlinks  # Creates compatibility symlinks

The old binary names (mcpbee-server, mcpbee-mcp) will continue to work via symlinks.

Configuration

Single config.yaml file:

redis:
  addr: localhost:6379
  
graph:
  enabled: true                      # Enable knowledge graph features
  auto_extract: true                 # Auto-extract entities from memories
  extraction_timeout: "5s"           # Timeout for entity extraction
  enable_async_extraction: true      # Process extraction asynchronously
  
calibration:
  enabled: true                      # Enable confidence calibration
  schedule: "0 0 2 * * *"           # Daily at 2 AM
  
log_level: info

Development

# Run tests
go test ./...

# Format code
go fmt ./...

# Build MCP server
go build -o bin/mcpbee-server ./cmd/mcpbee-mcp

# Build standalone server
go build -o bin/mcpbee ./cmd/mcpbee

Production Deployment

System Requirements

• Go 1.21+ or Docker
• Redis 6.0+
• 512MB RAM minimum
• Linux/macOS/Windows

Docker Deployment (Coming Soon)

# Docker image will be available after initial release
docker run -d \
  --name mcpbee \
  -v $(pwd)/config.yaml:/config.yaml \
  -e REDIS_ADDR=redis:6379 \
  garyblankenship/mcpbee:latest

Systemd Service

[Unit]
Description=MCPBee MCP Server
After=network.target redis.service

[Service]
Type=simple
User=mcpbee
ExecStart=/usr/local/bin/mcpbee-server
Restart=always

[Install]
WantedBy=multi-user.target

See directory for additional guides and documentation.

Knowledge Search

MCPBee includes enhanced search capabilities that make finding stored knowledge much easier:

Search Features

• Case-Insensitive - Searches work regardless of case (Gary, gary, GARY all work)
• Word-Based Matching - Finds memories containing any word from your query
• Metadata Search - Searches through metadata fields and tags
• Type Search - Query by memory type (e.g., pattern, user_info)
• Fallback Mode - Works even without RediSearch module

Example Queries

# Find user information
memory_query("Gary")           # Finds "User's name is Gary"
memory_query("user")           # Finds all user-related memories
memory_query("name")           # Finds memories containing "name"

# Search metadata
memory_query("critical")       # Finds memories marked as critical
memory_query("go")             # Finds Go-related patterns

# Multi-word queries (matches ANY word)
memory_query("error handling") # Finds error OR handling patterns

Note for Claude Code Users

After updating MCPBee, restart Claude Code to load the improved search functionality.

Knowledge Graph

MCPBee includes a powerful knowledge graph system that automatically builds a network of entities and relationships from your stored memories:

Entity Types

• Person - Individuals mentioned in memories (users, developers, contacts)
• Organization - Companies, teams, and organizational entities
• Location - Places, addresses, and geographic locations
• Technology - Programming languages, frameworks, tools, and concepts
• Concept - Abstract ideas and general entities

Automatic Entity Extraction

When you store memories, MCPBee automatically:

1. Extracts entities using NLP patterns
2. Identifies relationships between entities
3. Builds a searchable knowledge graph
4. Links entities back to source memories

Graph MCP Tools

Entity Management

# Create or update an entity
entity_create({
  "name": "John Doe",
  "type": "person",
  "observations": ["Software engineer", "Works on AI projects"]
})

# Query entities by type
entity_query({
  "type": "organization",
  "limit": 10
})

# View entity details
entity_view({
  "name": "OpenAI"
})

Relationship Management

# Create a relationship
relation_create({
  "from": "John Doe",
  "to": "Acme Corp",
  "type": "works_at"
})

Graph Navigation

# Traverse the graph from an entity
graph_traverse({
  "entity": "John Doe",
  "max_depth": 3,
  "max_nodes": 50
})

# Find path between entities
graph_path({
  "from": "John Doe",
  "to": "AI Research Lab",
  "max_depth": 5
})

Entity Extraction

# Extract entities from text
entity_extract({
  "text": "John works at Google in Mountain View on TensorFlow projects."
})
# Returns: persons, organizations, locations, and technologies

Configuration

Control graph features in config.yaml:

graph:
  enabled: true                    # Enable/disable graph features
  auto_extract: true               # Automatic entity extraction
  extraction_timeout: "5s"         # Timeout for extraction
  enable_async_extraction: true    # Async processing

Use Cases

• Contact Management - Track people and their organizations
• Technology Stack - Map technologies and their relationships
• Project Knowledge - Connect projects, teams, and technologies
• Geographic Context - Link locations with entities and events

Troubleshooting

MCP Tools Not Showing in Claude

1. Restart Claude Code
2. Check .mcp.json exists in project root
3. Verify binary path is absolute
4. Check logs: tail -f ~/.claude/logs/*.log

Redis Connection Failed

# Check Redis is running
redis-cli ping

# If not, start Redis
docker run -d -p 6379:6379 redis:alpine

Build Errors

# Ensure Go 1.21+
go version

# Clean and rebuild
go clean -cache
go build -o bin/mcpbee-server ./cmd/mcpbee-mcp

See for more solutions.

Philosophy

"Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." - Antoine de Saint-Exupéry

We removed 70% of the code that provided 0% of the value. The result is faster, cleaner, and more maintainable.

Contributing

We love contributions! See for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

Community

• 🐛 Report bugs
• 💡 Request features
• 💬 Join discussions
• ⭐ Star the project

License

- Use it, fork it, improve it!