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