Aidderall MCP Server

<!-- Copyright (C) 2024 Briam R. <briamr@gmail.com> This document is part of Aidderall MCP Server. Aidderall MCP Server is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. --> # Aidderall MCP - Exhaustive Detailed Specification ## Related Documentation - **[README](../../README.md)** - Project overview and quick start - **[Usage Guide](../Usage_Guide.md)** - Practical examples of using Aidderall - **[AI Assistant Evolution](AI_Assistant_Evolution.md)** - Vision for AI transformation - **[Work Log](../../worklog.md)** - Development history and architectural decisions ## **MCP Basics** ### **Assumptions** - MCP is written in python - MCP is an stdio MCP - MCP uses Anthropic MCP Python SDK ## **Core Data Structure Architecture** ### **Hybrid Stack-List Model** - **Primary Structure**: A stack where each level can optionally expand into a horizontal linked list - **Growth Patterns**: - **Vertical Growth**: New tasks pushed on top - **Horizontal Growth**: Current stack level extends rightward as a linked list (sequential task decomposition) - **Living Document Model**: Completed tasks remain visible in the structure, creating a historical record - **Focus Model**: Current task is marked with status CURRENT, can be any incomplete task via switch_focus ### **Task Node Specification** - **Unique ID**: System-generated identifier for each task - **Title**: String field, maximum 256 characters, brief task description - **Body**: Large text field, document-sized, stores full context, notes, intermediate results - **Status**: Implicit based on position (current/pending/completed) - **Position Metadata**: - Vertical stack position is tracked by global task array position - Horizontal stack position is tracked by parent task array - There are three kinds of task object - A parent Task object - Contains all the common fields - A MainTask object (Inherits from Task) - Adds a sub-tasks array - A SubTask object (Inherits from Task) - Does NOT contain a sub-tasks array - Only MainTasks can be extended - SubTasks are appended to the MainTask’s task array - SubTasks can NOT be extended ### **Behavioural Specification** - The system begins with no tasks in the global task array - (hereafter referred to as the “zen state”) - Since there are no MainTasks in the global task array, the current_task is None, and nothing can be extended; there is zen. - **Zen State Alternative**: Also achieved when all tasks are completed (living document remains visible) - In the zen state only new MainTask objects can be created (and consequently added to the task array via .extend) - There is a current_task reference which points to the task with status CURRENT - The current_task can point to either a MainTask or SubTask - To find the current_task - Search for any task with status == CURRENT - If manually set via switch_focus, that task is current - Otherwise, automatically determined as the rightmost incomplete task - If no incomplete tasks exist, current_task is None : and there is zen - The implication is that - there is a global task array of zero or more MainTasks - each MainTask has a task array of zero or more SubTasks - The global task array is treated as a stack - MainTasks can be pushed (.extend) - MainTasks can be popped (.pop) - MainTasks can NOT be popped if their task list contains >0 SubTasks - The AI does not know the different between MainTasks and SubTasks this is merely a bookkeeping distinction, to the AI ALL ARE TASKS. ## **Command Specifications** ### **Task Creation Commands** 1. **`create_new_task(title, body)`** - Creates new MainTask and extends the global task array - New task becomes current focus immediately “current_task” - Use case: Breaking current problem into subtask requiring deeper exploration - Parameters: title (required, ≤256 chars), body (required, unlimited) - Returns: - `task_id`: The new task's ID - `message`: Confirmation message - `is_current`: true (always current after creation) 2. **`extend_current_task(title, body)`** - Creates new SubTask object then - Gets the last MainTask object of the global task array - Adds the SubTask object to the end of the sub-tasks array belonging to the last MainTask object - Can NOT be called unless there exists at least ONE MainTask - Corollary: SubTask can not exist at root level in global task array - New task becomes current focus immediately “current_task” - Use case: Adding sequential step that must follow current work - Parameters: title (required, ≤256 chars), body (required, unlimited) - Returns: - `task_id`: The new task's ID - `message`: Confirmation message - `is_current`: true (always current after creation) ### **Navigation & Information Commands** 3. **`get_current_task()`** - Returns current task object (pointed to by current_task) - Response includes: - Task ID, title, full body content - Stack depth (how many levels deep) - Could be simple counter incremented/decremented every time new task is added or completed - Siblings to left (tasks requiring completion before pop) - since the current task is the top rightmost always, a simple list of all the SubTasks in the sub-task array of the last MainTask (minus the last element “current_task”) is sufficient (or an empty list, if none; or the current task is a MainTask “no more to the left”) - Breadcrumb trail from root to current - Breadcrumb trail could be siblings list, plus containing MainTask down to root - No parameters required 4. **`get_big_picture(format='text')`** - Returns representation of entire structure - Parameters: - `format` (optional): 'text' (default) or 'json' - Text format: - Space-indented outline structure - Shows task titles with status indicators (pending) or (completed) - Marks current position with "<-- YOU ARE HERE" - Example: ``` Main Task (pending) Subtask 1 (completed) Deeper task 1.1 (completed) Deeper task 1.2 (completed) Subtask 2 (pending) Deeper task 2.1 (completed) Deeper task 2.2 (current) <-- YOU ARE HERE ``` - JSON format: - Returns full task hierarchy with metadata - Includes: id, title, status, created_at, completed_at, sub_tasks - Current task marked with is_current: true ### **Task Completion & Work Log** 5. **`complete_current_task()`** - Marks current task as completed (changes status to COMPLETED) - **Task remains visible in structure** (living document approach) - Also archives to global completed tasks array for historical record - Focus behavior: - If incomplete siblings exist to left: Focus moves to leftmost incomplete sibling - If no incomplete siblings: Focus moves to parent if incomplete - Otherwise: Searches for any incomplete task from right to left - If all tasks completed: System enters zen state (all tasks visible but completed) 6. **`get_completed_tasks(order)`** - Accesses archive of all completed tasks - Parameters: - order: "chronological" or "logical" - chronological order enumerates the completed list from left to right, i.e. as tasks were done and the list was popped (inverse order) - logical order enumerates the completed list from right to left i.e. a logically ordered list (from topmost task (last executed), to bottom-most task (first executed)) - Returns: - `count`: Number of completed tasks - `tasks`: Array of task objects with id, title, body, completed_at timestamp ### ** Additional Commands** 7. **`update_current_task(body)`** - Modifies (overwrites) the body content of current task only - Title and ID remain unchanged - Use case: Accumulating results, refining understanding 8. **`get_stack_overview()`** - Returns structured data of entire system - Different from get_big_picture: Returns JSON/structured format vs plain text - Includes all task IDs for programmatic navigation 9. **`peek_context(include_body=False)`** - Returns parent and immediate left sibling context without changing focus - Parameters: - `include_body` (optional): Include task body content (default: False) - Returns: - `parent_context`: Parent task info (id, title, status, created_at, optionally body/completed_at) - `immediate_context`: Left sibling info (same fields) - Helps maintain awareness of why current work is being done 10. **`list_siblings(include_body=False)`** - Shows all tasks to the left of current task at the current stack level - Parameters: - `include_body` (optional): Include task body content (default: False) - Returns: - `count`: Number of siblings - `siblings`: Array with id, title, status, created_at, optionally body/completed_at - Helps with progress estimation 11. **`switch_focus(task_id)`** - Manually set focus to any task by ID (enables non-linear workflows) - Parameters: - `task_id`: ID of task to focus on - Returns: - Success/failure status - New focus path - Previous task retains its status, target task becomes CURRENT - Use get_big_picture or get_stack_overview to find task IDs 12. **`remove_task(task_id)`** - Remove a task from the visible structure (workspace cleanup) - Parameters: - `task_id`: ID of task to remove - Task remains in completed_tasks archive if it was completed - Removing parent removes all subtasks - Use for decluttering while preserving history ## **Behavioral Specifications** ### **Focus Management Rules** - Only ONE task can be the focus "current_task" at any time - Current task has status CURRENT and is marked with "YOU ARE HERE" - **Manual focus movement via switch_focus** enables non-linear workflows - Automatic focus movement on completion follows intelligent rules - System prevents orphaned or unreachable tasks ### **Completion Semantics** - **Tasks can be completed in any order** via switch_focus - Completed tasks remain visible with (completed) status - Parent task cannot be completed until all children completed - Completion is permanent - no "uncomplete" operation - Use remove_task to hide completed tasks while preserving history ### **Living Document & Archive Behavior** - Completed tasks remain visible in main structure (living document) - Every completed task also archived to completed_tasks array - Archive preserves exact state at completion time - Completion timestamp added at time of completion - Completed tasks searchable but not modifiable - remove_task hides from structure but preserves in archive - Archive persists only as long as MCP server is alive (for now) ### **Edge Cases Handled** - Empty global MainTasks array state (no tasks, zen state) - Single task (no siblings or parent) - Maximum nesting depth (currently envisioned as unbounded) - Concurrent access (concurrent access should be impossible (single MCP server model)) ## **Use Case Scenarios** ### **Complex Problem Solving** ``` 1. Create root task: "Design new feature" (current task) 2. Create subtask: "Research requirements" (pushes onto stack, becomes current) 3. Create subtask: "Interview users" (pushes onto stack, becomes current) 4. Extend with: "Analyze competitor solutions" (adds to right, becomes current) 5. Complete "Analyze competitor solutions" (focus moves left) 6. Complete "Interview users" (stack pops, back to "Research requirements") 7. Complete "Research requirements" (stack pops, back to "Design new feature") 8. Extend with: "Create specification" (adds to right, becomes current) 9. Complete "Create Specification" (focus moves left) 10. Complete root task: "Design new feature" (focus goes to "zen" no tasks state) ``` ## **Benefits Summary** 1. **Cognitive Enhancement**: External working memory with structured organization 2. **Focus Enforcement**: Prevents scatter-brained task switching 3. **Context Preservation**: Never lose track of why doing current work 4. **Knowledge Building**: Accumulates searchable library over time 5. **Interruption Recovery**: Can resume exactly where left off 6. **Progress Visibility**: Always know what's done and what remains 7. **Natural Workflow**: Matches human problem decomposition patterns This system essentially provides AI with a "cognitive prosthetic" that addresses fundamental limitations in memory, focus, and goal persistence across conversations. ## See Also - **[Usage Guide](../Usage_Guide.md)** - See these concepts in action with practical examples - **[AI Assistant Evolution](AI_Assistant_Evolution.md)** - Understand the broader vision this specification enables - **[Work Log](../../worklog.md)** - Review the development history and architectural decisions