Codebuddy MCP Server

A lightweight Cognitive Scaffolding Platform that provides advanced task decomposition, metacognitive guidance, and intelligent memory for AI agents.

Built on PhD-level research in cognitive load theory, hierarchical task networks, and prompt engineering best practices.

🧠 Cognitive Features

• Smart Task Planning: Hierarchical decomposition respecting Miller's 7±2 rule
• Metacognitive Guidance: Self-reflection prompts and adaptive strategies
• Complexity Assessment: Automatic cognitive load evaluation and management
• Pattern Recognition: Learning from successful project structures
• Software Engineering Integration: Clean Code and SOLID principle guidance
• Tool Usage Nudges: Smart suggestions for AI agents to use complementary tools

🚀 Core Capabilities

• Hierarchical Planning: Break complex problems using proven cognitive frameworks
• Progress Tracking: Update status with learning capture and insight generation
• Persistent Memory: Append-only JSONL storage with cognitive metadata
• Intelligent Search: Context-aware task discovery with success pattern matching
• Strategic Learning: Extract actionable insights from completed projects

Quick Start

Local Development

pip install -r requirements.txt
python codebuddy.py --host 0.0.0.0 --port 8000

Docker

docker build -t codebuddy-mcp .
docker run -p 8000:8000 -v $(pwd)/data:/app/data codebuddy-mcp

Docker Compose

docker-compose up -d

MCP Tools

• plan_task(problem: str) - Create a new task with generated steps
• update_task(task_id: str, status: str, notes: str) - Update task progress
• list_tasks(limit: int = 10) - Get recent tasks
• search_tasks(query: str) - Find tasks by keyword
• summarize_lessons() - Analyze success patterns and blockers

Configuration

The server accepts the following command-line arguments:

• --host - Host address to bind to (default: localhost)
• --port - Port number to bind to (default: 8000)
• --data-file - Path to JSONL storage file (default: data/tasks.jsonl)
• --log-level - Logging level (default: INFO)

Storage Format

Tasks are stored in data/tasks.jsonl with one JSON object per line:

{
  "id": "uuid",
  "problem": "string", 
  "steps": ["string"],
  "status": "planned|in_progress|completed|blocked",
  "notes": "string",
  "created_at": "iso8601",
  "updated_at": "iso8601"
}

Architecture

The server follows Clean Code and SOLID principles:

• models.py - Pydantic data models and validation
• storage.py - JSONL persistence with cross-platform file locking
• tools.py - MCP tool implementations and business logic
• error_handling.py - Structured error handling and health monitoring
• codebuddy.py - Main server application with FastMCP integration