kairos

kairos

一个可写入任务的 Microsoft Planner MCP 服务。

Agent 可在你的 Planner 计划中创建任务和分桶、列出其中的内容，并将任务标记为已完成。登录采用设备代码流程，并委托给你自己的 Entra 应用；只需 Graph 权限范围 Tasks.ReadWrite。令牌只能访问你所属的计划，无法访问租户中的其他内容。

kairos 是 iris 的姊妹项目；iris 是一个无法发送邮件的服务。它们刻意保持独立。iris 的价值在于不具备某项能力；Planner 写入服务的价值则在于写入本身。创建任务就是创建任务，完成任务就是完成任务。kairos 不会假装情况有所不同，因此安装前请先阅读它能做和不能做的事。

---

安装

uvx kairos-mcp        # run without installing
pip install kairos-mcp

Python 3.10 或更高版本。 macOS 自带 Python 3.9，版本太旧——mcp 需要 3.10 以上版本。请使用 uv（它附带 uvx 并管理自己的 Python），或者通过 Homebrew 安装当前版本的 Python（brew install [email protected]）。macOS 上的系统 python3 无法使用。

设置

你必须注册自己的 Entra 应用程序。 没有共享应用注册，也没有托管服务——kairos 会从你的计算机直接连接到你的租户。共享应用意味着必须信任他人的客户端 ID，使其拥有对你计划的写入权限。

1. Entra 管理中心 → 应用注册 → 新注册。单租户即可。无需重定向 URI。
2. 身份验证 → 设置 → 启用允许公共客户端流。设备代码登录需要此设置。任何地方都不会使用客户端密钥。
3. API 权限 → Microsoft Graph → 委托 → 添加 Tasks.ReadWrite（“创建、读取、更新和删除用户的任务和项目”）。不要添加其他权限。
4. 复制应用程序（客户端）ID和目录（租户）ID。两者都不是机密。

然后将 kairos 添加到你的 MCP 客户端：

{
  "mcpServers": {
    "kairos": {
      "command": "uvx",
      "args": ["kairos-mcp"],
      "env": {
        "KAIROS_CLIENT_ID": "<application (client) id>",
        "KAIROS_TENANT_ID": "<directory (tenant) id>",
        "KAIROS_DEFAULT_PLAN": "Development"
      }
    }
  }
}

登录一次，可以在终端中执行：

KAIROS_CLIENT_ID=... KAIROS_TENANT_ID=... uvx kairos-mcp auth

也可以在 MCP 客户端中执行：调用 kairos_login，打开 URL 并输入代码，然后调用 kairos_login_finish。无论哪种方式，令牌缓存都会保存在 ~/.config/kairos/token_cache.json 中，权限模式为 600，此后会自动静默刷新。

KAIROS_DEFAULT_PLAN 是可选的。如果不设置，每次调用都必须指定计划——但如果你的帐户只能看到一个计划，则会使用该计划。

客户端

kairos 是一个本地 stdio MCP 服务：MCP 客户端会在同一台计算机上将其作为子进程启动。它适用于任何支持本地 stdio 服务的客户端，例如 Claude Desktop、Cursor、Grok CLI 等。不适用于只接受通过 HTTP 连接远程 MCP 服务的客户端。

工具

工具	功能
kairos_login	启动设备代码登录，返回 URL 和代码
kairos_login_finish	完成登录；输入代码期间可安全地重复调用
kairos_auth_status	查看谁已登录、Graph 是否可访问，以及可见计划的数量
list_planner_plans	列出你可见的所有计划及其分桶和 ID（缓存几分钟；设置 refresh=true 可重新读取）
create_planner_task	创建任务：title、可选的 notes、plan、bucket、due_on（YYYY-MM-DD）。返回任务 ID 和 URL
create_planner_bucket	在计划中创建分桶。具有幂等性——如果已存在同名分桶，则返回该分桶而不会重复创建
list_planner_tasks	列出某个计划中的任务（或使用 plan="*" 列出所有任务），可选择仅列出一个分桶；默认仅列出未完成的任务
complete_planner_task	按 task_id 将任务标记为 100% 完成，或在标题匹配唯一时按 title 标记。reopen=true 可撤销此操作

计划和分桶按名称（不区分大小写）或 ID 匹配。名称部分匹配仅在结果唯一时有效。省略 bucket 时，将使用计划中的第一个分桶。

按标题完成任务时会拒绝有歧义的情况

complete_planner_task(title="deploy") 会搜索计划中的未完成任务。找到一个匹配项：将其完成。找到两个或更多：停止操作并列出它们的 ID，以便你使用确切的 task_id 再次调用。它绝不会替你选择。

CLI

kairos-mcp            run the MCP server on stdio (what your client launches)
kairos-mcp auth       interactive device-code sign-in
kairos-mcp status     who is signed in, is Graph reachable
kairos-mcp logout     remove the token cache

重新进行身份验证

密码更改、管理员撤销授权或长时间未使用后，刷新令牌会失效。此后，每个工具都会返回说明原因及解决方法的消息：在终端中运行 kairos-mcp auth，或在客户端中依次调用 kairos_login → kairos_login_finish。无需更改其他内容。

能做和不能做的事

能做： 在你所属的任何计划中创建任务和分组；创建任务时设置备注和截止日期；列出计划、分组和任务；将任务标记为已完成或重新打开。

不能做： 删除任何内容——没有删除工具，设计上也会一直如此。分配人员。设置优先级、标签、检查清单或附件。编辑现有任务的标题、备注或截止日期。查看你不属于其成员的计划。

Tasks.ReadWrite 是允许创建 Planner 任务的权限范围最窄的 Graph 权限。它也允许读取和更新你所属的每个计划中的所有任务，原则上还允许删除这些任务。kairos 不提供删除功能，但令牌拥有此权限——边界在于这段代码，而不是 Microsoft 的授权屏幕。如果你在意这个区别，就应该在意；请参阅 SECURITY.md。

其他控制

• 紧急停用开关 — 创建 ~/.config/kairos/DISABLED，或设置 KAIROS_DISABLED=1，所有工具都会拒绝执行操作。
• 审计日志 — 每次写入操作（登录、创建、完成、重新打开）都会追加到 ~/.config/kairos/audit.log。
• KAIROS_CONFIG_DIR 可将缓存、日志和紧急停用文件移至其他位置；KAIROS_TOKEN_CACHE 和 KAIROS_AUDIT_LOG 可分别覆盖单个路径。

Graph 说明（供感兴趣者参考）

任务备注不在任务本身上，而是存储在子级 details 实体中，Graph 会用 ETag 对其进行保护。kairos 会创建任务、读取 details 的 ETag，然后使用 If-Match 发送 PATCH 请求。完成任务时也会对任务本身进行同样的操作。Planner 的速率限制很严格，因此每次调用在遇到 429 时都会根据 Retry-After 重试，串联调用之间也会短暂停顿。新任务和分组会固定在其列顶部（orderHint: " !"）。

许可证

MIT — 请参阅 LICENSE。