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)

Related MCP server: DeltaTask MCP Server

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