umbraco-chrome-navigation

Umbraco バックオフィスナビゲーション (Claude-in-Chrome)

このスキルが存在する理由

Umbraco のバックオフィスは Lit の Web コンポーネントで構築されています。そのため、ブラウザ自動化にとって次の 3 つの問題が生じ、何も知らずに立ち向かうと多くのツール呼び出しを無駄にしてしまいます。

1. すべてが (オープンな) シャドウ DOM の中にあります。 組み込みの find および read_page ツールはシャドウルートを貫通しないため、バックオフィスのページではほとんど何も返しません。
2. モーダルは独自のスタッキングコンテキストにポータル化され、キャプチャされた約 1536px のビューポートから外れてレンダリングされることが頻繁にあり、あるいは積み重なって最新のものが画面外になることもあります。
3. スクリーンショットは遅延します — モーダルの遷移中はライブ DOM より遅れるため、もはや現在の状態を反映していないフレームをスクリーンショットして完全に誤読する可能性があります。

解決策は、ピクセルでナビゲートするのをやめることです。シャドウ DOM を貫通する小さなヘルパーを注入し、状態を DOM から読み取り (DOM は決して遅延しません)、座標ではなくラベル/テキストで操作します。スクリーンショットは、画像そのものが実際の成果物である場合 (何かがどのように見えるかの検証、またはユーザーへの証拠) にのみ撮影し、画面上に何があるかを把握する主要な手段としては使わないでください。

セットアップ (ブラウザセッションごとに 1 回)

ツールキットはこのスキルの scripts/umbraco-chrome-helpers.js にあります。そのファイルを読み、その内容全体を mcp__claude-in-chrome__javascript_tool に (バックオフィスのタブで) 貼り付けてください。これにより window.__umb が定義され、自身のソースが localStorage.__umbSrc に保存されます。

ページの読み込み (ナビゲート/リロード/ログインリダイレクト) は window.__umb を消去しますが localStorage は消去しないため、ナビゲーションのたびに次のワンライナーで再注入してください:

eval(localStorage.__umbSrc)

まず通常の方法でブラウザセッションを開始します: tabs_context_mcp → tabs_create_mcp (またはバックオフィスのタブを再利用)、次に <your-host>/umbraco のバックオフィスへ navigate します (このリポジトリのホストは localhost:44325 です)。

API

すべてのファインダーは要素の中心 {x, y} を返すため、computer ツールにフォールバックできます。

呼び出し	用途
__umb.snapshot()	表示されている操作可能な要素を tag[role] "label" @x,y として一覧表示 — 「何をクリックできるか」
__umb.find(text, {role, tag})	ラベル/テキスト (文字列または RegExp) で要素を座標付きで特定
__umb.click(text, {role, tag, nth})	ワークスペース内/モーダル内のほとんどのボタンやオプションをクリック
__umb.fill(labelSubstr, value)	<uui-input>/<input>/<textarea> を設定 (input+change を発火)
__umb.modals()	開いているモーダル/サイドバー/ダイアログとそれらのアクションボタンを一覧表示
__umb.waitFor(text, {role})	要素が現れるまでポーリング (セクションツリーは非同期で読み込まれます)
__umb.waitGone(text)	要素が消えるまでポーリング (例: モーダルが閉じた)
__umb.section(name)	セクションタブ (Content/Settings/…) を特定 — computer ツールでクリックするための座標を返します
__umb.treeActions(itemName)	ツリー項目の「View actions for 'X'」メニューを開く

あなたを救う 1 つのルール: 合成クリック vs. 信頼されたクリック

__umb.click() は要素の実際の .click() を使用します。これはワークスペースまたはモーダル内のボタンやオプション (Save、Submit、Discard、結果行、作成オプションなど) に対しては機能します。

次の 2 つには機能しません。これらは信頼されたユーザー操作を必要とするためです:

• セクションタブ (Content、Settings…) — SPA ルーターは合成クリックを無視します。
• サイドバーツリーのグループヘッダー (展開/折りたたみを行う h3 の "Structure"/"Templating")。

これらについては、__umb.find(...) (または __umb.section(...)) から座標を取得し、mcp__claude-in-chrome__computer でそれらをクリックします ({x,y} で left_click) — これは本物の信頼されたクリックです。

つまり、役割分担は次のとおりです: 状態を確認してページ内アクションを実行するのは DOM ヘルパー、ルートナビゲーションとツリーグループの切り替えは (ヘルパーが提供する座標での) computer ツール。

ヘルパーが明らかにする注意点

• 隠れた「変更を破棄」モーダル。 未保存の状態でワークスペースを離れると umb-discard-changes-modal がポップアップし、気付かないうちにナビゲーションをブロックします。ナビゲーションが何も起こらないように見える場合は、__umb.modals() を実行してください — モーダルが表示されます — その後 __umb.click('Discard changes') (または 'Save') で続行できます。
• 空白の作成ワークスペース。 …/create/… ワークスペース URL へのディープリンクは、しばしば 空白で描画されます。代わりにツリー/コレクションの 「Create」 アクションから作成に入ってください。
• 非同期のツリーロード。 セクションへ移動した後、サイドバーツリーは少し遅れて ロードされます。操作の前に __umb.waitFor('<a known item>') を実行してください。
• セッションの無効化。 DB を再作成すると (新規の無人インストール)、古いトークンが無効になり、 タブは /umbraco/login にリダイレクトされます。ヘルパーを再注入し、ユーザー名/パスワードの 入力欄を設定して送信ボタンをクリックすることでログインしてください。
• プライバシーガード。 javascript_tool から href/URL/base64 をまとめて返さないでください — ガードが結果全体をブロックします。ラベル + 座標のみを返してください (ヘルパーはすでにそうしています)。

信頼性の境界 — セットアップには API を優先する

UI を多段階の セットアップ (データ型の作成 → ドキュメントタイプ → コンテンツ) で 操作するのは本質的に脆いです。非同期ツリー、空白の作成ワークスペース、破棄ガードなどがあります。エンティティが単に 存在 すればよい場合は、Management API が適切なサーフェス です。Umbraco の e2e/Playwright テストヘルパー (@umbraco-cms/acceptance-test-helpers) を介して、適切に認証し、いくつかの umbracoApi.* 呼び出しでシードします。このスキルは、ライブのバックオフィス UI で実行する必要がある部分 (カスタムエディターが描画され動作するかの検証、フローのクリック操作、スクリーンショットの撮影) に使用してください。注意: バックオフィスの OAuth トークンはメモリ内に保持され、localStorage/sessionStorage には保存されないため、Claude-in-Chrome からの直接 API 呼び出しのためにページから借用することはできません。

典型的なループ

1. バックオフィスタブへ navigate し、ツールキットを注入します (または eval(localStorage.__umbSrc))。
2. __umb.snapshot() / __umb.find(...) で何があるかを確認します — スクリーンショットではありません。
3. コンピューターツールでヘルパー座標を使ってセクションを移動/ツリーグループを展開し、 ページ内アクションは __umb.click / __umb.fill で行います。
4. 各ステップの後、__umb.find / __umb.modals / location.pathname で検証します。
5. 成果物が視覚的なもの (見た目) である場合、またはユーザーへの証拠となる場合は、最後に 1 枚 スクリーンショットを撮ります。