@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/es-ES/local-file-mode.md

@@ -0,0 +1,433 @@
+---
+title: "Modo de archivo local"
+description: "Ejecute aplicaciones nativas del agente con Markdown, MDX y otros archivos de repositorio locales como fuente de verdad, incluidos documentos MDX estilo Obsidian con componentes personalizados."
+---
+
+# Modo de archivo local
+
+El modo de archivo local permite que una aplicación nativa del agente adjunte su UI normal y su superficie de acción
+directamente a archivos en un repositorio o espacio de trabajo. La aplicación todavía se siente como si estuviera alojada
+producto, pero sus vistas de lista, editor y herramientas de agente leen y escriben archivos locales
+en lugar de registros de aplicaciones respaldados por SQL.
+
+La primera implementación está en la plantilla de Contenido: la barra lateral izquierda es
+rellenado a partir de archivos locales `.md` y `.mdx`; al seleccionar una página se abre el estándar
+Editor de contenido y guardar escrituras en el archivo seleccionado. Los mismos archivos pueden
+También puede ser editado por Codex, Código Claude, el agente de la barra lateral Agent-Native o un normal
+editor.
+
+En cuanto al contenido, esto hace que el producto parezca Obsidian de código abierto para MDX:
+tus documentos se guardan como archivos, mientras que la aplicación agrega un editor visual, el agente actions
+Copias que se pueden compartir y componentes interactivos enriquecidos de MDX.
+
+Utilice el modo de archivo local cuando desee un flujo de trabajo basado en el repositorio:
+
+- un repositorio de documentos con `docs/*.mdx`
+- un blog con `blog/*.mdx`
+- recursos como posicionamiento, mensajería o notas del equipo en `resources/*.md`
+- una base de conocimientos personal estilo Obsidian con un editor MDX más completo
+- Documentos que necesitan bloques MDX personalizados e interactivos generados a partir del código React local
+- artefactos de aplicaciones que deberían ser fáciles de inspeccionar y parchar para los agentes de codificación
+
+Utilice el modo de base de datos cuando desee disfrutar de la experiencia de la aplicación colaborativa alojada:
+Compartir entre varios usuarios, permisos respaldados por SQL, comentarios, historial de versiones y
+alojamiento de producción sin acceso al sistema de archivos local.
+
+## El modelo mental
+
+Hay dos modos de fuente de verdad:
+
+| Modo                  | Fuente de la verdad                                        | Mejor para                                                                                                                   |
+| --------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Modo de base de datos | Filas SQL hasta Drizzle                                    | Aplicaciones alojadas, colaboración, uso compartido, comentarios, historial de versiones                                     |
+| Modo de archivo local | Archivos de repositorio declarados por `agent-native.json` | Flujos de trabajo locales/de desarrollo, revisión de Git, ediciones del agente de codificación, contenido nativo de archivos |
+
+El UI y el agente actions deben mantener la misma forma en ambos modos. Un contenido
+el editor aún edita documentos; la diferencia es si esos documentos resuelven
+a filas SQL o archivos locales.
+
+```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}"
+}
+```
+
+## Repositorio de ejemplo
+
+Un espacio de trabajo de contenido puede ser tan pequeño como este:
+
+```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" }
+  ]
+}
+```
+
+En el modo de archivo local, la barra lateral de Contenido muestra `docs/`, `blog/` y
+`resources/` árboles como páginas. Al seleccionar `docs/getting-started.mdx` se abre eso
+archivo en el editor de contenido estándar; la edición en el UI escribe de nuevo en
+`docs/getting-started.mdx`.
+
+`components/` no es una raíz de contenido. Es una biblioteca de componentes de vista previa que MDX
+los archivos pueden importarse o hacer referencia. El editor puede renderizar componentes MDX locales simples
+sin necesidad de clonar o bifurcar toda la aplicación de contenido.
+
+`extensions/` tampoco es una raíz de contenido. Es una biblioteca de extensión local:
+pequeños widgets aislados que pueden renderizarse en espacios de aplicaciones mientras su fuente permanece en
+el repositorio.
+
+## Instalar contenido en un repositorio
+
+Para documentos, blogs o espacios de trabajo MDX existentes, instale los archivos locales de contenido
+habilidad:
+
+```bash
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+```
+
+Esto copia la habilidad `content` en las carpetas de habilidades del agente del repositorio y escribe
+o actualiza `agent-native.json` con los valores predeterminados de contenido:
+
+- `mode: "local-files"` a nivel del espacio de trabajo
+- `apps.content.mode: "local-files"`
+- raíces de contenido para `docs/`, `blog/`, `content/` y `resources/`
+- `components/` para componentes locales MDX
+- `extensions/` para widgets de extensión local
+
+La habilidad instalada indica a los agentes de codificación que utilicen Content actions
+(`list-documents`, `get-document`, `edit-document`, `update-document`,
+`share-local-file-document` y archivo de componente actions) cuando se trata de una aplicación de contenido local
+o Agent Native Desktop Bridge los expone. Si no hay ningún puente en funcionamiento, la habilidad
+recurre a ediciones directas seguras del repositorio mientras conserva el frontmatter, las importaciones, JSX,
+y desconocido MDX.
+
+## Configuración
+
+Agregue `agent-native.json` al repositorio o a la raíz del espacio de trabajo:
+
+```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"]
+    }
+  }
+}
+```
+
+También puedes habilitar archivos locales con `AGENT_NATIVE_MODE=local-files` o
+`AGENT_NATIVE_DATA_MODE=local-files`; se prefiere el manifiesto porque
+documenta el contrato de la carpeta en el propio repositorio.
+
+## Formato de archivo de contenido
+
+El contenido dice Markdown y MDX. Frontmatter contiene metadatos de la página y el cuerpo es
+el documento editable:
+
+```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.
+```
+
+El título proviene del frontmatter `title` cuando está presente; de lo contrario, del
+nombre de archivo. El editor conserva la fuente MDX que aún no puede editar visualmente, por lo que
+Los agentes de codificación y los editores de texto normales siguen siendo puertas de escape seguras.
+
+## Componentes MDX personalizados
+
+El contenido puede obtener una vista previa de los componentes locales desde la carpeta `components` configurada.
+Esto está destinado a componentes MDX de estilo documentos, como pestañas, llamadas y paquetes
+instale fragmentos o bloques de código específicos del marco.
+
+Por ejemplo, agregue un componente interactivo junto a su contenido:
+
+```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,
+  },
+};
+```
+
+Luego úselo desde cualquier archivo MDX local:
+
+```mdx
+---
+title: "Launch Notes"
+---
+
+# Launch Notes
+
+<ImpactCounter label="wins" />
+```
+
+El servidor de desarrollo de contenido descubre las exportaciones con nombre de PascalCase y el valor predeterminado de PascalCase
+exportaciones de archivos `.tsx`, `.jsx`, `.ts` y `.js` en `components/`. Esos
+Los componentes se procesan dentro del editor y aparecen en el menú diagonal debajo
+**Componentes locales**. La inserción de barra diagonal crea una etiqueta mínima como
+`<ImpactCounter />`; agregue accesorios en la fuente MDX cuando sea necesario.
+
+La ejecución de componentes es intencionalmente una capacidad de puente entre desarrollo local y escritorio, no
+acceso simple a la carpeta del navegador alojado. Si abres `content.agent-native.com`,
+elija **Archivos locales** y elija una carpeta en Chrome, la aplicación puede leer y escribir
+los archivos `.md` y `.mdx` a través del navegador File System Access API, pero
+Chrome no expone una ruta de carpeta absoluta para que Vite pueda compilar
+`components/*.tsx`. Para obtener una vista previa y recargar en caliente componentes React personalizados, ejecute
+Contenido local o use Agent Native Desktop para que el puente local confiable pueda
+registre el espacio de trabajo elegido con el servidor de desarrollo de contenido local. En ese modo,
+ediciones en archivos de componentes existentes, recarga en caliente a través de Vite y adición o
+Al eliminar los archivos de componentes se vuelve a cargar el registro de componentes y el menú diagonal.
+
+Los agentes también pueden trabajar con esos archivos de componentes registrados. Usar
+`list-local-component-files` para encontrar la identificación del espacio de trabajo registrado, luego
+`write-local-component-file` para crear o actualizar `.tsx`, `.jsx`, `.ts` o
+Archivos `.js` en la carpeta `components/` del espacio de trabajo. Los archivos MDX siguen siendo los
+fuente de verdad para el uso de componentes; los archivos componentes permanecen en el repositorio normal
+archivos fuente revisados con Git.
+
+Si un componente exporta metadatos de entrada, seleccione el componente en el editor
+muestra un botón de edición en la esquina superior derecha del componente. Tipos de entrada admitidos
+son `string`, `textarea`, `number`, `boolean` y `select`. El formulario escribe
+vuelve a la etiqueta MDX, por lo que los archivos locales siguen siendo la fuente de la verdad. El
+Los metadatos se pueden exportar como `ComponentNameInputs`, `ComponentNameConfig.inputs`,
+`Component.inputs` o `agentNative.inputs`.
+
+Las etiquetas de componentes simples con accesorios literales pueden obtener una vista previa en línea:
+
+```mdx
+<FrameworkTabs value="react" />
+
+<Callout type="warning">This setting affects production deploys.</Callout>
+```
+
+Las expresiones JSX complejas se conservan en el código fuente. Si el editor no puede hacerlo de forma segura
+obtenga una vista previa de la propiedad de un componente todavía, muestra un marcador de posición de advertencia en lugar de
+soltar datos silenciosamente.
+
+## Compartir archivos locales
+
+Los archivos locales no se comparten directamente porque otros usuarios no pueden leer una ruta
+tu máquina. El botón Compartir de la barra de herramientas Contenido crea o actualiza un
+copia respaldada por la base de datos del archivo seleccionado, navega hasta esa copia y abre el
+ventana emergente de compartir normal. El archivo local original permanece en Archivos locales; el
+La copia de la base de datos aparece en Copias compartidas en modo de archivo local y utiliza el
+modelo estándar para compartir documentos.
+
+## Extensiones locales
+
+El modo de archivo local también puede cargar extensiones respaldadas por repositorio desde el archivo configurado
+Carpeta `extensions`. Cada extensión es un directorio con un `extension.json`
+manifiesto y un archivo de entrada 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` es el mismo formato de cuerpo de extensión Alpine/Tailwind utilizado por normal
+extensiones respaldadas por bases de datos. Cuando la aplicación Contenido ve una extensión local que
+declara `content.sidebar.bottom`, representa esa extensión en la parte inferior de
+la barra lateral de Contenido. El anfitrión pasa `window.slotContext` con el seleccionado
+ID del documento, título, metadatos de origen y si el contenido está en modo de archivo local.
+
+La aplicación obtiene una vista previa de las extensiones locales, pero las edita como archivos. Las extensiones
+la lista los muestra con una insignia de Archivo local y el visor de página completa apunta a
+el archivo de entrada. Extensión respaldada por SQL actions, como actualizar, eliminar, compartir y
+el historial no se aplica; use su editor, Codex, código Claude o historial de Git para
+cambios de fuente.
+
+Para v1, las extensiones locales son intencionalmente conservadoras:
+
+- pueden usar `extensionData` para su propio estado de ejecución pequeño
+- solo pueden llamar a los `appAction` enumerados en `extension.json`
+- Los asistentes SQL sin formato y `extensionFetch` externos están deshabilitados
+- Los destinos de ranura se declaran en `extension.json`, no se instalan a través de SQL
+
+Esto proporciona a los espacios de trabajo locales una superficie de complemento similar a Obsidian sin permitir que
+El archivo de repositorio arbitrario hereda todas las capacidades de una extensión respaldada por una base de datos.
+
+## Cómo lo usan las aplicaciones
+
+El modo de archivo local se implementa a través de los asistentes de artefactos locales del marco.
+Una aplicación declara raíces para los tipos de artefactos que posee, luego lee y escribe
+a través de la misma superficie de acción que su UI y su agente ya utilizan.
+
+Para Contenido, eso significa:
+
+- `list-documents` enumera los archivos `.md` y `.mdx` configurados.
+- `get-document` lee un archivo local seleccionado.
+- `update-document` escribe el archivo local seleccionado.
+- `create-document` crea un nuevo archivo `.mdx` local en la carpeta seleccionada.
+- `delete-document` elimina el archivo local.
+- La búsqueda se ejecuta en los archivos locales configurados.
+
+Mover, renombrar y reordenar páginas de archivos locales desde Content UI no lo es
+aún es compatible. Realice esas operaciones en el espacio de trabajo o con un agente de codificación; el
+La barra lateral de contenido reflejará el árbol de archivos resultante.
+
+Esto simplifica el contrato del agente: el agente puede seguir usando Content actions,
+y esos actions deciden si el objetivo está respaldado por SQL o por archivos.
+
+Otras aplicaciones pueden adoptar el mismo patrón con el tiempo. Una aplicación de Presentaciones puede mapear
+`slides/*.mdx` a cubiertas, una aplicación de Planes puede asignar `plans/*` a documentos de planos y
+La aplicación Paneles puede asignar `dashboards/*.mdx` a paneles. Aquellos específicos de la aplicación
+Las carpetas son convenciones superpuestas al mismo contrato de artefacto local.
+
+## Archivos locales frente a exportación/importación
+
+El contenido tiene dos flujos de trabajo de archivos diferentes:
+
+| Flujo de trabajo                       | Qué pasa                                                                                                                                                                                    |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Exportación/importación `/local-files` | El modo de base de datos sigue siendo la fuente de la verdad. Los archivos son una superficie de sincronización explícita que puedes exportar, editar, obtener una vista previa e importar. |
+| Modo de archivo local                  | Los archivos son la fuente de la verdad. La barra lateral de contenido y el editor funcionan directamente en archivos locales.                                                              |
+
+Utilice exportar/importar cuando desee revisar archivos ocasionalmente en un espacio de trabajo alojado.
+Utilice el modo de archivo local cuando el repositorio en sí sea el espacio de trabajo.
+
+## Historia y colaboración
+
+El modo de archivo local se basa en el historial nativo del archivo:
+
+- realizar cambios importantes en Git
+- usar solicitudes de extracción para revisión
+- permitir que los agentes de codificación editen los mismos archivos directamente
+- use diferencias de archivos normales para comprender los cambios
+
+El modo de base de datos sigue siendo el más adecuado para funciones de colaboración alojadas como
+Compartir, comentarios, historial de versiones respaldado por SQL y edición multiusuario en vivo.
+
+La sincronización del proveedor se puede superponer a cualquier modo. Por ejemplo, un repositorio de documentos puede
+Agregue actions que extraiga contenido de un CMS a archivos MDX locales o envíe los seleccionados
+archivos locales de regreso a ese CMS.
+
+## Seguridad en la producción
+
+El modo de archivo local le da a la aplicación actions acceso directo de escritura al espacio de trabajo configurado
+archivos. Esto es apropiado para el desarrollo local y un archivo de inquilino único confiable
+puentes, pero no es el modelo de seguridad de producción predeterminado.
+
+Cuando `NODE_ENV=production`, el marco rechaza el modo `local-files` a menos que usted
+conjunto:
+
+```bash
+AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION=true
+```
+
+Establezca esto solo para una implementación confiable de un solo inquilino donde todos los que puedan usarlo
+la aplicación puede leer y escribir los archivos configurados. Para alojamiento normal,
+aplicaciones multiusuario, uso del modo de base de datos y uso compartido respaldado por SQL.

package/docs/content/locales/es-ES/mcp-apps.md

@@ -0,0 +1,147 @@
+---
+title: "Aplicaciones MCP"
+description: "Cree e incruste aplicaciones MCP interactivas UI dentro de Claude, ChatGPT y otros hosts compatibles, utilizando rutas de aplicaciones reales, el puente de inserción y el puente de host API."
+---
+
+# Aplicaciones MCP
+
+**Esta página: UI en línea en Claude/ChatGPT.** Creación de recursos de la aplicación MCP y el puente de inserción que representa una ruta de aplicación real dentro del chat de un host compatible. Esta página también es el hogar único de la **matriz de soporte al cliente** ([below](#client-support)).
+
+| Si quieres…                                                                                        | Leer                                     |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Conecta un agente/host externo a tu aplicación                                                     | [External Agents](/docs/external-agents) |
+| Dale a tu agente más herramientas (consume otros servidores MCP)                                   | [MCP Clients](/docs/mcp-clients)         |
+| Crea UI en línea que se rendericen en Claude/ChatGPT                                               | **Esta página** — Aplicaciones MCP       |
+| Referencia del servidor MCP de nivel inferior (autenticación, herramientas, montaje personalizado) | [MCP Protocol](/docs/mcp-protocol)       |
+
+Las aplicaciones MCP son la extensión oficial `io.modelcontextprotocol/ui` que permite a los hosts compatibles (Claude, Claude Desktop, ChatGPT, VS Code GitHub Copilot, Goose, Postman, MCPJam y Cursor) representar UI interactivos en línea en el chat. En las aplicaciones nativas del agente, cada aplicación MCP es una **ruta React real**, no un widget simple-HTML independiente.
+
+Dentro del chat de una aplicación Agent-Native, prefiera [native chat renderers](/docs/native-chat-ui) para widgets propios como tablas, gráficos, resultados escritos y posibilidades de aprobación. Utilice aplicaciones MCP para UI en línea externo/entre hosts en Claude, ChatGPT, Copilot, Cursor y otros hosts compatibles, con la acción `link` como respaldo de enlace profundo universal.
+
+## Autoría: aplicaciones MCP opcionales UI {#mcp-apps}
+
+Para los hosts que admiten la extensión de aplicaciones MCP, una acción también puede anunciar un recurso UI en línea con `mcpApp`. Esta es una mejora progresiva para los flujos en los que el agente externo debe entregar al usuario una superficie interactiva en lugar de solo texto, por ejemplo, revisar un borrador de correo electrónico, editar una invitación de calendario o elegir entre variantes del panel generado.
+
+Utilice la aplicación React real con `embedRoute()` o `embedApp()` siempre que el usuario necesite UI. El modelo mental es simple: el objetivo `link` de la acción es también el objetivo de inserción de la aplicación MCP. Exponga la operación como una acción/herramienta normal, devuelva un vínculo profundo enfocado con `link` y agregue `mcpApp.resource = embedApp(...)` para que los hosts capaces carguen esa misma ruta en línea en lugar de abrir una nueva pestaña. Cuando ambos deben crearse a partir de la misma ruta, prefiera `embedRoute({ title, openLabel, path })`: es el contenedor conveniente que devuelve los campos `link` y `mcpApp` coincidentes de una sola llamada, mientras que `embedApp(...)` es el recurso de nivel inferior que asigna directamente a `mcpApp.resource`.
+
+Eso significa que las inserciones de aplicaciones completas pueden hacer cualquier cosa que la ruta pueda hacer una vez abierta: revisar o editar un borrador de correo electrónico, mostrar una bandeja de entrada/búsqueda filtrada, abrir un evento de calendario o un borrador de evento, cargar una página de extensión, inspeccionar un panel de análisis completo o un análisis guardado, continuar una presentación en el editor de Presentaciones o abrir un proyecto/editor de diseño. Prefiere URL/parámetros de enlace profundo y el puente de estado de aplicación/navegación `/_agent-native/open` existente en lugar de inventar un segundo protocolo de estado para aplicaciones MCP.
+
+En raras ocasiones, el objetivo correcto es una ruta de aplicación enfocada que representa un componente React compartido en lugar de todo el shell de la aplicación. La ruta `/chart` de Analytics es el modelo: toma una carga útil compacta `SqlPanel` en el URL y representa el mismo componente de gráfico que utiliza el panel. Esta sigue siendo una aplicación integrada, no una simple aplicación HTML MCP. Expóngalo o llámelo mediante una acción normal / `open_app({ path, embed: true })`, mantenga el URL determinista y deje que `embedApp()` represente esa ruta en línea.
+
+No escriba a mano aplicaciones únicas HTML MCP para el producto UI; si la acción necesita una superficie personalizada, agregue o reutilice primero una ruta/componente de aplicación real e incruste esa ruta.
+
+```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." }
+  ]
+}
+```
+
+El servidor MCP anuncia la extensión `io.modelcontextprotocol/ui`, agrega `_meta.ui.resourceUri` más `_meta["ui/resourceUri"]` a `tools/list` y también emite metadatos de compatibilidad de aplicaciones ChatGPT SDK (`openai/outputTemplate`, widget CSP/descripción/accesibilidad). Expone desde HTML hasta `resources/list`, `resources/templates/list` y `resources/read` usando MIME `text/html;profile=mcp-app`. El proxy stdio reenvía esos controladores de recursos desde la aplicación en vivo, por lo que los clientes de escritorio y CLI ven los mismos recursos que los clientes HTTP.
+
+Mantenga el constructor `link` existente incluso cuando agregue `mcpApp`. Los clientes exclusivos de CLI, los hosts más antiguos y cualquier host que no represente aplicaciones MCP ignorarán los metadatos de UI y seguirán necesitando el enlace `"Open in … →"`. `embedApp()` utiliza ese enlace como objetivo de lanzamiento, llama al asistente `create_embed_session` exclusivo de la aplicación, intercambia un ticket único de SQL en `/_agent-native/embed/start` y navega por el marco de la aplicación MCP hasta la ruta de destino con una sesión de navegador de corta duración más un respaldo de portador para recuperaciones del mismo origen. `open_app({ app, path, embed: true })` es la trampilla de escape genérica para rutas como paneles completos, bandejas de entrada filtradas, vistas de borradores de calendario, análisis y páginas de extensión, y debe usarse libremente cuando la aplicación completa es la superficie de revisión/edición más clara.
+
+`embedApp()` incluye el origen de la solicitud MCP en el recurso CSP para que el iniciador pueda recuperar y, cuando se solicite explícitamente, encuadrar la ruta de la aplicación propia firmada. Dispatch agrega los orígenes exactos de las aplicaciones otorgadas a su recurso `open_app`, de modo que un único conector de Dispatch puede integrar correo, calendario, diapositivas y el resto sin permitir todos los orígenes HTTPS. Pase solo marcos adicionales o dominios de recursos para una aplicación MCP personalizada que realmente incorpore un reproductor de terceros o cargue recursos de terceros.
+
+Dentro de esas rutas `embedApp()`, `sendToAgentChat()` admite integración. Las indicaciones enviadas automáticamente se transmiten al host MCP como `ui/update-model-context` más `ui/message`, por lo que un botón en la aplicación integrada puede continuar intencionalmente la conversación Claude/ChatGPT desde el estado de la aplicación seleccionada. El contexto oculto se envía como contexto modelo; el giro visible del usuario sigue siendo solo el mensaje de la aplicación, lo que evita el aterrador consentimiento del host en torno a las rutas internas de los archivos de estado de la aplicación. `submit: false` mantiene el comportamiento de precompletación/revisión local.
+
+## Puente de aplicación MCP de primera clase {#mcp-app-bridge}
+
+MCP Las inserciones de aplicaciones son inserciones de ruta, no miniproductos separados. `embedApp()` comienza desde el objetivo `link` de la acción, crea una sesión de inserción de corta duración e inicia esa ruta de aplicación firmada. Los hosts de aplicaciones MCP estándar pueden navegar por el marco de la aplicación MCP cuando el host puede hidratar la ruta directamente.
+
+```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 utiliza una ruta de trasplante de un solo fotograma: el documento de recursos recupera la aplicación firmada HTML y la hidrata dentro del iframe de la aplicación MCP de Claude porque Claude no permite de manera confiable iframes secundarios propiedad de la aplicación ni navegación por marcos externos. La web ChatGPT obtiene un iframe de ruta controlada porque su puente de aplicaciones nos brinda hosts `window.openai` estables API y control de altura limitado. Todas las rutas apuntan a la misma ruta de la aplicación firmada y representan la ruta normal y los componentes React. Diseñe rutas integradas para que una recarga con el mismo URL firmado reconstruya la misma vista.
+
+Para la misma aplicación `open_app({ embed: true })`, el marco crea el ticket de inicio de inserción durante la llamada de la herramienta original y almacena el URL de inicio firmado en metadatos ocultos de la herramienta. El actions personalizado puede devolver `embedStartUrl` por la misma ruta rápida; la capa MCP elimina el URL con boleto del `structuredContent` visible en el modelo y de los metadatos normales de enlace abierto. Cuando no hay ningún inicio de inserción URL presente, el recurso recurre al asistente `create_embed_session` exclusivo de la aplicación. Esto mantiene los hosts de producción que restringen las llamadas a herramientas iniciadas por iframe en la ruta directa sin filtrar sesiones únicas de aplicaciones URL en la transcripción. Si un usuario vuelve a abrir un chat antiguo después de que haya expirado un ticket de inicio único, la ruta de inicio devuelve una pequeña página de actualización y publica `agentNative.embedSessionExpired` en el contenedor; `embedApp()` borra el inicio obsoleto URL y genera un ticket nuevo a través de `create_embed_session` cuando todavía tiene la ruta de la aplicación original.
+
+ChatGPT obtiene una ruta de compatibilidad dedicada a través de `window.openai`: el documento de lanzamiento lee `toolInput`, `toolOutput` y `toolResponseMetadata` directamente, luego llama a `create_embed_session` a través de `window.openai.callTool(...)`. Los hosts de aplicaciones MCP estándar utilizan el puente `ui/*` JSON-RPC. Las rutas directamente hidratadas pueden llamar a `ui/update-model-context`, `ui/message`, `ui/open-link` y `ui/request-display-mode` a través de los asistentes del puente del host. La ruta trasplantada de Claude utiliza el mismo puente huésped directo de `ui/*` después de la hidratación. Cuando se utiliza la ruta ChatGPT o iframe de diagnóstico explícito, el contenedor transmite el mismo host actions a través de solicitudes postMessage `agentNative.mcpHost.*`. Mantenga la forma del resultado idéntica para ambas rutas: devuelva un `link` enfocado y contenido estructurado conciso.
+
+No configure el estándar `_meta.ui.domain` en una aplicación URL. MCP Apps trata ese campo como específico del host: Claude valida dominios sandbox estilo `{hash}.claudemcpcontent.com`, mientras que ChatGPT usa sus propios metadatos `openai/widgetDomain`. Omita `ui.domain` a menos que esté emitiendo deliberadamente un valor específico del host; el anfitrión elegirá un origen de zona de pruebas predeterminado.
+
+Las páginas de extensión mantienen su zona de pruebas en los chats incrustados de MCP sin tener que navegar por un segundo iframe de ruta. El uso normal de la aplicación genera `/_agent-native/extensions/:id/render` como un iframe secundario en espacio aislado. En el modo puente de chat MCP, el marco representa el mismo documento de extensión que el `srcDoc` en el espacio aislado dentro del iframe de ruta, evitando fallas del host `frame-ancestors` / `X-Frame-Options` y preservando al mismo tiempo `sandbox="allow-scripts allow-forms"`.
+
+El shell de recursos posee el tamaño del host externo. `embedApp({ height })` tiene como valor predeterminado `560px`, fija el shell en `320-900px` y reserva `44px` para la barra de herramientas pequeña, por lo que la ventana gráfica de ruta es `height - 44px`. Mantenga las rutas de aplicaciones integradas desplazables internamente y permita que el iniciador informe esa altura intrínseca limitada en lugar de la altura completa del documento; de lo contrario, el cambio de tamaño automático del host puede convertir una página de aplicación normal en un artefacto de chat muy alto. Un shell modificado solo afecta los nuevos recursos de la aplicación MCP y las nuevas llamadas a herramientas. Los marcos de conversación antiguos ChatGPT/Claude pueden mantener el comportamiento anterior de los recursos, así que verifique el tamaño con una renderización en línea nueva antes de juzgar una solución.
+
+### Modos de inserción {#embed-modes}
+
+Claude utiliza la ruta de trasplante de fotograma único de forma predeterminada. También puede forzarlo en otros hosts con `embedMode: "transplant"` o `frame: "transplant"` al depurar el comportamiento de carga del módulo del host. Puede forzar el iframe de diagnóstico anidado con `embedMode: "iframe"`, `renderMode: "iframe"`, `nested: true` o `frame: "iframe"`. Si el iframe está bloqueado, `embedApp()` lo reemplaza con una alternativa de aplicación abierta: el usuario puede volver a intentarlo en línea, abrir una sesión de inserción recién creada a través del host o usar la ruta visible URL. Mantén útil el objetivo `link` de la acción por sí solo porque sigue siendo la trampilla de escape universal.
+
+Al probar Claude a través de ngrok, utilice una compilación de producción (`npx @agent-native/core@latest build` y luego `npx @agent-native/core@latest start`) o una vista previa/producción implementada de URL. La ruta de trasplante de fotograma único de Claude funciona con fragmentos de activos de producción; Los módulos de desarrollo Vite sin formato, como `/app/root.tsx`, pueden protegerse mediante la autenticación de la aplicación y fallar en las importaciones dinámicas desde el origen del recurso Claude.
+
+## Puente de host API {#host-bridge}
+
+El puente del host es deliberadamente pequeño:
+
+| Modo                  | Tipo de mensaje                       | Úsalo para                                                           |
+| --------------------- | ------------------------------------- | -------------------------------------------------------------------- |
+| ruta de host directa  | `ui/update-model-context`             | Contexto oculto para el modelo anfitrión                             |
+| ruta de host directa  | `ui/message`                          | Publicar un cambio de usuario visible como anfitrión                 |
+| ruta de host directa  | `ui/open-link`                        | Abra una aplicación o URL externo a través del host                  |
+| ruta de host directa  | `ui/request-display-mode`             | Solicitar `inline`, `fullscreen` o `pip`                             |
+| Trasplante Claude     | `ui/*`                                | Mismo puente huésped directo después de la hidratación               |
+| ChatGPT / ruta iframe | `agentNative.mcpHostContext`          | Tema, configuración regional, plataforma de alojamiento, dimensiones |
+| ChatGPT / ruta iframe | `agentNative.embeddedAppReady`        | Confirmar la ruta iframe cargada                                     |
+| ChatGPT / ruta iframe | `agentNative.mcpHost.*` / `.response` | Retransmisión de contenedor para solicitudes de host                 |
+
+Las rutas integradas pueden usar `updateMcpAppModelContext()`, `openMcpAppHostLink()`, `requestMcpAppDisplayMode()`, `getMcpAppHostContext()` y `useMcpAppHostContext()` de `@agent-native/core/client`. `sendToAgentChat()` utiliza la misma ruta desde las inserciones de la aplicación completa para los mensajes enviados automáticamente.
+
+El modo de visualización es el mejor esfuerzo. El `McpAppRenderer` en la aplicación actualmente informa un contexto de alojamiento web en línea y un modo de visualización solo en línea; Los hosts externos pueden aceptar solicitudes de visualización más grandes, ignorarlas o responder con un error de modo no compatible. Mantenga siempre utilizable la ruta en línea.
+
+## Soporte al cliente y almacenamiento en caché {#client-support}
+
+La lista oficial actual de clientes de aplicaciones MCP incluye Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT y Cursor; El soporte del host aún varía según el plan, el canal de lanzamiento y la versión del cliente, así que consulte [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix). Las aplicaciones ChatGPT personalizadas MCP están disponibles a través del modo desarrollador para espacios de trabajo Business y Enterprise/Edu en la web ChatGPT; consulte las notas [developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-apps-in-chatgpt-beta) de OpenAI.
+
+Claude Code, Codex y otros clientes CLI/editor de código siguen recibiendo los mismos recursos y metadatos cuando admiten aplicaciones MCP, pero los tratan como hosts de enlace a menos que haya verificado la representación de iframe en línea en esa superficie exacta. El enlace profundo sigue siendo el recurso confiable cuando un host decide no representar un iframe. En la práctica, cada aplicación nativa del agente debe crearse con ambas: aplicaciones MCP para revisión/edición en línea en hosts compatibles y `link` para un retorno universal a la aplicación completa.
+
+Claude y ChatGPT pueden almacenar en caché metadatos de herramientas y recursos para un conector personalizado existente. Después de cambiar los metadatos de la aplicación MCP, verifique con una nueva llamada a la herramienta; Si el host todavía usa el descriptor anterior, vuelva a conectar el conector Claude o vuelva a escanear/revisar el conector ChatGPT para que actualice el catálogo. Si Claude registra una advertencia sobre `_meta.ui.csp` o `_meta.ui.permissions` viviendo en el descriptor de la herramienta después de una implementación, ese conector está usando metadatos obsoletos: elimine/vuelva a conectar el conector Claude e inicie una nueva conversación.
+
+## Pruebas {#testing}
+
+Pruebe las aplicaciones MCP con los accesorios livianos alrededor de `embedApp()` y `McpAppRenderer`; cubren CSP, contexto del host, inicio de aplicaciones y comportamiento de mensajes puente sin necesidad de un host externo real. Al validar la web ChatGPT o Claude, active una nueva llamada a la herramienta después de los cambios de shell y mida el iframe visible. Es posible que los fotogramas renderizados previamente en la misma conversación aún muestren la altura almacenada en caché o el comportamiento de inicio.
+
+## Relacionado {#related}
+
+- [External Agents](/docs/external-agents): conexión de Claude, ChatGPT, Codex y Cursor a aplicaciones alojadas; Matriz de compatibilidad de aplicaciones MCP; niveles de catálogo; enlaces profundos.
+- [MCP Protocol](/docs/mcp-protocol): el servidor MCP, autenticación, herramientas y `ask-agent` montados automáticamente.
+- [Actions](/docs/actions) — `defineAction`, el constructor de `link`, `publicAgent`.
+
+```
+
+```