Skills

Démarrage rapide des compétences

Installez @showly/mcp-server, autorisez depuis votre terminal et voyez rapidement une véritable URL d'aperçu.

La promesse principale de Showly est « déployez un site à partir de votre agent ». Cette page est la recette de bout en bout. L'installation et votre premier aperçu prennent environ 90 secondes sur un ordinateur portable frais ; le chemin de publication en production ajoute une étape d'approbation manuelle dans le navigateur (abordé dans la section 5).

1. Installez dans votre agent

Le chemin d'installation canonique est le package @showly/mcp-server (bin showly-mcp). Pour Claude Code :

npx @showly/mcp-server install --to claude-code

Pour Codex :

npx @showly/mcp-server install --to codex

Ceux-ci écrivent une seule entrée de serveur MCP (transport + URL) dans ~/.claude.json ou ~/.codex/config.toml. Aucun jeton n'est écrit : le l'agent découvre le serveur d'autorisation Showly de OAuth à partir du point de terminaison lui-même et exécute une connexion au navigateur lors de la première utilisation. Le colis contient également un manifest.json répertoriant chaque outil Showly, ses portées requises et si Les appels d'origine MCP sont autorisés.

Voir Installer la Skill pour savoir comment fonctionnent la connexion par navigateur et la connexion sans interface.

Si votre agent n'est pas pris en charge par le programme d'installation, exécutez npx @showly/mcp-server install --to stdout et collez l'extrait manuellement.

2. Autoriser à partir d'une vraie conversation

Ouvrez Claude Code (ou votre équivalent Codex) et demandez tout ce qui touche un Showly outil. Par exemple:

"Liste mes Showly sites."

L’agent appelle list_sites. Comme cette machine n’a pas encore de jeton Showly, votre hôte ouvre une connexion dans le navigateur et la personne clique sur Allow.

Si la machine n’a pas de navigateur (un serveur, un conteneur, une CI, un shell distant) ou si vous n’êtes pas devant elle, utilisez la connexion sans interface :

npx @showly/mcp-server login --to claude-code

Elle affiche exactement ceci, puis attend :

Showly needs one approval from you. If you do not have a Showly
account yet, you will be asked to create one first.

  1. Open this page:   https://showly.ai/oauth/device
  2. Enter this code:  K7QM-3XPD

Same machine as your browser? Use the direct link instead:
  https://showly.ai/oauth/device?user_code=K7QM-3XPD

The page will show the code K7QM-3XPD before you approve.
Approve ONLY if it matches the code above. If it shows a
different code, someone else is trying to get in - refuse it.

Waiting for approval until 14:58 local. Once you approve, this
command picks it up on its own - no need to come back and tell it.

Ouvrez la page sur n’importe quel appareil — votre téléphone convient — et connectez-vous avec l’adresse e-mail utilisée à l’inscription. L’écran de consentement affiche le code, les étendues demandées et les boutons Autoriser / Refuser.

Comparez le code de la page avec celui de votre terminal, cochez la case indiquant qu’ils correspondent, puis cliquez sur Autoriser. Cette vérification est l’essentiel : le nom affiché par un client sur cet écran est celui qu’il s’est donné, le code est donc la seule partie vérifiable. De retour dans votre terminal, la commande se termine en quelques secondes et les outils de lecture fonctionnent immédiatement.

3. Effectuez une modification sur une ligne et prévisualisez-la

Demandez à l'agent :

"Sur le site northstar, remplacez le H1 par 'Bonjour de W7' et donnez-moi un aperçu."

L'agent enchaîne quatre appels d'outil :

  1. create_change_plan — transforme votre phrase en un plan structuré.
  2. apply_site_patch — organise la modification en tant que _changeset_ (portée site:write).
  3. create_preview — construit l'ensemble de modifications et renvoie une URL d'Aperçu protégée (portée preview:create).
  4. run_checks — lit l'état lint/typecheck/build sur ce déploiement

(portée checks:run).

Les petites modifications prennent environ 5 secondes et une véritable application Next.js environ 30 secondes. L'agent affiche une URL d'Aperçu protégée pour examiner la modification sans affecter le site En ligne actuel.

4. Passer en production

Showly ne permet pas aux agents de publier directement en production. L'agent appelle request_publish (portée publish:request), qui crée une approbation en attente et renvoie un lien profond webApprovalUrl au lieu d'envoyer quoi que ce soit :

{
  "ok": true,
  "data": {
    "approvalId": "appr_xxx",
    "deploymentId": "dep_xxx",
    "state": "pending",
    "expiresAt": "2026-05-31T10:00:00.000Z",
    "reused": false,
    "webApprovalUrl": "https://showly.ai/app/deployments/dep_xxx/publish"
  }
}

L'agent vous remet le webApprovalUrl. Ouvrez-le, vérifiez l'aperçu exact et effectuer toute approbation de coéquipier requise par le plan. L'inscription à OTP/MFA n'est pas requis. Une fois la publication lancée, l'agent appelle get_preview_status avec waitForChange: true et il effectue des interrogations longues (30 secondes par défaut, jusqu'à 60 secondes plafond). Lorsque le déploiement de production passe à ready, la réponse inclut productionUrl, que l'agent renvoie comme URL Live finale.

Ce qui quitte votre machine

  • Votre agent s'exécute localement (Claude Code, Codex, ...).
  • La lecture du contexte ne renvoie que les données autorisées par les portées du jeton MCP.
  • Les fichiers modifiés sont envoyés à Showly lors de l'appel à apply_site_patch ou à un autre outil d'envoi.
  • Showly crée un Aperçu privé à partir de ces fichiers et inscrit les actions concernées dans l'historique d'audit.

Consultez Architecture pour le cycle de livraison complet.

Erreurs courantes

  • missing_bearer_token — l'agent n'a pas envoyé

Authorization: Bearer mcp_…. Relancez npx @showly/mcp-server install, puis redémarrez l'agent.

  • invalid_token — votre token est expiré, révoqué ou n'est pas un token MCP.

Invoquez à nouveau un outil Showly pour déclencher une nouvelle connexion au navigateur ; l'agent obtient automatiquement un nouveau jeton. (Pour le forcer, révoquez l'ancienne ligne sous Administrateur → Agent en premier.)

  • insufficient_scope — l'outil demandé a besoin d'une portée que vous n'avez pas accordée

pendant le flux de consentement. Révoquer + réautoriser, en approuvant cette fois le portée.

  • Publication de production — publish_site utilise une procédure en deux étapes de courte durée

confirmation après que l'utilisateur a dit oui. Si l'espace de travail a un politique d'approbation du deuxième évaluateur activée, utilisez request_publish et son webApprovalUrl à la place. Aucun des deux flux ne nécessite une inscription OTP/MFA.

Étapes suivantes