Woovi Pix MCP

Servidor MCP local em Go para consultar e, opcionalmente, criar cobranças Pix Woovi. A ferramenta pix_create_charge fica desativada por padrão. Não há Pix Out, transferências, reembolsos ou cancelamentos financeiros.

Stack: Go 1.27.3, MCP Go SDK v1.8.0, SQLite embutido e Goose v3 para migrações SQL. Quando escrita está habilitada, o servidor cria o banco privado e aplica as migrações ao iniciar. Não requer PostgreSQL nem Docker.

CLI local: setup, perfis, stdio, doctor, instalação segura em clientes JSON e Litestream opcional. Transporte remoto, distribuição pública e operações Pix Out estão fora do escopo. Validação externa no sandbox Woovi ainda não realizada.

Licença

Copyright 2026 Lucas Eufrasio e contribuidores. Licenciado sob a Apache License 2.0.

Projeto independente, não oficial da Woovi. A licença cobre o código deste repositório, não concede direitos sobre marcas de terceiros e não substitui os termos de uso da API Woovi. Dependências mantêm suas próprias licenças.

Related MCP server: refund-mcp-server

Configurar pela CLI

go build -o ./bin/woovi-pix-mcp ./cmd/woovi-pix-mcp
./bin/woovi-pix-mcp setup --profile sandbox
./bin/woovi-pix-mcp doctor --profile sandbox

O assistente interativo permite selecionar entre sandbox (https://api.woovi-sandbox.com), produção (https://api.woovi.com) e o simulador local (http://127.0.0.1:8081), informa o identificador estável da conta e mantém criação de cobranças desativada por padrão. O AppID é digitado mascarado e salvo no cofre de credenciais do sistema. Se o cofre não estiver disponível, o setup falha: não há fallback silencioso. Use setup --profile sandbox --secret-file somente se aceitar guardar o segredo sem criptografia em arquivo restrito ao usuário. Permissões POSIX são validadas; ACLs Windows ainda precisam validação antes de recomendar esse fallback lá. Perfis existentes não são sobrescritos: use outro nome para nova configuração.

Configure seu cliente com o caminho absoluto do binário e argumentos ["stdio", "--profile", "sandbox"]. Não inclua AppID na configuração do cliente. doctor é diagnóstico local; não chama Woovi nem cria cobrança.

Instalar

No Linux ou macOS, instale a release mais recente em ~/.local/bin:

curl -fsSL https://github.com/lucaswilliameufrasio/woovi-pix-mcp/releases/latest/download/woovi-pix-mcp-installer.sh | sh

Para instalar uma versão específica, baixe o instalador da release e informe a tag. Exemplo com v0.1.2:

curl -fsSL https://github.com/lucaswilliameufrasio/woovi-pix-mcp/releases/download/v0.1.2/woovi-pix-mcp-installer.sh | sh -s -- --tag v0.1.2

No Windows PowerShell, para a release mais recente:

Invoke-WebRequest https://github.com/lucaswilliameufrasio/woovi-pix-mcp/releases/latest/download/woovi-pix-mcp-installer.ps1 -OutFile woovi-pix-mcp-installer.ps1
.\woovi-pix-mcp-installer.ps1

Passe -Tag v0.1.2 para fixar uma versão no Windows. Os instaladores verificam o SHA-256 do pacote antes da instalação. É necessário adicionar ~/.local/bin ao PATH se ainda não estiver configurado.

profiles lista os nomes configurados sem carregar ou exibir credenciais. O identificador de conta precisa ser estável e corresponder à conta do AppID: o servidor não consegue verificar isso offline. Dois perfis da mesma conta e ambiente compartilham o histórico de idempotência, inclusive após trocar AppID.

Ao executar woovi-pix-mcp sem argumentos pela primeira vez em um terminal, sem as duas variáveis legadas completas, o CLI abre o assistente Bubble Tea para criar o perfil sandbox: use ↑/↓ para escolher o ambiente, Enter para avançar e Esc para cancelar. Depois de salvar, ele mostra os comandos para validar e conectar o cliente. Se já houver perfis, use profiles para escolher explicitamente; o perfil sandbox é iniciado automaticamente quando existir e nenhum par completo de variáveis de ambiente estiver configurado. Sem terminal, o CLI não solicita segredos: mostra como executar setup interativamente.

Instalar no cliente MCP

Sem --client, o CLI abre um seletor Bubble Tea com cinco clientes. O arquivo do projeto atual é sugerido; preview é o padrão e --apply salva com backup, preservando entradas alheias. Exemplo:

./bin/woovi-pix-mcp install-mcp --profile sandbox --client opencode --config ~/.config/opencode/opencode.json
./bin/woovi-pix-mcp install-mcp --profile sandbox --client opencode --config ~/.config/opencode/opencode.json --apply

Suporta OpenCode V2, Claude Code, Cursor, Codex CLI e Gemini CLI. JSONC, arquivos de configuração não privados ou symlinks são recusados; uma entrada diferente com o mesmo nome não é sobrescrita. Codex TOML recebe a entrada ao final para preservar comentários e tabelas existentes.

Comandos de desenvolvimento

make help lista os comandos disponíveis. Exemplos:

Para make fmt/make check, além de Go, instale golangci-lint 2.14.0, Python 3.12+ e uv. Ruff é resolvido na versão fixa 0.16.10. O lint também verifica espaçamento entre blocos Go; não basta passar no gofmt.

make test
make check
make migrate-create name=add_charge_metadata

Os testes usam arquivos SQLite reais temporários, inclusive processos separados. As novas migrations são timestamped e criadas pela Goose CLI. Não há target migrate-down/reset: a migration Down remove as tabelas de operação/auditoria e pode apagar evidência de idempotência.

Processo de release

Prepare Release abre um PR de changelog; após revisão/CI e merge, uma tag vX.Y.Z dispara Release, que repete os checks e cria um draft com binários Linux/macOS/Windows (amd64/arm64) e checksums SHA-256. Publicar o draft continua sendo uma decisão manual. Nenhuma release é disparada ao adicionar os workflows.

Veja docs/releases.md para configuração, preparação, tagueamento, verificação de artefatos e limitações de plataforma. Para validar o empacotamento local sem publicar: make release-snapshot (GoReleaser 2.18.2).

Executar

./bin/woovi-pix-mcp stdio --profile sandbox

Para compilar um binário local sem instalá-lo globalmente:

go build -o ./bin/woovi-pix-mcp ./cmd/woovi-pix-mcp

Execute o binário com stdio --profile sandbox para iniciar o servidor. Sem argumentos, a primeira execução em um terminal orienta a configuração. Se já houver um perfil sandbox, o comando sem argumentos inicia esse perfil; se houver apenas perfis com outros nomes, o CLI abre um seletor interativo. Em execuções sem terminal, escolha explicitamente com stdio --profile NAME. O diretório bin/ é apenas uma saída local e não deve ser versionado.

O AppID fica no processo servidor e nunca é um argumento ou resultado MCP. Logs operacionais vão para stderr; stdout fica reservado ao protocolo stdio. O host Woovi de produção é https://api.woovi.com, mas o servidor aceita apenas HTTPS para hosts remotos.

Criação é uma capacidade explicitamente opt-in. Requer identificador fixo da conta autorizada e limite máximo de R$ 100.000 por cobrança, sem banco externo:

No setup, responda yes somente se quiser habilitar criação. Para automação, o modo legado sem subcomando ainda aceita WOOVI_API_BASE_URL, WOOVI_APP_ID, WOOVI_ACCOUNT_ID e WOOVI_ENABLE_CHARGE_CREATION; injete o segredo pelo cofre da automação, nunca em argv, histórico do shell ou configuração dos clientes.

Cada referência é usada como correlationID Woovi e chave idempotente local. Repetir o mesmo payload retorna resultado já persistido; outra carga para a mesma referência conflita. Uma chamada com resultado incerto permanece UNKNOWN e não é reenviada automaticamente: a ferramenta primeiro consulta a Woovi pela referência e só fecha a operação quando referência e valor batem. Se não for encontrada, permanece UNKNOWN. O valor explícito está limitado a R$ 100.000 e expiração de 300 a 2.592.000 segundos. Tentativas e resultados são auditados no SQLite sem persistir AppID ou conteúdo do QR no log de auditoria. Esta fatia não implementa approval workflow.

O arquivo SQLite é criado sob o diretório de configuração do usuário, em woovi-pix-mcp/state/<escopo>/operations.db; o escopo separa URL/ambiente e conta. WOOVI_DATABASE_PATH permite indicar outro arquivo privado. Nunca apague o arquivo para resolver um erro: ele guarda a evidência das tentativas anteriores. SQLite usa WAL, synchronous FULL e espera limitada para escritores concorrentes. Não há DATABASE_URL nem importação PostgreSQL; esse MCP não teve usuários legados.

Teste rápido local — sem chamar a Woovi

Execute os comandos na raiz deste repositório, com Go 1.27.3 instalado. Este roteiro usa somente dados fictícios e não precisa de conta Woovi ou Docker.

1. Terminal 1: subir o simulador

mise exec go@1.27.3 -- go run ./cmd/woovi-simulator

Deixe esse terminal aberto. O simulador escuta em 127.0.0.1:8081.

2. Terminal 2: compilar e configurar

go build -o ./bin/woovi-pix-mcp ./cmd/woovi-pix-mcp
./bin/woovi-pix-mcp setup --profile teste

Responda ao assistente:

• Ambiente: simulator

• Conta: conta-teste

• Habilitar criação: no

• AppID: simulator (a entrada fica oculta)

Se o cofre do sistema estiver indisponível, repita o setup com o fallback explícito abaixo. Ele guarda o AppID sem criptografia em arquivo privado 0600:

./bin/woovi-pix-mcp setup --profile teste --secret-file

Se o perfil já existir, reutilize-o ou escolha outro nome; não há sobrescrita.

3. Conferir a configuração

./bin/woovi-pix-mcp doctor --profile teste

Esperado: ambiente simulator, credencial disponível sem exibir AppID e criação desabilitada. O banco pode aparecer como não inicializado: isso é normal em modo somente leitura. doctor não consulta nem mesmo o simulador.

4. Conectar ao OpenCode V2

Para configurar um cliente no projeto atual, execute o seletor interativo:

./bin/woovi-pix-mcp install-mcp --profile teste

Ele oferece OpenCode, Claude Code, Cursor, Codex CLI e Gemini CLI, usando os arquivos de configuração do projeto atual por padrão. O primeiro comando faz preview; revise e repita com --apply para gravar. Também é possível escolher cliente e arquivo explicitamente:

./bin/woovi-pix-mcp install-mcp --profile teste --client opencode --config opencode.json
./bin/woovi-pix-mcp install-mcp --profile teste --client opencode --config opencode.json --apply

Os caminhos padrão são opencode.json, .mcp.json, .cursor/mcp.json, .codex/config.toml e .gemini/settings.json, respectivamente. JSONC não é reescrito; TOML do Codex recebe a entrada ao final do arquivo. O instalador faz backup antes de aplicar e recusa sobrescrever uma entrada Woovi conflitante. Ele registra somente binário e perfil, nunca AppID; mantenha o binário no caminho usado na instalação.

Instale também o skill e os avisos de segurança específicos dos hosts suportados no projeto atual. Revise o preview antes de aplicar:

./bin/woovi-pix-mcp install-agent-assets
./bin/woovi-pix-mcp install-agent-assets --apply

Isso instala o skill em .agents/skills/ e .claude/skills/, o hook SessionStart do Claude Code e um plugin do OpenCode que acrescenta o aviso ao contexto de cada chamada. O aviso não bloqueia ferramentas nem substitui autorização; pix_create_charge é uma operação de escrita opcional. Nenhuma configuração global dos clientes é alterada.

5. Consultar a cobrança fictícia

Reabra o OpenCode para carregar o servidor woovi-pix-teste e peça:

Use o servidor woovi-pix-teste para consultar a cobrança demo-charge com pix_get_charge. Não use outros servidores nem crie cobranças.

Esperado: ID demo-charge, referência demo-order-001, estado ACTIVE e valor 1250 centavos (R$ 12,50), com código Pix fictício. Nenhuma chamada Woovi ou operação financeira real é feita. Termine o simulador com Ctrl+C.

O simulador também mantém uma assinatura sintética demo-subscription em memória para validar cancelamento, leitura do snapshot e paginação local:

curl -i -X PUT http://127.0.0.1:8081/api/v1/subscriptions/demo-subscription/cancel \
  -H 'Authorization: simulator'

curl -sS http://127.0.0.1:8081/api/v1/subscriptions/demo-subscription \
  -H 'Authorization: simulator'

curl -sS 'http://127.0.0.1:8081/api/v1/subscriptions/demo-subscription/installments?skip=0&limit=1' \
  -H 'Authorization: simulator'

curl -sS 'http://127.0.0.1:8081/api/v1/subscriptions/demo-subscription/installments?skip=1&limit=1' \
  -H 'Authorization: simulator'

O primeiro comando retorna 204; o segundo mostra status: CANCELED. O estado é sintético, vive apenas na memória do processo e volta a APPROVED após restart. O GET da assinatura devolve somente IDs e estado fictícios; os GETs de parcelas aceitam skip e limit de 1 a 100 e retornam pageInfo. A primeira página inclui uma parcela COMPLETED, a segunda uma SCHEDULED. Esse endpoint existe para exercitar adapters locais, não é ferramenta MCP, não cria uma recorrência Woovi e não chama nem cancela uma assinatura real.

O simulador manual de cobrança também aceita consulta/criação em memória; criação e idempotência são cobertas adicionalmente pelos testes automatizados. Para rodar a suíte e as verificações do projeto:

make check

Teste com o sandbox da própria Woovi

Este roteiro usa a API de teste externa da Woovi, não o simulador local. Não é necessário executar woovi-simulator. Execute apenas com autorização para usar essa conta; os passos abaixo não foram executados pela implementação ou pela CI. Não use credenciais de produção nem faça pagamentos reais.

1. Preparar a conta e uma cobrança de teste

• Acesse app.woovi-sandbox.com. O sandbox tem cadastro separado: dados de produção não funcionam nele.

• No painel do sandbox, obtenha um AppID da sua conta. A documentação de autenticação indica Admin Panel > Permissions > APIs para gerar a chave, com permissão de administrador. Use os escopos necessários para consulta.

• Tenha uma cobrança criada no sandbox pelo painel e copie seu ID ou correlationID. demo-charge é exclusivo do simulador e não deve ser usado aqui.

Referências oficiais: ambiente de teste e criação da chave API.

2. Compilar e configurar o perfil sandbox

go build -o ./bin/woovi-pix-mcp ./cmd/woovi-pix-mcp
./bin/woovi-pix-mcp setup --profile sandbox

Responda:

• Ambiente: sandbox (seleciona https://api.woovi-sandbox.com)

• Conta: um identificador estável dessa conta, por exemplo minha-conta-sandbox

• Habilitar criação: no, para começar somente com consulta

• AppID: o AppID do sandbox, no prompt oculto; nunca cole no chat ou no cliente

A conta é o escopo local de idempotência, não outro segredo; mantenha o mesmo identificador ao criar perfis para essa conta. Se o cofre estiver indisponível e você aceitar o arquivo privado sem criptografia, use explicitamente:

./bin/woovi-pix-mcp setup --profile sandbox --secret-file

3. Conferir e conectar ao cliente

./bin/woovi-pix-mcp doctor --profile sandbox

./bin/woovi-pix-mcp install-mcp --profile sandbox \
  --client opencode --config ~/.config/opencode/opencode.json

./bin/woovi-pix-mcp install-mcp --profile sandbox \
  --client opencode --config ~/.config/opencode/opencode.json --apply

Valem os requisitos de JSON e permissões do roteiro local. Esperado no doctor: ambiente sandbox, credencial disponível e criação desabilitada. Isso valida apenas a configuração local, não autenticação ou conectividade com a Woovi.

4. Consultar uma cobrança do sandbox

Reabra o cliente e substitua <ID_OU_CORRELATION_ID> pelo identificador copiado do painel. Se houver outros perfis instalados, selecione woovi-pix-sandbox:

Use somente o servidor woovi-pix-sandbox para chamar pix_get_charge com id igual a <ID_OU_CORRELATION_ID>. Não crie nem pague cobranças.

Esperado: a cobrança da sua conta sandbox, com ID/referência, estado e valor em centavos coerentes com o painel, sem AppID ou dados do pagador. Estado e valor dependem da cobrança escolhida; não há resultado fixo de R$ 12,50 aqui. Essa consulta é a verificação efetiva de API, credencial e escopo da conta.

5. Opcional: testar criação e idempotência no sandbox

Somente se quiser testar escrita e tiver autorização, siga o roteiro detalhado em docs/sandbox.md. Ele cria outro perfil com opt-in explícito e explica como repetir o mesmo payload e verificar conflito. Não pague o QR gerado, não use produção e não invente outra referência para contornar um timeout ou resultado incerto.

Contrato Woovi verificado

• Autenticação por Authorization: <AppID>; API retorna/aceita JSON e requer HTTPS. Limite documentado: 10 requisições por segundo.

• Consulta: GET /api/v1/charge/{id}; id aceita identificador da cobrança ou correlationID.

• O retorno MCP é minimizado a identificador, referência, estado, centavos BRL, expiração e código Pix; dados do pagador e payloads brutos são descartados.

• O cliente aplica limiter local conservador de 10 req/s (sem rajada) para respeitar o limite publicado pela Woovi.

• Referências: Autenticação e limites, API Redoc, Correlation ID/idempotência.

O simulador de teste também suporta POST e mantém cobranças idempotentes pela referência em memória; nunca use credencial ou host de produção nos testes.

Todos os testes de persistência SQLite executam automaticamente em make test, sem credenciais ou infraestrutura externa.

Litestream opcional e recuperação

Instale separadamente Litestream 0.5.12+ (série 0.5.x), validado com 0.5.17. Não é iniciado automaticamente e o MCP funciona sem ele.

./bin/woovi-pix-mcp replica-setup --profile sandbox --replica-url file:///absolute/private/backup/sandbox
# Alternativa: S3 ou compatível; access key e secret key entram em prompts sem eco.
./bin/woovi-pix-mcp replica-setup --profile sandbox --replica-url s3://my-bucket/account-specific-prefix --region us-east-1
./bin/woovi-pix-mcp replica-run --profile sandbox

Use apenas um dos destinos; configuração existente não é sobrescrita. Para S3 compatível use --endpoint https://.... Credenciais usam cofre do sistema ou --secret-file explicitamente; não coloque credenciais na URL. O processo filho recebe somente as credenciais da réplica, não o AppID. Prefira discos privados e criptografia/controle de acesso do bucket: a réplica contém dados de cobranças.

Inicie stdio uma vez para inicializar o banco antes da primeira réplica. replica-run fica em foreground; Ctrl+C o encerra. Um lock impede duas réplicas gerenciadas para o mesmo banco. replica-status verifica o estado local via Litestream; não atesta sincronização remota nem atraso zero. Saída bruta do processo externo é suprimida para evitar vazamento em mensagens de erro.

Para recuperar: pare todos os processos MCP e réplica; arquive manualmente o banco e seus sidecars, sem excluí-los. O destino e sidecars precisam estar ausentes; não existe opção force/overwrite nesta CLI.

./bin/woovi-pix-mcp replica-restore --profile sandbox --acknowledge-stale-state
./bin/woovi-pix-mcp doctor --profile sandbox

A restauração faz integrity check completo e cria operations.db.recovered, que bloqueia inicialização com criação habilitada. Não remova esse marcador antes de conferir o histórico da Woovi e reconciliar operações possivelmente ausentes na cópia. Se não conseguir reconciliar, permaneça em leitura. Não há importação automática de histórico PSP nem botão de desbloqueio automático. Uma falha de restore pode deixar arquivos parciais: arquive-os e investigue, não reinicie com estado vazio. O marcador também permanece em caso de falha.

Litestream replica de forma assíncrona: RPO depende do último envio confirmado; RTO depende da recuperação manual. Não oferece HA automática ou multiwriter. Uma cópia antiga pode esquecer uma criação já efetivada no provedor; restaurar o banco não autoriza repetir pedidos financeiros com novas referências.

Integração real de réplica em arquivo e armazenamento S3 local (SeaweedFS):

TEST_LITESTREAM_BINARY=/absolute/path/litestream make test-litestream

Esse target precisa Docker somente para os testes opcionais de réplica; uso normal continua sem Docker. CI executa ambos os backends e valida o checksum do binário fixado. Não chama Woovi nem usa credenciais reais.

Roteiro e troubleshooting: docs/sandbox.md.