verbatra mcp

Démarre un serveur Model Context Protocol en stdio : le transport standard en processus local que les clients MCP (Claude Desktop, Claude Code, Cursor et d'autres) utilisent pour lancer un serveur d'outils et lui parler. Il donne à un agent hébergé dans un terminal ou headless les mêmes capacités de statut de traduction, de glossaire et d'édition que les outils d'agent navigateur de Studio exposent, sans navigateur, sans port et sans application monopage servie.

Synopsis

verbatra mcp [flags]

@verbatra/mcp fournit aussi son propre binaire, donc un client MCP peut le lancer directement sans passer par la CLI verbatra :

verbatra-mcp [flags]

Les deux formes prennent les trois mêmes options et démarrent le même serveur, mais ce qui l'entoure diffère :

• verbatra mcp charge .env.local puis .env depuis le répertoire de travail avant de démarrer ; verbatra-mcp ne charge ni l'un ni l'autre, donc passe toute clé d'API dans l'environnement avec lequel le client MCP le lance.
• verbatra mcp rejette une option inconnue comme erreur d'utilisation et sort avec 2 ; verbatra-mcp ignore les options inconnues.
• Une erreur de démarrage ou de config sort avec 2 depuis verbatra mcp et avec 1 depuis verbatra-mcp.
• verbatra mcp s'arrête de force avec le code de sortie 130 sur une seconde interruption pendant l'extinction ; verbatra-mcp n'a pas ce chemin.

Options

Quand --allow-spend est absente, le serveur lit à la place la variable d'environnement VERBATRA_MCP_ALLOW_SPEND : 1, true, yes ou on (insensible à la casse) compte comme activé. L'option CLI l'emporte toujours sur la variable d'environnement. Sans l'une ni l'autre, translation.retranslateEntry et translation.translatePending ne sont pas exposés du tout : un client MCP qui liste les outils ne les voit jamais, et les appeler par leur nom échoue comme un outil inconnu. C'est une garantie par processus, pas une vérification par appel : un outil soumis à l'autorisation de dépense est donc structurellement impossible à appeler, et pas seulement refusé au moment de l'appel.

Configurer un client MCP

Pointe ton client MCP vers le binaire verbatra-mcp. Pour Claude Desktop, ajoute ceci à ton claude_desktop_config.json :

{
  "mcpServers": {
    "verbatra": {
      "command": "npx",
      "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Omets complètement le bloc env et son --allow-spend pour un serveur en lecture seule et édition locale uniquement : project.snapshot, les outils de statut et de glossaire, et translation.editEntry n'appellent jamais de fournisseur et n'ont besoin d'aucune clé. Ajoute --allow-spend au tableau args dès que tu veux aussi disposer de translation.retranslateEntry et translation.translatePending, et définis la variable d'environnement de clé d'API que lit ton fournisseur configuré (voir Fournisseurs).

Si tu invoques déjà tout via la CLI verbatra, lance-le plutôt comme sous-commande :

{
  "mcpServers": {
    "verbatra": {
      "command": "npx",
      "args": ["-y", "@verbatra/cli", "mcp", "--cwd", "/path/to/your/project"]
    }
  }
}

Outils

translation.retranslateEntry et translation.translatePending ne sont exposés que lorsque le serveur a été démarré avec --allow-spend. L'entrée de chaque outil, et la sortie de chaque outil dont la forme de résultat est petite et fermée, est un schéma JSON dérivé du même schéma zod contre lequel le serveur valide l'appel. Appeler un nom d'outil inconnu est une erreur au niveau du protocole ; appeler un outil connu avec une entrée qui échoue à la validation renvoie un résultat qui nomme le champ fautif, pour qu'un agent puisse lire l'échec et se corriger lui-même.

Les deux outils qui écrivent une entrée, translation.editEntry et translation.retranslateEntry, sont en outre protégés par outil, par locale et par clé : pendant qu'un appel pour une entrée donnée est encore en cours, un second appel au même outil nommant les mêmes locale et key n'est ni mis en file ni exécuté en parallèle. Il reçoit un résultat isError dont le texte indique qu'un appel correspondant est déjà en cours, pour que deux agents (ou un agent qui réessaie) ne se disputent pas la même entrée via le même outil. Les appels pour d'autres clés ou d'autres locales continuent de s'exécuter en même temps. translation.translatePending n'a pas de tel verrou.

Entrées et résultats

• status.check, status.diff et key.integrity prennent un tableau locales facultatif (au moins une entrée) qui restreint le résultat à ces locales ; key.integrity prend aussi la key à vérifier.
• translation.editEntry prend locale, key et value, avec value limitée à 20 000 caractères.
• glossary.write prend { term, translation }, avec term limité à 200 caractères et translation à 2 000 ; translation: null supprime le terme. Il nécessite un glossaire stocké dans un fichier (la clé glossary de la config pointant vers un fichier JSON) ; un glossaire inline ou l'absence de glossaire échoue avec GLOSSARY_NOT_FILE_BACKED.
• translation.editEntry et translation.retranslateEntry renvoient { accepted, value, reason?, details? }. Une valeur refusée porte reason, parmi placeholder, markup, icu, degenerate ou empty, et details qui nomme ce qui a échoué ; translation.retranslateEntry ajoute reviewReasons à un résultat accepté : les signalements des heuristiques de révision pour la nouvelle valeur, vide quand aucune ne s'est déclenchée.
• lock.state renvoie exists et, quand le fichier de verrouillage existe, sa version ainsi que, par locale, les décomptes keyCount, missing, stale et upToDate.
• usage.summary renvoie l'usage de la dernière exécution et, quand un budget de tokens était configuré, un budget dont le standing vaut within, stopped-before-ceiling ou reached, et dont le supported indique si le chiffre compté provient entièrement de l'utilisation rapportée par le fournisseur lui-même.

Les contrôles de balisage en ligne dans key.integrity (markupMatches, markupDetails) et dans translation.editEntry (la raison markup), un id de format custom: dans project.snapshot et budget.standing dans usage.summary sont arrivés avec cette version.

Expurgation des secrets

Chaque résultat d'outil et chaque ligne de log passe par la même expurgation des secrets que Studio utilise : une valeur ayant la forme d'une clé d'API de fournisseur, ou la valeur exacte actuelle d'une variable d'environnement de fournisseur configurée, est remplacée par [REDACTED] avant même d'atteindre le client ou stderr. glossary.get et glossary.write signalent aussi quels termes ont été expurgés, pour que tu puisses distinguer un placeholder expurgé du vrai texte et ne jamais le réécrire.

stdout est le canal du protocole

Le transport stdio de MCP utilise stdout exclusivement pour les messages du protocole. verbatra mcp et verbatra-mcp n'impriment jamais de bannière, de ligne de log ni rien d'autre sur stdout ; tous les logs et diagnostics vont sur stderr à la place. Le serveur charge la config avant de connecter le transport, donc une erreur de config est écrite sur stderr immédiatement et le processus sort sans jamais parler le protocole. Une fois en marche, les diagnostics par appel (un appel échoué, un appel rejeté parce qu'un appel correspondant est en cours, un outil inconnu) vont aussi sur stderr.

Installation

@verbatra/mcp est un paquet à part, atteint via un import dynamique pour que le reste de la CLI fonctionne sans lui. S'il n'est pas installé, verbatra mcp sort avec le code 2 en affichant :

Verbatra's MCP server requires @verbatra/mcp. Install it with: pnpm add -D @verbatra/mcp

Lancer verbatra-mcp directement ne nécessite aucune CLI : installe @verbatra/mcp seul, ou laisse npx le récupérer à la demande comme montré ci-dessus.

Exemples

# start the MCP server with only local, non-spending tools
verbatra mcp

# also advertise the provider-calling tools
verbatra mcp --allow-spend

# resolve a project outside the current directory
verbatra mcp --cwd /path/to/project --config verbatra.config.ts

Codes de sortie

Voici les codes de sortie de verbatra mcp ; le binaire autonome verbatra-mcp diffère comme décrit dans le synopsis ci-dessus.

Voir aussi

• verbatra studio et Piloter Studio avec un agent de navigateur couvrent la surface d'agent basée sur le navigateur que ce serveur complète.
• Fournisseurs documente de quelle variable d'environnement chaque fournisseur lit sa clé d'API.
• verbatra check et verbatra diff sont les mêmes calculs que status.check et status.diff exposent.