@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/local-file-mode.md

@@ -0,0 +1,433 @@
+---
+title: "Mode fichier local"
+description: "Exécutez des applications natives d'agent avec Markdown, MDX et d'autres fichiers de dépôt locaux comme source de vérité, y compris des documents MDX de style Obsidian avec des composants personnalisés."
+---
+
+# Mode fichier local
+
+Le mode Fichier local permet à une application native d'agent d'attacher son UI et sa surface d'action normales
+directement vers les fichiers d'un dépôt ou d'un espace de travail. L'application ressemble toujours à une application hébergée
+produit, mais ses vues de liste, son éditeur et ses outils d'agent lisent et écrivent des fichiers locaux
+au lieu des enregistrements d'application basés sur SQL.
+
+La première implémentation se trouve dans le modèle de contenu : la barre latérale gauche est
+rempli à partir des fichiers `.md` et `.mdx` locaux, la sélection d'une page ouvre la norme
+Éditeur de contenu et enregistrement des écritures dans le fichier sélectionné. Les mêmes fichiers peuvent
+être également modifié par Codex, Claude Code, l'agent de la barre latérale Agent-Native ou un utilisateur normal
+éditeur.
+
+Pour le contenu, cela donne au produit l'impression d'être Obsidian open source pour MDX :
+vos documents vivent sous forme de fichiers, tandis que l'application ajoute un éditeur visuel, l'agent actions,
+copies partageables et riches composants interactifs MDX.
+
+Utilisez le mode fichier local lorsque vous souhaitez un workflow axé sur le dépôt :
+
+- un dépôt de documents avec `docs/*.mdx`
+- un blog avec `blog/*.mdx`
+- ressources telles que le positionnement, la messagerie ou les notes d'équipe dans `resources/*.md`
+- une base de connaissances personnelle de style Obsidian avec un éditeur MDX plus riche
+- documents nécessitant des blocs MDX personnalisés interactifs générés à partir du code React local
+- Artefacts d'application qui devraient être faciles à inspecter et à corriger pour les agents de codage
+
+Utilisez le mode base de données lorsque vous souhaitez bénéficier de l'expérience d'une application collaborative hébergée :
+partage multi-utilisateurs, autorisations basées sur SQL, commentaires, historique des versions et
+hébergement de production sans accès au système de fichiers local.
+
+## Le modèle mental
+
+Il existe deux modes de source de vérité :
+
+| Mode                 | Source de vérité                               | Idéal pour                                                                                                       |
+| -------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Mode base de données | Lignes SQL jusqu'à Drizzle                     | Applications hébergées, collaboration, partage, commentaires, historique des versions                            |
+| Mode fichier local   | Fichiers Repo déclarés par `agent-native.json` | Workflows locaux/de développement, révision de Git, modifications de l'agent de codage, contenu natif du fichier |
+
+Le UI et l'agent actions doivent conserver la même forme dans les deux modes. Un contenu
+l'éditeur édite toujours les documents ; la différence est de savoir si ces documents résolvent
+vers des lignes SQL ou des fichiers locaux.
+
+```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}"
+}
+```
+
+## Exemple de dépôt
+
+Un espace de travail de contenu peut être aussi petit que ceci :
+
+```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 mode fichier local, la barre latérale Contenu affiche les `docs/`, `blog/` et
+Arborescences `resources/` sous forme de pages. La sélection de `docs/getting-started.mdx` ouvre cela
+fichier dans l'éditeur de contenu standard ; l'édition dans le UI réécrit dans
+`docs/getting-started.mdx`.
+
+`components/` n'est pas une racine de contenu. Il s'agit d'une bibliothèque de composants en avant-première que MDX
+les fichiers peuvent être importés ou référencés. L'éditeur peut restituer des composants MDX locaux simples
+sans que vous ayez à cloner ou à dupliquer l'intégralité de l'application de contenu.
+
+`extensions/` n'est pas non plus une racine de contenu. Il s'agit d'une bibliothèque d'extensions locale :
+petits widgets en bac à sable qui peuvent s'afficher dans les emplacements d'application tandis que leur source reste dans
+le dépôt.
+
+## Installer le contenu dans un dépôt
+
+Pour un espace de travail de documents, de blog ou MDX existant, installez les fichiers locaux de contenu
+compétence :
+
+```bash
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+```
+
+Cela copie la compétence `content` dans les dossiers de compétences d'agent du dépôt et écrit
+ou met à jour `agent-native.json` avec les valeurs par défaut du contenu :
+
+- `mode: "local-files"` au niveau de l'espace de travail
+- `apps.content.mode: "local-files"`
+- racines de contenu pour `docs/`, `blog/`, `content/` et `resources/`
+- `components/` pour les composants locaux MDX
+- `extensions/` pour les widgets d'extension locale
+
+La compétence installée indique aux agents de codage d'utiliser le contenu actions
+(`list-documents`, `get-document`, `edit-document`, `update-document`,
+`share-local-file-document` et fichier de composant actions) lorsqu'une application de contenu locale
+ou le pont Agent Native Desktop les expose. Si aucun pont ne fonctionne, la compétence
+revient à des modifications de dépôt directes sécurisées tout en préservant le contenu, les importations, JSX,
+et MDX inconnu.
+
+## Configuration
+
+Ajoutez `agent-native.json` à la racine du dépôt ou de l'espace de travail :
+
+```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"]
+    }
+  }
+}
+```
+
+Vous pouvez également activer les fichiers locaux avec `AGENT_NATIVE_MODE=local-files` ou
+`AGENT_NATIVE_DATA_MODE=local-files` ; le manifeste est préféré car il
+documente le contrat de dossier dans le dépôt lui-même.
+
+## Format de fichier de contenu
+
+Le contenu lit Markdown et MDX. Frontmatter contient les métadonnées de la page et le corps est
+le document modifiable :
+
+```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.
+```
+
+Le titre vient du frontmatter `title` lorsqu'il est présent, sinon du
+nom de fichier. L'éditeur conserve la source MDX qu'il ne peut pas encore modifier visuellement, donc
+Les agents de codage et les éditeurs de texte normaux restent des issues de secours sûres.
+
+## Composants MDX personnalisés
+
+Le contenu peut prévisualiser les composants locaux du dossier `components` configuré.
+Ceci est destiné aux composants MDX de style document tels que les onglets, les légendes, le package
+installez des extraits ou des blocs de code spécifiques au framework.
+
+Par exemple, ajoutez un composant interactif à côté de votre contenu :
+
+```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,
+  },
+};
+```
+
+Utilisez-le ensuite à partir de n'importe quel fichier MDX local :
+
+```mdx
+---
+title: "Launch Notes"
+---
+
+# Launch Notes
+
+<ImpactCounter label="wins" />
+```
+
+Le serveur de développement de contenu découvre les exportations nommées PascalCase et PascalCase par défaut
+exporte à partir de fichiers `.tsx`, `.jsx`, `.ts` et `.js` sous `components/`. Ceux
+les composants s'affichent dans l'éditeur et apparaissent dans le menu barre oblique sous
+**Composants locaux**. L'insertion d'une barre oblique crée une balise minimale telle que
+`<ImpactCounter />` ; ajoutez des accessoires dans la source MDX si nécessaire.
+
+L'exécution des composants est intentionnellement une fonctionnalité de pont de développement local/de bureau, et non
+accès simple au dossier du navigateur hébergé. Si vous ouvrez `content.agent-native.com`,
+choisissez **Fichiers locaux** et choisissez un dossier dans Chrome, l'application peut lire et écrire
+les fichiers `.md` et `.mdx` via le système de fichiers du navigateur Accédez à API, mais
+Chrome n'expose pas de chemin de dossier absolu à compiler par Vite
+`components/*.tsx`. Pour prévisualiser et recharger à chaud les composants React personnalisés, exécutez
+Contenu localement ou utilisez Agent Native Desktop pour que le pont local de confiance puisse
+enregistrez l'espace de travail sélectionné auprès du serveur de développement de contenu local. Dans ce mode,
+modifications des fichiers de composants existants, rechargement à chaud via Vite et ajout de ou
+la suppression des fichiers de composants recharge le registre des composants et le menu barre oblique.
+
+Les agents peuvent également travailler avec ces fichiers de composants enregistrés. Utiliser
+`list-local-component-files` pour trouver l'identifiant de l'espace de travail enregistré, puis
+`write-local-component-file` pour créer ou mettre à jour `.tsx`, `.jsx`, `.ts` ou
+Fichiers `.js` dans le dossier `components/` de l'espace de travail. Les fichiers MDX restent les
+source de vérité pour l'utilisation des composants ; les fichiers de composants restent un dépôt normal
+fichiers sources examinés avec Git.
+
+Si un composant exporte des métadonnées d'entrée, sélection du composant dans l'éditeur
+affiche un bouton d'édition dans le coin supérieur droit du composant. Types d'entrée pris en charge
+sont `string`, `textarea`, `number`, `boolean` et `select`. Le formulaire écrit
+revient à la balise MDX, les fichiers locaux restent donc la source de vérité. Le
+les métadonnées peuvent être exportées au format `ComponentNameInputs`, `ComponentNameConfig.inputs`,
+`Component.inputs` ou `agentNative.inputs`.
+
+Les balises de composants simples avec des accessoires littéraux peuvent être prévisualisées en ligne :
+
+```mdx
+<FrameworkTabs value="react" />
+
+<Callout type="warning">This setting affects production deploys.</Callout>
+```
+
+Les expressions complexes JSX sont conservées dans la source. Si l'éditeur ne peut pas en toute sécurité
+prévisualisez encore un accessoire de composant, il affiche un espace réservé d'avertissement plutôt que
+supprimer silencieusement des données.
+
+## Partage de fichiers locaux
+
+Les fichiers locaux ne sont pas partagés directement car les autres utilisateurs ne peuvent pas lire de chemin
+votre machine. Le bouton Partager de la barre d'outils Contenu crée ou actualise un
+copie sauvegardée dans la base de données du fichier sélectionné, accède à cette copie et ouvre le
+popover de partage normal. Le fichier local d'origine reste sous Fichiers locaux ; le
+la copie de la base de données apparaît sous Copies partagées en mode fichier local et utilise le
+modèle standard de partage de documents.
+
+## Extensions locales
+
+Le mode fichier local peut également charger des extensions sauvegardées en dépôt à partir du fichier configuré
+Dossier `extensions`. Chaque extension est un répertoire avec un `extension.json`
+manifeste et un fichier d'entrée 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` est le même format de corps d'extension Alpine/Tailwind utilisé par la normale
+extensions basées sur une base de données. Lorsque l'application de contenu détecte une extension locale qui
+déclare `content.sidebar.bottom`, il affiche cette extension en bas de
+la barre latérale Contenu. L'hôte transmet `window.slotContext` avec le
+ID du document, titre, métadonnées sources et si le contenu est en mode fichier local.
+
+Les extensions locales sont prévisualisées par l'application mais modifiées sous forme de fichiers. Les extensions
+la liste les affiche avec un badge de fichier local et la visionneuse pleine page renvoie à
+le fichier d'entrée. Extension actions basée sur SQL, telle que la mise à jour, la suppression, le partage et
+l'historique ne s'applique pas ; utilisez votre éditeur, le code Codex, le code Claude ou l'historique Git pour
+modifications de la source.
+
+Pour la version v1, les extensions locales sont intentionnellement conservatrices :
+
+- ils peuvent utiliser `extensionData` pour leur propre petit état d'exécution
+- ils ne peuvent appeler que les `appAction` répertoriés dans `extension.json`
+- Les assistants SQL bruts et les `extensionFetch` externes sont désactivés
+- les emplacements cibles sont déclarés dans `extension.json`, non installés via SQL
+
+Cela donne aux espaces de travail locaux une surface de plugin de type Obsidian sans laisser passer
+un fichier de dépôt arbitraire hérite de toutes les fonctionnalités d'une extension basée sur une base de données.
+
+## Comment les applications l'utilisent
+
+Le mode fichier local est implémenté via les assistants d'artefacts locaux du framework.
+Une application déclare les racines des types d'artefacts qu'elle possède, puis lit et écrit
+via la même surface d'action, son UI et son agent l'utilisent déjà.
+
+Pour le contenu, cela signifie :
+
+- `list-documents` répertorie les fichiers `.md` et `.mdx` configurés.
+- `get-document` lit un fichier local sélectionné.
+- `update-document` écrit le fichier local sélectionné.
+- `create-document` crée un nouveau fichier `.mdx` local dans le dossier sélectionné.
+- `delete-document` supprime le fichier local.
+- la recherche s'exécute sur les fichiers locaux configurés.
+
+Le déplacement, le renommage et la réorganisation des pages de fichiers locaux à partir du contenu UI ne sont pas autorisés
+pas encore pris en charge. Effectuer ces opérations dans l'espace de travail ou avec un agent de codage ; le
+La barre latérale de contenu reflétera l'arborescence de fichiers résultante.
+
+Le contrat de l'agent reste ainsi simple : l'agent peut continuer à utiliser Content actions,
+et ces actions décident si la cible est sauvegardée sur SQL ou sur fichier.
+
+D'autres applications peuvent adopter le même modèle au fil du temps. Une application Slides peut cartographier
+`slides/*.mdx` aux decks, une application Plans peut mapper `plans/*` aux documents de plan, et
+L'application Dashboards peut mapper `dashboards/*.mdx` aux tableaux de bord. Ceux spécifiques à l'application
+les dossiers sont des conventions superposées au même contrat d'artefact local.
+
+## Fichiers locaux vs exportation/importation
+
+Le contenu comporte deux flux de travail de fichiers différents :
+
+| Flux de travail                   | Que se passe-t-il                                                                                                                                                            |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Export/importation `/local-files` | Le mode base de données reste la source de vérité. Les fichiers constituent une surface de synchronisation explicite que vous exportez, modifiez, prévisualisez et importez. |
+| Mode fichier local                | Les fichiers sont la source de la vérité. La barre latérale de contenu et l'éditeur fonctionnent directement sur les fichiers locaux.                                        |
+
+Utilisez l'exportation/importation lorsque vous souhaitez examiner occasionnellement des fichiers dans un espace de travail hébergé.
+Utilisez le mode fichier local lorsque le dépôt lui-même est l'espace de travail.
+
+## Historique et collaboration
+
+Le mode fichier local s'appuie sur l'historique natif des fichiers :
+
+- valider les modifications importantes dans Git
+- utiliser les demandes d'extraction pour examen
+- laisser les agents de codage modifier directement les mêmes fichiers
+- utiliser les différences de fichiers normales pour comprendre les changements
+
+Le mode base de données reste le meilleur choix pour les fonctionnalités de collaboration hébergées telles que
+partage, commentaires, historique des versions soutenu par SQL et édition multi-utilisateurs en direct.
+
+La synchronisation du fournisseur peut être superposée à l'un ou l'autre mode. Par exemple, un dépôt de documents peut
+ajouter des actions qui extraient le contenu d'un CMS vers des fichiers MDX locaux ou poussent la sélection
+fichiers locaux vers ce CMS.
+
+## Sécurité de la production
+
+Le mode fichier local donne à l'application actions un accès direct en écriture à l'espace de travail configuré
+fichiers. Cela est approprié pour le développement local et les fichiers à locataire unique de confiance
+des ponts, mais ce n'est pas le modèle de sécurité de production par défaut.
+
+Lorsque `NODE_ENV=production`, le framework refuse le mode `local-files` sauf si vous
+définir :
+
+```bash
+AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION=true
+```
+
+Définissez cela uniquement pour un déploiement fiable à locataire unique où tous ceux qui peuvent l'utiliser
+l'application est autorisée à lire et à écrire les fichiers configurés. Pour un hébergement normal,
+Applications multi-utilisateurs, utilisez le mode base de données et le partage basé sur SQL.

package/docs/content/locales/fr-FR/mcp-apps.md

@@ -0,0 +1,147 @@
+---
+title: "Applications MCP"
+description: "Créez et intégrez des applications interactives MCP UI dans Claude, ChatGPT et d'autres hôtes compatibles, en utilisant de véritables routes d'application, le pont d'intégration et le pont hôte API."
+---
+
+# Applications MCP
+
+**Cette page : les UI en ligne dans Claude/ChatGPT.** Création des ressources de l'application MCP et du pont intégré qui restitue un véritable itinéraire d'application dans le chat d'un hôte compatible. Cette page constitue également la page d'accueil unique de la **matrice de support client** ([below](#client-support)).
+
+| Si vous voulez…                                                                               | Lire                                     |
+| --------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Connectez un agent/hôte externe à votre application                                           | [External Agents](/docs/external-agents) |
+| Donnez plus d'outils à votre agent (consommez d'autres serveurs MCP)                          | [MCP Clients](/docs/mcp-clients)         |
+| Créez des UI en ligne qui s'affichent dans Claude/ChatGPT                                     | **Cette page** — Applications MCP        |
+| Référence du serveur MCP de niveau inférieur (authentification, outils, montage personnalisé) | [MCP Protocol](/docs/mcp-protocol)       |
+
+Les applications MCP sont l'extension officielle `io.modelcontextprotocol/ui` qui permet aux hôtes compatibles (Claude, Claude Desktop, ChatGPT, VS Code GitHub Copilot, Goose, Postman, MCPJam et Cursor) de rendre les UI interactifs en ligne dans le chat. Dans les applications natives d'agent, chaque application MCP est une **véritable route React**, et non un widget distinct HTML.
+
+Dans le chat d'une application Agent-Native, préférez [native chat renderers](/docs/native-chat-ui) pour les widgets propriétaires tels que les tableaux, les graphiques, les résultats saisis et les possibilités d'approbation. Utilisez les applications MCP pour les UI externes/inter-hôtes en ligne dans Claude, ChatGPT, Copilot, Cursor et d'autres hôtes compatibles, avec l'action `link` comme solution de secours universelle pour les liens profonds.
+
+## Création : applications MCP en option UI {#mcp-apps}
+
+Pour les hôtes qui prennent en charge l'extension d'applications MCP, une action peut également annoncer une ressource UI en ligne avec `mcpApp`. Il s'agit d'une amélioration progressive pour les flux dans lesquels l'agent externe doit fournir à l'utilisateur une surface interactive au lieu d'un simple texte – par exemple, consulter un brouillon d'e-mail, modifier une invitation de calendrier ou choisir entre les variantes de tableau de bord générées.
+
+Utilisez la véritable application React avec `embedRoute()` ou `embedApp()` chaque fois que l'utilisateur a besoin de UI. Le modèle mental est simple : la cible `link` de l'action est également la cible intégrée de l'application MCP. Exposez l'opération comme une action/un outil normal, renvoyez un lien profond ciblé avec `link` et ajoutez `mcpApp.resource = embedApp(...)` afin que les hôtes capables chargent cette même route en ligne au lieu d'ouvrir un nouvel onglet. Lorsque les deux doivent être construits à partir du même itinéraire, préférez `embedRoute({ title, openLabel, path })` : c'est le wrapper pratique qui renvoie les champs `link` et `mcpApp` correspondants à partir d'un seul appel, tandis que `embedApp(...)` est la ressource de niveau inférieur que vous attribuez directement à `mcpApp.resource`.
+
+Cela signifie que les intégrations d'applications complètes peuvent faire tout ce que l'itinéraire peut faire une fois ouvertes : réviser ou modifier un brouillon d'e-mail, afficher une boîte de réception/une recherche filtrée, ouvrir un événement de calendrier ou un brouillon d'événement, charger une page d'extension, inspecter un tableau de bord d'analyse complet ou une analyse enregistrée, continuer une présentation dans l'éditeur de diapositives ou ouvrir un projet/éditeur de conception. Préférez les paramètres URL/deep-link et le pont de navigation/état d'application `/_agent-native/open` existant plutôt que d'inventer un deuxième protocole d'état pour les applications MCP.
+
+Dans de rares occasions, la bonne cible est une route d'application ciblée qui restitue un composant React partagé au lieu de l'ensemble du shell de l'application. L'itinéraire `/chart` d'Analytics est le modèle : il prend une charge utile `SqlPanel` compacte dans le URL et restitue le même composant graphique que celui utilisé par le tableau de bord. Il s'agit toujours d'une application intégrée, pas d'une simple application HTML MCP. Exposez-le ou appelez-le via une action normale / `open_app({ path, embed: true })`, gardez le URL déterministe et laissez `embedApp()` restituer cet itinéraire en ligne.
+
+Ne pas écrire à la main des applications HTML MCP uniques pour le produit UI ; si l'action nécessite une surface personnalisée, ajoutez ou réutilisez d'abord un véritable itinéraire/composant d'application et intégrez cet itinéraire.
+
+```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." }
+  ]
+}
+```
+
+Le serveur MCP annonce l'extension `io.modelcontextprotocol/ui`, ajoute `_meta.ui.resourceUri` plus `_meta["ui/resourceUri"]` à `tools/list` et émet également des métadonnées de compatibilité ChatGPT Apps SDK (`openai/outputTemplate`, widget CSP/description/accessibilité). Il expose les HTML à `resources/list`, `resources/templates/list` et `resources/read` en utilisant MIME `text/html;profile=mcp-app`. Le proxy stdio transfère ces gestionnaires de ressources depuis l'application en direct, afin que les clients de bureau et CLI voient les mêmes ressources que les clients HTTP.
+
+Conservez le générateur `link` existant même lors de l'ajout de `mcpApp`. Les clients CLI uniquement, les hôtes plus anciens et tout hôte qui ne restitue pas les applications MCP ignoreront les métadonnées UI et auront toujours besoin du lien `"Open in … →"`. `embedApp()` utilise ce lien comme cible de lancement, appelle l'assistant `create_embed_session` réservé à l'application, échange un ticket SQL unique sur `/_agent-native/embed/start` et navigue dans le cadre de l'application MCP jusqu'à l'itinéraire cible avec une session de navigateur de courte durée plus un support de secours pour les récupérations de même origine. `open_app({ app, path, embed: true })` est la trappe de secours générique pour les itinéraires tels que les tableaux de bord complets, les boîtes de réception filtrées, les brouillons de calendrier, les analyses et les pages d'extension, et doit être utilisé généreusement lorsque l'application complète constitue la surface de révision/modification la plus claire.
+
+`embedApp()` inclut l'origine de la requête MCP dans la ressource CSP afin que le lanceur puisse récupérer et, lorsqu'il est explicitement demandé, encadrer l'itinéraire signé de l'application propriétaire. Dispatch ajoute les origines exactes des applications accordées à sa ressource `open_app` afin qu'un seul connecteur Dispatch puisse intégrer le courrier, le calendrier, les diapositives et le reste sans autoriser chaque origine HTTPS. Transmettez uniquement des domaines de trames ou de ressources supplémentaires pour une application MCP personnalisée qui intègre véritablement un lecteur tiers ou charge des ressources tierces.
+
+À l'intérieur de ces routes `embedApp()`, `sendToAgentChat()` est compatible avec l'intégration. Les invites soumises automatiquement sont transmises à l'hôte MCP en tant que `ui/update-model-context` plus `ui/message`, de sorte qu'un bouton dans l'application intégrée peut intentionnellement poursuivre la conversation Claude/ChatGPT à partir de l'état de l'application sélectionné. Le contexte masqué est envoyé comme contexte de modèle ; le tour visible de l'utilisateur reste simplement l'invite de l'application, ce qui évite un consentement effrayant de l'hôte autour des chemins de fichiers internes de l'état de l'application. `submit: false` reste un comportement de pré-remplissage/révision local.
+
+## Pont d'application MCP de première classe {#mcp-app-bridge}
+
+Les intégrations d'applications MCP sont des intégrations d'itinéraires, et non des mini-produits séparés. `embedApp()` démarre à partir de la cible `link` de l'action, crée une session d'intégration de courte durée et lance cette route d'application signée. Les hôtes de l'application MCP standard peuvent naviguer eux-mêmes dans le cadre de l'application MCP lorsque l'hôte peut hydrater directement l'itinéraire.
+
+```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}"
+}
+
+```
+
+Le Web Claude utilise un chemin de transplantation à image unique : le document de ressource récupère l'application signée HTML et l'hydrate dans l'iframe de l'application MCP de Claude, car Claude n'autorise pas de manière fiable les iframes enfants appartenant à l'application ou la navigation dans des images externes. Le Web ChatGPT obtient une iframe d'itinéraire contrôlé car son pont d'applications nous offre des hôtes `window.openai` stables API et un contrôle de hauteur limité. Tous les chemins pointent vers la même route d'application signée et restituent la route normale et les composants React. Concevez des itinéraires intégrés afin qu'un rechargement avec le même URL signé reconstruise la même vue.
+
+Pour `open_app({ embed: true })` de la même application, le framework génère le ticket de démarrage d'intégration lors de l'appel de l'outil d'origine et stocke le URL de démarrage signé dans les métadonnées cachées de l'outil. Le actions personnalisé peut renvoyer le `embedStartUrl` pour le même chemin rapide ; la couche MCP supprime le URL porteur du ticket du `structuredContent` visible par le modèle et des métadonnées normales de lien ouvert. Lorsqu’aucun démarrage d’intégration URL n’est présent, la ressource revient à l’assistant `create_embed_session` réservé aux applications. Cela permet aux hôtes de production de restreindre les appels d'outils lancés par iframe sur la route directe sans divulguer les URL de session d'application unique dans la transcription. Si un utilisateur rouvre une ancienne discussion après l'expiration d'un ticket de démarrage unique, la route de démarrage renvoie une petite page d'actualisation et publie `agentNative.embedSessionExpired` dans le wrapper ; `embedApp()` efface le démarrage obsolète URL et crée un nouveau ticket via `create_embed_session` alors qu'il a toujours l'itinéraire d'origine de l'application.
+
+ChatGPT obtient un chemin de compatibilité dédié via `window.openai` : le document de lancement lit directement `toolInput`, `toolOutput` et `toolResponseMetadata`, puis appelle `create_embed_session` via `window.openai.callTool(...)`. Les hôtes d'applications MCP standard utilisent le pont `ui/*` JSON-RPC. Les itinéraires directement hydratés peuvent appeler `ui/update-model-context`, `ui/message`, `ui/open-link` et `ui/request-display-mode` via les assistants de pont hôte. La route transplantée de Claude utilise le même pont hôte direct `ui/*` après hydratation. Lorsque le chemin d'iframe de diagnostic ChatGPT ou explicite est utilisé, le wrapper relaie le même hôte actions sur les requêtes postMessage `agentNative.mcpHost.*`. Gardez la forme du résultat identique pour les deux chemins : renvoyez un `link` ciblé et un contenu structuré concis.
+
+Ne définissez pas le standard `_meta.ui.domain` sur une application URL. MCP Apps traite ce champ comme spécifique à l'hôte : Claude valide les domaines sandbox de style `{hash}.claudemcpcontent.com`, tandis que ChatGPT utilise ses propres métadonnées `openai/widgetDomain`. Omettez `ui.domain` sauf si vous émettez délibérément une valeur spécifique à l'hôte ; l'hôte choisira une origine sandbox par défaut.
+
+Les pages d'extension conservent leur bac à sable dans les intégrations de chat MCP sans naviguer dans une deuxième iframe de route. L'utilisation normale de l'application rend `/_agent-native/extensions/:id/render` sous la forme d'une iframe enfant en bac à sable. En mode pont de discussion MCP, le framework restitue le même document d'extension que le `srcDoc` en bac à sable à l'intérieur de l'iframe de route, évitant ainsi les échecs de l'hôte `frame-ancestors` / `X-Frame-Options` tout en préservant `sandbox="allow-scripts allow-forms"`.
+
+Le shell de ressources possède la taille de l'hôte externe. `embedApp({ height })` est par défaut `560px`, fixe la coque à `320-900px` et réserve `44px` pour la petite barre d'outils, de sorte que la fenêtre d'affichage de l'itinéraire est `height - 44px`. Gardez les itinéraires des applications intégrées défilables en interne et laissez le lanceur signaler la hauteur intrinsèque délimitée plutôt que la hauteur totale du document ; sinon, le redimensionnement automatique de l'hôte peut transformer une page d'application normale en un très grand artefact de discussion. Un shell modifié affecte uniquement les nouvelles ressources de l'application MCP et les nouveaux appels d'outils. Les anciennes trames de conversation ChatGPT/Claude peuvent conserver le comportement précédent des ressources, alors vérifiez le dimensionnement avec un nouveau rendu en ligne avant de juger d'un correctif.
+
+### Modes d'intégration {#embed-modes}
+
+Claude utilise par défaut le chemin de transplantation d'une seule image. Vous pouvez également le forcer sur d'autres hôtes avec `embedMode: "transplant"` ou `frame: "transplant"` lors du débogage du comportement de chargement du module hôte. Vous pouvez forcer l'iframe de diagnostic imbriquée avec `embedMode: "iframe"`, `renderMode: "iframe"`, `nested: true` ou `frame: "iframe"`. Si l'iframe est bloquée, `embedApp()` la remplace par une solution de secours d'application ouverte : l'utilisateur peut réessayer en ligne, ouvrir une session d'intégration fraîchement créée via l'hôte ou utiliser la route visible URL. Gardez la cible `link` de l'action utile seule, car elle reste la trappe de secours universelle.
+
+Lorsque vous testez Claude via ngrok, utilisez une version de production (`npx @agent-native/core@latest build` puis `npx @agent-native/core@latest start`) ou une version d'aperçu/production déployée URL. Le chemin de transplantation à image unique de Claude fonctionne avec des morceaux d'actifs de production ; Les modules de développement bruts Vite tels que `/app/root.tsx` peuvent être protégés par l'authentification de l'application et faire échouer les importations dynamiques à partir de l'origine de la ressource Claude.
+
+## Pont hôte API {#host-bridge}
+
+Le pont hôte est volontairement petit :
+
+| Mode                        | Type de message                       | Utilisez-le pour                                          |
+| --------------------------- | ------------------------------------- | --------------------------------------------------------- |
+| route hôte directe          | `ui/update-model-context`             | Contexte masqué pour le modèle hôte                       |
+| route hôte directe          | `ui/message`                          | Publier un utilisateur visible comme hôte                 |
+| route hôte directe          | `ui/open-link`                        | Ouvrez un URL externe ou une application via l'hôte       |
+| route hôte directe          | `ui/request-display-mode`             | Demander `inline`, `fullscreen` ou `pip`                  |
+| Greffe Claude               | `ui/*`                                | Même pont hôte direct après hydratation                   |
+| ChatGPT / itinéraire iframe | `agentNative.mcpHostContext`          | Thème, paramètres régionaux, plate-forme hôte, dimensions |
+| ChatGPT / itinéraire iframe | `agentNative.embeddedAppReady`        | Confirmez l'iframe de route chargée                       |
+| ChatGPT / itinéraire iframe | `agentNative.mcpHost.*` / `.response` | Relais wrapper pour les requêtes d'hôte                   |
+
+Les itinéraires intégrés peuvent utiliser `updateMcpAppModelContext()`, `openMcpAppHostLink()`, `requestMcpAppDisplayMode()`, `getMcpAppHostContext()` et `useMcpAppHostContext()` à partir de `@agent-native/core/client`. `sendToAgentChat()` utilise le même chemin d'accès à partir des intégrations d'applications complètes pour les invites soumises automatiquement.
+
+Le mode d'affichage est le meilleur effort. Le `McpAppRenderer` intégré à l'application signale actuellement un contexte d'hébergement Web en ligne et un mode d'affichage en ligne uniquement ; les hôtes externes peuvent honorer des demandes d'affichage plus importantes, les ignorer ou répondre avec une erreur de mode non pris en charge. Gardez toujours l'itinéraire en ligne utilisable.
+
+## Support client et mise en cache {#client-support}
+
+La liste officielle actuelle des clients des applications MCP comprend Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT et Cursor ; la prise en charge de l'hôte varie toujours selon le plan, le canal de publication et la version du client, alors vérifiez le [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix). Les applications MCP personnalisées ChatGPT sont disponibles via le mode développeur pour les espaces de travail Business et Enterprise/Edu sur le Web ChatGPT ; voir les notes [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 et les autres clients CLI/éditeur de code reçoivent toujours les mêmes ressources et métadonnées lorsqu'ils prennent en charge les applications MCP, mais les traitent comme des hôtes de liaison, sauf si vous avez vérifié le rendu iframe en ligne dans cette surface exacte. Le lien profond reste la solution de secours fiable lorsqu'un hôte choisit de ne pas restituer une iframe. En pratique, chaque application native d'agent doit être créée avec les deux : applications MCP pour la révision/modification en ligne sur des hôtes compatibles, et `link` pour un aller-retour universel vers l'application complète.
+
+Claude et ChatGPT peuvent mettre en cache les métadonnées des outils et des ressources pour un connecteur personnalisé existant. Après avoir modifié les métadonnées de l'application MCP, vérifiez avec un nouvel appel d'outil ; si l'hôte utilise toujours l'ancien descripteur, reconnectez le connecteur Claude ou analysez/vérifiez à nouveau le connecteur ChatGPT afin qu'il actualise le catalogue. Si Claude enregistre un avertissement concernant `_meta.ui.csp` ou `_meta.ui.permissions` vivant sur le descripteur d'outil après un déploiement, ce connecteur utilise des métadonnées obsolètes : supprimez/reconnectez le connecteur Claude et démarrez une nouvelle discussion.
+
+## Tests {#testing}
+
+Testez les applications MCP avec les appareils légers autour de `embedApp()` et `McpAppRenderer` ; ils couvrent CSP, le contexte de l'hôte, le lancement de l'application et le comportement des messages de pont sans avoir besoin d'un véritable hôte externe. Lors de la validation du Web ChatGPT ou Claude, déclenchez un nouvel appel d'outil après les modifications du shell et mesurez l'iframe visible. Les images précédemment rendues dans la même conversation peuvent toujours afficher la hauteur en cache ou le comportement de lancement.
+
+## Connexe {#related}
+
+- [External Agents](/docs/external-agents) : connexion de Claude, ChatGPT, Codex et Cursor aux applications hébergées ; Matrice de compatibilité des applications MCP ; niveaux de catalogue ; liens profonds.
+- [MCP Protocol](/docs/mcp-protocol) : le serveur MCP monté automatiquement, l'authentification, les outils et `ask-agent`.
+- [Actions](/docs/actions) — `defineAction`, le constructeur `link`, `publicAgent`.
+
+```
+
+```