# 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
```bash
pip install -r requirements.txt
python codebuddy.py --host 0.0.0.0 --port 8000
```

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

### Docker Compose
```bash
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:

```json
{
  "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