Saltar al contenido
Verbumia
Empezar gratis

MCP

Referencia API

Verbumia incluye un servidor MCP nativo para que cualquier cliente compatible con MCP — Claude Desktop, Cursor, tu propio agente — pueda buscar claves, proponer traducciones, revisar PRs e inspeccionar la cola de claves faltantes. Dos líneas de config, tu token, listo.

1. Obtén una API key

En tu dashboard, ve a Org Settings → API Keys → Create. Asígnale el scope mcp:* (cubre las cinco herramientas de abajo). El secret se muestra una sola vez; copia la cadena completa vrb_live_<prefix>.<secret>.

Guárdala en el llavero del SO o en un .env local — nunca la commitees. La key está ligada a tu org (y opcionalmente a un proyecto); las llamadas fuera de ese scope devuelven 404. Revoca desde el dashboard cuando quieras; las keys revocadas devuelven 401 en la siguiente llamada.

2. Instala (o sáltatelo)

El servidor MCP se publica en npm y Homebrew. Con npx no necesitas instalar nada — Claude Desktop tira de la última versión en cada arranque. Con brew obtienes un binario local fijado, útil tras firewalls estrictos.

npx (recomendado) 
1// sin instalación — npx tira de la última @verbumia/mcp bajo demanda2npx -y @verbumia/mcp --version
Homebrew (alternativa) Tap se publica en V1 
1// opcional: instalar globalmente una vez — llega con el lanzamiento V12brew install verbumia/tap/verbumia-mcp

3. Conecta Claude Desktop

Abre el archivo de config de Claude Desktop, añade la entrada verbumia bajo mcpServers, luego cierra y vuelve a abrir la 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}

Tres variables de entorno en total: VERBUMIA_TOKEN (obligatoria), VERBUMIA_PROJECT (opcional — pre-fija un proyecto para que el agente no tenga que llamar a list_projects primero) y VERBUMIA_API_BASE (opcional — por defecto https://api.verbumia.ca; sobrescríbela para self-hosted o staging).

Cursor (y otros clientes MCP)

Mismo JSON, archivo distinto. En Cursor, ponlo en .cursor/mcp.json (scope de proyecto) o ~/.cursor/mcp.json (scope de usuario). Para otros clientes, sigue la doc de configuración MCP de tu cliente — la entrada mcpServers.verbumia es 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}

Las 5 herramientas V1

Una vez configurado, el agente dispone de estas herramientas. No las llamas por nombre — describe tu intención en el chat y el agente las elige. Los nombres de abajo son los identificadores canónicos, útiles al leer trazas del agente o construir agentes propios sobre el mismo servidor.

list_projects Enumera los proyectos a los que la API key actual tiene acceso. Útil para elegir un workspace al inicio de un chat.

Args

  • limit number límite opcional sobre el número de proyectos devueltos

Prompt de ejemplo

"Lista mis proyectos de Verbumia."

get_project_info Obtén metadatos del proyecto: idioma fuente, idiomas destino, namespaces, total de claves.

Args

  • project_uuid string required

Prompt de ejemplo

"¿Qué idiomas y namespaces lleva el proyecto Checkout?"

list_missing_keys Lista los eventos pendientes de claves faltantes capturados por el SDK en runtime (paginado por cursor). Filtra por namespace o idioma.

Args

  • project_uuid string required
  • namespace string limita a un namespace (p. ej. "checkout")
  • language_code string limita a un idioma (p. ej. "ja")
  • cursor string cursor de paginación devuelto por una llamada previa
  • limit number tamaño de página (default 20)

Prompt de ejemplo

"¿Qué claves de traducción faltan para ja en el namespace checkout?"

propose_translation Envía un valor de traducción para una clave en un idioma destino. Siempre se escribe como draft; un revisor humano la promueve después — Verbumia es el gestor, no el motor.

Args

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

Prompt de ejemplo

"Propón \"Confirmer la commande\" para checkout.review.confirm en fr-CA."

validate_translations Lintea un payload JSON i18next antes de pushear: paridad de placeholders ICU, claves faltantes/sobrantes, drift de tipos entre locales.

Args

  • project_uuid string required
  • language_code string required
  • payload object required mapa de traducciones con forma JSON i18next

Prompt de ejemplo

"Valida este archivo de traducción contra la fuente inglesa del proyecto."

Verificar que funciona

  1. 1 Reinicia Claude Desktop completamente (cierra, relanza — la config se lee al arranque).
  2. 2 Abre un chat nuevo. El icono del martillo debe mostrar verbumia con 5 herramientas disponibles.
  3. 3 Escribe "List my Verbumia projects." El agente debería llamar a list_projects y devolver tus workspaces.

¿Atascado? Revisa los logs de Claude Desktop en ~/Library/Logs/Claude/mcp*.log (macOS). El 90% de los problemas son typos en el JSON o un token caducado.

Siguiente

Inicio rápido
React + i18next
Captura claves faltantes en runtime, de extremo a extremo.
Referencia
Todas las docs
CLI, referencia API (en curso).