Addtaskmanager MCP Server

🚀 addTaskManager MCP 服務器

addTaskManager MCP 服務器是一個與 addTaskManager iOS/macOS 應用集成的 MCP（模型上下文協議）服務器，它實現了由 Dragos Roua 創建的 ADD（評估 - 決策 - 執行）框架。該服務器為你的 addTaskManager 生產力工作流程提供 AI 協助，同時嚴格遵循 ADD 框架基於領域的限制規則。

🚀 快速開始

本 MCP 服務器為你的 addTaskManager 生產力工作流程提供 AI 協助，同時嚴格遵守 ADD 框架基於領域的限制：

• 評估領域：創建和編輯任務/項目/想法，但不能分配上下文或截止日期。
• 決策領域：分配上下文、截止日期和提醒，但不能編輯內容。
• 執行領域：僅將項目標記為已完成（其他情況下為只讀）。

✨ 主要特性

身份驗證

• 安全的蘋果登錄集成。
• 使用 CloudKit.js 進行身份驗證，以訪問個人數據。
• 用戶特定的數據隔離。

評估領域操作

• assess_create_task - 創建具有可編輯內容的新任務。
• assess_edit_task - 編輯任務內容。
• assess_create_project - 創建新項目。
• assess_edit_project - 編輯項目標題。
• assess_create_idea - 捕捉新想法。
• assess_create_collection - 創建新集合。
• assess_create_context - 創建新上下文。
• assess_edit_idea - 編輯想法標題。
• assess_add_task_to_project - 將現有任務添加到項目中。
• assess_add_task_to_idea - 將現有任務添加到想法中。
• assess_remove_task_from_project - 從項目中移除已分配的任務。
• assess_remove_task_from_idea - 從想法中移除已分配的任務。
• assess_archive_task_to_collection - 將任務存檔到現有集合中。
• assess_archive_project_to_collection - 將項目存檔到現有集合中。

決策領域操作

• decide_assign_context - 為任務/項目分配上下文。
• decide_set_project_interval - 設置項目間隔（開始日期和結束日期）。
• decide_set_task_due_date - 為任務設置截止日期。
• decide_set_task_alert - 設置任務提醒。
• decide_move_task_to_do - 將任務移動到執行領域。
• decide_move_task_to_assess_from_decide - 將任務從決策領域移動到評估領域。
• decide_move_project_to_do - 將項目移動到執行領域。
• decide_move_project_to_assess_from_decide - 將項目從決策領域移動到評估領域。

執行領域操作

• do_mark_task_as_done - 將任務標記為已完成。
• do_mark_project_as_done - 將項目標記為已完成。

查詢操作

• get_tasks_by_realm - 按領域過濾任務。
• get_projects_by_realm - 按領域過濾項目。
• get_ideas - 獲取所有想法。
• get_collections - 獲取所有集合。
• get_tasks_by_context - 按上下文過濾。
• get_stalled_items_in_decide - 查找決策領域中停滯的項目（任務 + 項目）。
• get_undecided_items_in_decide - 查找決策領域中未決定的項目（任務 + 項目）。
• get_ready_items_in_decide - 查找決策領域中準備執行的項目（任務 + 項目）。
• get_tasks_today_in_do - 查找執行領域中今天完成的任務。
• get_tasks_tomorrow_in_do - 查找執行領域中明天完成的任務。
• get_tasks_soon_in_do - 查找執行領域中即將完成的任務。
• get_tasks_overdue_in_do - 查找執行領域中逾期的任務。

通用操作

• moveToRealm - 將任務或項目移動到任何領域（評估/決策/執行）。

📦 安裝指南

從 npm 安裝（即將推出）

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

從源代碼安裝

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

📚 詳細文檔

配置

環境變量

服務器支持開發和生產兩種配置。將 .env.example 複製為 .env 並進行配置：

# 環境
NODE_ENV=production  # 或 development
# FORCE_CLOUDKIT=true  # 在開發環境中強制使用 CloudKit

# CloudKit 配置（必需）
CLOUDKIT_CONTAINER_ID=iCloud.com.yourapp.zentasktic
CLOUDKIT_API_TOKEN=your_api_token_here
CLOUDKIT_ENVIRONMENT=production  # 或 development
CLOUDKIT_AUTH_METHOD=user  # 或 server-to-server

# 安全配置（生產環境）
ENCRYPTION_KEY=your_32_byte_encryption_key_here
ALLOWED_ORIGINS=https://yourapp.com,https://localhost:3000
RATE_LIMIT_WINDOW_MS=900000  # 15 分鐘
RATE_LIMIT_MAX_REQUESTS=100
AUDIT_LOGGING=true
SESSION_TIMEOUT_MS=86400000  # 24 小時

# 可選：用於服務器到服務器的身份驗證
# CLOUDKIT_SERVER_KEY=your_server_key_id
# CLOUDKIT_PRIVATE_KEY_PATH=/path/to/private/key.p8
# CLOUDKIT_PRIVATE_KEY_PASSPHRASE=your_passphrase

# 可選：自定義重定向 URI
# CLOUDKIT_REDIRECT_URI=https://yourapp.com/auth/callback

CloudKit 控制檯設置

1. 登錄 CloudKit 控制檯。
2. 選擇你的 addTaskManager 容器。
3. 轉到“API 訪問”→“服務器到服務器密鑰”。
4. 創建一個新的 JavaScript API 令牌。
5. 將你的 Web 應用域名添加到允許的源列表中。
6. 將 API 令牌複製到 CLOUDKIT_API_TOKEN。

使用方法

與 Claude Desktop 一起使用

將以下內容添加到你的 Claude Desktop MCP 配置文件（macOS 上為 ~/Library/Application Support/Claude/claude_desktop_config.json）中：

{
  "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"
      }
    }
  }
}

開發環境配置：

{
  "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"
      }
    }
  }
}

與 Web 應用一起使用

1. 在你的 Web 應用中實現蘋果登錄。
2. 獲取用戶的 CloudKit Web 身份驗證令牌。
3. 使用該令牌調用 authenticate_user。
4. 開始使用特定領域的操作。

示例身份驗證流程：

// 蘋果登錄成功後
const authResult = await mcp.callTool('authenticate_user', {
  webAuthToken: user.cloudKitWebAuthToken
});

// 現在你可以使用其他工具
const tasks = await mcp.callTool('get_tasks_by_realm', {
  realm: 'assess'
});

ADD 框架規則

服務器強制執行以下 ADD 框架限制：

評估領域

• ✅ 創建/編輯任務內容（標題、正文）
• ✅ 創建項目和想法
• ❌ 分配上下文或截止日期
• ❌ 標記為已完成

決策領域

• ✅ 為任務/項目分配上下文
• ✅ 設置截止日期和提醒
• ✅ 在不同領域之間移動項目
• ❌ 編輯任務/項目內容
• ❌ 標記為已完成

執行領域

• ✅ 將任務/項目標記為已完成
• ✅ 查看項目（只讀）
• ❌ 編輯任何內容
• ❌ 分配上下文或日期

開發

# 克隆並安裝
git clone https://github.com/dragosroua/addtaskmanager-mcp-server.git
cd addtaskmanager-mcp-server
npm install

# 設置環境
cp .env.example .env
# 使用你的 CloudKit 憑證編輯 .env

# 開發模式，進行 TypeScript 編譯
npm run dev

# 生產環境構建
npm run build

# 啟動構建後的服務器
npm start

# 代碼質量檢查
npm run lint
npm run typecheck

# 測試（如果可用）
npm test

項目結構

src/
├── config/
│   └── production.ts          # 基於環境的配置
├── services/
│   ├── CloudKitService.ts     # CloudKit 集成
│   └── UserAuthService.ts     # 用戶身份驗證
├── types/
│   └── cloudkit.ts           # TypeScript 類型定義
└── index.ts                  # 主 MCP 服務器實現

開發注意事項

• 使用 ESM 模塊（package.json 中 type: "module"）。
• TypeScript 編譯到 dist/ 目錄。
• 支持開發和生產兩種 CloudKit 環境。
• 基於環境的配置，考慮了安全性。
• 為 CloudKit 集成提供了全面的類型定義。

架構

AI 助手 (Claude Desktop) → MCP 服務器 → CloudKit 服務
                                    ↓
                            環境配置
                            安全控制
                            用戶身份驗證
                                    ↓
                            ADD 框架規則
                                    ↓
                            addTaskManager 數據
                            (用戶的 iCloud 容器)

組件概述

• MCP 服務器：模型上下文協議服務器實現。
• CloudKit 集成：適用於生產環境的 CloudKit Web 服務客戶端。
• 身份驗證：基於蘋果 ID 的用戶身份驗證，帶有會話管理。
• 安全層：加密、速率限制、審計日誌、CORS 保護。
• ADD 框架：基於領域的業務邏輯強制執行。
• 類型安全：全面的 TypeScript 定義。

安全

• 基於環境的安全：開發/生產環境有不同的安全配置文件。
• 用戶身份驗證：使用 CloudKit Web 身份驗證令牌進行蘋果 ID 身份驗證。
• 會話管理：安全的會話處理，可配置超時時間。
• 數據加密：可配置敏感數據的加密密鑰。
• 速率限制：可配置請求速率限制，具有用戶特定的限制。
• CORS 保護：可配置 Web 應用集成的允許源。
• 審計日誌：全面的操作日誌，用於安全監控。
• 數據隔離：用戶只能訪問自己的 addTaskManager 數據。
• 領域強制：ADD 框架規則防止未經授權的操作。

關於 ADD 框架

ADD（評估 - 決策 - 執行）框架由 Dragos Roua 創建，作為 GTD（搞定一切）的替代方案。它強調：

• 順序處理：項目按順序在各個領域中流動。
• 認知負載管理：每個領域都有特定的、有限的功能。
• 平衡生產力：在保持效率的同時，保留創造力和幸福感。

瞭解更多：dragosroua.com