README.md•13.8 kB
# Welcome to Aidderall MCP Server!
Aidderal is a Model Context Protocol (MCP) server implementation for hierarchical task management, providing AI assistants with a cognitive prosthetic for maintaining focus and context across complex problem-solving sessions.
AI assistants have a hard time dealing with long running tasks, in part due to limitations in the amount of information they can handle at any one point in time (context window).
Aidderall solves this issue by giving the AI assistant:
- Focus
- A map of the current cognitive landscape with context
Think of aidderall as many small context windows which help the AI focus and remember!
## Overview
Aidderall implements a flexible hierarchical task management system where:
- Tasks can be organized in nested structures for complex work decomposition
- Create independent tasks for parallel work streams
- Navigate freely between any tasks using switch_focus
- Complete tasks in any order that makes sense for your workflow
- All tasks remain visible as a living document of your work
## What does Aidderall look like?
```
Aidderall Visual Representation
================================
1. Basic Structure - Tasks grow vertically, subtasks grow horizontally:
┌─────────────────┐
│ MainTask C │ ← Latest main task
│ [PENDING] │
└─────────────────┘
↑
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MainTask B │ ──→ │ SubTask B.1 │ ──→ │ SubTask B.2 │
│ [COMPLETED] │ │ [COMPLETED] │ │ [CURRENT] ← │ ← YOU ARE HERE
└─────────────────┘ └─────────────────┘ └─────────────────┘
↑
┌─────────────────┐ ┌─────────────────┐
│ MainTask A │ ─→ │ SubTask A.1 │
│ [COMPLETED] │ │ [COMPLETED] │
└─────────────────┘ └─────────────────┘
2. Living Document - Completed tasks remain visible:
Before (traditional todo): After (Aidderall):
┌─────────────────┐ ┌─────────────────┐
│ ☐ Task A │ │ ✓ Task A │ ← Still visible!
│ ☐ Task B │ │ ✓ Task B │ ← Context preserved
│ ☐ Task C │ │ ☐ Task C │
└─────────────────┘ └─────────────────┘
Traditional: Completed = Gone Aidderall: Completed = History
3. Flexible Navigation with switch_focus:
┌─────────────────┐
│ Task D │
│ [PENDING] │ ←────────────┐
└─────────────────┘ │
↑ │ Can jump to any task!
┌─────────────────┐ │
│ Task C │ │
│ [CURRENT] ← │ ←──────┐ │
└─────────────────┘ │ │
↑ │ │
┌─────────────────┐ │ │
│ Task B │ ←──────┘ │
│ [COMPLETED] │ │
└─────────────────┘ │
↑ │
┌─────────────────┐ │
│ Task A │ ←────────────┘
│ [COMPLETED] │
└─────────────────┘
4. Real-world Example - Implementing a Feature:
┌─────────────────────┐
│ Add User Auth │
│ [COMPLETED] │
└─────────────────────┘
↑
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
└───→ │ Design DB Schema │ ──→ │ Create API │ ──→ │ Add UI Forms │
│ [COMPLETED] │ │ [COMPLETED] │ │ [CURRENT] ← │
└──────────────────┘ └──────────────────┘ └──────────────────┘
↑
│ ┌──────────────────┐
└───→ │ Add JWT logic │
│ [COMPLETED] │
└──────────────────┘
5. Value Propositions Visualized:
Traditional Linear Todo: Aidderall Hierarchical:
======================== =========================
☐ Research auth libraries Research Phase
☐ Design database schema │
☐ Create user table ├─→ Auth libraries
☐ Create session table │ └─→ JWT vs Sessions
☐ Implement JWT │
☐ Create login endpoint Design Phase
☐ Create register endpoint │
☐ Add password hashing ├─→ Database Schema
☐ Create login form │ ├─→ User table
☐ Create register form │ └─→ Session table
☐ Add form validation │
Implementation Phase
Problems: │
- No hierarchy ├─→ Backend API
- No context │ ├─→ Login endpoint
- Hard to see relationships │ ├─→ Register endpoint
- Completed = disappeared │ └─→ Password hashing
│
└─→ Frontend UI
├─→ Login form
├─→ Register form
└─→ Validation
Benefits:
✓ Clear hierarchy
✓ Preserved context
✓ Visible relationships
✓ Complete history
6. Zen State - Two Paths:
Path 1: No tasks Path 2: All completed
┌─────────────────┐ ┌─────────────────┐
│ │ │ ✓ Task A │
│ Empty Stack │ │ ✓ Task B │
│ (Zen State) │ │ ✓ Task C │
│ │ │ (Zen State) │
└─────────────────┘ └─────────────────┘
```
## Features
- **Hierarchical Task Management**: Create main tasks and extend them with subtasks
- **Focus Enforcement**: Only one task can be active at a time
- **Context Preservation**: Maintain breadcrumb trails and sibling awareness
- **Task Completion**: Archive completed tasks with timestamps
- **State Persistence**: Track all tasks and their relationships
## Acknowledgements
- Thanks to **Alberto *“KewlPops”* Fernandez** for coming up with the name... the project name was not so exciting before! 😀
## Installation
1. Clone the repository:
```bash
git clone https://github.com/user/aidderall_mcp.git
cd aidderall_mcp
```
2. Create and activate a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install dependencies:
```bash
pip install -r requirements.txt
```
4. For development, install with dev dependencies:
```bash
pip install -e ".[dev]"
```
## Usage
### Running the Server
Start the MCP server:
```bash
python -m src.server
```
The server runs via the Python module directly.
### Integrating with AI Assistants
#### For Claude Code
If you have Claude Code installed, you can add Aidderall directly:
```bash
claude mcp add aidderall-mcp /path/to/aidderall_mcp/run_mcp.sh
```
#### Manual Configuration
Alternatively, add the server to your MCP configuration:
```json
{
"mcpServers": {
"aidderall": {
"command": "python",
"args": ["-m", "src.server"]
}
}
}
```
## Available Commands
### Task Creation
- `create_new_task(title, body)` - Create a new independent task for unrelated work or new topics
- `extend_current_task(title, body)` - Add a subtask to organize and break down the current task
### Navigation & Information
- `get_current_task()` - Returns current task with context
- `get_big_picture(format='text')` - Shows entire task hierarchy (format: 'text' or 'json')
- `get_stack_overview()` - Returns JSON structure of system
- `peek_context(include_body=False)` - View parent and sibling context
- `list_siblings(include_body=False)` - List tasks at current level
### Task Management
- `complete_current_task()` - Mark current task as complete (stays visible)
- `update_current_task(body)` - Update current task body
- `switch_focus(task_id)` - Switch focus to any task by ID
- `remove_task(task_id)` - Remove task from structure (preserves in history)
- `get_completed_tasks(order)` - View completed task archive
## Example Workflow
```python
# Start with a root task
create_new_task("Design new feature", "Research and design specs")
# Break it down into subtasks for organization
extend_current_task("Research requirements", "User research needed")
extend_current_task("Interview users", "Conduct user interviews")
extend_current_task("Analyze competitors", "Research competitor solutions")
# Work on tasks in any order using switch_focus
get_big_picture() # See all tasks with their IDs
switch_focus("task-id-for-research") # Jump to research task
complete_current_task() # Complete it when done
# Jump to any other task
switch_focus("task-id-for-interviews") # Work on interviews
# ... do some work ...
switch_focus("task-id-for-competitors") # Switch to competitor analysis
# Create parallel work streams
create_new_task("Write documentation", "Document the new feature")
extend_current_task("API docs", "Write API documentation")
extend_current_task("User guide", "Write user guide")
# Jump between different work streams freely
switch_focus("task-id-for-design") # Back to design work
switch_focus("task-id-for-api-docs") # Jump to documentation
# Complete tasks as they're finished, in any order
complete_current_task() # Completes whatever you're currently focused on
# View all tasks - completed ones remain visible
get_big_picture()
# Output shows:
# Design new feature (pending)
# Research requirements (completed)
# Interview users (pending)
# Analyze competitors (completed)
# Write documentation (pending)
# API docs (completed)
# User guide (pending)
# Clean up workspace by removing completed tasks
remove_task("task-id-for-research") # Removes from view but keeps in history
```
## Development
### Running Tests
```bash
pytest -v
```
### Code Coverage
```bash
pytest --cov=src tests/
```
### Code Formatting
```bash
black src tests
isort src tests
```
### Type Checking
```bash
mypy src
```
## Architecture
- `models.py` - Core data structures (Task, MainTask, SubTask)
- `task_manager.py` - Task management logic and state handling
- `handlers.py` - MCP command implementations
- `server.py` - MCP server entry point
## Documentation
- **[Usage Guide](documentation/Usage_Guide.md)** - Comprehensive guide for getting AI assistants to use Aidderall effectively
- **[Technical Specification](documentation/vision/Aidderall_Vision.md)** - Detailed technical specification of the hybrid stack-list model
- **[AI Assistant Evolution](documentation/vision/AI_Assistant_Evolution.md)** - Vision for transforming AI from stateless oracle to focused worker
- **[Work Log](worklog.md)** - Development history and architectural decisions
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.
Copyright (C) 2024 Briam R. <briamr@gmail.com>
