README.md•2.89 kB
# 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