Aller au contenu
Verbumia
Commencer gratuitement

MCP

Référence API

Verbumia fournit un serveur MCP natif pour que tout client compatible MCP — Claude Desktop, Cursor, votre propre agent — puisse chercher des clés, proposer des traductions, réviser des PRs, et inspecter la file des manquantes. Deux lignes de config, votre token, c'est fait.

1. Obtenir une clé API

Dans votre dashboard, allez à Org Settings → API Keys → Create. Donnez-lui le scope mcp:* (couvre les cinq outils ci-dessous). Le secret est affiché une seule fois ; copiez l'intégralité de vrb_live_<prefix>.<secret>.

Stockez-le dans le keychain de votre OS ou dans un .env local — ne le committez jamais. La clé est liée à votre org (et optionnellement à un projet) ; les appels hors scope retournent 404. Révoquez depuis le dashboard à tout moment ; les clés révoquées renvoient 401 au prochain appel.

2. Installer (ou non)

Le serveur MCP est publié sur npm et Homebrew. Avec npx vous n'avez rien à installer — Claude Desktop tire la dernière version à chaque lancement. Avec brew vous obtenez un binaire local figé, utile derrière des firewalls stricts.

npx (recommandé) 
1// pas d'installation — npx tire la dernière version de @verbumia/mcp à la demande2npx -y @verbumia/mcp --version
Homebrew (alternative) Tap publié au lancement V1 
1// optionnel : installer une fois globalement — arrive au lancement V12brew install verbumia/tap/verbumia-mcp

3. Brancher Claude Desktop

Ouvrez le fichier de config de Claude Desktop, ajoutez l'entrée verbumia sous mcpServers, puis quittez et relancez l'app.

claude_desktop_config.json 
1// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json2// Windows: %APPDATA%/Claude/claude_desktop_config.json3{4  "mcpServers": {5    "verbumia": {6      "command": "npx",7      "args": ["-y", "@verbumia/mcp"],8      "env": {9        "VERBUMIA_TOKEN":   "vrb_live_<prefix>.<secret>",10        "VERBUMIA_PROJECT": "<project_uuid>"11      }12    }13  }14}

Trois variables d'environnement au total : VERBUMIA_TOKEN (obligatoire), VERBUMIA_PROJECT (optionnel — pré-cible un projet pour que l'agent n'ait pas besoin d'appeler list_projects d'abord), et VERBUMIA_API_BASE (optionnel — défaut https://api.verbumia.ca ; override pour self-host ou staging).

Cursor (et autres clients MCP)

Même JSON, fichier différent. Dans Cursor, déposez-le dans .cursor/mcp.json (scope projet) ou ~/.cursor/mcp.json (scope utilisateur). Pour les autres clients, suivez la doc de config MCP de votre client — l'entrée mcpServers.verbumia est identique.

.cursor/mcp.json 
1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "verbumia": {5      "command": "npx",6      "args": ["-y", "@verbumia/mcp"],7      "env": { "VERBUMIA_TOKEN": "vrb_live_<prefix>.<secret>" }8    }9  }10}

Les 5 outils V1

Une fois configuré, l'agent dispose de ces outils. Vous ne les appelez pas par nom — décrivez votre intention en chat et l'agent choisit. Les noms ci-dessous sont les identifiants canoniques, utiles pour lire les traces d'agent ou construire vos propres agents sur le même serveur.

list_projects Énumère les projets accessibles à la clé API courante. Utile pour choisir un workspace en début de chat.

Args

  • limit number limite optionnelle sur le nombre de projets retournés

Exemple de prompt

« Liste mes projets Verbumia. »

get_project_info Récupère les métadonnées du projet : langue source, langues cibles, namespaces, nombre total de clés.

Args

  • project_uuid string required

Exemple de prompt

« Quelles langues et namespaces ship le projet Checkout ? »

list_missing_keys Liste les événements de clés manquantes capturés par le SDK runtime (paginé par cursor). Filtrable par namespace ou langue.

Args

  • project_uuid string required
  • namespace string limite à un namespace (ex. « checkout »)
  • language_code string limite à une langue (ex. « ja »)
  • cursor string cursor de pagination retourné par un appel précédent
  • limit number taille de page (défaut 20)

Exemple de prompt

« Quelles clés de traduction manquent pour ja dans le namespace checkout ? »

propose_translation Soumet une valeur de traduction pour une clé dans une langue cible. Toujours écrit en draft ; un reviewer humain promeut plus tard — Verbumia est le gestionnaire, pas le moteur.

Args

  • project_uuid string required
  • key string required
  • namespace string required
  • language_code string required
  • value string required

Exemple de prompt

« Propose \"Confirmer la commande\" pour checkout.review.confirm en fr-CA. »

validate_translations Lint d'un payload JSON i18next avant push : parité des placeholders ICU, clés manquantes/superflues, dérive de type entre locales.

Args

  • project_uuid string required
  • language_code string required
  • payload object required map de traductions au format JSON i18next

Exemple de prompt

« Valide ce fichier de traduction contre la source anglaise du projet. »

Vérifier que ça marche

  1. 1 Redémarrez Claude Desktop complètement (quittez, relancez — la config est lue au démarrage).
  2. 2 Ouvrez un nouveau chat. L'icône marteau doit montrer verbumia avec 5 outils disponibles.
  3. 3 Tapez « List my Verbumia projects. » L'agent devrait appeler list_projects et retourner vos workspaces.

Bloqué ? Consultez les logs de Claude Desktop dans ~/Library/Logs/Claude/mcp*.log (macOS). 90 % des problèmes sont des typos dans le JSON ou un token périmé.

Ensuite

Démarrage rapide
React + i18next
Capturer les clés manquantes en runtime, de bout en bout.
Référence
Toutes les docs
CLI, référence API (en cours).