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
- 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 topicsextend_current_task(title, body)- Add a subtask to organize and break down the current task
Navigation & Information
get_current_task()- Returns current task with contextget_big_picture(format='text')- Shows entire task hierarchy (format: 'text' or 'json')get_stack_overview()- Returns JSON structure of systempeek_context(include_body=False)- View parent and sibling contextlist_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 bodyswitch_focus(task_id)- Switch focus to any task by IDremove_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 handlinghandlers.py- MCP command implementationsserver.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.
Copyright (C) 2024 Briam R. briamr@gmail.com