Saltar para o conteúdo
Verbumia
Começar grátis

MCP

Referência API

O Verbumia inclui um servidor MCP nativo para que qualquer cliente compatível com MCP — Claude Desktop, Cursor, o teu próprio agente — possa procurar chaves, propor traduções, rever PRs e inspecionar a fila de chaves em falta. Duas linhas de config, o teu token, pronto.

1. Obtém uma API key

No teu dashboard, vai a Org Settings → API Keys → Create. Atribui-lhe o scope mcp:* (cobre as cinco ferramentas abaixo). O secret é mostrado uma única vez; copia a string completa vrb_live_<prefix>.<secret>.

Guarda-a no keychain do teu SO ou num .env local — nunca a faças commit. A key está ligada à tua org (e opcionalmente a um projeto); chamadas fora desse scope devolvem 404. Revoga a partir do dashboard quando quiseres; keys revogadas devolvem 401 na chamada seguinte.

2. Instala (ou salta)

O servidor MCP é publicado no npm e no Homebrew. Com npx não precisas de instalar nada — o Claude Desktop puxa a versão mais recente a cada arranque. Com brew obténs um binário local fixo, útil atrás de firewalls restritivos.

npx (recomendado) 
1// sem instalação — npx puxa o último @verbumia/mcp a pedido2npx -y @verbumia/mcp --version
Homebrew (alternativa) Tap publica no V1 
1// opcional: instala globalmente uma vez — chega com o lançamento V12brew install verbumia/tap/verbumia-mcp

3. Liga o Claude Desktop

Abre o ficheiro de config do Claude Desktop, adiciona a entrada verbumia sob mcpServers, depois fecha e relança a 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}

Três variáveis de ambiente no total: VERBUMIA_TOKEN (obrigatória), VERBUMIA_PROJECT (opcional — pré-define um projeto para que o agente não tenha de chamar list_projects primeiro) e VERBUMIA_API_BASE (opcional — por defeito https://api.verbumia.ca; sobrescreve para self-hosted ou staging).

Cursor (e outros clientes MCP)

Mesmo JSON, ficheiro diferente. No Cursor, coloca-o em .cursor/mcp.json (scope de projeto) ou ~/.cursor/mcp.json (scope de utilizador). Para outros clientes, segue a doc de configuração MCP do teu cliente — a entrada mcpServers.verbumia é idêntica.

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

As 5 ferramentas V1

Uma vez configurado, o agente tem estas ferramentas disponíveis. Não as chamas por nome — descreve a tua intenção no chat e o agente escolhe. Os nomes abaixo são os identificadores canónicos, úteis ao ler traces do agente ou ao construir agentes próprios sobre o mesmo servidor.

list_projects Enumera os projetos a que a API key atual tem acesso. Útil para escolher um workspace no início de um chat.

Args

  • limit number limite opcional ao número de projetos devolvidos

Prompt de exemplo

"Lista os meus projetos Verbumia."

get_project_info Vai buscar os metadados do projeto: língua de origem, línguas de destino, namespaces, total de chaves.

Args

  • project_uuid string required

Prompt de exemplo

"Que línguas e namespaces tem o projeto Checkout?"

list_missing_keys Lista os eventos pendentes de chaves em falta capturados pelo SDK em runtime (paginado por cursor). Filtra por namespace ou língua.

Args

  • project_uuid string required
  • namespace string restringe a um namespace (p. ex. "checkout")
  • language_code string restringe a uma língua (p. ex. "ja")
  • cursor string cursor de paginação devolvido por uma chamada anterior
  • limit number tamanho da página (default 20)

Prompt de exemplo

"Que chaves de tradução faltam para ja no namespace checkout?"

propose_translation Submete um valor de tradução para uma chave numa língua de destino. Sempre escrito como draft; um revisor humano promove-o depois — o Verbumia é o gestor, não o motor.

Args

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

Prompt de exemplo

"Propõe \"Confirmer la commande\" para checkout.review.confirm em fr-CA."

validate_translations Faz lint de um payload JSON i18next antes do push: paridade dos placeholders ICU, chaves em falta/a mais, drift de tipo entre locales.

Args

  • project_uuid string required
  • language_code string required
  • payload object required mapa de traduções em formato JSON i18next

Prompt de exemplo

"Valida este ficheiro de tradução contra a fonte inglesa do projeto."

Verificar que funciona

  1. 1 Reinicia o Claude Desktop por completo (sai, relança — a config é lida no arranque).
  2. 2 Abre um novo chat. O ícone do martelo deve mostrar verbumia com 5 ferramentas disponíveis.
  3. 3 Escreve "List my Verbumia projects." O agente deve chamar list_projects e devolver os teus workspaces.

Empancado? Verifica os logs do Claude Desktop em ~/Library/Logs/Claude/mcp*.log (macOS). 90% dos problemas são typos no JSON ou um token caducado.

Seguinte

Início rápido
React + i18next
Captura chaves em falta em runtime, ponta a ponta.
Referência
Todas as docs
CLI, referência API (em curso).