Caelo CMS

@caelo-cms/mcp-server

Caelo CMS のインストール環境向け MCP サーバーです。トークンのスコープによって、2 つの接続先が選択されます。

• caelo_chat（デフォルトモード、スコープ chat）— Caelo 独自の AI エージェントと通信します。実現したいことを説明すると、Caelo の chat-runner が作業を行います。
• Power-MCP（caelo-admin-mcp バイナリ／caelo-mcp-server admin、スコープ admin）— chat-runner のツールカタログ全体を直接公開するため、あなたのエージェント（Claude Code など）がツールループを操作し、Caelo 自身はプロバイダーへの呼び出しを行いません。さらに、caelo-mcp-server export は、インストール環境の実行時コンテキストから生成した CLAUDE.md と .claude/skills/ ツリーを書き出します。

どのモードも薄いシムです。呼び出しは HTTPS POST に変換され、管理者用インストール環境の /api/mcp/* エンドポイントに送信されます。これらのエンドポイントは、ライブ編集オーバーレイを支えるものと同じ chat-runner の仕組みに処理を渡します。Power-MCP の動作モデル全体（作業セッション、共有ドラフト、承認ゲート）については、ドキュメントの MCP ページをご覧ください。

インストール

Caelo のインストール環境で、次の操作を行います。

1. Owner として /settings/mcp にアクセスします。
2. New token をクリックし、名前（claude-code、laptop、ci など）を付け、必要に応じて AI の利用上限（マイクロセント）を設定して、一度だけ表示されるベアラートークンをコピーします。
3. ページには、Claude Code、Claude Desktop、Codex CLI、Cursor、VS Code、Gemini CLI 用の、すぐにコピーできるセットアップ手順が表示されます。ターミナルコマンドまたは JSON 設定エントリーに加えて、クライアントによる読み込み方法も記載されています。

デスクトップアプリ（Claude Desktop、Cursor、VS Code）はターミナルの PATH を引き継ぎません。設定には bunx のフルパス（which bunx）を指定し、名前だけを指定しないでください。

ブラウザー上の ChatGPT と claude.ai は、このサーバーを利用できません。インターネット上でホストされる MCP サーバー（Streamable HTTP + OAuth）にしか接続できませんが、このサーバーは stdio 経由でお使いのマシン上で動作するためです。#806 で追跡しています。

その他の MCP 対応クライアントを手動で設定する場合：

# stdio server invoked by your MCP-aware client
bunx @caelo-cms/mcp-server@latest

起動時に、インストール環境で実行されているものと完全に同じリリースに切り替わります（ドキュメントの MCP ページをご覧ください）。そのため、コマンドにバージョンを指定する必要はありません。また、@latest によって bunx が古いキャッシュ済みインストールを再利用しないようにします。

次の環境変数を設定してください。

変数	必須	備考
CAELO_ADMIN_URL	はい	https://admin.example.com — インストール環境を指定します。https:// が必須です（http:// は localhost の場合のみ使用できます）。
CAELO_MCP_TOKEN	はい	/settings/mcp で発行されたベアラーです。
CAELO_IAP_SERVICE_ACCOUNT	GCP のインストール環境では必須	管理者用の MCP サービスアカウントです。管理者用環境が Google IAP の背後にある場合、/settings/mcp の各クライアント用スニペットに含まれます。

CAELO_ADMIN_URL または CAELO_MCP_TOKEN を設定しなくてもサーバーは起動し、ツールを一覧表示します（MCP ディレクトリはサーバーをこの方法で調べます）が、ツール呼び出しはすべて失敗し、設定が必要な変数名が示されます。その場合、Power-MCP はこのリリースに同梱されているカタログ（power-catalogue.json）を一覧表示します。設定後は、プラグインのツールも含む管理者用の最新カタログが常に一覧表示されます。export は代わりに終了します。

Google IAP の背後にあるインストール環境（GCP）

gcp および gcp-firebase のインストール環境では、管理者用環境は Identity-Aware Proxy の背後にあります。Google の認証情報が含まれていないリクエストは、Caelo が受け取る前にすべて拒否されます。CAELO_IAP_SERVICE_ACCOUNT が設定されている場合、サーバーは Application Default Credentials を使い、IAM Credentials の signJwt でそのサービスアカウントとして有効期間の短い JWT に署名し、x-caelo-mcp-token とともに Authorization ヘッダーで送信します。IAP は前者を、Caelo は後者を検証します。

お使いのマシンで一度だけ、次のセットアップを行います。

gcloud auth application-default login

プロビジョナーはサービスアカウント（caelo-mcp@<project>）を作成し、IAP の許可リストに追加して、IAP の許可リストに登録された全員がそのアカウントとして署名できるようにします。新しいインストール環境では Pulumi を通じて、既存の環境では cms-provision upgrade の実行時に設定されます。サービスアカウントキーは使用しません。

caelo_chat ツール

フィールド	型	説明
message	string, required	Caelo エージェントに伝えたい内容です。
chatSessionId	uuid, optional	既存のチャットセッションを続けます。
attachments	array, optional	caelo_upload_images が返す画像参照を最大4件指定します。
pageId	uuid, optional	新しいチャットを1つのページに紐付け、エージェントのページコンテキストブロックに情報を入力します。

出力：アシスタントの返信テキストと、chatSessionId（次の呼び出し用）、requestId（完全な監査証跡を確認するには /settings/audit/<requestId> に進みます）、エージェントが実行した構造化されたツール呼び出しの要約、ターンごとのコスト（マイクロセント単位）、およびエージェントが「Owner の承認待ちの項目が N 件あります」と通知するための pendingProposals 件数を含む JSON ブロックです。

編集をチャット経由にする理由

閲覧／公開／提案の操作はチャット経由で行います。「どのページがありますか？」と尋ねると、Caelo エージェントが内部で pages.list を呼び出し、テキストで回答します。認証サーフェス、RLS のスコープ設定、監査証跡、ブラウザーと同じ提案・実行の Owner 承認ゲートを使用します。リモートエージェントはプログラム用 API ではなく、人間と同等のエージェントとやり取りします。

ライセンス

MPL-2.0。

画像のアップロード

どちらのモードでも caelo_upload_images を利用できます。たとえば、次のように呼び出します。

{"images":[{"filePath":"/home/me/Pictures/character.png","alt":"Main character reference"}]}

パスは MCP プロセスからの相対パスです。代わりに、base64 と任意の filename を使用できます。filePath と base64 のいずれか一方だけを指定してください。アップロードでは PNG／JPEG／WebP／GIF に対応しており、1ファイルあたり最大5 MiB、1回の呼び出しあたり最大4ファイルをアップロードできます。結果にはファイルごとの成功／エラーと attachments 配列が含まれます。この配列を message とともに caelo_chat に渡すと、画像の実際の内容を Caelo の AI に送信できます。管理者モードでは、返されたアセット ID を通常のメディア／ページツールで使用できます。

どちらのスコープでも、トークン所有者に現在の content.write 権限が必要です。画像は共有 CMS メディアライブラリに保存され、管理者向けのプレビューには認証が必要です。アップロードだけではページは公開されません。一部のファイルのアップロードに失敗した場合も、成功したファイルは保持されるため、失敗した項目だけを再試行してください。HTTP の例とサーバーの制限については、ドキュメントの MCP ページを参照してください。