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" }