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

Aidderall Logo

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

Clone the repository:

git clone https://github.com/user/aidderall_mcp.git
cd aidderall_mcp

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

For development, install with dev dependencies:

pip install -e ".[dev]"

Usage

Running the Server

Start the MCP server:

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:

claude mcp add aidderall-mcp /path/to/aidderall_mcp/run_mcp.sh

Manual Configuration

Alternatively, add the server to your MCP configuration:

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

# 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

pytest -v

Code Coverage

pytest --cov=src tests/

Code Formatting

black src tests
isort src tests

Type Checking

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 - Comprehensive guide for getting AI assistants to use Aidderall effectively
Technical Specification - Detailed technical specification of the hybrid stack-list model
AI Assistant Evolution - Vision for transforming AI from stateless oracle to focused worker
Work Log - Development history and architectural decisions

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.

Aidderall MCP Server

README Documentation