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