@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ja-JP/local-file-mode.md

@@ -0,0 +1,433 @@
+---
+title: "ローカル ファイル モード"
+description: "ローカルの Markdown、MDX、およびその他のリポジトリ ファイルを信頼できるソースとして使用して、エージェント ネイティブ アプリを実行します。これには、カスタム コンポーネントを含む Obsidian スタイルの MDX ドキュメントが含まれます。"
+---
+
+# ローカル ファイル モード
+
+ローカル ファイル モードにより、エージェント ネイティブ アプリは通常の UI とアクション サーフェスをアタッチできます
+リポジトリまたはワークスペース内のファイルに直接。アプリは依然としてホストされているように感じます
+製品ですが、そのリスト ビュー、エディタ、エージェント ツールはローカル ファイルの読み取りと書き込みを行います
+SQL がサポートするアプリ レコードの代わり。
+
+最初の実装はコンテンツ テンプレート内にあります。左側のサイドバーは
+ローカルの `.md` および `.mdx` ファイルから設定され、ページを選択すると標準ファイルが開きます
+コンテンツ エディター、および保存すると、選択したファイルに書き戻されます。同じファイルは
+Codex、Claude コード、Agent-Native サイドバー エージェント、または通常のエージェントでも編集できます
+編集者。
+
+コンテンツに関しては、これにより製品が MDX のオープンソース Obsidian のように感じられます:
+ドキュメントはファイルとして保存されますが、アプリにはビジュアル エディター、エージェント actions が追加されます。
+共有可能なコピー、および豊富なインタラクティブな MDX コンポーネント。
+
+リポジトリ優先のワークフローが必要な場合は、ローカル ファイル モードを使用します。
+
+- `docs/*.mdx` のドキュメント リポジトリ
+- `blog/*.mdx` のブログ
+- `resources/*.md` のポジショニング、メッセージング、チームメモなどのリソース
+- より豊富な MDX エディターを備えた個人用の Obsidian スタイルのナレッジ ベース
+- ローカルの React コードから生成されたインタラクティブなカスタム MDX ブロックを必要とするドキュメント
+- コーディング エージェントが簡単に検査してパッチを適用できるアプリ アーティファクト
+
+ホストされたコラボレーション アプリのエクスペリエンスが必要な場合は、データベース モードを使用します。
+マルチユーザー共有、SQL による権限、コメント、バージョン履歴、および
+ローカル ファイル システムにアクセスしない運用ホスティング。
+
+## メンタルモデル
+
+2 つの信頼できる情報源モードがあります:
+
+| モード                   | 真実の源                                                  | こんな人に最適                                                                                        |
+| ------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| データベースモード       | SQL 行から Drizzle                                        | ホストされているアプリ、コラボレーション、共有、コメント、バージョン履歴                              |
+| ローカル ファイル モード | `agent-native.json` によって宣言されたリポジトリ ファイル | ローカル/開発ワークフロー、Git レビュー、コーディング エージェント編集、ファイルネイティブ コンテンツ |
+
+UI とエージェント actions は、両方のモードで同じ形状のままである必要があります。コンテンツ
+エディターは引き続きドキュメントを編集します。違いは、それらの文書が解決されるかどうかです
+SQL 行またはローカル ファイルへ。
+
+```an-diagram title="Same actions, two sources of truth" summary="The UI and agent call identical actions in both modes. The action layer decides whether each call resolves to SQL rows or repo files."
+{
+  "html": "<div class=\"diagram-mode\"><div class=\"diagram-col entry\"><div class=\"diagram-node\">Content UI</div><div class=\"diagram-node\">Agent + actions<br><small class=\"diagram-muted\">list/get/update-document</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-row resolve\"><div class=\"diagram-panel\" data-rough><span class=\"diagram-pill accent\">Database mode</span><small class=\"diagram-muted\">SQL rows via Drizzle</small><small class=\"diagram-muted\">hosted · sharing · comments · history</small></div><div class=\"diagram-panel\" data-rough><span class=\"diagram-pill ok\">Local File Mode</span><small class=\"diagram-muted\">repo files via agent-native.json</small><small class=\"diagram-muted\">Git review · coding-agent edits</small></div></div></div>",
+  "css": ".diagram-mode{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-mode .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-mode .diagram-arrow{font-size:22px;line-height:1}.diagram-mode .resolve{display:flex;gap:12px;flex-wrap:wrap}.diagram-mode .diagram-panel{display:flex;flex-direction:column;gap:4px;padding:12px 14px}"
+}
+```
+
+## リポジトリの例
+
+コンテンツ ワークスペースは次のように小さくすることができます:
+
+```an-file-tree title="A Content workspace repo"
+{
+  "entries": [
+    { "path": "agent-native.json", "note": "declares which folders are content roots and their kinds" },
+    { "path": "docs/", "note": "content root — shows in the sidebar as pages" },
+    { "path": "docs/getting-started.mdx" },
+    { "path": "docs/guides/custom-components.mdx" },
+    { "path": "blog/", "note": "content root" },
+    { "path": "blog/launch-post.mdx" },
+    { "path": "resources/", "note": "content root" },
+    { "path": "resources/messaging/positioning.md" },
+    { "path": "components/", "note": "NOT a content root — preview component library MDX can import" },
+    { "path": "components/FrameworkTabs.tsx" },
+    { "path": "components/Callout.tsx" },
+    { "path": "extensions/", "note": "NOT a content root — local extension library (sandboxed widgets)" },
+    { "path": "extensions/doc-status/extension.json" },
+    { "path": "extensions/doc-status/index.html" }
+  ]
+}
+```
+
+ローカル ファイル モードでは、コンテンツ サイドバーに `docs/`、`blog/`、および
+`resources/` ツリーをページとして表示します。 `docs/getting-started.mdx` を選択すると、
+ファイル。 UI で編集すると
+`docs/getting-started.mdx`.
+
+`components/` はコンテンツ ルートではありません。 MDX
+ファイルはインポートまたは参照できます。エディターは単純なローカル MDX コンポーネントをレンダリングできます
+コンテンツ アプリ全体を複製したりフォークしたりする必要はありません。
+
+`extensions/` もコンテンツ ルートではありません。これはローカル拡張ライブラリです:
+ソースをアプリ スロットに保持したままアプリ スロットでレンダリングできる小さなサンドボックス ウィジェット
+リポジトリ。
+
+## コンテンツをリポジトリにインストールする
+
+既存のドキュメント、ブログ、または MDX ワークスペースの場合は、コンテンツ ローカル ファイルをインストールします
+スキル:
+
+```bash
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+```
+
+これにより、`content` スキルがリポジトリのエージェント スキル フォルダにコピーされ、書き込まれます
+または、コンテンツのデフォルトで `agent-native.json` を更新します。
+
+- ワークスペース レベルの `mode: "local-files"`
+- `apps.content.mode: "local-files"`
+- `docs/`、`blog/`、`content/`、および `resources/` のコンテンツ ルート
+- ローカル MDX コンポーネントの `components/`
+- ローカル拡張ウィジェット用の `extensions/`
+
+インストールされたスキルは、コーディング エージェントにコンテンツ actions を使用するよう指示します
+(`list-documents`, `get-document`, `edit-document`, `update-document`,
+`share-local-file-document`、およびコンポーネント ファイル actions) (ローカル コンテンツ アプリの場合)
+または Agent Native デスクトップ ブリッジがそれらを公開します。橋が稼働していない場合、スキル
+フロントマター、インポート、JSX を保持しながら、安全な直接リポジトリ編集にフォールバックします。
+そして不明な MDX。
+
+## 構成
+
+`agent-native.json` をリポジトリまたはワークスペースのルートに追加します。
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "roots": [
+        {
+          "name": "Docs",
+          "path": "docs",
+          "kind": "docs",
+          "extensions": [".md", ".mdx"]
+        },
+        {
+          "name": "Blog",
+          "path": "blog",
+          "kind": "blog",
+          "extensions": [".md", ".mdx"]
+        },
+        {
+          "name": "Resources",
+          "path": "resources",
+          "kind": "resources",
+          "extensions": [".md", ".mdx"]
+        }
+      ],
+      "components": "components",
+      "extensions": "extensions",
+      "hide": ["**/_*.md", "**/_*.mdx"]
+    }
+  }
+}
+```
+
+`AGENT_NATIVE_MODE=local-files` または
+`AGENT_NATIVE_DATA_MODE=local-files`;マニフェストが優先されるのは、
+リポジトリ自体のフォルダー コントラクトを文書化します。
+
+## コンテンツ ファイル形式
+
+コンテンツは Markdown および MDX を読み取ります。 Frontmatter はページのメタデータを保持し、本文は
+編集可能なドキュメント:
+
+```mdx
+---
+title: "Getting Started"
+icon: "sparkles"
+isFavorite: true
+updatedAt: "2026-06-12T20:00:00.000Z"
+---
+
+# Getting Started
+
+Use <FrameworkTabs value="react" /> to show framework-specific code.
+```
+
+タイトルは、存在する場合は `title` フロントマターから取得され、それ以外の場合は、
+ファイル名。エディターは、まだ視覚的に編集できない MDX ソースを保持します。そのため
+コーディング エージェントと通常のテキスト エディタは安全な避難口のままです。
+
+## カスタム MDX コンポーネント
+
+コンテンツは、構成された `components` フォルダーからローカル コンポーネントをプレビューできます。
+これは、タブ、コールアウト、パッケージなどのドキュメント スタイルの MDX コンポーネントを対象としています
+スニペット、またはフレームワーク固有のコード ブロックをインストールします。
+
+たとえば、コンテンツの隣にインタラクティブ コンポーネントを追加します。
+
+```tsx
+// components/ImpactCounter.tsx
+import { useState } from "react";
+
+export function ImpactCounter({
+  label = "points",
+  accent = "blue",
+  featured = false,
+}: {
+  label?: string;
+  accent?: "blue" | "green" | "purple";
+  featured?: boolean;
+}) {
+  const [count, setCount] = useState(3);
+  const accentClass =
+    accent === "green"
+      ? "border-green-300 bg-green-50"
+      : accent === "purple"
+        ? "border-purple-300 bg-purple-50"
+        : "border-blue-300 bg-blue-50";
+
+  return (
+    <div className={`rounded-md border p-4 ${accentClass}`}>
+      <div className="text-sm text-muted-foreground">Launch impact</div>
+      <div className="mt-1 text-3xl font-semibold">
+        {count} {label}
+      </div>
+      {featured ? <div className="mt-1 text-sm">Featured metric</div> : null}
+      <button
+        type="button"
+        className="mt-3 rounded border px-3 py-1 text-sm"
+        onClick={() => setCount((value) => value + 1)}
+      >
+        Add point
+      </button>
+    </div>
+  );
+}
+
+export const ImpactCounterInputs = {
+  label: {
+    type: "string",
+    label: "Metric label",
+    default: "points",
+  },
+  accent: {
+    type: "select",
+    label: "Accent",
+    options: ["blue", "green", "purple"],
+    default: "blue",
+  },
+  featured: {
+    type: "boolean",
+    label: "Featured",
+    default: false,
+  },
+};
+```
+
+次に、ローカルの MDX ファイルからそれを使用します。
+
+```mdx
+---
+title: "Launch Notes"
+---
+
+# Launch Notes
+
+<ImpactCounter label="wins" />
+```
+
+Content dev サーバーは、PascalCase という名前のエクスポートと PascalCase のデフォルトを検出します
+は、`.tsx`、`.jsx`、`.ts`、および `.js` ファイルから `components/` の下にエクスポートします。それら
+コンポーネントはエディタ内でレンダリングされ、
+**ローカルコンポーネント**。スラッシュを挿入すると、
+`<ImpactCounter />`;必要に応じて、MDX ソースにプロパティを追加します。
+
+コンポーネントの実行は、意図的にローカル開発/デスクトップ ブリッジ機能ではなく、
+プレーン ホスト ブラウザー フォルダー アクセス。 `content.agent-native.com` を開くと、
+**ローカル ファイル** を選択し、Chrome でフォルダーを選択します。アプリが読み書きできる
+`.md` および `.mdx` ファイルは、ブラウザ ファイル システム アクセス API を介してアクセスされますが、
+Chrome は、Vite をコンパイルするための絶対フォルダー パスを公開しません
+`components/*.tsx`。カスタム React コンポーネントをプレビューしてホット リロードするには、
+コンテンツをローカルに保存するか、信頼できるローカル ブリッジができるように Agent Native デスクトップを使用します
+選択したワークスペースをローカルのコンテンツ開発サーバーに登録します。そのモードでは、
+Vite を介して既存のコンポーネント ファイルを編集し、ホット リロードし、または追加します。
+コンポーネント ファイルを削除すると、コンポーネント レジストリとスラッシュ メニューが再ロードされます。
+
+エージェントは、登録されたコンポーネント ファイルを操作することもできます。使用
+`list-local-component-files` で登録されたワークスペース ID を検索し、
+`write-local-component-file` は、`.tsx`、`.jsx`、`.ts` を作成または更新します。
+ワークスペースの `components/` フォルダーにある `.js` ファイル。 MDX ファイルは
+コンポーネントの使用法に関する信頼できる情報源。コンポーネント ファイルは通常のリポジトリのままです
+Git でレビューされたソース ファイル。
+
+コンポーネントが入力メタデータをエクスポートする場合、エディターでコンポーネントを選択する
+は、コンポーネントの右上隅に編集ボタンを表示します。サポートされている入力タイプ
+は、`string`、`textarea`、`number`、`boolean`、および `select` です。フォームには
+は MDX タグに戻るため、ローカル ファイルが信頼できる情報源のままになります。
+メタデータは `ComponentNameInputs`、`ComponentNameConfig.inputs` としてエクスポートできます
+`Component.inputs`、または `agentNative.inputs`。
+
+リテラル props を含む単純なコンポーネント タグはインラインでプレビューできます。
+
+```mdx
+<FrameworkTabs value="react" />
+
+<Callout type="warning">This setting affects production deploys.</Callout>
+```
+
+複雑な JSX 式はソースに保存されます。編集者が安全に作業できない場合
+コンポーネント プロップをプレビューしても、警告のプレースホルダーが表示されません。
+サイレントにデータを削除します。
+
+## ローカル ファイルの共有
+
+他のユーザーはパスを読み取ることができないため、ローカル ファイルは直接共有されません
+あなたのマシン。コンテンツ ツールバーの [共有] ボタンは、
+選択したファイルのデータベースにバックアップされたコピー。そのコピーに移動して、
+通常の共有ポップオーバー。元のローカル ファイルはローカル ファイルの下に残ります。
+データベース コピーは、ローカル ファイル モードの共有コピーの下に表示され、
+標準ドキュメント共有モデル。
+
+## ローカル内線番号
+
+ローカル ファイル モードでは、設定されたファイルからリポジトリにバックアップされた拡張機能をロードすることもできます。
+`extensions` フォルダー。各拡張子は、`extension.json`
+マニフェストと HTML エントリ ファイル:
+
+```text
+extensions/
+  doc-status/
+    extension.json
+    index.html
+```
+
+```json
+{
+  "id": "doc-status",
+  "name": "Doc Status",
+  "description": "Shows metadata for the selected Content file.",
+  "entry": "index.html",
+  "slots": ["content.sidebar.bottom"],
+  "permissions": {
+    "appActions": ["list-documents"],
+    "extensionData": true
+  }
+}
+```
+
+`index.html` は、通常で使用されるのと同じ Alpine/Tailwind 拡張本体形式です
+データベースベースの拡張機能。コンテンツ アプリがローカル拡張機能を認識すると、
+`content.sidebar.bottom` を宣言すると、
+the Content sidebar. The host passes `window.slotContext` with the selected
+ドキュメント ID、タイトル、ソース メタデータ、コンテンツがローカル ファイル モードかどうか。
+
+ローカル拡張子はアプリによってプレビューされますが、ファイルとして編集されます。拡張機能
+リストにはローカル ファイル バッジが表示され、フルページ ビューアは に戻ります
+エントリファイル。 SQL でサポートされる拡張機能 actions (更新、削除、共有、
+履歴は適用されません。エディタ、Codex、Claude コード、または Git 履歴を使用してください。
+ソースの変更。
+
+v1 の場合、ローカル拡張機能は意図的に保守的です:
+
+- 独自の小さな実行時状態に `extensionData` を使用できます
+- `extension.json` にリストされている `appAction` のみを呼び出すことができます
+- 生の SQL ヘルパーと外部 `extensionFetch` は無効になります
+- スロット ターゲットは `extension.json` で宣言されており、SQL を通じてインストールされていません
+
+これにより、ローカル ワークスペースに Obsidian のようなプラグイン サーフェスが提供されます。
+任意のリポジトリ ファイルは、データベースベースの拡張機能のすべての機能を継承します。
+
+## アプリでの使用方法
+
+ローカル ファイル モードは、フレームワークのローカル アーティファクト ヘルパーを通じて実装されます。
+アプリは、所有するアーティファクト タイプのルートを宣言し、読み取りと書き込みを行います
+UI とエージェントがすでに使用している同じアクション サーフェスを介して。
+
+コンテンツの場合、それは次のことを意味します:
+
+- `list-documents` には、構成された `.md` および `.mdx` ファイルがリストされます。
+- `get-document` は、選択されたローカル ファイルを読み取ります。
+- `update-document` は、選択されたローカル ファイルを書き込みます。
+- `create-document` は、選択したフォルダーに新しいローカル `.mdx` ファイルを作成します。
+- `delete-document` はローカル ファイルを削除します。
+- 検索は、設定されたローカル ファイル全体で実行されます。
+
+コンテンツ UI からのローカル ファイル ページの移動、名前変更、並べ替えはできません
+はまだサポートされています。これらの操作はワークスペースまたはコーディング エージェントを使用して実行します。
+コンテンツ サイドバーには、結果のファイル ツリーが反映されます。
+
+これにより、エージェント契約がシンプルになります。エージェントはコンテンツ actions を使用し続けることができます。
+これらの actions は、ターゲットが SQL ベースであるかファイルベースであるかを決定します。
+
+他のアプリも時間の経過とともに同じパターンを採用する可能性があります。スライド アプリではマッピングが可能
+`slides/*.mdx` をデッキに、計画アプリは `plans/*` を計画ドキュメントにマッピングでき、
+ダッシュボード アプリでは、`dashboards/*.mdx` をダッシュボードにマッピングできます。アプリ固有のもの
+フォルダは、同じローカル アーティファクト コントラクトの上に階層化された規則です。
+
+## ローカル ファイルとエクスポート/インポート
+
+コンテンツには 2 つの異なるファイル ワークフローがあります:
+
+| ワークフロー                           | 何が起こるか                                                                                                                              |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `/local-files` エクスポート/インポート | データベース モードは依然として信頼できる情報源です。ファイルは、エクスポート、編集、プレビュー、インポートするための明示的な同期面です。 |
+| ローカル ファイル モード               | ファイルは真実の情報源です。コンテンツ サイドバーとエディタはローカル ファイルで直接動作します。                                          |
+
+ホストされたワークスペースでファイルを時折確認したい場合は、エクスポート/インポートを使用します。
+リポジトリ自体がワークスペースである場合は、ローカル ファイル モードを使用します。
+
+## 歴史とコラボレーション
+
+ローカル ファイル モードはファイルネイティブの履歴に基づいています:
+
+- 重要な変更を Git にコミットする
+- プル リクエストをレビューに使用する
+- コーディング エージェントが同じファイルを直接編集できるようにする
+- 通常のファイルの差分を使用して変更を理解する
+
+データベース モードは、引き続きホスト型コラボレーション機能に適しています。
+共有、コメント、SQL によるバージョン履歴、ライブ マルチユーザー編集。
+
+プロバイダー同期は、どちらのモードの上にも重ねることができます。たとえば、ドキュメント リポジトリでは、
+CMS からローカル MDX ファイルにコンテンツをプルする actions を追加するか、選択したものをプッシュします
+ローカル ファイルを CMS に戻します。
+
+## 生産の安全性
+
+ローカル ファイル モードでは、アプリ actions に構成されたワークスペースへの直接書き込みアクセスが許可されます
+ファイル。これは、ローカル開発および信頼できるシングルテナント ファイルに適しています
+ブリッジですが、これはデフォルトの実稼働セキュリティ モデルではありません。
+
+`NODE_ENV=production` の場合、フレームワークは、次の操作を行わない限り `local-files` モードを拒否します。
+セット:
+
+```bash
+AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION=true
+```
+
+誰もが使用できる信頼できるシングルテナント展開に対してのみ設定してください
+アプリは構成されたファイルの読み取りと書き込みを許可されます。通常のホストの場合、
+マルチユーザー アプリでは、データベース モードと SQL による共有を使用します。

package/corpus/core/docs/content/locales/ja-JP/mcp-apps.md

@@ -0,0 +1,147 @@
+---
+title: "MCP アプリ"
+description: "実際のアプリ ルート、埋め込みブリッジ、およびホスト ブリッジ API を使用して、対話型 MCP アプリ UI を Claude、ChatGPT、およびその他の互換性のあるホスト内に作成および埋め込みます。"
+---
+
+# MCP アプリ
+
+**このページ: Claude/ChatGPT のインライン UI。** MCP アプリ リソースの作成と、互換性のあるホストのチャット内で実際のアプリ ルートをレンダリングする埋め込みブリッジ。このページは、**クライアント サポート マトリックス** ([below](#client-support)) の単一のホームでもあります。
+
+| もしご希望であれば…                                                          | 読む                                     |
+| ---------------------------------------------------------------------------- | ---------------------------------------- |
+| 外部エージェント/ホストをアプリに接続する                                    | [External Agents](/docs/external-agents) |
+| エージェントにさらに多くのツールを提供します (他の MCP サーバーを使用します) | [MCP Clients](/docs/mcp-clients)         |
+| Claude/ChatGPT でレンダリングするインライン UI を構築する                    | **このページ** — MCP アプリ              |
+| 下位レベルの MCP サーバー参照 (認証、ツール、カスタム マウント)              | [MCP Protocol](/docs/mcp-protocol)       |
+
+MCP アプリは、互換性のあるホスト (Claude、Claude デスクトップ、ChatGPT、VS Code GitHub Copilot、Goose、Postman、MCPJam、および Cursor) がチャット内でインタラクティブな UI をレンダリングできるようにする公式 `io.modelcontextprotocol/ui` 拡張機能です。エージェント ネイティブ アプリでは、すべての MCP アプリは **実際の React ルート**であり、個別のプレーン HTML ウィジェットではありません。
+
+Agent-Native アプリ独自のチャット内では、表、グラフ、入力された結果、承認アフォーダンスなどのファーストパーティ ウィジェットには [native chat renderers](/docs/native-chat-ui) を優先します。 Claude、ChatGPT、Copilot、Cursor、およびその他の互換性のあるホストの外部/クロスホスト インライン UI には MCP アプリを使用し、ユニバーサル ディープリンク フォールバックとしてアクション `link` を使用します。
+
+## オーサリング: オプションの MCP アプリ UI {#mcp-apps}
+
+MCP アプリ拡張機能をサポートするホストの場合、アクションは `mcpApp` を使用してインライン UI リソースをアドバタイズすることもできます。これは、外部エージェントがテキストだけではなくインタラクティブなサーフェスをユーザーに渡す必要があるフローの進歩的な機能強化です。たとえば、電子メールの下書きのレビュー、カレンダーの招待状の編集、生成されたダッシュボードのバリエーションからの選択などです。
+
+ユーザーが UI を必要とするときはいつでも、実際の React アプリを `embedRoute()` または `embedApp()` とともに使用します。メンタル モデルは単純です。アクションの `link` ターゲットは、MCP アプリ埋め込みターゲットでもあります。操作を通常のアクション/ツールとして公開し、`link` でフォーカスされたディープ リンクを返し、`mcpApp.resource = embedApp(...)` を追加して、有能なホストが新しいタブを開く代わりに同じルートをインラインでロードできるようにします。両方を同じルートから構築する必要がある場合は、`embedRoute({ title, openLabel, path })` を優先します。これは、1 回の呼び出しから一致する `link` および `mcpApp` フィールドを返す便利なラッパーですが、`embedApp(...)` は、`mcpApp.resource` に直接割り当てる下位レベルのリソースです。
+
+つまり、フルアプリの埋め込みは、一度開いたルートで実行できることはすべて実行できることを意味します。メールの下書きの確認または編集、フィルターされた受信トレイ/検索の表示、カレンダー イベントまたはイベントの下書きを開く、拡張機能ページの読み込み、完全な分析ダッシュボードまたは保存された分析の検査、スライド エディターでのデッキの続行、デザイン プロジェクト/エディターの開きなどです。 MCP アプリ用の 2 番目の状態プロトコルを発明するよりも、URL/ディープリンク パラメーターと既存の `/_agent-native/open` ナビゲーション/アプリ状態ブリッジを優先します。
+
+まれに、適切なターゲットが、アプリ シェル全体ではなく 1 つの共有 React コンポーネントをレンダリングする、集中したアプリ ルートである場合があります。 Analytics の `/chart` ルートがモデルです。URL 内のコンパクトな `SqlPanel` ペイロードを受け取り、ダッシュボードが使用するのと同じグラフ コンポーネントをレンダリングします。これはまだアプリの埋め込みであり、プレーンな HTML MCP アプリではありません。通常のアクション / `open_app({ path, embed: true })` を通じて公開または呼び出し、URL の決定性を維持し、`embedApp()` にそのルートをインラインでレンダリングさせます。
+
+製品 UI 用の 1 回限りのプレーン HTML MCP アプリを手書きしないでください。アクションにカスタム サーフェスが必要な場合は、最初に実際のアプリのルート/コンポーネントを追加または再利用し、そのルートを埋め込みます。
+
+```an-diagram title="MCP App embed round-trip" summary="The action's link target is also the embed target. Capable hosts load the same signed app route inline; everyone else falls back to the deep link."
+{
+  "html": "<div class=\"diagram-embed\"><div class=\"diagram-card\" data-rough><strong>Action</strong><small class=\"diagram-muted\">`link` target = MCP App embed target</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\" data-rough><strong>embedApp()</strong><span class=\"diagram-pill accent\">create_embed_session</span><small class=\"diagram-muted\">mints short-lived embed session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\" data-rough><strong>/_agent-native/embed/start</strong><small class=\"diagram-muted\">exchanges one-time SQL ticket</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\" data-rough><strong>Signed app route</strong><span class=\"diagram-pill ok\">real React route</span><small class=\"diagram-muted\">short-lived browser session</small></div><div class=\"diagram-fallback\"><span class=\"diagram-pill warn\">no MCP Apps support</span><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>&quot;Open in … &rarr;&quot; deep link</div></div></div>",
+"css": ".diagram-embed{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-embed .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:140px}.diagram-embed .diagram-arrow{font-size:22px;line-height:1}.diagram-embed .diagram-fallback{display:flex;flex-direction:column;align-items:center;gap:6px;margin-inline-start:8px}"
+}
+
+```
+
+```ts
+import { embedApp } from "@agent-native/core";
+
+export default defineAction({
+  // ...description, schema, run, link...
+  mcpApp: {
+    resource: embedApp({
+      title: "Review draft",
+      description: "Open the generated draft in the real Mail compose UI.",
+      iframeTitle: "Agent-Native Mail",
+      openLabel: "Open in Mail",
+    }),
+  },
+});
+```
+
+```an-annotated-code title="The mcpApp resource config"
+{
+  "filename": "actions/review-draft.ts",
+  "language": "ts",
+  "code": "import { embedApp } from \"@agent-native/core\";\n\nexport default defineAction({\n  // ...description, schema, run, link...\n  mcpApp: {\n    resource: embedApp({\n      title: \"Review draft\",\n      description: \"Open the generated draft in the real Mail compose UI.\",\n      iframeTitle: \"Agent-Native Mail\",\n      openLabel: \"Open in Mail\",\n    }),\n  },\n});",
+  "annotations": [
+    { "lines": "6", "label": "Progressive enhancement", "note": "`mcpApp.resource` advertises an inline UI for hosts that support the MCP Apps extension. Keep the action's `link` builder too — CLI-only and older hosts ignore the UI metadata and still need the deep link." },
+    { "lines": "7", "label": "Embed = the link target", "note": "`embedApp()` uses the action's `link` as its launch target: it calls `create_embed_session`, exchanges a one-time SQL ticket at `/_agent-native/embed/start`, and navigates the MCP App frame to the same signed app route." },
+    { "lines": "11", "label": "Universal fallback label", "note": "`openLabel` is the visible `\"Open in … →\"` text used as the deep-link escape hatch when a host does not render the inline iframe." }
+  ]
+}
+```
+
+MCP サーバーは、拡張機能 `io.modelcontextprotocol/ui` をアドバタイズし、`_meta.ui.resourceUri` と `_meta["ui/resourceUri"]` を `tools/list` に追加し、ChatGPT アプリ SDK 互換性メタデータ (`openai/outputTemplate`、ウィジェット CSP/説明/アクセシビリティ) も発行します。 MIME `text/html;profile=mcp-app` を使用して、HTML から `resources/list`、`resources/templates/list`、および `resources/read` を公開します。標準入出力プロキシはライブ アプリからこれらのリソース ハンドラーを転送するため、デスクトップおよび CLI クライアントは HTTP クライアントと同じリソースを認識します。
+
+`mcpApp` を追加する場合でも、既存の `link` ビルダーを保持します。 CLI のみのクライアント、古いホスト、および MCP アプリをレンダリングしないホストは、UI メタデータを無視しますが、それでも `"Open in … →"` リンクが必要です。 `embedApp()` は、そのリンクを起動ターゲットとして使用し、アプリ専用の `create_embed_session` ヘルパーを呼び出し、`/_agent-native/embed/start` で 1 回限りの SQL チケットを交換し、短期間のブラウザー セッションと同一オリジン フェッチのベアラー フォールバックを使用して、MCP アプリ フレームをターゲット ルートにナビゲートします。 `open_app({ app, path, embed: true })` は、完全なダッシュボード、フィルターされた受信トレイ、カレンダーの下書きビュー、分析、拡張ページなどのルートの一般的なエスケープ ハッチであり、完全なアプリが最も明確なレビュー/編集画面である場合には積極的に使用する必要があります。
+
+`embedApp()` には、リソース CSP に MCP リクエスト起点が含まれているため、ランチャーは署名されたファーストパーティ アプリ ルートをフェッチし、明示的にリクエストされた場合はフレーム化できます。 Dispatch は、付与されたアプリの正確なオリジンを `open_app` リソースに追加するため、すべての HTTPS オリジンを許可することなく、単一の Dispatch コネクタでメール、カレンダー、スライドなどをインライン化できます。サードパーティ プレーヤーを実際に埋め込むか、サードパーティ アセットをロードするカスタム MCP アプリに対してのみ、追加のフレームまたはリソース ドメインを渡します。
+
+これらの `embedApp()` ルート内では、`sendToAgentChat()` は埋め込みを認識します。自動送信されたプロンプトは、`ui/update-model-context` と `ui/message` として MCP ホストに中継されるため、埋め込みアプリのボタンは、選択したアプリの状態から Claude/ChatGPT の会話を意図的に継続できます。非表示のコンテキストはモデル コンテキストとして送信されます。表示されるユーザーのターンはアプリのプロンプトのみであるため、内部のアプリ状態ファイル パスに関する恐ろしいホストの同意が回避されます。 `submit: false` はローカルの事前入力/レビュー動作のままです。
+
+## ファーストクラス MCP アプリ ブリッジ {#mcp-app-bridge}
+
+MCP アプリの埋め込みはルートの埋め込みであり、個別のミニ製品ではありません。 `embedApp()` は、アクションの `link` ターゲットから開始され、短期間の埋め込みセッションを作成し、署名されたアプリ ルートを起動します。標準 MCP アプリ ホストは、ホストがルートを直接ハイドレートできる場合、MCP アプリ フレーム自体をナビゲートできます。
+
+```an-diagram title="Two host bridge paths, one signed route" summary="Claude transplants the hydrated route and uses the direct ui/_bridge; ChatGPT gets a controlled iframe via window.openai and relays host actions over postMessage. Both point at the same signed app route."
+{
+  "html": "<div class=\"diagram-bridge\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><strong>Claude web</strong><span class=\"diagram-pill accent\">single-frame transplant</span><small class=\"diagram-muted\">hydrates signed app HTML in Claude's iframe, then direct`ui/_` host bridge</small></div><div class=\"diagram-card\" data-rough><strong>ChatGPT web</strong><span class=\"diagram-pill accent\">controlled route iframe</span><small class=\"diagram-muted\">`window.openai`host APIs ·`agentNative.mcpHost.*` postMessage relay</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Same signed app route<br><small class=\"diagram-muted\">normal route + React components</small></div></div>",
+"css": ".diagram-bridge{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-bridge .diagram-col{display:flex;flex-direction:column;gap:12px}.diagram-bridge .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;max-width:300px}.diagram-bridge .diagram-arrow{font-size:22px;line-height:1}.diagram-bridge .diagram-box{padding:16px 18px;text-align:center}"
+}
+
+```
+
+Claude Web は単一フレーム移植パスを使用します。リソース ドキュメントは署名済みアプリ HTML を取得し、それを Claude の MCP アプリ iframe 内にハイドレートします。これは、Claude がアプリ所有の子 iframe または外部フレーム ナビゲーションを確実に許可しないためです。 ChatGPT Web は、アプリ ブリッジが安定した `window.openai` ホスト API と制限された高さ制御を提供するため、制御されたルート iframe を取得します。すべてのパスは同じ署名済みアプリ ルートを指し、通常のルートと React コンポーネントをレンダリングします。同じ署名付き URL でリロードすると同じビューが再構築されるように、埋め込みルートを設計します。
+
+同じアプリ `open_app({ embed: true })` の場合、フレームワークは元のツール呼び出し中に埋め込み開始チケットを作成し、署名された開始 URL を非表示のツール メタデータに保存します。カスタム actions は、同じ高速パスに対して `embedStartUrl` を返すことができます。 MCP レイヤーは、チケットを含む URL をモデルに表示される `structuredContent` および通常のオープンリンク メタデータから削除します。埋め込み開始 URL が存在しない場合、リソースはアプリ専用の `create_embed_session` ヘルパーにフォールバックします。これにより、実稼働ホストは、ワンタイム アプリ セッション URL をトランスクリプトに漏らすことなく、iframe によって開始されるツール呼び出しを直接ルートで制限するようになります。 1 回限りの開始チケットの有効期限が切れた後にユーザーが古いチャットを再度開くと、開始ルートは小さな更新ページを返し、`agentNative.embedSessionExpired` をラッパーにポストします。 `embedApp()` は、古い開始 URL をクリアし、元のアプリ ルートがまだ残っている場合に、`create_embed_session` を通じて新しいチケットを作成します。
+
+ChatGPT は、`window.openai` を通じて専用の互換性パスを取得します。起動ドキュメントは、`toolInput`、`toolOutput`、および `toolResponseMetadata` を直接読み取り、その後、`window.openai.callTool(...)` 経由で `create_embed_session` を呼び出します。標準の MCP アプリ ホストは、`ui/*` JSON-RPC ブリッジを使用します。直接ハイドレートされたルートは、ホスト ブリッジ ヘルパーを通じて `ui/update-model-context`、`ui/message`、`ui/open-link`、および `ui/request-display-mode` を呼び出すことができます。 Claude の移植ルートは、ハイドレーション後に同じ直接 `ui/*` ホスト ブリッジを使用します。 ChatGPT または明示的な診断 iframe パスが使用される場合、ラッパーは `agentNative.mcpHost.*` postMessage リクエストを介して同じホスト actions を中継します。両方のパスで結果の形状を同一に保ちます。焦点を絞った `link` と簡潔な構造化コンテンツを返します。
+
+標準の `_meta.ui.domain` をアプリ URL に設定しないでください。 MCP アプリはそのフィールドをホスト固有として扱います。Claude は `{hash}.claudemcpcontent.com` スタイルのサンドボックス ドメインを検証しますが、ChatGPT は独自の `openai/widgetDomain` メタデータを使用します。意図的にホスト固有の値を発行する場合を除き、`ui.domain` を省略します。ホストはデフォルトのサンドボックスオリジンを選択します。
+
+拡張ページは、2 番目のルート iframe をナビゲートせずに、MCP チャット埋め込み内にサンドボックスを保持します。通常のアプリの使用では、`/_agent-native/extensions/:id/render` がサンドボックス化された子 iframe としてレンダリングされます。 MCP チャット ブリッジ モードでは、フレームワークはルート iframe 内でサンドボックス化された `srcDoc` と同じ拡張ドキュメントをレンダリングし、`sandbox="allow-scripts allow-forms"` を維持しながらホスト `frame-ancestors` / `X-Frame-Options` の障害を回避します。
+
+リソース シェルは外部ホスト サイズを所有します。 `embedApp({ height })` のデフォルトは `560px` で、シェルを `320-900px` にクランプし、小さいツールバー用に `44px` を予約するため、ルート ビューポートは `height - 44px` になります。埋め込まれたアプリのルートを内部でスクロール可能な状態に保ち、ランチャーがドキュメント全体の高さではなく、制限された固有の高さを報告できるようにします。そうしないと、ホストの自動サイズ変更により、通常のアプリ ページが非常に縦長のチャット アーティファクトに変わってしまう可能性があります。変更されたシェルは、新しい MCP アプリ リソースと新しいツール呼び出しにのみ影響します。古い ChatGPT/Claude 会話フレームは以前のリソースの動作を保持している可能性があるため、修正を判断する前に新しいインライン レンダリングでサイズを確認してください。
+
+### 埋め込みモード {#embed-modes}
+
+Claude は、デフォルトで単一フレーム移植パスを使用します。ホストのモジュール読み込み動作をデバッグするときに、`embedMode: "transplant"` または `frame: "transplant"` を使用して他のホストで強制することもできます。 `embedMode: "iframe"`、`renderMode: "iframe"`、`nested: true`、または `frame: "iframe"` を使用して、ネストされた診断 iframe を強制できます。 iframe がブロックされている場合、`embedApp()` はそれをオープンアプリのフォールバックに置き換えます。ユーザーはインラインで再試行するか、ホスト経由で新たに生成された埋め込みセッションを開くか、表示可能なルート URL を使用できます。アクションの `link` ターゲットは、依然として万能の脱出ハッチであるため、単独で有用なままにしておきます。
+
+ngrok を通じて Claude をテストする場合は、実稼働ビルド (`npx @agent-native/core@latest build`、次に `npx @agent-native/core@latest start`) またはデプロイされたプレビュー/実稼働 URL を使用します。 Claude の単一フレーム移植パスは、実稼働アセット チャンクで動作します。 `/app/root.tsx` などの生の Vite 開発モジュールはアプリ認証によって保護され、Claude リソース オリジンからの動的インポートに失敗する可能性があります。
+
+## ホストブリッジ API {#host-bridge}
+
+ホスト ブリッジは意図的に小さくなっています:
+
+| モード                  | メッセージタイプ                      | 次の目的で使用してください                                |
+| ----------------------- | ------------------------------------- | --------------------------------------------------------- |
+| 直接ホスト ルート       | `ui/update-model-context`             | ホスト モデルの非表示コンテキスト                         |
+| 直接ホスト ルート       | `ui/message`                          | 表示されているユーザーが主催者になることを投稿            |
+| 直接ホスト ルート       | `ui/open-link`                        | ホスト経由で外部またはアプリ URL を開きます               |
+| 直接ホスト ルート       | `ui/request-display-mode`             | `inline`、`fullscreen`、または `pip` をリクエスト         |
+| Claude 移植             | `ui/*`                                | 水和後の同じ直接ホストブリッジ                            |
+| ChatGPT / iframe ルート | `agentNative.mcpHostContext`          | テーマ、ロケール、ホスト プラットフォーム、ディメンション |
+| ChatGPT / iframe ルート | `agentNative.embeddedAppReady`        | ルート iframe がロードされていることを確認します          |
+| ChatGPT / iframe ルート | `agentNative.mcpHost.*` / `.response` | ホストリクエストのラッパーリレー                          |
+
+埋め込みルートは、`@agent-native/core/client` から `updateMcpAppModelContext()`、`openMcpAppHostLink()`、`requestMcpAppDisplayMode()`、`getMcpAppHostContext()`、および `useMcpAppHostContext()` を使用できます。 `sendToAgentChat()` は、自動送信プロンプトにフルアプリ埋め込みからの同じパスを使用します。
+
+表示モードはベストエフォートです。アプリ内 `McpAppRenderer` は現在、インライン Web ホスト コンテキストとインライン専用表示モードをレポートします。外部ホストは、より大きな表示要求を受け入れたり、無視したり、サポートされていないモードのエラーを返したりすることがあります。インライン ルートは常に使用可能な状態にしておきます。
+
+## クライアントのサポートとキャッシュ {#client-support}
+
+現在の公式 MCP アプリ クライアント リストには、Claude、Claude デスクトップ、VS Code GitHub Copilot、Goose、Postman、MCPJam、ChatGPT、および Cursor が含まれています。ホストのサポートはプラン、リリース チャネル、クライアントのバージョンによって異なるため、[MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix) を確認してください。 ChatGPT カスタム MCP アプリは、ChatGPT Web 上の Business および Enterprise/Edu ワークスペースの開発者モードを通じて利用できます。 OpenAI の [developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-apps-in-chatgpt-beta) メモを参照してください。
+
+Claude コード、Codex、およびその他の CLI/コードエディター クライアントは、MCP アプリをサポートする場合でも同じリソースとメタデータを受け取りますが、その正確なサーフェスでのインライン iframe レンダリングを検証していない限り、それらをリンクアウト ホストとして扱います。ホストが iframe をレンダリングしないことを選択した場合でも、ディープ リンクは信頼性の高いフォールバックとして残ります。実際には、すべてのエージェント ネイティブ アプリは、対応ホストでのインライン レビュー/編集用の MCP アプリと、完全なアプリへのユニバーサル ラウンドトリップ用の `link` の両方を使用して作成する必要があります。
+
+Claude および ChatGPT は、既存のカスタム コネクタのツールとリソースのメタデータをキャッシュできます。 MCP アプリのメタデータを変更した後、新しいツール呼び出しで検証します。ホストがまだ古い記述子を使用している場合は、Claude コネクタを再接続するか、ChatGPT コネクタを再スキャン/レビューして、カタログを更新します。デプロイ後に Claude がツール記述子に存在する `_meta.ui.csp` または `_meta.ui.permissions` に関する警告をログに記録する場合、そのコネクタは古いメタデータを使用しています。Claude コネクタを削除または再接続し、新しいチャットを開始してください。
+
+## テスト {#testing}
+
+`embedApp()` および `McpAppRenderer` 周辺の軽量フィクスチャを使用して MCP アプリをテストします。実際の外部ホストを必要とせずに、CSP、ホスト コンテキスト、アプリの起動、ブリッジ メッセージの動作をカバーします。 ChatGPT または Claude Web を検証する場合、シェルの変更後に新しいツール呼び出しをトリガーし、表示される iframe を測定します。同じ会話内で以前にレンダリングされたフレームには、キャッシュされた高さまたは起動動作が引き続き表示される場合があります。
+
+## 関連 {#related}
+
+- [External Agents](/docs/external-agents) — Claude、ChatGPT、Codex、および Cursor をホストされたアプリに接続します。 MCP アプリ互換性マトリックス;カタログ階層。ディープリンク。
+- [MCP Protocol](/docs/mcp-protocol) — 自動マウントされた MCP サーバー、認証、ツール、および `ask-agent`。
+- [Actions](/docs/actions) — `defineAction`、`link` ビルダー、`publicAgent`。
+
+```
+
+```