Aidderall

Aidderall is an MCP server implementation for hierarchical task management that helps AI assistants maintain focus and context across complex problem-solving sessions. It enables you to organize work in nested tasks, pursue parallel streams, and navigate freely between tasks while preserving a living history of completed work.

How to use

You will run the AI-focused MCP server locally and connect your MCP client to interact with a hierarchical task structure. Use the client to create root tasks, add subtasks, switch focus between tasks, and complete work in any order. Completed tasks remain visible to preserve context and history, and you can explore the full task map at any time.

How to install

Prerequisites you need before starting are Python 3.8 or later and Git. You should also have a working shell environment to run commands.

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

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

pip install -r requirements.txt

pip install -e ".[dev]"

To start the MCP server locally, run the following command:

python -m src.server

Configuration and running notes

The server is designed to persist session data automatically. Each server instance creates a unique session and saves state in SQLite. Use a client to connect, create and manage tasks, and rely on the server to preserve focus state and the full history across restarts.

If you want to configure an MCP client to launch the server directly, you can use the following local configuration that starts the server via Python in module mode.

{
  "mcpServers": {
    "aidderall": {
      "command": "python",
      "args": ["-m", "src.server"]
    }
  }
}

Usage patterns and workflow

• Create a root task to define the main objective. Extend it with subtasks to break work into manageable chunks.

• Use switch_focus to jump between tasks, enabling parallel work streams while keeping context intact.

• Complete tasks when done. Completed tasks remain visible to preserve history and context for future reference.

Example workflow

Start with a root task, then break it into subtasks, switch focus between tasks, and observe how the hierarchy and history evolve as you work.

Persistence and sessions

Task state is automatically persisted to SQLite after every mutation. Each server instance manages its own session, and you can list, resume, or delete past sessions as needed.

Available tools

create_new_task

Create a new independent root task for unrelated work or new topics.

extend_current_task

Add a subtask to organize and break down the current task.

get_current_task

Return the current task along with its context.

get_big_picture

Display the entire task hierarchy in text or JSON format.

get_stack_overview

Return a JSON structure of the system state.

peek_context

View context for the current task including parent and siblings.

list_siblings

List tasks at the current hierarchical level.

complete_current_task

Mark the current task as completed while keeping it visible for context.

update_current_task

Update the body or details of the current task.

switch_focus

Switch focus to any task by its ID to work on it directly.

remove_task

Remove a task from the structure while preserving it in history.

get_completed_tasks

View the archive of completed tasks.

list_sessions

List all persisted sessions with metadata.

resume_session

Resume a previous session and restore task state.

delete_session

Delete a stale session that is not the active one.