Vai al contenuto
Verbumia
Inizia gratis

MCP

Riferimento API

Verbumia include un server MCP nativo così che qualsiasi client MCP-compatibile — Claude Desktop, Cursor, il tuo agente — possa cercare chiavi, proporre traduzioni, revisionare PR e ispezionare la coda delle chiavi mancanti. Due righe di config, il tuo token, fatto.

1. Ottieni una API key

Nella tua dashboard, vai a Org Settings → API Keys → Create. Assegnale lo scope mcp:* (copre tutti e cinque i tool sotto). Il secret è mostrato una volta sola; copia l'intera stringa vrb_live_<prefix>.<secret>.

Conservala nel keychain del tuo OS o in un .env locale — non committarla mai. La key è legata alla tua org (e opzionalmente a un progetto); le chiamate fuori scope restituiscono 404. Revoca dalla dashboard quando vuoi; le key revocate rispondono 401 alla chiamata successiva.

2. Installa (o salta)

Il server MCP è pubblicato su npm e Homebrew. Con npx non devi installare nulla — Claude Desktop tira l'ultima versione a ogni avvio. Con brew ottieni un binario locale fissato, utile dietro firewall restrittivi.

npx (consigliato) 
1// nessuna installazione — npx tira l'ultimo @verbumia/mcp on demand2npx -y @verbumia/mcp --version
Homebrew (alternativa) Tap pubblicato al lancio V1 
1// opzionale: installa globalmente una volta — arriva al lancio V12brew install verbumia/tap/verbumia-mcp

3. Collega Claude Desktop

Apri il file di config di Claude Desktop, aggiungi la voce verbumia sotto mcpServers, poi chiudi e rilancia 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}

Tre variabili d'ambiente in totale: VERBUMIA_TOKEN (obbligatoria), VERBUMIA_PROJECT (opzionale — pre-imposta un progetto così l'agente non deve chiamare prima list_projects) e VERBUMIA_API_BASE (opzionale — default https://api.verbumia.ca; sovrascrivi per self-hosted o staging).

Cursor (e altri client MCP)

Stesso JSON, file diverso. In Cursor, mettilo in .cursor/mcp.json (scope progetto) o ~/.cursor/mcp.json (scope utente). Per altri client, segui la doc di configurazione MCP del tuo client — la voce mcpServers.verbumia è identica.

.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}

I 5 tool V1

Una volta configurato, l'agente ha questi tool a disposizione. Non li chiami per nome — descrivi la tua intenzione in chat e l'agente sceglie. I nomi sotto sono gli identificatori canonici, utili per leggere le tracce dell'agente o costruire agenti custom sopra lo stesso server.

list_projects Enumera i progetti a cui la API key corrente ha accesso. Utile per scegliere un workspace all'inizio di una chat.

Args

  • limit number limite opzionale sul numero di progetti restituiti

Prompt di esempio

"Elenca i miei progetti Verbumia."

get_project_info Recupera i metadata del progetto: lingua sorgente, lingue target, namespace, conteggio totale chiavi.

Args

  • project_uuid string required

Prompt di esempio

"Quali lingue e namespace ship il progetto Checkout?"

list_missing_keys Elenca gli eventi pendenti di chiavi mancanti catturati dall'SDK runtime (paginato per cursor). Filtra per namespace o lingua.

Args

  • project_uuid string required
  • namespace string limita a un namespace (es. "checkout")
  • language_code string limita a una lingua (es. "ja")
  • cursor string cursor di paginazione restituito da una chiamata precedente
  • limit number dimensione pagina (default 20)

Prompt di esempio

"Quali chiavi di traduzione mancano per ja nel namespace checkout?"

propose_translation Invia un valore di traduzione per una chiave in una lingua target. Sempre scritto come draft; un reviewer umano lo promuove dopo — Verbumia è il manager, non il motore.

Args

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

Prompt di esempio

"Proponi \"Confirmer la commande\" per checkout.review.confirm in fr-CA."

validate_translations Linta un payload JSON i18next prima del push: parità dei placeholder ICU, chiavi mancanti/in eccesso, drift di tipo tra locali.

Args

  • project_uuid string required
  • language_code string required
  • payload object required mappa di traduzioni in forma JSON i18next

Prompt di esempio

"Valida questo file di traduzione contro la sorgente inglese del progetto."

Verifica che funzioni

  1. 1 Riavvia Claude Desktop completamente (chiudi, rilancia — la config viene letta all'avvio).
  2. 2 Apri una nuova chat. L'icona del martello deve mostrare verbumia con 5 tool disponibili.
  3. 3 Scrivi "List my Verbumia projects." L'agente dovrebbe chiamare list_projects e restituire i tuoi workspace.

Bloccato? Controlla i log di Claude Desktop in ~/Library/Logs/Claude/mcp*.log (macOS). Il 90% dei problemi sono typo nel JSON o un token scaduto.

Prossimo

Avvio rapido
React + i18next
Cattura chiavi mancanti a runtime, end-to-end.
Riferimento
Tutte le docs
CLI, riferimento API (in corso).