Referência / CLI
Página traduzida automaticamente
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/mcptraz, 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.enve imprime a versão do@verbatra/mcppara--version.- Os dois saem com
2diante de uma flag desconhecida, de um valor de flag ausente ou de um argumento solto. Overbatra-mcpfaz isso, e aceita-he-V, com o@verbatra/mcp0.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/projectFlags
| Flag | Argumento | Padrão | Efeito |
|---|---|---|---|
--allow-spend | nenhum | VERBATRA_, caso contrário desativado | anuncia as duas ferramentas que chamam um provedor de tradução; veja Ferramentas pagas |
--redact-values | nenhum | VERBATRA_, caso contrário desativado | substitui 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_; veja Diretório do projeto.
Comportamento
Diretório do projeto
Quando --cwd está ausente e CLAUDE_ 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_ 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_ 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
| Ferramenta | O que faz | Somente leitura | Chama um provedor |
|---|---|---|---|
project.snapshot | a configuração resolvida: configured, configSource, locales, formato, files.pattern, provedor, glossário, humanEdits, prune, valuesRedacted | sim | não |
project.doctor | todas as verificações de configuração com o status, o detail e, quando falhou, um fix | sim | não |
status.check | contagem por locale de chaves ausentes, obsoletas e em dia | sim | não |
status.diff | lista por locale das chaves que seriam adicionadas, retraduzidas ou órfãs | sim | não |
glossary.get | todos os termos do glossário com as traduções, as traduções proibidas e o contexto, com os segredos ocultados | sim | não |
glossary.write | altera um termo do glossário: uma tradução, dados por locale, o contexto ou se ele continua sem tradução | não | não |
lock.state | a versão do arquivo de lock e, por locale de destino, a contagem de chaves mais as contagens de ausentes, obsoletas e em dia | sim | não |
history.list | commits recentes do git que tocam um arquivo de locale, com autor, data, assunto e caminhos | sim | não |
history.keyRevisions | as revisões do git de uma chave em um locale, com diff por palavra novo | sim | não |
key.integrity | a 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 locale | sim | não |
locale.integrity | toda tradução que falha agora nas verificações de placeholder, marcação ou ICU, por locale | sim | não |
key.value | o texto de origem e de destino atuais de uma chave, com a procedência e o contexto do tradutor | sim | não |
key.context | o que key.value retorna, mais os termos do glossário que se aplicam, o maxLength e a verificação de um draft opcional | sim | não |
locale.values | o texto de origem e de destino de várias chaves, filtrado por keys ou query, página por página | sim | não |
translation.editEntry | grava uma tradução manual para uma chave em um locale, condicionada às verificações de integridade | não | não |
translation.estimate | o que translation.translatePending enviaria e custaria, como translate --estimate | sim | não |
translation.retranslateEntry | pede ao provedor configurado que retraduza uma chave em um locale | não | sim |
translation.translatePending | traduz toda chave ausente ou obsoleta, opcionalmente só para alguns locales e dentro de um teto maxTokens | não | sim |
review.queue | todo valor escrito por máquina que ninguém aprovou ainda, com as sinalizações da última execução | sim | não |
report.provenance | contagens de procedência por locale, como o verbatra report provenance as fornece, mais chaves paginadas sob demanda | sim | não |
review.approve | registra, por instrução do usuário, que uma pessoa identificada aprova a tradução atual de uma chave | não | não |
review.reject | registra, por instrução do usuário, que uma pessoa identificada rejeita a tradução de uma chave e a remove | não | não |
usage.summary | o uso de tokens e o status do orçamento da última execução | sim | não |
usage.history | execuções recentes, custo e cobertura novo | sim | não |
- Uma chamada por vez. Uma segunda chamada da mesma ferramenta para a mesma entrada (
translation.editEntry,translation.retranslateEntry), ou uma segunda execução detranslation.translatePending, é recusada comisErrorenquanto a primeira está em andamento. - Trabalho humano.
translation.retranslateEntryrecusa uma chave fixada comKEY_e, a menos quePINNED humanEdits: "overwrite", o valor de uma pessoa comKEY_;PROTECTED translation.editEntryrecusa uma chave fixada.translation.translatePendinglista essas chaves emprotected. Veja Manter traduções humanas. - Procedência. Um valor gravado por
translation.editEntryrecebeoriginagent.review.queueé a mesma fila que o Studio mostra: todo valormachine,memory,fuzzyouagentnão aprovado. Veja Decisões de revisão. - Decisões de revisão.
review.approveereview.rejectaceitamlocale,key,expectedValueouexpectedHash(um valor alterado é recusado comREVIEW_) e um nome deVALUE_ CHANGED reviewer. Uma aprovação vale paraverbatra check --require-reviewed.
Entradas e resultados
status.check,status.diffekey.integrityaceitam um arraylocalesopcional;key.integrityaceita também akey.key.integrityretorna{ locales: [{ locale, entries }] }, cada entrada commatches,missing,extra,icuValid,markupMatchese os detalhes deles.translation.editEntryaceitalocale,keye umvaluede até 20.000 caracteres. Ele retorna{ accepted, value, reason?, details? }, etranslation.retranslateEntryo mesmo maisreviewReasons?eusage?, em quereasonéplaceholder,markup,icu,degenerateouempty.glossary.writeexige um glossário baseado em arquivo, caso contrário falha comGLOSSARY_; um termo que difere apenas em maiúsculas e minúsculas atualiza o que está armazenado.NOT_ FILE_ BACKED
Mais entradas e resultados
translation.estimate,locale.integrity,locale.valuesereport.provenanceaceitam o mesmo arraylocalesopcional, ekey.integrityfalha comUNKNOWN_para uma chave desconhecida.KEY - Cada entrada de
key.integritytraz tambémicuArmsMatche os detalhes dela. glossary.getaceita umlocaleopcional e então acrescentaeffective, os termos a que aquele locale está sujeito.key.value,lock.state,status.checkestatus.difftrazem a procedência, omitida quando overbatra.provenance.jsonnão pode ser lido.locale.valuesereport.provenancepaginam as entradas na ordem das chaves de origem:limit(padrão 200, no máximo 1.000) e depois onextCursorda página anterior comocursor. Uma página lista só os locales para os quais tem entradas, e um cursor obsoleto falha como entrada inválida.locale.valuesaceitakeysou umquerysem diferenciar maiúsculas de minúsculas e retorna arrays de entradas, não o mapa de chaves do Studio.report.provenancesempre retorna contagens completas;includeEntriesacrescenta as chaves, opcionalmente para algunsbuckets.history.listaceitalimit(padrão 50, no máximo 200). Comavailable: false, oreasondele égit-missing,not-a-repository,bare-repository,dubious-ownership,timeout,output-too-large,unsafe-configougit-too-old.usage.historyaceitalimit, o número de execuções mais recentes (padrão 50, no máximo 200) novo.history.keyRevisionsaceitalocale,key(no máximo 1.024 caracteres) elimit, o número de commits examinados (padrão 50, no máximo 200) novo.usage.summarylê apenas a última execução (usage.historylista as anteriores), omiteusagequando essa execução não informou nenhum e traz os campos de orçamento apenas sob um orçamentomaxTokens.budget.supported: falsesignifica que uma requisição não informou uso ou falhou;tokensUsedentã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émincomplete: { 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
lockTimeoutMsopcional, de0a600000, padrão30000: por quanto tempo esperar por uma trava de escrita ocupada antes de falhar comLOCK_, sem gravar nada.CONTENDED - 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
outputSchemadele falha comOUTPUT_; se vier de uma ferramenta de escrita, a alteração já foi aplicada, então não tente de novo.SCHEMA_ MISMATCH - O texto de uma chamada com falha começa com o código de erro dela, como
UNKNOWN_, e termina com uma linhaKEY: ... Next step: ...quando o erro tem uma, o mesmo texto dohintda CLI.
Estimar e depois gastar
translation.estimate é sempre listada. translation.translatePending aceita locales opcional (um não configurado falha com UNKNOWN_ 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:
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 validDepois 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_. 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_ definida com um valor que VERBATRA_ 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:
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:
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/mcpCada versão também está no MCP Registry oficial como io.github.verbatra/verbatra.
Códigos de saída
| Código | Significado |
|---|---|
0 | encerrado de forma limpa por uma única interrupção, ou porque o cliente fechou o stdin |
1 | o fechamento do servidor falhou durante o encerramento |
2 | não foi possível iniciar: um arquivo --config ausente, um @verbatra/mcp ausente ou, com --redact-values, antigo demais, ou um erro de uso |
130 | encerrado à 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
- Conectar um cliente MCP configura os clientes stdio.
- Operar o Studio com um agente de navegador: a contraparte no navegador das ferramentas deste servidor.
verbatra checkeverbatra diffsustentamstatus.checkestatus.diff.