Skip to main content
Glama

Aidderall Logo

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

Related MCP server: Codebuddy MCP Server

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

  • Session Persistence: Task state is automatically persisted to SQLite on every mutation — survives server restarts, crashes, and context compaction

  • Session Management: Each server instance gets a unique session. List, resume, or clean up previous sessions

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:

git clone https://github.com/user/aidderall_mcp.git
cd aidderall_mcp
  1. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies:

pip install -r requirements.txt
  1. 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

Session Management

  • list_sessions() - List all persisted sessions with metadata (task count, current task, last modified)

  • resume_session(session_id) - Resume a previous session's task state (empty sessions are auto-cleaned on resume)

  • delete_session(session_id) - Delete a stale session (cannot delete the active session)

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

Persistence

Task state is automatically persisted to SQLite at ~/.aidderall/sessions/<session_id>/state.db. Each server instance generates a unique session ID, so concurrent sessions never interfere with each other.

  • Auto-save: Every mutation (create, extend, complete, update, switch, remove) writes to disk immediately

  • Auto-restore: Resuming a session loads the full task hierarchy, completed archive, and focus state

  • Auto-cleanup: Empty sessions are deleted when you resume a different session

Architecture

  • models.py - Core data structures (Task, MainTask, SubTask) with serialization

  • task_manager.py - Task management logic and state handling

  • handlers.py - MCP command implementations

  • persistence.py - SQLite-backed session persistence

  • 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

  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 file for details.

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

Available Tools

12 tools
complete_current_taskA

Mark current task as COMPLETED. Task remains visible in structure (living document approach). Focus automatically moves to a nearby incomplete task. Creates permanent record in history. You can use switch_focus to work on any specific task instead. Use remove_task to clean up workspace later.

Inputs: no named parameters.

create_new_taskA

Create an INDEPENDENT task for unrelated work. Use for: new topics, context switches, or parallel workstreams. Adds a new top-level task to your workspace. Previous task keeps its status. Example: working on Feature A, need to research Topic B → create_new_task for Topic B. For breaking down current work, use extend_current_task.

Inputs: title (required), body (required).

extend_current_taskA

Add a subtask to organize and decompose work. Creates hierarchical structure for complex tasks. Subtasks help break down work into manageable pieces. You can work on tasks in any order using switch_focus. Example: Task A → Task B → Task C creates a nested structure, but you can jump between them freely. For unrelated work, use create_new_task.

Inputs: title (required), body (required).

get_big_pictureA

See ALL tasks in your task stack (including completed ones). Shows full work context as a living document. Marks current task with 'YOU ARE HERE'. Indicates zen state when no tasks exist OR all tasks are completed.

Inputs: format.

get_completed_tasksA

View chronological history of ALL completed tasks. This is a permanent archive separate from the visible structure. Tasks remain here even after being removed from the workspace. Useful for reviewing what you've accomplished over time.

Inputs: order.

get_current_taskA

Get the task with CURRENT status (your active focus). May be manually set via switch_focus, or automatically determined. In zen state (no tasks OR all tasks completed), returns appropriate message.

Inputs: no named parameters.

get_stack_overviewB

Get structured data of your entire task stack (JSON format with all task details and relationships)

Inputs: no named parameters.

list_siblingsB

See all sibling tasks to the left of current focus. May include both pending and completed tasks. Helpful for understanding your position in the current task sequence.

Inputs: include_body.

peek_contextA

Look at parent task and previous sibling without changing focus (understand WHY you're doing current task)

Inputs: include_body.

remove_taskA

Remove a task from the structure (cleanup your workspace). The task remains in completed_tasks history if it was completed. Can remove any task (completed or not). Removing a parent task removes all its subtasks. Use get_big_picture or get_stack_overview to see task IDs.

Inputs: task_id (required).

switch_focusA

Switch focus to ANY task by ID. The primary way to navigate your task workspace - jump between tasks in any order, revisit completed work, or change priorities on the fly. Current task retains its status, target task becomes current. Use get_big_picture or get_stack_overview to see task IDs.

Inputs: task_id (required).

update_current_taskB

Update notes/content of the task you're currently focused on (current task only)

Inputs: body (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity. For example, 'complete_current_task' marks a task as completed, 'create_new_task' adds an independent task, and 'extend_current_task' adds a subtask—these are well-differentiated. Tools like 'get_big_picture' and 'get_stack_overview' serve different informational needs (overview vs. structured data), and navigation tools like 'switch_focus' and 'peek_context' have unique roles.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, such as 'complete_current_task', 'create_new_task', and 'get_big_picture'. There are no deviations in naming conventions, making the set predictable and easy to understand. This consistency aids in agent comprehension and tool selection.

    Tool Count5/5

    With 12 tools, the count is well-scoped for a task management server, covering creation, navigation, status updates, and information retrieval without being overwhelming. Each tool serves a specific function in managing tasks, such as 'remove_task' for cleanup and 'list_siblings' for context, ensuring a comprehensive yet manageable toolset.

    Completeness5/5

    The toolset provides complete coverage for task management, including CRUD operations (create, update, remove), status changes (complete), navigation (switch_focus, peek_context), and information retrieval (get_current_task, get_big_picture). There are no obvious gaps; agents can handle all aspects of task lifecycle and workspace management without dead ends.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A cognitive scaffolding platform that helps AI agents break down complex tasks into manageable steps using hierarchical planning and metacognitive guidance. Provides persistent memory, progress tracking, and intelligent pattern recognition to learn from successful project structures.
      -
    • A
      license
      B
      quality
      B
      maintenance
      Put your digital chores on autopilot: Build always-on agents from a single prompt. Give Claude Code goals like "Maintain my repo" and it works on them in the background on a schedule, asks you to approve actions from a pane beside your chat or your phone, and remembers your decisions. Claude Code plugins + MCP server, local SQLite.
      2
      41
      42
      Apache 2.0