acquia-source

Acquia Source

Acquia Source（「Source powered by Drupal CMS」）は、Drupal CMS 11+ と Drupal Canvas ページビルダー（drupal.org/project/canvas、旧 Experience Builder）を基盤とするマネージド SaaS CMS です。サーバー／SSH アクセスや任意の contrib モジュールは利用できません。操作には JSON:API、MCP サーバー、Canvas Page API、@drupal-canvas CLI を使用します。管理画面／ログイン先は https://source.acquia.com です。

Acquia Source は SaaS 製品であり、Acquia Cloud Platform ではありません。acli CLI は Cloud Platform を管理するものであり、Source サイトには使用しません。ここでは使用しないでください。Source は、Web 管理画面と以下の API を通じて操作します。

サイトの識別情報と認証情報

• CMS URL は https://<uuid>.cms.acquia.site の形式です（サイト作成時に自動生成され、後からカスタムドメインを割り当てられます）。このベース URL は JSON:API ホストおよび OAuth ホストです。
• API クライアント（OAuth2 の client_id／secret）は、管理画面の API → API clients → Add API client から作成します。
• @drupal-canvas CLI は、ローカルの .env（コミットしないこと）からすべての値を読み込みます。

  CANVAS_SITE_URL=https://<uuid>.cms.acquia.site
  CANVAS_CLIENT_ID=<client_id>
  CANVAS_CLIENT_SECRET=<client_secret>
  CANVAS_JSONAPI_PREFIX=api        # Source serves JSON:API under /api, not the Drupal default /jsonapi
  # CANVAS_ACCESS_TOKEN=<token>    # optional: a pre-issued Bearer token instead of client credentials
  

認証（simple_oauth 経由の OAuth2）

• トークンエンドポイント： POST https://<site>/oauth/token、Content-Type: application/x-www-form-urlencoded。
• グラント： Authorization Code（ユーザーが操作）、Client Credentials（サーバー／エージェント — 自動化にはこちらを使用）、Refresh Token。
• API 呼び出し時のリクエストヘッダー： Authorization: Bearer <access_token>。
• スコープ： content:read／content:write などのコンテンツスコープ（例 — 全リストは公開されていません）。Canvas CLI には canvas:asset_library と canvas:js_component が必要です。API クライアントの作成時に Client Credentials を有効にし、これらのスコープを追加してください。

手動でのクライアント認証情報トークン取得：

curl -s -X POST "$CANVAS_SITE_URL/oauth/token" \
  -d grant_type=client_credentials \
  -d client_id="$CANVAS_CLIENT_ID" \
  -d client_secret="$CANVAS_CLIENT_SECRET" \
  -d scope="canvas:asset_library canvas:js_component" | jq -r .access_token

JSON:API

• Source のベースパスは /api です（Drupal のデフォルトである /jsonapi は上書きされています — CANVAS_JSONAPI_PREFIX=api を設定してください）。そのため、コレクションの URL は https://<site>/api/<entity_type>/<bundle> です（例：/api/node/article）。
• リソースタイプは標準の Drupal 形式 {entity_type}--{bundle} です（node--article、media--image、taxonomy_term--tags、…）。Source 独自のプレフィックスは確認されていません。
• 管理画面には JSON:API Query Builder（API → JSON:API Query Builder）があり、クエリとコードをその場で生成できます。また、サイトごとの OpenAPI documentation（API → OpenAPI documentation）もあります。サイトごとの正確なバンドル／フィールドを確認するには、これらを使用してください。

curl -s -H "Authorization: Bearer $TOKEN" \
  "$CANVAS_SITE_URL/api/node/article?page[limit]=5" | jq '.data[].attributes.title'

MCP サーバー（AI エージェントを接続）

Acquia Source には、HTTP トランスポートと動的クライアント登録による OAuth2 を使用する MCP サーバーが付属しています。これは実験的機能でサイトごとに有効化する必要があります。

1. 有効化： 管理画面 → Configurations → Experimental features → MCP Server の切り替えをオンにします。
2. URL の取得： Source 管理画面の MCP Client Configuration から、サイトの MCP URL をコピーします（エンドポイント URL はサイトごとにプロビジョニングされます。固定の公開パスをハードコードすることはできません）。
3. Claude Code に登録：

   claude mcp add acquia-source-mcp <ACQUIA_SOURCE_SITE_MCP_URL>
   

   次に /mcp を実行し、acquia-source-mcp を選択して Authenticate をクリックし、OAuth フローを完了します（動的クライアント登録のため、client_id を手動で指定する必要はありません）。

公開される機能（drupal:// および canvas:// URI を介した読み取り専用リソースと書き込みツール）：

• Content Management — コンテンツタイプ、メディアタイプ、ボキャブラリー、テキストフォーマット、およびノード、メディア、タクソノミー用語の作成／更新。
• Content Modeling — フィールドストレージ、フィールドタイプ、およびコンテンツタイプの作成とフィールドの追加。
• Drupal Canvas — コンポーネントとページ、およびレイアウトとコンポーネントプロパティの管理。

エージェントが会話形式でコンテンツをモデリングしたり Canvas レイアウトを編集したりする場合は、独自に実装した JSON:API 呼び出しより MCP サーバーを優先してください。決定的なスクリプトによるデプロイには、JSON:API／Page API を使用してください。

Canvas Code Components — CLI ワークフロー

公式ツールを使って React/JSX Code Components をスキャフォールドし、管理します（コンポーネント作成のルールについては公式 Canvas スキルをインストールしてください。ルールを独自に作り直す必要はありません）。

• npx @drupal-canvas/create@latest — コードベースをスキャフォールドします（デフォルトのテンプレートはacquia/nebulaです。Page API のリファレンスと注意点を含む AGENTS.md と SETUP.md が用意されています）。
• npx canvas download / npx canvas upload -c <comp1,comp2> -y — リポジトリとサイトの間でコンポーネントを取得／送信します。コミット対象の canvas.config.json で構成を定義し、コミット対象外の .env に上記のシークレットを保存します。

Canvas Page API — ページのデプロイ

ページはコンポーネントをアップロードしたあと、ページ全体のコンポーネントツリーを使って PATCH することで構築します。実際に苦労してわかったルールは次のとおりです（守らないと何時間も費やすことになります）。

• 各 PATCH はページ全体を置き換えます。 複数の PATCH で段階的に構築してはいけません。完全なコンポーネントツリーを組み立て、1 回のアトミックなリクエストで送信してください。
• アップロードのたびにバージョンハッシュが変わります。 canvas upload のあとには、すべてのコンポーネントのバージョンハッシュを再確認してください。ハッシュをハードコードしてはいけません。新しいハッシュが付与されるのは変更されたコンポーネントだけです。
• FormattedText はライブサイトでインラインの style 属性を削除します（Storybook では機能しますが、ライブサイトでは機能しません）。テキストの配置には、CVA バリアントを使って layout プロパティ（left_aligned/center_aligned/right_aligned）を追加してください。インラインの style="text-align:…" は使わないでください。
• Image コンポーネントには Drupal のメディアパイプラインの URL が必要です（alternateWidths を含むもの）。外部 URL や data URI はエラーにならずに受け付けられますが、ライブサイトでは表示されない 0×0 の画像としてレンダリングされます。ロゴにはインライン SVG／テキストを使い、コンテンツ画像はまず Drupal メディアとしてアップロードしてください。
• プロパティに生の 16 進数カラーを指定してはいけません。global.css の Tailwind テーマトークンにマッピングした CVA バリアントを使ってください。
• パディングの重なり： section は px-4 を、grid_container は px-6 を追加するため、375px の画面では合計で約 80px になります。内側のコンテナにはレスポンシブプレフィックス（px-0 md:px-6）を使ってください。
• 空のスロットコンテナには min-w-*/min-h-* が必要です。これにより Canvas エディターで操作可能な状態を保てます。
• デプロイスクリプトのパターン：.env を読み込む → クライアント認証情報でトークンを取得する → すべてのバージョンハッシュを一度に確認する → ツリーを構築する（親を子より先に配置し、インスタンスごとに新しい UUID を使い、inputs は json.dumps() の文字列にする）→ 1 回の PATCH を送信する。先頭に VERSIONS 辞書を用意してください。

ドキュメント

• 概要：https://docs.acquia.com/acquia-source/overview
• API 統合（JSON:API）：https://docs.acquia.com/acquia-source/api-integration
• アクセスと認証（OAuth2）：https://docs.acquia.com/acquia-source/access-and-authentication
• MCP サーバー：https://docs.acquia.com/acquia-source/acquia-source-mcp-server
• カスタムコンポーネントの作成（CLI）：https://docs.acquia.com/acquia-source/creating-custom-components
• JSON:API Query Builder：https://docs.acquia.com/acquia-source/jsonapi-query-builder
• 公式 Canvas コンポーネントスキル：https://github.com/drupal-canvas/skills · スターターテンプレート：https://github.com/acquia/nebula