kairos

kairos

タスクを書き込む Microsoft Planner MCP サーバーです。

エージェントは Planner のプランにタスクやバケットを作成し、登録内容を一覧表示し、タスクを完了済みにできます。サインインには、お客様自身の Entra アプリを使ったデバイスコード認証を使用し、Graph のスコープは Tasks.ReadWrite のみです。トークンでアクセスできるのは、お客様がメンバーになっているプランだけであり、テナント内のほかの情報にはアクセスできません。

kairos は、メールを送信できないメールサーバーである 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"
      }
    }
  }
}

ターミナルから、または MCP クライアント内でサインインします。

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 の設定は任意です。設定しない場合、各呼び出しでプランを指定する必要があります。ただし、お客様のアカウントから見えるプランがちょうど 1 つの場合は、そのプランが使われます。

クライアント

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="*" を指定します）。バケットを 1 つに絞ることもでき、デフォルトでは未完了のタスクのみ表示します
complete_planner_task	task_id を指定するか、一致するタスクが 1 つだけの場合は title を指定して、タスクを 100% 完了済みにします。reopen=true で取り消せます

プランとバケットは、名前（大文字と小文字を区別しません）または ID で照合されます。一意に特定できる場合は、名前の一部でも指定できます。bucket を省略すると、プランの最初のバケットが使われます。

タイトルでの完了処理では、曖昧な一致を選びません

complete_planner_task(title="deploy") は、プラン内の未完了タスクを検索します。一致が1件なら、そのタスクを完了します。2件以上一致した場合は処理を中止し、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 に関する補足

タスクのメモはタスク自体ではなく、Graph が ETag で保護する子 details エンティティに保存されます。kairos はタスクを作成し、details の ETag を読み取ってから、If-Match を指定して PATCH します。完了処理も、タスク自体に対して同じ手順を行います。Planner は厳しくスロットリングするため、すべての呼び出しで 429 が返された場合は Retry-After に従って再試行し、連続する呼び出しの間には短い待機時間を設けています。新しいタスクとバケットは、列の先頭に配置されます（orderHint: " !"）。

ライセンス

MIT — LICENSE をご覧ください。