@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ko-KR/local-file-mode.md

@@ -0,0 +1,433 @@
+---
+title: "로컬 파일 모드"
+description: "로컬 Markdown, MDX 및 기타 repo 파일을 정보 소스로 사용하여 에이전트 네이티브 앱을 실행합니다. 여기에는 맞춤 구성요소가 포함된 Obsidian 스타일 MDX 문서도 포함됩니다."
+---
+
+# 로컬 파일 모드
+
+로컬 파일 모드를 사용하면 에이전트 네이티브 앱이 일반 UI 및 작업 표면을 연결할 수 있습니다.
+저장소나 작업공간의 파일에 직접 연결됩니다. 앱이 여전히 호스팅된 것처럼 느껴집니다.
+제품, 목록 보기, 편집기 및 에이전트 도구는 로컬 파일을 읽고 씁니다
+SQL 지원 앱 기록 대신
+
+첫 번째 구현은 콘텐츠 템플릿에 있습니다. 왼쪽 사이드바는 다음과 같습니다.
+로컬 `.md` 및 `.mdx` 파일로 채워지며, 페이지를 선택하면 표준이 열립니다.
+컨텐츠 편집기 및 저장하면 선택한 파일에 다시 기록됩니다. 동일한 파일은 다음과 같습니다.
+Codex, Claude 코드, Agent-Native 사이드바 에이전트 또는 일반 사용자로도 편집 가능
+편집자.
+
+콘텐츠의 경우 제품이 MDX용 오픈 소스 Obsidian처럼 느껴집니다.
+문서는 파일로 저장되고 앱에는 시각적 편집기인 에이전트 actions가 추가됩니다.
+공유 가능한 복사본 및 풍부한 대화형 MDX 구성 요소
+
+저장소 우선 워크플로를 원할 경우 로컬 파일 모드를 사용하세요.
+
+- `docs/*.mdx`를 사용한 문서 저장소
+- `blog/*.mdx`가 있는 블로그
+- `resources/*.md`의 포지셔닝, 메시지 또는 팀 메모와 같은 리소스
+- 풍부한 MDX 편집기를 갖춘 개인 흑요석 스타일 지식 기반
+- 로컬 React 코드에서 생성된 대화형 사용자 정의 MDX 블록이 필요한 문서
+- 코딩 에이전트가 쉽게 검사하고 패치할 수 있는 앱 아티팩트
+
+호스팅된 협업 앱 경험을 원할 때 데이터베이스 모드를 사용하세요:
+다중 사용자 공유, SQL 지원 권한, 댓글, 버전 기록 및
+로컬 파일 시스템 액세스가 없는 프로덕션 호스팅
+
+## 정신 모델
+
+두 가지 정보 소스 모드가 있습니다:
+
+| 모드              | 진실의 근원                            | 최적의 용도                                                        |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------------ |
+| 데이터베이스 모드 | Drizzle를 통한 SQL 행                  | 호스팅된 앱, 공동 작업, 공유, 댓글, 버전 기록                      |
+| 로컬 파일 모드    | `agent-native.json`가 선언한 Repo 파일 | 로컬/개발 워크플로, 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" />
+```
+
+콘텐츠 개발 서버는 내보내기 및 PascalCase 기본값이라는 PascalCase를 검색합니다.
+`components/` 아래의 `.tsx`, `.jsx`, `.ts` 및 `.js` 파일에서 내보냅니다. 그
+구성요소는 편집기 내에서 렌더링되고 아래의 슬래시 메뉴에 나타납니다
+**로컬 구성요소**. 슬래시를 삽입하면 다음과 같은 최소한의 태그가 생성됩니다.
+`<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`.
+
+리터럴 소품이 있는 간단한 구성 요소 태그는 인라인으로 미리 볼 수 있습니다.
+
+```mdx
+<FrameworkTabs value="react" />
+
+<Callout type="warning">This setting affects production deploys.</Callout>
+```
+
+복잡한 JSX 표현식은 소스에 보존됩니다. 편집자가 안전하게 할 수 없는 경우
+아직 구성 요소 속성을 미리 보면
+데이터를 자동으로 삭제합니다.
+
+## 로컬 파일 공유
+
+다른 사용자가 경로를 읽을 수 없기 때문에 로컬 파일은 직접 공유되지 않습니다.
+당신의 기계. 콘텐츠 도구 모음의 공유 버튼은
+선택한 파일의 데이터베이스 기반 복사본을 찾아 해당 복사본을 탐색하고
+일반 공유 팝오버. 원본 로컬 파일은 로컬 파일 아래에 남아 있습니다.
+데이터베이스 복사본은 로컬 파일 모드의 공유 복사본 아래에 나타나며
+표준 문서 공유 모델.
+
+## 지역 확장
+
+로컬 파일 모드는 구성된 파일에서 repo 지원 확장을 로드할 수도 있습니다.
+`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, 제목, 소스 메타데이터 및 콘텐츠가 로컬 파일 모드에 있는지 여부
+
+로컬 확장자는 앱에서 미리 볼 수 있지만 파일로 편집됩니다. 확장 프로그램
+목록에는 로컬 파일 배지가 표시되며 전체 페이지 뷰어는 다음을 가리킵니다
+항목 파일입니다. 업데이트, 삭제, 공유 및
+이력은 적용되지 않습니다. 편집기, Codex, Claude 코드 또는 Git 기록을 사용하여
+소스 변경.
+
+v1의 경우 로컬 확장은 의도적으로 보수적입니다.
+
+- 그들은 자신의 작은 런타임 상태를 위해 `extensionData`를 사용할 수 있습니다
+- `extension.json`에 나열된 `appAction`만 호출할 수 있습니다
+- 원시 SQL 도우미 및 외부 `extensionFetch`가 비활성화되었습니다.
+- 슬롯 대상은 SQL를 통해 설치되지 않은 `extension.json`에서 선언되었습니다.
+
+이것은 로컬 작업 공간에 Obsidian과 유사한 플러그인 표면을 제공하지만
+임의의 repo 파일은 데이터베이스 지원 확장 프로그램의 모든 기능을 상속합니다.
+
+## 앱이 이를 사용하는 방법
+
+로컬 파일 모드는 프레임워크의 로컬 아티팩트 도우미를 통해 구현됩니다.
+앱은 자신이 소유한 아티팩트 유형의 루트를 선언한 다음 읽고 씁니다.
+UI와 에이전트가 이미 사용하고 있는 동일한 작업 표면을 통해
+
+콘텐츠의 경우 다음을 의미합니다.
+
+- `list-documents`에는 구성된 `.md` 및 `.mdx` 파일이 나열됩니다.
+- `get-document`는 선택한 로컬 파일을 읽습니다.
+- `update-document`는 선택한 로컬 파일을 씁니다.
+- `create-document`는 선택한 폴더에 새 로컬 `.mdx` 파일을 생성합니다.
+- `delete-document`는 로컬 파일을 삭제합니다.
+- 검색은 구성된 로컬 파일 전체에서 실행됩니다.
+
+컨텐츠 UI에서 로컬 파일 페이지를 이동하고, 이름을 바꾸고, 순서를 바꾸는 것은
+아직 지원됩니다. 작업 공간이나 코딩 에이전트를 사용하여 해당 작업을 수행하십시오.
+콘텐츠 사이드바에는 결과 파일 트리가 반영됩니다.
+
+이렇게 하면 에이전트 계약이 단순해집니다. 에이전트는 콘텐츠 actions를 계속 사용할 수 있습니다.
+그리고 actions는 대상이 SQL 지원인지 파일 지원인지 결정합니다.
+
+시간이 지남에 따라 다른 앱도 동일한 패턴을 채택할 수 있습니다. 프레젠테이션 앱은 지도를 작성할 수 있습니다
+`slides/*.mdx`를 데크에 연결하고 Plans 앱은 `plans/*`를 계획 문서에 매핑할 수 있으며
+대시보드 앱은 `dashboards/*.mdx`를 대시보드에 매핑할 수 있습니다. 특정 앱
+폴더는 동일한 로컬 아티팩트 계약 위에 쌓인 규칙입니다.
+
+## 로컬 파일과 내보내기/가져오기
+
+콘텐츠에는 두 가지 파일 작업 흐름이 있습니다:
+
+| 워크플로우                       | 무슨 일이 일어나는지                                                                                                     |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `/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/ko-KR/mcp-apps.md

@@ -0,0 +1,147 @@
+---
+title: "MCP 앱"
+description: "실제 앱 경로, 포함 브리지 및 호스트 브리지 API를 사용하여 Claude, ChatGPT 및 기타 호환 호스트 내에 대화형 MCP 앱 UI를 작성하고 포함합니다."
+---
+
+# 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 Desktop, ChatGPT, VS Code GitHub Copilot, Goose, Postman, MCPJam 및 Cursor)가 채팅에서 대화형 UI를 인라인으로 렌더링할 수 있게 해주는 공식 `io.modelcontextprotocol/ui` 확장입니다. 에이전트 기반 앱에서 모든 MCP 앱은 별도의 일반 HTML 위젯이 아닌 **실제 React 경로**입니다.
+
+Agent-Native 앱의 자체 채팅 내에서 표, 차트, 입력된 결과 및 승인 어포던스와 같은 자사 위젯에 대해 [native chat renderers](/docs/native-chat-ui)를 선호합니다. Claude, ChatGPT, Copilot, Cursor 및 기타 호환 호스트의 외부/교차 호스트 인라인 UI용 MCP 앱을 범용 딥 링크 폴백으로 `link` 작업과 함께 사용하세요.
+
+## 작성: 선택적 MCP 앱 UI {#mcp-apps}
+
+MCP 앱 확장을 지원하는 호스트의 경우 작업은 `mcpApp`를 사용하여 인라인 UI 리소스를 광고할 수도 있습니다. 이는 외부 에이전트가 사용자에게 텍스트만 제공하는 대신 대화형 화면을 제공해야 하는 흐름에 대한 점진적인 개선 사항입니다. 예를 들어 이메일 초안 검토, 캘린더 초대 편집, 생성된 대시보드 변형 중에서 선택 등이 있습니다.
+
+사용자가 UI가 필요할 때마다 `embedRoute()` 또는 `embedApp()`와 함께 실제 React 앱을 사용하세요. 정신 모델은 간단합니다. 작업의 `link` 대상은 MCP 앱 삽입 대상이기도 합니다. 작업을 일반 작업/도구로 노출하고, `link`를 사용하여 집중된 딥 링크를 반환하고, `mcpApp.resource = embedApp(...)`를 추가하여 유능한 호스트가 새 탭을 여는 대신 동일한 경로를 인라인으로 로드하도록 합니다. 둘 다 동일한 경로에서 빌드해야 하는 경우 `embedRoute({ title, openLabel, path })`를 선호하세요. 이는 한 번의 호출에서 일치하는 `link` 및 `mcpApp` 필드를 반환하는 편리한 래퍼인 반면, `embedApp(...)`는 `mcpApp.resource`에 직접 할당하는 하위 수준 리소스입니다.
+
+이는 경로가 열리면 이메일 초안 검토 또는 편집, 필터링된 받은 편지함/검색 표시, 달력 이벤트 또는 이벤트 초안 열기, 확장 페이지 로드, 전체 분석 대시보드 또는 저장된 분석 검사, 슬라이드 편집기에서 데크 계속하기, 디자인 프로젝트/편집기 열기 등 경로가 열리면 할 수 있는 모든 작업을 전체 앱 삽입으로 수행할 수 있음을 의미합니다. MCP 앱을 위한 두 번째 상태 프로토콜을 개발하는 것보다 URL/딥 링크 매개변수와 기존 `/_agent-native/open` 탐색/앱 상태 브리지를 선호하세요.
+
+드물게 올바른 대상은 전체 앱 셸 대신 하나의 공유 React 구성 요소를 렌더링하는 집중된 앱 경로입니다. Analytics의 `/chart` 경로가 모델입니다. URL에서 컴팩트한 `SqlPanel` 페이로드를 가져와 대시보드에서 사용하는 것과 동일한 차트 구성 요소를 렌더링합니다. 이것은 여전히 ​​일반 HTML MCP 앱이 아닌 앱 삽입입니다. 일반 작업/`open_app({ path, embed: true })`를 통해 이를 노출하거나 호출하고, URL를 결정적으로 유지하고, `embedApp()`가 해당 경로를 인라인으로 렌더링하도록 합니다.
+
+제품 UI에 대한 일회성 일반 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`를 사용하여 `resources/list`, `resources/templates/list` 및 `resources/read`를 통해 HTML를 노출합니다. stdio 프록시는 라이브 앱에서 해당 리소스 핸들러를 전달하므로 데스크톱 및 CLI 클라이언트는 HTTP 클라이언트와 동일한 리소스를 볼 수 있습니다.
+
+`mcpApp`를 추가하는 경우에도 기존 `link` 빌더를 유지합니다. CLI 전용 클라이언트, 이전 호스트 및 MCP 앱을 렌더링하지 않는 모든 호스트는 UI 메타데이터를 무시하고 여전히 `"Open in … →"` 링크가 필요합니다. `embedApp()`는 해당 링크를 실행 대상으로 사용하고, 앱 전용 `create_embed_session` 도우미를 호출하고, `/_agent-native/embed/start`에서 일회성 SQL 티켓을 교환하고, 단기 브라우저 세션과 동일 출처 가져오기에 대한 베어러 폴백을 통해 MCP 앱 프레임을 대상 경로로 이동합니다. `open_app({ app, path, embed: true })`는 전체 대시보드, 필터링된 받은 편지함, 일정 초안 보기, 분석 및 확장 페이지와 같은 경로를 위한 일반적인 탈출구이며 전체 앱이 가장 명확한 검토/편집 표면일 때 자유롭게 사용해야 합니다.
+
+`embedApp()`에는 리소스 CSP에 MCP 요청 원본이 포함되어 있으므로 런처가 명시적으로 요청하는 경우 서명된 자사 앱 경로를 가져오고 프레임화할 수 있습니다. Dispatch는 부여된 앱의 정확한 출처를 `open_app` 리소스에 추가하므로 단일 Dispatch 커넥터가 모든 HTTPS 출처를 허용하지 않고도 메일, 캘린더, 슬라이드 및 나머지 항목을 인라인할 수 있습니다. 실제로 타사 플레이어를 내장하거나 타사 자산을 로드하는 사용자 정의 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 웹은 단일 프레임 이식 경로를 사용합니다. 리소스 문서는 서명된 앱 HTML를 가져와 Claude의 MCP 앱 iframe 내에서 이를 수화합니다. 왜냐하면 Claude는 ​​앱 소유 하위 iframe 또는 외부 프레임 탐색을 안정적으로 허용하지 않기 때문입니다. ChatGPT 웹은 Apps 브리지가 안정적인 `window.openai` 호스트 API 및 제한된 높이 제어를 제공하기 때문에 제어된 경로 iframe을 얻습니다. 모든 경로는 동일한 서명된 앱 경로를 가리키며 일반 경로와 React 구성 요소를 렌더링합니다. 동일한 서명된 URL를 사용하여 다시 로드하면 동일한 뷰가 재구성되도록 포함된 경로를 설계합니다.
+
+동일 앱 `open_app({ embed: true })`의 경우 프레임워크는 원래 도구 호출 중에 포함 시작 티켓을 생성하고 서명된 시작 URL를 숨겨진 도구 메타데이터에 저장합니다. 사용자 정의 actions는 동일한 빠른 경로에 대해 `embedStartUrl`를 반환할 수 있습니다. MCP 레이어는 모델 표시 `structuredContent` 및 일반 오픈 링크 메타데이터에서 티켓 보유 URL를 제거합니다. 포함 시작 URL가 없으면 리소스는 앱 전용 `create_embed_session` 도우미로 대체됩니다. 이는 일회성 앱 세션 URL를 기록으로 유출하지 않고 직접 경로에서 iframe 시작 도구 호출을 제한하는 프로덕션 호스트를 유지합니다. 일회성 시작 티켓이 만료된 후 사용자가 이전 채팅을 다시 열면 시작 경로는 작은 새로 고침 페이지를 반환하고 `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 Apps는 해당 필드를 호스트별 필드로 처리합니다. Claude는 `{hash}.claudemcpcontent.com` 스타일 샌드박스 도메인의 유효성을 검사하는 반면, ChatGPT는 자체 `openai/widgetDomain` 메타데이터를 사용합니다. 의도적으로 호스트별 값을 내보내는 경우가 아니면 `ui.domain`를 생략하세요. 호스트는 기본 샌드박스 원본을 선택합니다.
+
+확장 페이지는 두 번째 경로 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`는 현재 인라인 웹 호스트 컨텍스트와 인라인 전용 디스플레이 모드를 보고합니다. 외부 호스트는 더 큰 디스플레이 요청을 수락하거나 무시하거나 지원되지 않는 모드 오류로 응답할 수 있습니다. 항상 인라인 경로를 사용할 수 있도록 유지하세요.
+
+## 클라이언트 지원 및 캐싱 {#client-support}
+
+현재 공식 MCP 앱 클라이언트 목록에는 Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT 및 Cursor가 포함됩니다. 호스트 지원은 여전히 ​​계획, 릴리스 채널 및 클라이언트 버전에 따라 다르므로 [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix)를 확인하세요. ChatGPT 맞춤형 MCP 앱은 ChatGPT 웹의 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 웹을 검증할 때 셸 변경 후 새로운 도구 호출을 트리거하고 표시되는 iframe을 측정하세요. 동일한 대화에서 이전에 렌더링된 프레임에는 여전히 캐시된 높이 또는 실행 동작이 표시될 수 있습니다.
+
+## 관련 {#related}
+
+- [External Agents](/docs/external-agents) — Claude, ChatGPT, Codex 및 커서를 호스팅된 앱에 연결합니다. MCP 앱 호환성 매트릭스; 카탈로그 계층; 딥 링크.
+- [MCP Protocol](/docs/mcp-protocol) — 자동 마운트된 MCP 서버, 인증, 도구 및 `ask-agent`.
+- [Actions](/docs/actions) — `defineAction`, `link` 빌더, `publicAgent`.
+
+```
+
+```