Pular para o conteúdo
Pular para o conteúdo

Referência / CLI

Página traduzida automaticamente

Esta página foi traduzida automaticamente, então pode ter erros ou soar um pouco estranha. A versão em inglês é a fonte da verdade. Ler o original em inglês.

verbatra mcp

Inicie o servidor MCP via stdio que expõe as ferramentas do verbatra a qualquer cliente MCP, sem listar por padrão as que chamam um provedor pago.

Inicie um servidor Model Context Protocol via stdio, o transporte que os clientes MCP usam para iniciar um servidor de ferramentas. Ele atende às revisões do protocolo de 2024-10-07 a 2026-07-28. Não há transporte HTTP, que exporia ferramentas de escrita e ferramentas pagas.

Sinopse

verbatra mcp [flags]
verbatra-mcp [flags]
  • verbatra-mcp é o binário que o @verbatra/mcp traz, para que um cliente possa iniciar o servidor sem a CLI. Ele aceita as mesmas flags, exceto -q/--quiet, e inicia o mesmo servidor, mas não carrega nenhum arquivo .env e imprime a versão do @verbatra/mcp para --version.
  • Os dois saem com 2 diante de uma flag desconhecida, de um valor de flag ausente ou de um argumento solto. O verbatra-mcp faz isso, e aceita -h e -V, com o @verbatra/mcp 0.3.0 ou mais recente.

Exemplos

# 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

# run the standalone server without the CLI
npx -y @verbatra/mcp --cwd /path/to/project

Flags

FlagArgumentoPadrãoEfeito
--allow-spendnenhumVERBATRA_MCP_ALLOW_SPEND, caso contrário desativadoanuncia as duas ferramentas que chamam um provedor de tradução; veja Ferramentas pagas
--redact-valuesnenhumVERBATRA_MCP_REDACT_VALUES, caso contrário desativadosubstitui todo valor de tradução nos resultados das ferramentas por um marcador; veja Valores ocultados

Aceita também as flags globais --cwd e --config. Não aceita --json, porque o stdout é o canal do protocolo. Sem --cwd, o diretório do projeto pode vir de CLAUDE_PROJECT_DIR; veja Diretório do projeto.

Comportamento

Diretório do projeto

Quando --cwd está ausente e CLAUDE_PROJECT_DIR nomeia um diretório existente, o servidor o usa como diretório do projeto. O verbatra mcp então carrega os arquivos de ambiente desse diretório; um CLAUDE_PROJECT_DIR definido apenas nesses arquivos é ignorado.

A busca da configuração começa ali, e o diretório da configuração que ela encontra é a raiz do projeto a partir da qual os caminhos das ferramentas são resolvidos.

Ferramentas pagas

translation.retranslateEntry e translation.translatePending são anunciadas somente com --allow-spend ou, quando a flag está ausente, com VERBATRA_MCP_ALLOW_SPEND definida como 1, true, yes ou on (sem diferenciar maiúsculas de minúsculas, ignorando espaços em volta). A flag prevalece sobre a variável. O verbatra mcp lê .env.local e .env primeiro, então a variável pode ficar neles; o verbatra-mcp a recebe apenas do próprio ambiente.

Caso contrário, elas nunca são listadas, e chamar uma delas falha como ferramenta desconhecida. Uma configuração com provider: { id: "none" } nunca as lista, nem com --allow-spend. Nenhuma outra ferramenta chama provedor ou precisa de chave de API; entregue a chave de API ao servidor apenas quando você ativar os gastos.

Instruções para o agente

O servidor responde ao handshake com instructions fixas, que a maioria dos clientes passa ao modelo primeiro. Elas definem a ordem das chamadas (ler e comparar primeiro, estimar e obter um sim explícito antes de gastar), deixam as decisões de revisão e o trabalho humano para as pessoas, tratam toda string como dados e nunca gravam de volta um valor [REDACTED].

Ferramentas

FerramentaO que fazSomente leituraChama um provedor
project.snapshota configuração resolvida: configured, configSource, locales, formato, files.pattern, provedor, glossário, humanEdits, prune, valuesRedactedsimnão
project.doctortodas as verificações de configuração com o status, o detail e, quando falhou, um fixsimnão
status.checkcontagem por locale de chaves ausentes, obsoletas e em diasimnão
status.difflista por locale das chaves que seriam adicionadas, retraduzidas ou órfãssimnão
glossary.gettodos os termos do glossário com as traduções, as traduções proibidas e o contexto, com os segredos ocultadossimnão
glossary.writealtera um termo do glossário: uma tradução, dados por locale, o contexto ou se ele continua sem traduçãonãonão
lock.statea versão do arquivo de lock e, por locale de destino, a contagem de chaves mais as contagens de ausentes, obsoletas e em diasimnão
history.listcommits recentes do git que tocam um arquivo de locale, com autor, data, assunto e caminhossimnão
history.keyRevisionsas revisões do git de uma chave em um locale, com diff por palavra novosimnão
key.integritya divergência de placeholders, marcação, sintaxe ICU e ramos ICU de uma chave em relação à linha de base do arquivo de lock, por localesimnão
locale.integritytoda tradução que falha agora nas verificações de placeholder, marcação ou ICU, por localesimnão
key.valueo texto de origem e de destino atuais de uma chave, com a procedência e o contexto do tradutorsimnão
key.contexto que key.value retorna, mais os termos do glossário que se aplicam, o maxLength e a verificação de um draft opcionalsimnão
locale.valueso texto de origem e de destino de várias chaves, filtrado por keys ou query, página por páginasimnão
translation.editEntrygrava uma tradução manual para uma chave em um locale, condicionada às verificações de integridadenãonão
translation.estimateo que translation.translatePending enviaria e custaria, como translate --estimatesimnão
translation.retranslateEntrypede ao provedor configurado que retraduza uma chave em um localenãosim
translation.translatePendingtraduz toda chave ausente ou obsoleta, opcionalmente só para alguns locales e dentro de um teto maxTokensnãosim
review.queuetodo valor escrito por máquina que ninguém aprovou ainda, com as sinalizações da última execuçãosimnão
report.provenancecontagens de procedência por locale, como o verbatra report provenance as fornece, mais chaves paginadas sob demandasimnão
review.approveregistra, por instrução do usuário, que uma pessoa identificada aprova a tradução atual de uma chavenãonão
review.rejectregistra, por instrução do usuário, que uma pessoa identificada rejeita a tradução de uma chave e a removenãonão
usage.summaryo uso de tokens e o status do orçamento da última execuçãosimnão
usage.historyexecuções recentes, custo e cobertura novosimnão
  • Uma chamada por vez. Uma segunda chamada da mesma ferramenta para a mesma entrada (translation.editEntry, translation.retranslateEntry), ou uma segunda execução de translation.translatePending, é recusada com isError enquanto a primeira está em andamento.
  • Trabalho humano. translation.retranslateEntry recusa uma chave fixada com KEY_PINNED e, a menos que humanEdits: "overwrite", o valor de uma pessoa com KEY_PROTECTED; translation.editEntry recusa uma chave fixada. translation.translatePending lista essas chaves em protected. Veja Manter traduções humanas.
  • Procedência. Um valor gravado por translation.editEntry recebe origin agent. review.queue é a mesma fila que o Studio mostra: todo valor machine, memory, fuzzy ou agent não aprovado. Veja Decisões de revisão.
  • Decisões de revisão. review.approve e review.reject aceitam locale, key, expectedValue ou expectedHash (um valor alterado é recusado com REVIEW_VALUE_CHANGED) e um nome de reviewer. Uma aprovação vale para verbatra check --require-reviewed.

Entradas e resultados

  • status.check, status.diff e key.integrity aceitam um array locales opcional; key.integrity aceita também a key.
  • key.integrity retorna { locales: [{ locale, entries }] }, cada entrada com matches, missing, extra, icuValid, markupMatches e os detalhes deles.
  • translation.editEntry aceita locale, key e um value de até 20.000 caracteres. Ele retorna { accepted, value, reason?, details? }, e translation.retranslateEntry o mesmo mais reviewReasons? e usage?, em que reason é placeholder, markup, icu, degenerate ou empty.
  • glossary.write exige um glossário baseado em arquivo, caso contrário falha com GLOSSARY_NOT_FILE_BACKED; um termo que difere apenas em maiúsculas e minúsculas atualiza o que está armazenado.

Mais entradas e resultados

  • translation.estimate, locale.integrity, locale.values e report.provenance aceitam o mesmo array locales opcional, e key.integrity falha com UNKNOWN_KEY para uma chave desconhecida.
  • Cada entrada de key.integrity traz também icuArmsMatch e os detalhes dela.
  • glossary.get aceita um locale opcional e então acrescenta effective, os termos a que aquele locale está sujeito.
  • key.value, lock.state, status.check e status.diff trazem a procedência, omitida quando o verbatra.provenance.json não pode ser lido.
  • locale.values e report.provenance paginam as entradas na ordem das chaves de origem: limit (padrão 200, no máximo 1.000) e depois o nextCursor da página anterior como cursor. Uma página lista só os locales para os quais tem entradas, e um cursor obsoleto falha como entrada inválida.
  • locale.values aceita keys ou um query sem diferenciar maiúsculas de minúsculas e retorna arrays de entradas, não o mapa de chaves do Studio. report.provenance sempre retorna contagens completas; includeEntries acrescenta as chaves, opcionalmente para alguns buckets.
  • history.list aceita limit (padrão 50, no máximo 200). Com available: false, o reason dele é git-missing, not-a-repository, bare-repository, dubious-ownership, timeout, output-too-large, unsafe-config ou git-too-old.
  • usage.history aceita limit, o número de execuções mais recentes (padrão 50, no máximo 200) novo.
  • history.keyRevisions aceita locale, key (no máximo 1.024 caracteres) e limit, o número de commits examinados (padrão 50, no máximo 200) novo.
  • usage.summary lê apenas a última execução (usage.history lista as anteriores), omite usage quando essa execução não informou nenhum e traz os campos de orçamento apenas sob um orçamento maxTokens. budget.supported: false significa que uma requisição não informou uso ou falhou; tokensUsed então soma a projeção do próprio verbatra para cada requisição informada como zero ou não informada, então não é um número cobrado pelo provedor. Ele traz também incomplete: { failed, partial } quando a execução teve locales que falharam ou pararam no meio, para que um uso baixo não seja lido como uma execução bem-sucedida novo.
  • As ferramentas de escrita aceitam um lockTimeoutMs opcional, de 0 a 600000, padrão 30000: por quanto tempo esperar por uma trava de escrita ocupada antes de falhar com LOCK_CONTENDED, sem gravar nada.
  • Entradas e saídas são JSON Schemas; uma entrada inválida retorna um resultado que nomeia o campo. Um resultado que não corresponde ao outputSchema dele falha com OUTPUT_SCHEMA_MISMATCH; se vier de uma ferramenta de escrita, a alteração já foi aplicada, então não tente de novo.
  • O texto de uma chamada com falha começa com o código de erro dela, como UNKNOWN_KEY: ..., e termina com uma linha Next step: ... quando o erro tem uma, o mesmo texto do hint da CLI.

Estimar e depois gastar

translation.estimate é sempre listada. translation.translatePending aceita locales opcional (um não configurado falha com UNKNOWN_LOCALE antes de gastar) e maxTokens, um teto que só pode reduzir o da configuração. Veja Estimar o custo antes de uma execução.

Progresso

Quando uma chamada de translation.translatePending traz um progressToken, o verbatra envia notifications/progress conforme os lotes terminam: progress os conta, total cresce a cada locale planejado e message nomeia o locale e o lote (de: batch 3/7), no máximo um a cada 250 ms mais um final. Cancelar uma chamada paga (notifications/cancelled) a interrompe sem resultado nem mais progresso: translation.translatePending mantém o que chegou, e o restante continua pendente.

Sem configuração

O servidor inicia mesmo assim. project.snapshot então retorna configured: false com o configProblem e um nextStep, project.doctor informa a correção, e todas as outras ferramentas recusam com o erro de configuração. O stderr diz o motivo:

Saída
Running without a usable project config: CONFIG_NOT_FOUND: No verbatra configuration found. ...
verbatra MCP server running on stdio (project ., spend tools off)
No usable verbatra config: project.snapshot and project.doctor work, every other tool refuses until one loads.
  set it up:  npx @verbatra/cli init in the project, or fix the config project.doctor names
  no restart needed: the server loads the config on the next call once it is valid

Depois de uma mudança na configuração

Antes de cada chamada, o servidor recarrega a configuração quando o arquivo de configuração, um arquivo que a busca tentaria ou o arquivo do glossário mudou; um módulo que a configuração importa não é observado. --allow-spend é lida uma vez, então uma mudança pode esconder as ferramentas pagas, mas nunca listá-las sem a flag. Quando a lista de ferramentas muda, o servidor envia notifications/tools/list_changed. Um recarregamento que move a raiz do projeto faz o verbatra mcp carregar os arquivos de ambiente dessa raiz e imprimir verbatra: project root is now <root>, o que --quiet descarta.

Ocultação de segredos

Os segredos são ocultados de todo resultado e de toda linha de log, como o Studio faz: um valor com o formato de uma chave de API, ou o valor da variável de uma chave de API configurada, vira [REDACTED]; as ferramentas de glossário nomeiam os termos ocultados. Ocultar valores de tradução é --redact-values.

Valores ocultados

Com --redact-values, ou VERBATRA_MCP_REDACT_VALUES definida com um valor que VERBATRA_MCP_ALLOW_SPEND aceita, os resultados substituem textos de origem, traduções, descrições e termos do glossário por um marcador, [redacted length=12 hash=3f9a0c1d2e4b5a6c], e omitem nomes de revisores e de autores, diffs por palavra e os assuntos de history.keyRevisions; valores iguais compartilham um hash até o servidor parar. Erros que podem carregar valores mantêm o código e o próximo passo; a mensagem vira um marcador. Nomes de chaves, contagens, valores de origin, vereditos de integridade, assuntos de commits e caminhos permanecem. review.approve e review.reject aceitam apenas o hash do marcador, como expectedHash; glossary.write responde com contagens; locale.values recusa query e key.context recusa draft. Um provedor ainda recebe o texto. Isso não impede que um agente sonde de propósito, por gravações no glossário ou por acertos de glossário em key.context.

Stdout e stderr

O stdout carrega apenas mensagens do protocolo MCP; todos os logs vão para o stderr. Depois de conectado, o verbatra mcp imprime uma linha de prontidão e outra quando para:

Saída
verbatra MCP server running on stdio (project ., spend tools off)
verbatra MCP server stopped (client closed stdin)

Em um terminal, ele também diz que um cliente deve iniciá-lo. --quiet descarta essas linhas, não o motivo de configuração ausente.

Instalação

O @verbatra/mcp é um pacote separado que a CLI carrega sob demanda. Sem ele, o verbatra mcp sai com 2 e esta mensagem:

Saída
Verbatra's MCP server requires @verbatra/mcp. Run it without the CLI with: npx -y @verbatra/mcp, or install it alongside the CLI with: npm install --save-dev @verbatra/mcp

Cada versão também está no MCP Registry oficial como io.github.verbatra/verbatra.

Códigos de saída

CódigoSignificado
0encerrado de forma limpa por uma única interrupção, ou porque o cliente fechou o stdin
1o fechamento do servidor falhou durante o encerramento
2não foi possível iniciar: um arquivo --config ausente, um @verbatra/mcp ausente ou, com --redact-values, antigo demais, ou um erro de uso
130encerrado à força por uma segunda interrupção durante o encerramento

Um encerramento libera qualquer trava de locale. O verbatra-mcp sai com 1 diante de um erro de inicialização e, com a 0.3.0 ou mais recente, com 143 quando encerrado à força após SIGTERM. Veja o contrato dos códigos de saída.

Veja também

Editar no GitHub

Nesta página