verbatra mcp

Arranca un servidor Model Context Protocol por stdio: el transporte estándar de proceso local que usan los clientes MCP (Claude Desktop, Claude Code, Cursor y otros) para lanzar un servidor de herramientas y hablar con él. Le da a un agente alojado en terminal o headless las mismas capacidades de estado de traducción, glosario y edición que exponen las herramientas de agente del navegador de Studio, sin navegador, sin puerto y sin servir una aplicación de una sola página.

Sinopsis

verbatra mcp [flags]

@verbatra/mcp también incluye su propio binario, así que un cliente MCP puede lanzarlo directamente sin pasar por la CLI de verbatra:

verbatra-mcp [flags]

Ambas formas aceptan los mismos tres flags y arrancan el mismo servidor, pero lo que lo rodea difiere:

• verbatra mcp carga .env.local y luego .env desde el directorio de trabajo antes de arrancar; verbatra-mcp no carga ninguno de los dos, así que pasa cualquier clave de API en el entorno con el que lo lanza el cliente MCP.
• verbatra mcp rechaza un flag desconocido como error de uso y sale con 2; verbatra-mcp ignora los flags desconocidos.
• Un error de arranque o de configuración sale con 2 desde verbatra mcp y con 1 desde verbatra-mcp.
• verbatra mcp se detiene a la fuerza con el código de salida 130 ante una segunda interrupción durante el apagado; verbatra-mcp no tiene esa vía.

Flags

Cuando falta --allow-spend, el servidor lee en su lugar la variable de entorno VERBATRA_MCP_ALLOW_SPEND: 1, true, yes u on (sin distinguir mayúsculas) cuenta como activado. El flag de la CLI siempre gana sobre la variable de entorno. Sin ninguno de los dos, translation.retranslateEntry y translation.translatePending no se exponen en absoluto: un cliente MCP que liste las herramientas nunca las ve, y llamarlas por nombre falla como herramienta desconocida. Esta es una garantía por proceso, no una comprobación por llamada, así que una herramienta bloqueada por gasto es estructuralmente imposible de llamar, no simplemente rechazada en el momento de la llamada.

Configurar un cliente MCP

Apunta tu cliente MCP al binario verbatra-mcp. Para Claude Desktop, añade esto a tu 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"
      }
    }
  }
}

Omite por completo el bloque env y su --allow-spend para un servidor solo de lectura y edición local: project.snapshot, las herramientas de estado y glosario, y translation.editEntry nunca llaman a un proveedor ni necesitan una clave. Añade --allow-spend al array args en cuanto también quieras translation.retranslateEntry y translation.translatePending disponibles, y define la variable de entorno de la clave de API que lee tu proveedor configurado (consulta Proveedores).

Si ya invocas todo a través de la CLI de verbatra, ejecútalo como subcomando en su lugar:

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

Herramientas

translation.retranslateEntry y translation.translatePending solo se exponen cuando el servidor se inició con --allow-spend. La entrada de cada herramienta, y la salida de cada herramienta cuya forma de resultado es pequeña y cerrada, es un JSON Schema derivado del mismo esquema zod contra el que el servidor valida la llamada. Llamar a un nombre de herramienta desconocido es un error a nivel de protocolo; llamar a una herramienta conocida con una entrada que falla la validación devuelve un resultado que nombra el campo problemático, así que un agente puede leer el fallo y autocorregirse.

Los dos escritores de entradas, translation.editEntry y translation.retranslateEntry, están además protegidos por herramienta, locale y clave: mientras una llamada para una entrada sigue en curso, una segunda llamada a la misma herramienta que nombre el mismo locale y la misma key no se encola ni se ejecuta en paralelo. Recibe un resultado isError cuyo texto indica que ya hay una llamada equivalente en curso, así que dos agentes (o un agente que reintenta) no pueden competir por la misma entrada a través de la misma herramienta. Las llamadas para otras claves u otros locales siguen ejecutándose a la vez. translation.translatePending no tiene esa protección.

Entradas y resultados

• status.check, status.diff y key.integrity aceptan un array locales opcional (con al menos una entrada) que limita el resultado a esos locales; key.integrity también recibe la key que se va a comprobar.
• translation.editEntry recibe locale, key y value, con value limitado a 20.000 caracteres.
• glossary.write recibe { term, translation }, con term limitado a 200 caracteres y translation a 2.000; translation: null elimina el término. Necesita un glosario respaldado por archivo (la clave glossary de la configuración apuntando a un archivo JSON); un glosario en línea, o no tener ninguno, falla con GLOSSARY_NOT_FILE_BACKED.
• translation.editEntry y translation.retranslateEntry devuelven { accepted, value, reason?, details? }. Un valor rechazado lleva reason, uno de placeholder, markup, icu, degenerate o empty, y details nombrando lo que falló; translation.retranslateEntry añade reviewReasons a un resultado aceptado: las señales de las heurísticas de revisión para el nuevo valor, vacío cuando no saltó ninguna.
• lock.state devuelve exists y, cuando el archivo de bloqueo existe, su version y, por locale, los recuentos keyCount, missing, stale y upToDate.
• usage.summary devuelve el usage de la última ejecución y, cuando se configuró un presupuesto de tokens, un budget cuyo standing es within, stopped-before-ceiling o reached, y cuyo supported indica si la cifra contada es en su totalidad el uso que informó el propio proveedor.

Las comprobaciones de marcado en línea en key.integrity (markupMatches, markupDetails) y en translation.editEntry (el motivo markup), un id de formato custom: en project.snapshot y budget.standing en usage.summary llegaron en esta versión.

Redacción de secretos

Cada resultado de herramienta y cada línea de log pasa por la misma redacción de secretos que usa Studio: un valor con forma de clave de API de proveedor, o el valor exacto actual de una variable de entorno de proveedor configurada, se reemplaza por [REDACTED] antes de llegar siquiera al cliente o a stderr. glossary.get y glossary.write también informan de qué términos se redactaron, así que puedes distinguir un placeholder redactado del texto real y no volver a escribirlo nunca.

stdout es el canal del protocolo

El transporte stdio de MCP usa stdout exclusivamente para mensajes de protocolo. verbatra mcp y verbatra-mcp nunca imprimen un banner, una línea de log ni nada más en stdout; todo log y diagnóstico va a stderr en su lugar. El servidor carga la configuración antes de conectar el transporte, así que un error de configuración se escribe en stderr de inmediato y el proceso sale sin llegar a hablar el protocolo. Una vez en marcha, los diagnósticos por llamada (una llamada fallida, una llamada rechazada porque ya hay una equivalente en curso, una herramienta desconocida) también van a stderr.

Instalación

@verbatra/mcp es un paquete aparte, al que se llega mediante un import dinámico para que el resto de la CLI funcione sin él. Si no está instalado, verbatra mcp sale con 2 y este mensaje:

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

Ejecutar verbatra-mcp directamente no necesita la CLI en absoluto: instala @verbatra/mcp por separado, o deja que npx lo obtenga bajo demanda como se muestra arriba.

Ejemplos

# 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

Códigos de salida

Estos son los códigos de salida de verbatra mcp; el verbatra-mcp independiente difiere como se describe en la sinopsis de arriba.

Relacionado

• verbatra studio y Opera Studio con un agente del navegador cubren la superficie de agente basada en navegador que este servidor complementa.
• Proveedores documenta de qué variable de entorno lee cada proveedor su clave de API.
• verbatra check y verbatra diff son los mismos cálculos que exponen status.check y status.diff.