Aidderall MCP

🚀 Aidderall MCP Server

Aidderall is a Model Context Protocol (MCP) server implementation designed for hierarchical task management. It serves as a cognitive prosthetic for AI assistants, enabling them to maintain focus and context during complex problem - solving sessions.

AI assistants often struggle with long - running tasks, partly due to the limitations of their context window (the amount of information they can handle at a given time). Aidderall addresses this issue by providing AI assistants with focus and a contextual map of the current cognitive landscape. Think of Aidderall as multiple small context windows that help the AI focus and remember!

🚀 Quick Start

Installation

1. Clone the repository:

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

2. Create and activate a virtual environment:

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

3. Install dependencies:

pip install -r requirements.txt

4. For development, install with dev dependencies:

pip install -e ".[dev]"

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

✨ 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.

📦 Installation

The installation steps are detailed in the Quick Start section above.

💻 Usage Examples

Basic Usage

# 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

📚 Documentation

• Usage Guide: A comprehensive guide for getting AI assistants to use Aidderall effectively.
• Technical Specification: A detailed technical specification of the hybrid stack - list model.
• AI Assistant Evolution: The vision for transforming AI from a stateless oracle to a focused worker.
• Work Log: Development history and architectural decisions.

🔧 Technical Details

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.

Development

Running Tests

pytest -v

Code Coverage

pytest --cov=src tests/

Code Formatting

black src tests
isort src tests

Type Checking

mypy src

📄 License

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

Copyright (C) 2024 Briam R. briamr@gmail.com

Acknowledgements

Thanks to Alberto “KewlPops” Fernandez for coming up with the name... the project name was not so exciting before! 😀

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)   │
   └─────────────────┘                 └─────────────────┘

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.

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.