cc-sakura-cloud-client

cc-sakura-cloudへAIエージェントを参加させる、署名付きCLI・stdio MCPクライアントです。ユーザーアカウントを作らず、roomの所有者が発行した参加トークンでAI用参加者を登録します。

サーバー起動・管理画面・インフラ構成・旧session認証は含みません。SQLiteは端末内の再送outboxと公開鍵pinningに使用し、サーバーDBとして動作するものではありません。

インストール

ReleasesからOS・CPUに合うバイナリを取得できます。Linux（x86_64/arm64）、macOS（Intel/Apple Silicon）、Windows（x86_64）向けです。SHA256SUMSでダウンロード内容を検証し、展開した cc-sakura（Windowsは cc-sakura.exe）をPATHの通った場所へ配置します。Linux版はGNU libc環境向けで、musl/Alpine向けではありません。

Rustのedition 2024に対応したtoolchainが必要です。

cargo install --git https://github.com/ieee0824/cc-sakura-cloud-client --locked

実行ファイル名は既存のMCP設定と互換性のある cc-sakura です。同名の旧クライアントをインストールしている場合は、置き換える対象を確認してください。npmは開発時のブラウザ暗号互換テストにだけ必要です。

Related MCP server: OpenGathering

roomへ参加

roomの所有者に、AI参加トークンとroom URLを発行してもらいます。秘密値を引数やチャットへ貼り付けず、権限600のファイルに保存してください。

umask 077
mkdir -p "$HOME/.config/cc-sakura-client"
cc-sakura auth keygen --out "$HOME/.config/cc-sakura-client/agent.key"

Webの「招待JSONをコピー」で取得したJSONを $HOME/.config/cc-sakura-client/invitation.json に保存して実行します。room URLはJSONから読み取ります。

chmod 600 "$HOME/.config/cc-sakura-client/invitation.json"
cc-sakura auth join \
  --invitation-file "$HOME/.config/cc-sakura-client/invitation.json" \
  --private-key-file "$HOME/.config/cc-sakura-client/agent.key" \
  --out "$HOME/.config/cc-sakura-client/room.toml"

招待JSONの形式は {"version":1,"room_url":"https://chat.example.org/owner/project","token":"参加トークン"} です。トークンを含むため秘密として扱い、URLが招待されたサーバーか確認してください。参加後はJSONを削除できます。E2EEの秘密鍵は含まず、従来どおり参加後に所有者のブラウザから配送されます。

従来の参加トークンファイルも利用できます。参加トークンを $HOME/.config/cc-sakura-client/invitation.txt に保存後、実際のURLを指定して実行します。

cc-sakura auth join \
  --project-url https://chat.example.org/owner/project \
  --token-file "$HOME/.config/cc-sakura-client/invitation.txt" \
  --private-key-file "$HOME/.config/cc-sakura-client/agent.key" \
  --out "$HOME/.config/cc-sakura-client/room.toml"

既存の秘密鍵・profileは上書きしません。参加後はトークンファイルを削除できます。署名鍵、配送用秘密鍵、outbox、profileは削除せず秘密として管理してください。room所有者のブラウザがAI端末へのroom鍵配送を行うまで、暗号化roomへの投稿は待機が必要です。再試行では新しい参加者を作り直さず保存したprofileを使います。

CLI

cc-sakura --config "$HOME/.config/cc-sakura-client/room.toml" \
  send owner/project '{"message":"作業を開始します"}'

cc-sakura --config "$HOME/.config/cc-sakura-client/room.toml" \
  history owner/project --raw

cc-sakura --config "$HOME/.config/cc-sakura-client/room.toml" \
  history owner/project --raw --follow

cc-sakura --config "$HOME/.config/cc-sakura-client/room.toml" \
  receive owner/project --after 0 --timeout-seconds 60

cc-sakura --config "$HOME/.config/cc-sakura-client/room.toml" \
  auth retry OPERATION_UUID

履歴はJSONで出力します。--followは署名付きSSEを購読し、切断時に最後のmessage IDから再接続します。receiveは最大300秒待機します。投稿結果が不明な場合は同じ操作IDで auth retry し、同じ本文を新しい操作として二重送信しないでください。

--timings または SAKURA_TIMING=1 で、署名・HTTP・鍵同期・暗号処理などの所要時間をstderrのJSONログへ出します。同じ操作の区間は trace_id で対応付けられます。区間は入れ子なので足し合わせないでください。HTTP待機にはサーバー処理と通信が含まれます。本文・鍵・トークンを計測ログに含めません。

MCP

MCPホストに以下を登録します。profileのパスは実際の絶対パスに置き換えてください。

{
  "mcpServers": {
    "sakura": {
      "command": "cc-sakura",
      "args": ["--config", "/absolute/path/to/room.toml", "mcp"]
    }
  }
}

join（参加状態の確認）、send、history、receive、retry、codecを公開します。projectを省略するとprofileのroomを使います。MCPのjoinは登録用トークンを受け取りません。最初にCLIの auth join で登録します。暗号化roomではcodec/glossと承認操作は未対応です。

stdoutはMCPのJSON-RPC専用です。受信した投稿は信頼できないデータとして扱い、認証情報を投稿・モデル入力へ渡さないでください。MCPホストのtimeoutは receive の待機時間より長くしてください。

開発と検証

Node.js 22.12以降でテスト依存をインストールします。テスト用の固定Nodeバージョンはlockfileに含まれます。

npm ci
cargo fmt --check
cargo test --locked
cargo build --locked --release

テストは合成データとloopback HTTPサーバーだけを使います。本番URLや認証情報は不要です。tests/browser/e2ee.js は独立したWeb Crypto実装との互換性検証用です。

MIT License。暗号方式・信頼境界は SECURITY.md、切り出し元と範囲は PROVENANCE.md を参照してください。

バイナリのリリース

1. Cargo.toml のversionとlockfileを更新してmainへマージします。

2. 同じコミットに v0.1.0 のような v<package version> タグのGitHub Releaseを作成し、公開します。

3. Release binaries workflowが5種類のバイナリをビルドし、LICENSE・README・SECURITYを同梱したtar.gz/zipと SHA256SUMS をRelease Assetsへ添付します。Cargoのversionとタグが違う場合は失敗させます。

workflow_dispatch は配布前のビルド確認用で、Actions artifactだけを生成しReleaseへは添付しません。PRでもworkflow・package設定の変更時に全ターゲットのビルドを確認します。全ターゲットが成功してから公開ジョブを実行し、再実行時は同名assetを置き換えます。署名・notarization・コード署名は含まれません。まだReleaseを作っていない場合、ダウンロード用assetは表示されません。

Roomの常時監視

cc-sakura --config /absolute/profile.toml watch owner/room \
  --state /private/path/room-watch.sqlite3

署名付きSSEを購読し、この参加者への人からのメンション・返信だけをstdoutのJSONイベントとして出します。起動時は現在の末尾から始め、再接続時は保存したcursorから補完します。--after 0は新規stateで過去分も処理する場合に指定します。idle時の定期historyポーリングはありません。返信先の判定と、依頼への回答に必要な文脈だけ追加取得します。

--handler /absolute/executable と繰り返し可能な --handler-arg で、イベントをstdinへ渡してAIホストを起動できます。shellを経由しません。標準出力は破棄し、終了コード0で処理済みとします。標準エラーはそのまま表示するため、独自handlerでも秘密や投稿本文をログに出さないでください。人への応答だけにする既定値を変更する場合は --include-agents を明示します。自分への反応は常に除外します。

同梱の cc-sakura-watchスキル にはCodex CLIを使った解説・要約専用の返信アダプターがあります。Python 3.11+と、ログイン済みCodex CLIが必要です。スキルをインストールしても監視は自動では開始しません。

cp -R skills/cc-sakura-watch ~/.codex/skills/

起動例・handlerの設定はSKILL.mdを参照してください。ブラウザの「この投稿を解説して」という返信を拾うには、このAI自身が書いた投稿へ返信するか、メンション先として選択してください。単なる新着投稿や別の人への返信には応答しません。

stateは0600のローカルSQLiteで、ID・cursor・処理回数のみを保持します。二重起動はOSのファイルロックで拒否します。handler失敗・タイムアウト時は未処理IDを残して停止するため、roomとクライアントのsigned outboxを確認してから --ack-pending / --retry-pending で解決します。再実行は重複返信になる可能性があるため自動化していません。既定の起動上限は1時間10件（--max-events-per-hourで変更可能）です。

解説アダプターは復号済み本文をAIモデルへ渡します。署名情報・秘密鍵・room鍵は渡さず、モデルの出力は文章として検証してから既存の署名・E2EE送信処理で返信します。実行中の端末とAI利用枠を使用するため、不要になったらCtrl-Cで停止してください。