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
• 🔌 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?

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 -config config.yaml

Option 2: Install with Go

go install github.com/garyblankenship/mcpbee/cmd/mcpbee-mcp@latest
mcpbee-mcp

Option 3: Build from Source

git clone https://github.com/garyblankenship/mcpbee.git
cd mcpbee
go build -o bin/mcpbee-server ./cmd/mcpbee-mcp
./bin/mcpbee-server

Quick Start

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

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

# MCP server runs via Claude Code (configured in .mcp.json)
# No direct command line execution needed

📚 See examples/ for detailed usage and CONTRIBUTING.md 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
• Smart Search - Case-insensitive, word-based, and metadata search capabilities
• File Operations - Read, write, and manage files through MCP tools
• Shell Commands - Execute commands safely with proper validation
• Pattern Learning - Automatically remembers successful solutions

⚡ 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

Clean, direct communication with intelligent event-driven learning. Features an integrated learning engine for pattern recognition and proactive suggestions.

Project Structure

mcpbee/
├── cmd/
│   ├── mcpbee-mcp/          # MCP server (for Claude Code)
│   ├── mcpbee/              # Standalone server
│   └── mcpbee-test/         # Test utilities
├── internal/
│   ├── mcp/                 # MCP server and tools
│   ├── learning/            # Intelligence engine and pattern learning
│   ├── knowledge/           # Knowledge storage and search
│   ├── eventbus/            # Event-driven communication
│   ├── config/              # Configuration management
│   └── shared/              # Shared utilities
├── .mcp.json                # Claude Code MCP configuration
└── config.yaml              # Server configuration

Configuration

Single config.yaml file:

redis:
  addr: localhost:6379
  
worker:
  process_interval: 100
  
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 docs/ 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.

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 docs/TROUBLESHOOTING.md 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 CONTRIBUTING.md 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

MIT - Use it, fork it, improve it!