addTaskManager MCP Server

An MCP (Model Context Protocol) server that integrates with the addTaskManager iOS/macOS app, implementing the ADD (Assess-Decide-Do) framework created by Dragos Roua.

Overview

This MCP server provides AI assistance for your addTaskManager productivity workflow while respecting the strict realm-based restrictions of the ADD framework:

• Assess Realm: Create and edit tasks/projects/ideas, but cannot assign contexts or due dates
• Decide Realm: Assign contexts, due dates, and alerts, but cannot edit content
• Do Realm: Mark items as complete only (read-only otherwise)

Features

Authentication

• Secure Apple Sign-In integration
• CloudKit.js authentication for personal data access
• User-specific data isolation

Assess Realm Operations

• `assess_create_task` - Create new tasks with editable content
• `assess_edit_task` - Edit task content
• `assess_create_project` - Create new projects
• `assess_edit_project` - Edit project title
• `assess_create_idea` - Capture new ideas
• `assess_create_collection` - Create new collection
• `assess_create_context` - Create new context
• `assess_edit_idea` - Edit idea title
• `assess_add_task_to_project` - Add an existing task to a project
• `assess_add_task_to_idea` - Add an existing task to an idea
• `assess_remove_task_from_project` - Remove a task assigned to a project
• `assess_remove_task_from_idea` - Remove a task assigned to an idea
• `assess_archive_task_to_collection` - Archive a task to an existing collection
• `assess_archive_project_to_collection` - Archive a project to an existing collection

Decide Realm Operations

• `decide_assign_context` - Assign contexts to tasks/projects
• `decide_set_project_interval` - Set a project interval (start date and end date)
• `decide_set_task_due_date` - Set due date to a task
• `decide_set_task_alert` - Set task alerts
• `decide_move_task_to_do` - Move task to Do realm
• `decide_move_task_to_assess_from_decide` - Move task to Assess realm
• `decide_move_project_to_do` - Move project to Do realm
• `decide_move_project_to_assess_from_decide` - Move project to Assess realm

Do Realm Operations

• `do_mark_task_as_done` - Mark tasks as completed
• `do_mark_project_as_done` - Mark projects as completed

Query Operations

• `get_tasks_by_realm` - Filter tasks by realm
• `get_projects_by_realm` - Filter projects by realm
• `get_ideas` - Get all ideas
• `get_collections` - Get all collections
• `get_tasks_by_context` - Filter by context
• `get_stalled_items_in_decide` - Find stalled items (task + projects) in Decide
• `get_undecided_items_in_decide` - Find undecided items (task + projects) in Decide
• `get_ready_items_in_decide` - Find ready to do items (task + projects) in Decide
• `get_tasks_today_in_do` - Find tasks done today in Do
• `get_tasks_tomorrow_in_do` - Find tasks done tomorrow in Do
• `get_tasks_soon_in_do` - Find tasks done soon in Do
• `get_tasks_overdue_in_do` - Find tasks overdue in Do

General Operations

• `moveToRealm` - Move a task or project to any realm (assess/decide/do)

Installation

From npm (Coming Soon)

npm install -g @dragosroua/addtaskmanager-mcp-server

From Source

git clone https://github.com/dragosroua/addtaskmanager-mcp-server.git
cd addtaskmanager-mcp-server
npm install
npm run build

Configuration

Environment Variables

The server supports both development and production configurations. Copy `.env.example` to `.env` and configure:

# Environment
NODE_ENV=production  # or development
# FORCE_CLOUDKIT=true  # Force CloudKit in development

# CloudKit Configuration (Required)
CLOUDKIT_CONTAINER_ID=iCloud.com.yourapp.zentasktic
CLOUDKIT_API_TOKEN=your_api_token_here
CLOUDKIT_ENVIRONMENT=production  # or development
CLOUDKIT_AUTH_METHOD=user  # or server-to-server

# Security Configuration (Production)
ENCRYPTION_KEY=your_32_byte_encryption_key_here
ALLOWED_ORIGINS=https://yourapp.com,https://localhost:3000
RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
RATE_LIMIT_MAX_REQUESTS=100
AUDIT_LOGGING=true
SESSION_TIMEOUT_MS=86400000  # 24 hours

# Optional: For server-to-server authentication
# CLOUDKIT_SERVER_KEY=your_server_key_id
# CLOUDKIT_PRIVATE_KEY_PATH=/path/to/private/key.p8
# CLOUDKIT_PRIVATE_KEY_PASSPHRASE=your_passphrase

# Optional: Custom redirect URI
# CLOUDKIT_REDIRECT_URI=https://yourapp.com/auth/callback

CloudKit Dashboard Setup

1. Log into CloudKit Dashboard

2. Select your addTaskManager container

3. Go to API Access → Server-to-Server Keys

4. Create a new JavaScript API token

5. Add your web app's domain to allowed origins

6. Copy the API token to `CLOUDKIT_API_TOKEN`

Usage with Claude Desktop

Add to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

{
  "mcpServers": {
    "addTaskManager": {
      "command": "node",
      "args": ["/path/to/addtaskmanager-mcp-server/dist/index.js"],
      "env": {
        "NODE_ENV": "production",
        "CLOUDKIT_CONTAINER_ID": "iCloud.com.yourapp.zentasktic",
        "CLOUDKIT_API_TOKEN": "your_api_token_here",
        "CLOUDKIT_ENVIRONMENT": "production",
        "ENCRYPTION_KEY": "your_32_byte_encryption_key_here"
      }
    }
  }
}

For development:

{
  "mcpServers": {
    "addTaskManager": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/addtaskmanager-mcp-server",
      "env": {
        "NODE_ENV": "development",
        "CLOUDKIT_CONTAINER_ID": "iCloud.com.yourapp.zentasktic",
        "CLOUDKIT_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Usage with Web App

1. Implement Apple Sign-In on your web app

2. Get user's CloudKit web auth token

3. Call `authenticate_user` with the token

4. Start using realm-specific operations

Example authentication flow:

// After Apple Sign-In success
const authResult = await mcp.callTool('authenticate_user', {
  webAuthToken: user.cloudKitWebAuthToken
});

// Now you can use other tools
const tasks = await mcp.callTool('get_tasks_by_realm', {
  realm: 'assess'
});

ADD Framework Rules

The server enforces these ADD framework restrictions:

Assess Realm

• ✅ Create/edit task content (title, body)
• ✅ Create projects and ideas
• ❌ Assign contexts or due dates
• ❌ Mark as complete

Decide Realm

• ✅ Assign contexts to tasks/projects
• ✅ Set due dates and alerts
• ✅ Move items between realms
• ❌ Edit task/project content
• ❌ Mark as complete

Do Realm

• ✅ Mark tasks/projects as complete
• ✅ View items (read-only)
• ❌ Edit any content
• ❌ Assign contexts or dates

Development

# Clone and install
git clone https://github.com/dragosroua/addtaskmanager-mcp-server.git
cd addtaskmanager-mcp-server
npm install

# Setup environment
cp .env.example .env
# Edit .env with your CloudKit credentials

# Development mode with TypeScript compilation
npm run dev

# Production build
npm run build

# Start built server
npm start

# Code quality
npm run lint
npm run typecheck

# Test (when available)
npm test

Project Structure

src/
├── config/
│   └── production.ts          # Environment-based configuration
├── services/
│   ├── CloudKitService.ts     # CloudKit integration
│   └── UserAuthService.ts     # User authentication
├── types/
│   └── cloudkit.ts           # TypeScript type definitions
└── index.ts                  # Main MCP server implementation

Development Notes

• Uses ESM modules (type: "module" in package.json)
• TypeScript compiled to `dist/` directory
• Supports both development and production CloudKit environments
• Environment-based configuration with security considerations
• Comprehensive type definitions for CloudKit integration

Architecture

AI Assistant (Claude Desktop) → MCP Server → CloudKit Services
                                    ↓
                            Environment Config
                            Security Controls
                            User Authentication
                                    ↓
                            ADD Framework Rules
                                    ↓
                            addTaskManager Data
                            (User's iCloud Container)

Component Overview

• MCP Server: Model Context Protocol server implementation
• CloudKit Integration: Production-ready CloudKit Web Services client
• Authentication: Apple ID-based user authentication with session management
• Security Layer: Encryption, rate limiting, audit logging, CORS protection
• ADD Framework: Realm-based business logic enforcement
• Type Safety: Comprehensive TypeScript definitions

Security

• Environment-Based Security: Different security profiles for development/production
• User Authentication: Apple ID authentication with CloudKit web auth tokens
• Session Management: Secure session handling with configurable timeouts
• Data Encryption: Configurable encryption keys for sensitive data
• Rate Limiting: Configurable request rate limiting with user-specific limits
• CORS Protection: Configurable allowed origins for web app integration
• Audit Logging: Comprehensive operation logging for security monitoring
• Data Isolation: Users can only access their own addTaskManager data
• Realm Enforcement: ADD framework rules prevent unauthorized operations

About the ADD Framework

The ADD (Assess-Decide-Do) framework was created by Dragos Roua as an alternative to GTD (Getting Things Done). It emphasizes:

• Sequential Processing: Items flow through realms in order
• Cognitive Load Management: Each realm has specific, limited functions
• Balanced Productivity: Maintains efficiency while preserving creativity and well-being

Learn more: dragosroua.com