CoralSwarm Connect

CoralSwarm Connect

CoralSwarm MCP に接続し、作業内容をセッション中に自動で海に記録できるようにします。記録はセッション終了時だけでなく、セッション中の自然な区切りで行われます。Claude Code、Cursor、Codex 向けに提供されています。管理ツールのいずれか1つでプラグインを有効にしてください。2つで有効にすると SessionStart が2回実行されます（カーネルが重複分を何もしないように処理します）。

インストール

公開ディレクトリへの申請資料と、別途用意された OpenAI ZIP ビルダーについては、ディレクトリへの公開を参照してください。OpenAI ディレクトリパッケージは、リクエストされた検索と選択した保存をキャプチャフックなしでサポートします。以下のコーディングプラグインでは、従来のキャプチャ動作が維持されます。

利用方法は2段階あります。プラグインでは、MCP ツールに加えてキャプチャフックと同梱のスキルを利用できます。生の MCP URLではツールのみを利用でき、どの MCP クライアントでも動作します。

クライアント	インストール
Claude Code（プラグイン）	/plugin marketplace add CoralSwarm/coralswarm-connect 続けて /plugin install coralswarm-connect@coralswarm-connect
Cursor（プラグイン）	このリポジトリをプラグインソースとして追加し、coralswarm-connectをインストールしてから、MCP ログインを完了します
Codex（プラグイン）	同じリポジトリ、同じプラグイン名を使用します。初回に Codex からフックを信頼するか確認される場合があります
任意の MCP クライアント — Cursor、ChatGPT、VS Code、ご自身のクライアントなど —（ツールのみ）	streamable HTTP タイプの MCP サーバーを https://api.coralswarm.com/mcp に追加します

coralswarm-connect@coralswarm-connectは誤記ではありません。前半はプラグイン、後半はこのリポジトリが公開するマーケットプレイスを指します（どちらもcoralswarm-connectという名前です。.claude-plugin/marketplace.jsonを参照してください）。シェルでは、同じ2つのコマンドを claude plugin marketplace add … ／ claude plugin install … として実行できます。

いずれかの方法でインストールしたら、認証を行います。Claude Code では /mcp を実行し、coralswarmサーバーの認証を選択します。Cursor では /mcp login または mcp_auth プロンプトを使用します。認証方式は、動的なクライアント登録を使う OAuth（Clerk）です。貼り付ける API キーも、設定ファイルに記載する内容もありません。

MCP URL には、記載されている文字列をそのまま指定する必要があります。Cursor は、サーバーの保護リソースメタデータと一致しない fly.dev リソースを拒否します。

CoralSwarm Connect は、現時点ではどのクライアントの組み込みプラグインディレクトリやコネクタディレクトリにも掲載されていません。上記は、現在利用できる手順です。このリポジトリには、公式 MCP Registry向けに com.coralswarm/coralswarm という名前で登録するための server.json も含まれています。これはリリースタグによって公開されます（リリースを参照）。そのため、タグが公開されるまでは、Registry に掲載済みとはみなさないでください。

プラグインが有効なときは、scripts/install.mjsを実行しないでください。settings.jsonに同じイベントが二重に登録されてしまいます。

公開プラグインリポジトリ。 このリポジトリはマーケットプレイスのソースです。製品のバックエンドは引き続き CoralSwarm/coralswarm にあります。/plugin marketplace update coralswarm-connectで更新してください。

初回の信頼確認と OAuth。 プラグインが提供する MCP サーバーでも、初回はサーバーの承認（信頼確認プロンプト）と /mcp による OAuth の完了が必要です。プラグインはサーバーを宣言しますが、アカウントを事前に認証することはできません。

プラグインが設定する内容

1. MCP 接続（.mcp.json）— CoralSwarm MCP サーバーを （HTTP トランスポートで）宣言し、認証後にそのツール（list_oceans、recent_activity、ask_ocean、 search_atoms、get_reef、add_context、list_sessions、…）を利用できるようにします。

   プラグインの .mcp.json はそのままの URL https://api.coralswarm.com/mcp です（ホストは ${VAR:-default} を展開せず、 Cursor はサーバーの保護されたリソースのメタデータとバイト単位で完全に一致する必要があります）。組織ごとの別のアドレスはありません。同じ URL で、個人の ocean と、所属しているすべての組織にアクセスできます。ステージング環境やローカルバックエンドは、ユーザーレベルの MCP 上書き設定（~/.cursor/mcp.json / claude mcp add）で指定します。プラグインは編集しません。

   個人用か組織用かは URL ではなく、インバンドで選択します。1 つ以上の組織に所属している場合、接続はワークスペース用ツールの list_tenants と select_tenant のみに制限された状態で開始されます。list_tenants を呼び出し、次に select_tenant で目的の組織を選択します（個人の ocean を使う場合は org_id を指定しません）。これにより、選択した領域に限定された残りのツールが利用可能になります。いつでも select_tenant を再度呼び出せば切り替えられます。以前の URL ごとの設定と異なり、新しいセッションは不要です。

   両方を同時に使いたい場合は、この同じ URL を別のサーバー名で 2 回目として登録し（下記の手動インストールを参照）、各登録で個別に select_tenant を呼び出します。それぞれが独自の OAuth 接続と記憶された選択内容を持ちます。1 つのセッションで両方のツールセットを利用でき、サーバー名で区別できます。

2. キャプチャフック（hooks/hooks.json）。すべてセッション中に実行されます。

   • SessionStart → エージェントに、関連する ocean のコンテキストを読み込み、各マイルストーンを発生時に保存するよう促します。また、エージェントがすべての保存に付与する、サニタイズ済みのセッションメタデータ（プロジェクトキー、Git ブランチ、認証情報を除去したリモート、リポジトリパス、ホスト名、ハーネスのバージョン）を出力します。ハイブリッドのインベントリ行には、登録済みのキャプチャイベントとこのセッションで観測されたイベントが一覧表示されます。特定のイベントが一度も発生しないホストでも、ターンをブロックせず、機能を制限した状態で動作します。
   • UserPromptSubmit → 最近の進捗を保存するよう促すデバウンス済みのリマインダー（アクティブな作業約 15 分ごと）と、セッション中に Git ブランチが変わった際の 1 行通知を送ります。これはセッション中に繰り返し実行されるキャプチャです。
   • PreCompact → 会話がコンパクト化される直前に、未保存の作業を ocean にフラッシュし、何も失われないようにします。
   • Stop → 最後の安全策（約 10 分間のデバウンス）です。
   • PostToolUse（マッチャー add_context）→ add_context による保存が実行されるたびにローカルのアクティビティ台帳に記録します（Claude mcp__…add_context、Cursor MCP: …/add_context / CallDynamicTool）。これにより、クラッシュしたセッションを確実に復旧できます（下記を参照）。すべてのイベントは hooks/run.mjs を通じてディスパッチされます。

3. coralswarm-connect スキル — **「onboard coralswarm」**と伝えると、同梱のスキルが同じセットアップ手順を会話形式で案内します（別の方法で MCP をインストールした場合や、接続を一通り確認したい場合に便利です）。

**プラグインのインストールには、必ず Stop の安全策が含まれます。**手動インストーラー （scripts/install.mjs）では、これを省略する --no-stop フラグを指定できます。しかし、プラグインの hooks.json は静的で、インストール時のフラグを受け取れないため、ここでは Stop フックが常に含まれます。約 10 分ごと、セッション単位でデバウンスされるため、頻繁に実行されることはありません。主な処理は PreCompact とセッション中のリマインダーが担います。

フックは ${CLAUDE_PLUGIN_ROOT} を参照します。Claude Code、Cursor、Codex はこれをこのプラグインのインストールディレクトリに展開します。各イベントのコマンドは node "${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs" です（Cursor は独立した args 配列を無視します）。フックスクリプトはセッションごとのデバウンス状態、ブランチ状態、プライマー状態を ~/.coralswarm/state/ に書き込みます（手動インストールの場合と共有されます）。プライマーは session_id ごとに 1 回だけ実行されるため、Claude と Cursor を両方インストールしても二重に挿入されません。

セッションメタデータと認証情報の除去保証（フェーズ 2）

SessionStart プライマーはフックの標準入力ペイロードを読み取り、ベストエフォートでセッションメタデータを収集します。利用できないフィールドは省略され、git／環境変数が利用できない場合もフックは実行を続けます。セッションチェックポイントの保存には、引き続き session_id が必要です。任意の出所情報は省略できます。Git リモートは、バックエンドの v1 ノーマライザー（backend/src/project_key.rs）をバイト単位で忠実に移植した hooks/project-key.mjs を通して処理されます。このノーマライザーは、値がプロンプトに注入される前に、埋め込み認証情報を必ず除去します。そのため、https://x:[email protected]/a/b.git のようにトークンを含むリモートも、出力されるのは github.com/a/b のみです。これらの値はベストエフォートの出所情報であり、サーバーはすべてを再正規化し、再検証します。

エージェントセッション — バックグラウンド実行、ボットとそのサブエージェント

ボットやバックグラウンドワーカーは、安定した session_id と session_kind="agent" の両方を add_context に渡し、agent_name と実際のクライアントの platform を指定することで、エージェントセッションを保存します。トピックが変わっても同じセッション ID を使い、マイルストーンごとに新しいチェックポイント ID を使用してください。session_kind だけを指定した場合、保存されるのは引き続きノートです。

サポート対象のハーネスでは、エージェント名を指定するだけで十分です。起動前に CORALSWARM_AGENT_NAME を設定するか、自身の名前を CLAUDE_AGENT_SDK_CLIENT_APP で指定する Claude Agent SDK のもとで実行すると、プライマーはハーネスのセッション ID とともに agent_name を出力します。サーバーはその名前の有無から session_kind=agent を推測します。サーバーがほかの方法で識別できないハーネスの場合に限り、CORALSWARM_SESSION_KIND=agent（および CORALSWARM_PLATFORM、CORALSWARM_TASK）を明示的に設定してください。カスタムボットは MCP を直接呼び出し、実行状態にセッション ID とチェックポイント ID を保持します。スタンドアロンのノート、コーディングの会話、ボットのチェックポイント、再試行、保存内容の確認については、保存の仕様と例を参照してください。環境変数と、各サブエージェントのセッションを親にリンクする方法については、エージェントのセットアップを参照してください。

決定論的な照合 — クラッシュまたは強制終了したセッションの復旧方法

上記の通知はモデル主導です。エージェントが対応しなければ効果はありません。 それでも作業が取りこぼされるケースが3つあります。

• 強制終了 — SIGKILL、ノートPCを閉じる、OOM などの場合、終了フックは一切実行されないため、終了時に何も書き出せません。
• エージェントがセッション途中の通知を無視する。
• 1回の長いターンで、デバウンスされたリマインダーの間に大量の作業が行われる。

終了したセッションは、終了時に「未保存の作業があります」というマーカーを書き込めないため、プラグインは通常の動作中に継続的にハートビートを書き込み、次のセッションの開始時に照合します。セッションごとに、小さなレコード（パスとタイムスタンプのみで、トランスクリプトの内容は一切含みません）を次の場所に保持します。 ~/.coralswarm/state/sessions/{session_id}.json

• SessionStart、UserPromptSubmit、Stop／PreCompact は last_activity_at を更新し、トランスクリプトのパス、cwd、プロジェクトキーを記録します。
• PostToolUse フックは add_context が実行されるたびに last_save_at を記録します。復旧時の保存で、ツール入力に元のセッションの session_id を渡すと、そのセッションのレコードに記録されます。これにより、後のセッションでの保存が、以前のセッションの保留フラグを確実に解除できます。

次の新しい SessionStart で、プライマーは台帳をスキャンし、同じプロジェクトに属し、過去7日以内のもので、現在のセッションを除外したうえで、last_activity_at が last_save_at より後（つまり、作業が一度も保存されていない）となっているレコードを最大3件、最近のものから抽出します。各セッションについて、そのセッションのローカルトランスクリプトの末尾のみを読み取るよう、範囲を限定した指示を注入します（ファイルサイズは数百 MB に達することがあるため、全体を読むことは決してありません）。その内容を簡潔な要約にまとめ、元の session_id を指定して add_context で保存します。これによりフラグが解除されます。各セッションが提示されるのは最大2回で、その後は放棄済みとしてマークされ、一覧が整理された状態に保たれます。30日を過ぎたレコードは削除されます。

この仕組みはすべてローカルで完結します。バックエンドの変更も、長期間有効なトークンも、トランスクリプトの生データのアップロードもありません。保存する内容を選ぶのは、引き続きモデルだけです。台帳が決定論的にするのは、あくまでリマインダーです。注入時の安全対策として、台帳の値はデータとして扱います。候補として提示するのは、session_id が UUID 形式で、トランスクリプトのパスがホームディレクトリ内に実際に存在するファイルである場合に限ります。ID とパスから制御文字を除去して JSON エスケープし、トランスクリプトの内容をプライマーが読み込むことは一切ありません。

環境変数で調整できます（間隔変数と同様に、有限の正の値に制限されます）。 CORALSWARM_RECONCILE_WINDOW_DAYS（7）、CORALSWARM_RECONCILE_PRUNE_DAYS（30）、CORALSWARM_RECONCILE_MAX_OFFERS（2）、CORALSWARM_RECONCILE_MAX_CANDIDATES（3）。

テスト（依存関係なし）

node tests/run.mjs

Rust のユニットテストと同じケースマトリクスを使ったノーマライザーの実行、トークンを含むリモートがある一時的な git リポジトリでのエンドツーエンドの session-primer 実行（出力にシークレットが決して現れないことを検証）、リポジトリ外での正常な機能縮退、クラッシュ後の照合、run.mjs を介した Cursor 形式の stdin（デュアルエミット、プライマーの1回のみの実行、MCP:／CallDynamicTool による保存の記録）、決定論的照合の台帳、およびすべての .mjs に対する node --check を実行します。自動再開（[CoralSwarm resume]）は意図的に含めていません。

キャプチャは、接続済みのエージェントが add_context MCP ツールを呼び出して実行されるため、既存の OAuth を利用します。認証情報は保存されず、バックエンドの変更も不要です。

手動でのインストール／アンインストール（フォールバック、プラグインシステムなし）

プラグイン経由で利用できない場合（古い Claude Code を使っている場合や、特定の settings.json スコープにフックを設定したい場合）は、従来のインストーラーも引き続き利用できます。フックスクリプトを ~/.coralswarm/hooks/ にコピーし、Claude Code の settings.json にフックのエントリーを冪等にマージします。既存のフックが上書きされることはなく、コマンドパスが CoralSwarm のフックディレクトリを指すフックだけが対象になります。

node scripts/install.mjs --scope project     # this repo only (default)
node scripts/install.mjs --scope user        # every session
node scripts/install.mjs --scope project --no-stop     # omit the Stop backstop
node scripts/install.mjs --scope project --uninstall

手動インストールとプラグイン経由のインストールは機能的に同等です（同じ 4 つのイベント、同じコマンド）。同じスコープに両方を実行しないでください。フックが二重に実行されます。プラグインをインストールした場合、手動インストーラーは不要です。

自動化の範囲と決定論的なアップグレード

これはモデル駆動型です。キャプチャーの成否は、エージェントがフックのプロンプトに従って動作するかどうかに左右されます。重要なマイルストーンの記録には信頼できますが、バイト単位での完全な保証はありません。完全に決定論的な方法として、エージェントの動作に関係なくセッションの生のトランスクリプトを CoralSwarm に POST するシェルフックが考えられますが、そのためにはオンボーディング時に発行する長期間有効な CLI トークンと、取り込み認証エンドポイントが必要です。これは文書化済みの今後の対応項目であり、まだ実装されていません。

その他のホスト

新しい MCP ホストにはカーネルの書き換えではなく、新しいマニフェストが必要です。Claude Code は .claude-plugin/plugin.json、Cursor は .cursor-plugin/plugin.json、Codex は .codex-plugin/plugin.json を使用します。これら 3 つはすべて、同じ .mcp.json、skills/、hooks/hooks.json を参照します。scripts/install.mjs は、プラグインマネージャーがないマシン向けに、引き続き Claude の settings.json 用フォールバックとして使われます（exec 形式：command: "node"、args: [absolute run.mjs]）。

リリース

1 つのバージョンを 4 つのマニフェストで管理します：.claude-plugin/plugin.json、 .cursor-plugin/plugin.json、.codex-plugin/plugin.json、server.json です。scripts/check-version.sh はバージョンが一致しない場合に失敗し、PR の CI でも実行されます。

# 1. bump all four to the new version, in a PR
bash scripts/check-version.sh          # must pass before you push

# 2. after it merges, tag the merge commit on main
git tag v1.2.3 && git push origin v1.2.3

タグを作成すると .github/workflows/release.yml が開始され、タグがマニフェストのバージョンと一致すること（--expect）を再確認し、テストを実行し、server.json を検証し、coralswarm.com の DNS 証明でレジストリに認証してから公開します。ブランチや PR から公開されることはありません。

バージョンには厳密な SemVer 2.0.0 を使用します。レジストリは範囲指定を受け付けず、SemVer に準拠しないバージョンは公開後に予測可能な順序で並ばないため、先頭のゼロや空の識別子は使用できません。このジョブが実行する mcp-publisher バイナリは、署名キーを保持する唯一のステップであるため、特定のリリースに固定し、実行前にチェックサムを検証します。

GitHub OIDC ではなく DNS 証明を使うのは、レジストリが認証方式に基づいて名前空間を決定するためです。GitHub 認証で許可されるのは io.github.<owner>/* のみですが、com.coralswarm/* のような逆引き DNS 名前空間にはドメイン検証が必要です。coralswarm.com の頂点 TXT レコードと MCP_REGISTRY_DNS_PRIVATE_KEY シークレットについては、ワークフローのヘッダーに記載されています。

サポート

• バグと機能リクエスト：GitHub Issues
• その他のお問い合わせ：[email protected]
• セキュリティ：SECURITY.md を参照してください

コントリビューション

PR のみ受け付けます。main はロックされています。CONTRIBUTING.md と SECURITY.md を参照してください。PR を作成する前に node tests/run.mjs と bash scripts/check-version.sh を実行してください。