> ## Documentation Index
> Fetch the complete documentation index at: https://faces.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Vue d'ensemble MCP

> Utilisez Faces avec Claude et d'autres assistants IA compatibles MCP pour construire des présentations diapositive par diapositive.

Le server MCP (Model Context Protocol) de Faces permet aux assistants IA comme Claude de construire des présentations interactives et explorables diapositive par diapositive. Votre assistant écrit lui-même le code de chaque diapositive, sans utiliser de crédits.

## Qu'est-ce que MCP ?

MCP est un protocole ouvert qui permet aux assistants IA de se connecter à des outils externes. Lorsque vous connectez Claude au server MCP de Faces, Claude peut :

* **Créer un projet vide** pour démarrer une nouvelle présentation (dans votre équipe personnelle ou n'importe quelle équipe à laquelle vous appartenez)
* **Lister les équipes** auxquelles vous appartenez pour que l'assistant puisse choisir la bonne
* **Lister et parcourir** vos projets existants (y compris les projets partagés en équipe)
* **Lire et modifier des diapositives individuelles** : inspecter les fichiers source des diapositives et en écrire de nouveaux. Fonctionne pour tout projet dont vous êtes le propriétaire, un membre de l'équipe (pour les projets partagés en équipe) ou un éditeur invité
* **Définir le design system du projet** : la palette et les polices partagées par toutes les diapositives
* **Attacher des plugins** à une diapositive, comme un formulaire de contact ou un présentateur vidéo IA en direct
* **Capturer une diapositive** pour vérifier visuellement la mise en page, l'espacement et la typographie après l'édition
* **Publier ou dépublier** un projet et lire son URL en direct

Il n'y a pas d'outil côté server du type « générer une présentation complète » exposé via MCP. L'assistant lui-même crée chaque diapositive. Pour construire une nouvelle présentation, il crée un projet vide puis remplit les diapositives une par une.

## Outils disponibles

### Session et mode agent

<table>
  <colgroup>
    <col style={{ width: "300px" }} />

    <col />
  </colgroup>

  <thead>
    <tr><th>Outil</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>get\_user\_state</code></td><td>Lit votre état d'éditeur en direct à travers les onglets de navigateur ouverts : le projet que vous consultez, la diapositive sélectionnée et si le mode agent est activé. L'assistant appelle ceci en premier pour savoir sur quel projet vous travaillez.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>start\_agent\_mode</code></td><td>Active le « mode agent » pour un projet dans votre navigateur : masque la barre latérale droite et affiche une barre flottante indiquant qu'un agent pilote la session. Passez <code>enabled: false</code> pour le désactiver. Vous pouvez toujours le désactiver manuellement.</td></tr>
  </tbody>
</table>

### Équipes

<table>
  <colgroup>
    <col style={{ width: "300px" }} />

    <col />
  </colgroup>

  <thead>
    <tr><th>Outil</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>list\_teams</code></td><td>Liste les équipes auxquelles vous appartenez. Renvoie <code>id</code>, <code>slug</code>, <code>name</code>, <code>role</code> et <code>isPersonal</code>. Utilisez l'<code>id</code> de l'équipe lors de l'appel à <code>create\_project</code>.</td></tr>
  </tbody>
</table>

### Projets

<table>
  <colgroup>
    <col style={{ width: "300px" }} />

    <col />
  </colgroup>

  <thead>
    <tr><th>Outil</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>create\_project</code></td><td>Crée un nouveau projet vide. Renvoie le <code>projectSlug</code> et l'<code>editorUrl</code>. Accepte un <code>teamId</code> optionnel. Omettez-le pour utiliser votre équipe personnelle, ou passez un <code>id</code> renvoyé par <code>list\_teams</code> pour créer le projet sous une équipe spécifique.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>list\_projects</code></td><td>Liste les projets auxquels vous avez accès (possédés, partagés en équipe, ou partagés avec vous) avec pagination (<code>cursor</code>, <code>limit</code>, <code>published</code>).</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>get\_project</code></td><td>Récupère les détails d'un projet et ses URLs pour un slug donné.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>rename\_project</code></td><td>Renomme un projet. Le slug et les URLs restent inchangés.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>duplicate\_project</code></td><td>Crée une copie complète d'un projet, y compris toutes les diapositives. Renvoie un nouveau <code>projectSlug</code> et un nouvel <code>editorUrl</code>.</td></tr>
  </tbody>
</table>

### Design system

<table>
  <colgroup>
    <col style={{ width: "300px" }} />

    <col />
  </colgroup>

  <thead>
    <tr><th>Outil</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>get\_project\_config</code></td><td>Lit le fichier <code>project.config.json</code>, y compris les paramètres de mise en page et les design tokens partagés (couleurs de la palette et polices) utilisés par toutes les diapositives.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>update\_project\_config</code></td><td>Met à jour <code>project.config.json</code>, par exemple pour définir la palette et les polices du projet avant de styliser les diapositives. Seules les clés que vous passez sont modifiées.</td></tr>
  </tbody>
</table>

### Publication

<table>
  <colgroup>
    <col style={{ width: "300px" }} />

    <col />
  </colgroup>

  <thead>
    <tr><th>Outil</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>publish\_project</code></td><td>Publie la dernière version d'un projet et le rend publiquement accessible. Renvoie l'<code>publishedUrl</code>.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>unpublish\_project</code></td><td>Met un projet publié hors ligne. Le projet et ses diapositives sont conservés.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>get\_project\_url</code></td><td>Récupère l'URL en direct actuelle d'un projet (sous-domaine ou domaine personnalisé plus chemin) ainsi que les sous-domaines et domaines disponibles vers lesquels basculer.</td></tr>
  </tbody>
</table>

<Note>
  Modifier l'URL en direct, ajouter des sous-domaines ou connecter des domaines personnalisés se fait depuis le tableau de bord, le [CLI](/fr/cli/commands) ou l'[API REST](/fr/api-reference/publishing/update-url). Ces actions ne sont pas exposées comme outils MCP.
</Note>

### Diapositives

<table>
  <colgroup>
    <col style={{ width: "300px" }} />

    <col />
  </colgroup>

  <thead>
    <tr><th>Outil</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>list\_slides</code></td><td>Liste toutes les diapositives d'un projet. Renvoie les IDs et les noms des diapositives.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>get\_slide</code></td><td>Lit les fichiers source d'une diapositive (<code>face.tsx</code>, <code>face.content.json</code>, <code>face.controls.json</code>).</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>create\_slides</code></td><td>Crée une ou plusieurs diapositives vides dans l'ordre en un seul appel atomique. Renvoie les nouveaux <code>slideId</code>s dans le même ordre. Passez <code>editing: true</code> pour afficher immédiatement le dégradé de chargement sur chaque nouvelle diapositive.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>reorder\_slides</code></td><td>Réorganise toutes les diapositives d'un projet en un seul appel atomique. Passez la liste complète des <code>slideId</code>s existants dans l'ordre final souhaité. Utilisez ceci pour restructurer un deck existant ; ne supprimez et ne recréez jamais des diapositives juste pour les réorganiser.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>update\_slide</code></td><td>Met à jour les fichiers source d'une diapositive. Valide et compile avant l'enregistrement, renvoie des erreurs si le code ne compile pas.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>start\_slide\_editing</code></td><td>Affiche le dégradé de chargement dans l'éditeur avant de faire des modifications.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>finish\_slide\_editing</code></td><td>Efface le dégradé de chargement après l'édition (appelez toujours cette commande, même en cas d'échec).</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>view\_slide</code></td><td>Prend une capture d'écran d'une diapositive et la renvoie sous forme d'image pour que l'assistant puisse vérifier visuellement la mise en page, l'espacement et la typographie. Passez <code>isMobile: true</code> pour la mise en page mobile.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>get\_slide\_guide</code></td><td>Récupère la référence complète de création de diapositive (formats de fichiers, types de blocs, contrôles, typographie, exemples). À appeler avant d'écrire du code de diapositive pour la première fois.</td></tr>
  </tbody>
</table>

### Plugins

<table>
  <colgroup>
    <col style={{ width: "300px" }} />

    <col />
  </colgroup>

  <thead>
    <tr><th>Outil</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>list\_plugins</code></td><td>Liste les plugins disponibles à attacher à une diapositive : des comportements d'exécution que le code d'une diapositive ne peut pas exprimer seul, comme collecter des soumissions de formulaire ou intégrer un présentateur vidéo IA en direct.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>get\_plugin\_docs</code></td><td>Récupère le schéma de config d'un plugin, les fonctions qu'il expose et des exemples de code montrant comment une diapositive l'appelle. À lire avant <code>setup\_plugin</code>.</td></tr>
    <tr><td style={{ whiteSpace: "nowrap" }}><code>setup\_plugin</code></td><td>Configure une instance de plugin sur une diapositive. La config est validée par rapport au schéma du plugin et écrite dans le fichier <code>face.plugins.json</code> de la diapositive ; les autres instances sont préservées.</td></tr>
  </tbody>
</table>

## Construire une nouvelle présentation

1. `get_slide_guide` : lire la référence de création (seulement la première fois)
2. *(Optionnel)* `list_teams` : si l'utilisateur peut souhaiter le projet dans une équipe spécifique, listez-les et demandez. Sinon, ignorez et l'équipe personnelle sera utilisée.
3. `create_project({ name, teamId? })` : renvoie le `projectSlug` et l'`editorUrl`
4. *(Recommandé)* `update_project_config({ projectSlug, config })` : définissez le design system partagé (palette et polices) avant de styliser les diapositives, pour que chaque diapositive reste cohérente.
5. `create_slides({ projectSlug, slides: [{ name }, ...], editing: true })` : UN seul appel avec toutes les diapositives que vous prévoyez d'ajouter, dans l'ordre. Renvoie les nouveaux `slideId`s. N'appelez jamais cet outil en boucle ou en parallèle pour le même projet.
6. Pour chaque `slideId` renvoyé (en parallèle ou séquentiellement) :
   1. `update_slide({ projectSlug, slideId, files })` : écrit `face.tsx`, `face.content.json`, `face.controls.json`
   2. `view_slide({ projectSlug, slideId })` : capture la diapositive pour vérifier qu'elle s'affiche comme prévu
   3. `finish_slide_editing({ projectSlug, slideId })` : efface le dégradé de chargement
7. Partagez l'`editorUrl` avec l'utilisateur.

## Modifier une diapositive existante

1. *(Optionnel)* `get_user_state` : découvrez quel projet et quelle diapositive l'utilisateur a actuellement ouverts
2. `get_slide_guide` : si vous ne l'avez pas encore lu
3. `start_slide_editing(slideId)`
4. `get_slide(slideId)` : lire les fichiers actuels
5. `update_slide(slideId, files)`
6. `view_slide(slideId)` : vérifiez le résultat visuellement
7. `finish_slide_editing(slideId)`

## Authentification

Le server MCP utilise **OAuth** pour l'authentification. Lors de votre première connexion, vous serez invité à vous connecter à votre compte Faces via votre navigateur. Aucune gestion de clé API nécessaire, le flow OAuth gère tout automatiquement.

Comme MCP est authentifié par compte (et non par équipe), les nouveaux projets sont par défaut créés dans votre **équipe personnelle**, à moins que l'assistant ne passe un `teamId` explicite issu de `list_teams`. Cela diffère de l'API REST et du CLI, qui s'authentifient avec des clés API associées à une équipe et créent toujours les projets sous l'équipe de la clé. (Pour le CLI, l'équipe est choisie via `faces login --team <slug-or-id>` ; pour les clés API REST, dans **Settings > Developers** sur le tableau de bord.)

## Contrôle d'accès

Les outils MCP respectent le même modèle de permissions que le reste de Faces :

* **Propriétaire du projet** : accès complet en lecture/écriture.
* **Projets partagés en équipe** : tout membre de l'équipe propriétaire peut lire et modifier.
* **Collaborateurs invités** : peuvent lire ; seuls les collaborateurs avec la permission d'édition peuvent mettre à jour les diapositives.

Si l'utilisateur connecté n'a pas accès à un projet, les outils MCP renvoient « Project not found or you don't have access ».