AEM Content Manager (ACM)

ACM MCP Server

Model Context Protocol サーバーです。Adobe Experience Manager 上で実行される AEM Content Manager (ACM) に、AI エージェント（Claude Code、Claude Desktop、VS Code、Cursor、その他の MCP クライアント）を接続します。AEM as a Cloud Service にも対応しています。

エージェントは、ACM 経由で AEM 上の Groovy スクリプトを検証・実行し、長時間実行される処理を追跡し、実行履歴やコンソール出力を読み取り、インスタンスに保存されたスクリプトを参照できます。設定済みの任意のインスタンスで利用できるため、author と publish、または別の環境との比較も可能です。すべての呼び出しは、設定した認証情報を持つユーザーとして実行されます。

graph LR
    client["MCP client<br>(Claude, ...)"] <-- "stdio (MCP)" --> server["acm-mcp-server<br>(your machine)"]
    server <-- "HTTPS" --> aem["AEM instances + ACM<br>/apps/acm/api/*.json"]

警告

このサーバーを使うと、AI エージェントがユーザーの権限で AEM 上の任意の Groovy コードを実行できます。共有インスタンスや本番インスタンスを接続する前に、セキュリティをお読みください。

ヒント

VS Code をお使いですか？ACM extension にはこのサーバーがバンドルされており、有効なすべてのインスタンスに登録されます。認証情報には VS Code のシークレットストレージが使用されます。以下のセットアップは不要です。また、ACM: Export MCP Config を実行すると、他のエージェント向けの設定ファイルが作成されます。

要件

• Node.js 22 以降。
• 各 AEM インスタンスに ACM がインストールされていること。履歴なし（history: false）でコードを実行するには、ACM 0.9.74 以降が必要です。
• 各インスタンスで ACM API にアクセスできるユーザー（権限を参照）。

セットアップ

サーバーは、VS Code 拡張機能の設定と同じキー（acm. プレフィックスを含む）を使用する JSON ドキュメントで設定します。settings.json からコピーしたブロックをそのまま設定として使用できます。

{
  "acm.instances": [
    { "name": "local-author", "url": "http://localhost:4502", "authMode": "basic", "user": "admin" },
    { "name": "local-publish", "url": "http://localhost:4503", "authMode": "basic", "user": "admin" },
    { "name": "dev", "url": "https://author-pXXXX-eYYYY.adobeaemcloud.com", "authMode": "bearer",
      "secret": { "env": "ACM_DEV_TOKEN" }, "readonly": true },
    { "name": "prod", "url": "https://author.example.com", "authMode": "cookie",
      "secret": { "file": "~/.config/acm/prod.cookie" }, "enabled": false }
  ],
  "acm.activeInstance": "local-author",
  "acm.http.timeout": 30000,
  "acm.run.timeout": 120000,
  "acm.run.pollInterval": 1000
}

タイムアウトのキーは省略可能で、デフォルト値は次のとおりです。不明なキーは無視されるため、設定ブロック全体を貼り付けることができます。

1. 設定ファイルを作成する

インスタンスのフィールド：

フィールド	説明
name	一意の名前です。ツールでは省略可能な instance 引数として指定します。
url	AEM の URL（author または publish）。例：http://localhost:4502。
authMode	bearer、cookie、または basic。
user	Basic 認証のユーザー（basic の場合は必須）。
secret	認証情報。シークレットを参照してください。ローカルの admin／admin SDK の場合は省略します。
readonly	true にすると、このインスタンスでコードを実行または中止するツールが無効になります。本番環境では推奨されます。セキュリティを参照してください。
enabled	false にすると、すべてのツールでこのインスタンスが非表示になります。例：本番環境を一時的に対象外にする場合（デフォルトは true）。

認証情報の選択：

authMode	使用する場面	シークレットの取得方法
bearer	AEM as a Cloud Service（推奨）	Cloud Manager → 環境の Developer Console → Integrations → Local token →「Get Local Development Token」。有効期限は 24 時間で、ユーザー本人として動作します。
cookie	AEM as a Cloud Service でのクイックスタート、またはログイン可能な任意のインスタンス	AEM にログインした後の login-token Cookie の値（DevTools → Application → Cookies）。CSRF トークンは自動的に処理されます。
basic	ローカル AEM SDK、オンプレミス	通常は admin／admin。

login-token Cookie は約 12 時間で有効期限が切れます。サーバーを再起動せずに更新するには、secret: { "file": "path" } を使用してください。

シークレット

secret はベアラートークン、login-token Cookie（値または name=value）、または Basic 認証のパスワードです。次の形式で指定します。

• リテラル値。開発時に便利です。設定ファイルは自分だけが読み取れるようにしてください（chmod 600）。そうなっていない場合、サーバーが警告します。
• { "env": "NAME" } — サーバープロセスの環境変数から読み取ります。設定ファイルには何も書き込まれません。
• { "file": "path" } — ~ は展開され、相対パスは設定ファイルを基準に解決されます。リクエストのたびに再読み込みされるため、ディスク上のトークンを更新するのに再起動は不要です。ファイルが見つからないか空の場合、そのインスタンスでのみ失敗します。

ローカル URL でユーザー admin を使った Basic 認証では、パスワードはデフォルトで admin です。そのため、ローカル SDK ではシークレットは不要です。

2. エージェントにサーバーを登録する

すべての MCP クライアントで必要な情報は同じです。設定場所と形式はクライアントによって異なるため、このガイドではクライアント固有のファイルについては説明しません。

設定	値
トランスポート	stdio
コマンド	npx
引数	-y、@wppes/acm-mcp-server
環境変数	手順 1 のパスを指定した ACM_CONFIG_FILE

ACM_CONFIG_FILE の代わりに、ドキュメントを ACM_CONFIG としてインラインで渡すこともできます。この場合、ファイルよりも優先されます。

最も簡単な方法は、自身の設定を把握しているエージェントに依頼することです。

このツールの MCP 設定に ACM MCP サーバーを追加してください。トランスポートは stdio、コマンドは npx、引数は -y @wppes/acm-mcp-server、環境変数は、以下に列挙する ACM インスタンスを含む JSON ファイルを指す ACM_CONFIG_FILE にします。シークレットはそのファイルに含めず、環境変数またはファイルを参照するようにしてください。コミットされる可能性のあるファイルにシークレットを書き込まないでください。値をどこに設定すればよいか教えてください。このツールのドキュメントを調べて、MCP サーバーの設定場所と形式を確認してください。その後、acm_list_instances と acm_health を呼び出して検証してください。

3. 接続を確認する

エージェントに acm_list_instances、続いて acm_health を呼び出すよう依頼してください。最初のツールでは、有効な各インスタンスと認証モード、認証情報が設定されているかどうかを確認できます。2 つ目のツールでは、それぞれのインスタンスについて ACM が報告する状態を確認できます。

インスタンス

ツールは、次のルールで選択された 1 つのインスタンスだけに作用します。

1. 指定されている場合は、任意の instance 引数。有効なインスタンス名である必要があります。
2. それ以外の場合は、有効なインスタンス名が指定されていれば acm.activeInstance。
3. それ以外の場合は、設定されている有効なインスタンスが 1 つだけなら、そのインスタンス。
4. それ以外の場合は、有効なインスタンス名の一覧を示して呼び出しが失敗します。そのため、誤って別のインスタンスで実行されることはありません。

acm.activeInstance が不明または無効なインスタンス名（入力ミスなど）を指している場合、サーバーは起動時に stderr に警告を出し、acm_list_instances もその警告を再度表示するため、エージェントから確認できます。その場合は、未設定として上記のルールが適用されます。

acm_list_instances では、どのインスタンスがアクティブか、またどのインスタンスに認証情報があるかを確認できます。書き込みツール（acm_run_code、acm_abort_execution、acm_describe_inputs）は常に 1 つのインスタンスだけに作用します。すべてのインスタンスで実行する呼び出しは意図的に用意されていません。インスタンスを比較する場合（例：author と publish の差異を確認する場合）は、それぞれで同じ読み取り専用コードを実行し、結果を diff してください。手順については、同梱のスクリプティングガイドを参照してください。両方で ACM に接続できる必要があります。これはローカル、オンプレミス、AMS（直接の publish URL）では可能ですが、AEMaaCS の publish には接続できません。

ツール

ツール	説明
acm_list_instances	有効なインスタンスを一覧表示します。名前、URL、認証モード、読み取り専用フラグ、アクティブなインスタンス、および認証情報が設定されているかどうかを表示します。
acm_health	接続、認証、および ACM が報告するインスタンスの状態（/apps/acm/api/state.json）を確認し、ACM のヘルスチェックでインスタンスが正常でないと判定された場合は警告します。instance を指定しない場合は、すべての有効なインスタンスを確認します。最初に呼び出してください。
acm_validate_code	Groovy を実行せずにコンパイルチェックします（mode=parse）。行番号と列番号を含むコンパイルエラーを返します。実行履歴には記録されません。
acm_run_code	Groovy を実行キューに追加し、完了するかタイムアウトするまでポーリングして、ステータスとコンソール出力全体を返します。describeRun() を使用するスクリプトでは inputs をサポートします。history: false を指定すると、同期的に実行され、履歴には記録されません（下記を参照）。
acm_get_execution	キュー内、実行中、アーカイブ済みのいずれであっても、ID を指定して実行のステータス、入力、エラー、コンソール出力を取得します。
acm_abort_execution	キュー内または実行中の実行を中止します。context.checkAborted() を呼び出すスクリプトは、正常に停止します。
acm_list_executions	実行履歴を新しい順に一覧表示します。必要に応じて、キュー内および実行中の実行だけに絞り込めます。
acm_list_scripts	/conf/acm/settings/script の下に保存されている Groovy スクリプトを種類（MANUAL、AUTOMATIC、…）ごとに一覧表示します。
acm_get_script	ID またはパスを指定して、保存済みスクリプトの Groovy コードを読み取ります。
acm_describe_inputs	スクリプトが describeRun() で宣言する入力（名前、型、デフォルト値）を解決します。この処理では ACM が describeRun() を実行するため、コード実行として扱われます。
acm_get_output_file	名前を指定して実行出力をダウンロードします。対象は console、または outputs.file(...) / outputs.text(...) で作成された出力です。

すべてのツールで省略可能な instance 引数を指定できます。デフォルトについてはインスタンスを参照してください。

単独の Groovy スニペットは自動的に canRun()/doRun() 構造でラップされるため、println "hello" は acm_validate_code および acm_run_code で有効な入力です。

履歴に記録しない実行

キューに追加された実行はすべて ACM の実行履歴に保存されるため、スクリプトを素早く反復していると履歴がすぐに埋まります。history: false を指定すると、acm_run_code は /apps/acm/api/execute-code.json を直接呼び出し、実行は記録されません。このような実行には次の特徴があります。

• ポーリングや中止に使える実行 ID がなく、出力ファイルも保持されません。
• waitMs 経過後にクライアント側で打ち切られますが、AEM 上ではスクリプトの実行が続く場合があります。

スクリプトの開発中に、短時間の読み取り専用実行やドライランを行う場合に使用してください。最終版や、コンテンツを変更する処理は、変更を監査できるようデフォルトの history: true で実行してください。

履歴に記録しない実行には ACM の console/execute/nohistory 機能が必要です（デフォルトでは管理者のみ利用可能）。この機能がない場合、呼び出しは 403 で失敗します。このような実行も ACM の監査ログには表示されます。

スクリプトガイド

このサーバーには ACM Groovy スクリプトスキルが付属しているため、エージェントは追加設定なしで、有効かつ安全なスクリプトを作成できます。

• 指示。 スキルの基本事項（API を決して捏造しない、ドライランを行う、中止チェックを行う、実行前に検証する）は、クライアントの接続時に送信されます。クライアントはこれらをモデルのコンテキストに追加します。
• プロンプト。 acm-groovy-script はガイド全文を返します。
• リソース。 ガイドとそのリファレンスは、acm://skill/SKILL.md、acm://skill/references/api.md（ACM のソースから生成された、すべての ACM 変数、クラス、メソッドの一覧）、acm://skill/references/scripts.md、および acm://skill/templates/ の下にあるスクリプトテンプレートから利用できます。

例

次のようにエージェントに依頼します。

ACM を使って、/content/wknd/us/en の下にある wknd/components/teaser コンポーネントの数を数えてください。

エージェントは acm_health を呼び出した後、次のようなスクリプトを検証して実行します。

boolean canRun() {
    return conditions.always()
}

void doRun() {
    def sql = "SELECT * FROM [nt:base] AS n WHERE ISDESCENDANTNODE(n, '/content/wknd/us/en') AND n.[sling:resourceType] = 'wknd/components/teaser'"
    def count = 0
    repo.queryRaw(sql).forEach { resource ->
        context.checkAborted()
        count++
    }
    out.info("Found ${count} instance(s)")
}

Permissions

ACM は 3 つのレベルでアクセスを確認します。認証情報を使用するユーザーには、それぞれで jcr:read が必要です。

1. /apps/acm/api 配下の API ノード
2. /apps/acm/feature 配下の機能ノード
3. /conf/acm/settings/script 配下のスクリプトパス

デフォルトでは、管理者のみがアクセスできます。ツールのアクセス設定を参照してください。ツールからの 403 には、このヒントが含まれます。401 は、トークンまたは Cookie の有効期限が切れていることを意味します。

Security

• エージェントはユーザーとして動作します。 すべてのスクリプトは、設定されたユーザーの権限で実行されます。モデルが誤りを犯す可能性があり、モデルが読み取るコンテンツ（ページ、スクリプト、実行出力）がモデルの動作を誘導しようとすることもあります。タスクを実行できる範囲で、最小限の権限を持つユーザーを使用してください。
• 本番インスタンスには readonly を設定してください。 ヘルスチェック、検証、履歴、スクリプトの読み取りツールは引き続き動作しますが、そのインスタンスでのコードの実行、説明、強制終了はブロックされます。これはエージェントによるこれらのツールの呼び出しを防ぐだけです。セキュリティ境界ではありません。検証では引き続き、送信された Groovy が AEM 上でコンパイルされ、Groovy のコンパイル時変換によってコードが実行される可能性があります。実際の制御となるのは、設定されたユーザーの AEM 権限です。enabled: false を設定すると、インスタンス全体が非表示になります。
• 実行は追跡可能です。 キューに追加された実行は ACM の履歴に保存されます。履歴に残らない実行（履歴機能がない場合、または canRun() によってキューに追加されなかった場合）は、ユーザーとコードのチェックサムとともに ACM の監査ログに記録されます。console/execute/nohistory は、必要なユーザーにのみ付与してください。
• エージェントには必要な権限だけを付与してください。 script/execute 機能があり、console/execute がないユーザーは、保存済みスクリプトをそのまま実行することしかできません。
• 共有インスタンスで実行する前に、スクリプトを確認してください。 それらのインスタンスでは、MCP クライアントで acm_run_code を自動承認しないでください。
• 破壊的な変更には、ドライランを優先してください。 ACM の repo.dryRun(...) パターンを使用してください。同梱のスクリプトガイドでは、モデルがこのパターンを使うよう誘導しています。
• 認証情報はローカルに保持されます。 サーバーはお使いのマシン上で動作し、設定されたインスタンス URL とのみ通信します。{ "env" } および { "file" } のシークレット参照を優先するか、リテラルのシークレットを chmod 600 の設定ファイルに保存してください。コミットするファイルには絶対に保存しないでください。

Contributing

サーバーのビルド、テスト、リリースについては、開発ガイドを参照してください。

License

AEM Content Manager の一部であり、Apache License, Version 2.0に基づいてライセンスされています。「現状有姿」で提供され、いかなる種類の保証もありません。ご自身の責任でご使用ください（ライセンスの第 7 条および第 8 条を参照）。