-
securityF
license-
qualityEnables integration with Things3, allowing the creation and management of tasks and projects via the MCP protocol, including synchronization with Agenda projects.
Last updated -
39
Integrates with Apple's ecosystem through Apple Sign-In authentication and CloudKit services for secure access to user data stored in iCloud containers
Provides direct integration with iCloud CloudKit services for managing personal productivity data within the addTaskManager iOS/macOS app, including tasks, projects, ideas, and collections stored in the user's iCloud container
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 contentassess_edit_task- Edit task contentassess_create_project- Create new projectsassess_edit_project- Edit project titleassess_create_idea- Capture new ideasassess_create_collection- Create new collectionassess_create_context- Create new contextassess_edit_idea- Edit idea titleassess_add_task_to_project- Add an existing task to a projectassess_add_task_to_idea- Add an existing task to an ideaassess_remove_task_from_project- Remove a task assigned to a projectassess_remove_task_from_idea- Remove a task assigned to an ideaassess_archive_task_to_collection- Archive a task to an existing collectionassess_archive_project_to_collection- Archive a project to an existing collection
Decide Realm Operations
decide_assign_context- Assign contexts to tasks/projectsdecide_set_project_interval- Set a project interval (start date and end date)decide_set_task_due_date- Set due date to a taskdecide_set_task_alert- Set task alertsdecide_move_task_to_do- Move task to Do realmdecide_move_task_to_assess_from_decide- Move task to Assess realmdecide_move_project_to_do- Move project to Do realmdecide_move_project_to_assess_from_decide- Move project to Assess realm
Do Realm Operations
do_mark_task_as_done- Mark tasks as completeddo_mark_project_as_done- Mark projects as completed
Query Operations
get_tasks_by_realm- Filter tasks by realmget_projects_by_realm- Filter projects by realmget_ideas- Get all ideasget_collections- Get all collectionsget_tasks_by_context- Filter by contextget_stalled_items_in_decide- Find stalled items (task + projects) in Decideget_undecided_items_in_decide- Find undecided items (task + projects) in Decideget_ready_items_in_decide- Find ready to do items (task + projects) in Decideget_tasks_today_in_do- Find tasks done today in Doget_tasks_tomorrow_in_do- Find tasks done tomorrow in Doget_tasks_soon_in_do- Find tasks done soon in Doget_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
Log into CloudKit Dashboard
Select your addTaskManager container
Go to API Access → Server-to-Server Keys
Create a new JavaScript API token
Add your web app's domain to allowed origins
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
Implement Apple Sign-In on your web app
Get user's CloudKit web auth token
Call
authenticate_userwith the tokenStart 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/directorySupports 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
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityProvides API access to a locally-hosted task management system with features for creating, updating, and organizing tasks, including support for urgency levels, effort estimates, subtasks, and bi-directional sync with Obsidian markdown files.Last updated -1212MIT License
- AsecurityAlicenseAqualityAdds persistent task management to AI coding assistants in IDEs, allowing them to track multi-step tasks across sessions and maintain organized workflow with project-scoped todo lists.Last updated -223MIT License
- AsecurityFlicenseAqualityEnables AI assistants to manage tasks through YAML-based storage with subtask suggestions, status updates, and Mermaid Gantt chart generation. Supports hierarchical task structures with attributes like dependencies, milestones, and parallel execution.Last updated -2661