PRRO.cloud

prro-mcp

Servidor MCP para a API PRRO.cloud. Dá aos assistentes de IA (Claude Code, Claude Desktop, Cursor e outros clientes do Model Context Protocol) acesso às suas caixas registradoras, turnos, tarefas fiscais, cobrança e webhooks.

Para quem: desenvolvedores que integram o PRRO em uma loja ou sistema contábil. O assistente vê o estado real das caixas, tarefas e entregas de webhooks e ajuda a escrever e depurar a integração: por que o recibo não passou, se o turno está aberto, se é um turno de teste, o que o receptor do webhook respondeu.

• Somente leitura. Nenhuma ferramenta registra documentos na autoridade fiscal, abre ou fecha turnos, nem altera configurações.
• Funciona localmente via stdio; o token é obtido de uma variável de ambiente.
• Construído sobre prro-go e o Go SDK oficial do MCP.
• Fornece ao assistente o contrato da API (OpenAPI) — para escrever código de integração.

Token

Emita um token de máquina separado para o assistente no painel, na seção de tokens:

• restrinja-o às caixas que o assistente deve ver (de preferência, uma caixa de teste);
• cobrança, faturas e webhooks são lidos apenas por um token com acesso a todas as caixas;
• você pode revogar o token no painel pelo identificador jti — exibido pela ferramenta whoami.

O token é uma credencial: não envie a configuração do cliente MCP com ele para o repositório.

Instalação

Claude Desktop — baixe o prro-mcp.mcpb do último release, abra-o com um duplo clique e insira o token nas configurações da extensão. O pacote contém builds para macOS e Windows.

Binário pronto — arquivo para Linux, macOS ou Windows (amd64/arm64) dos releases; descompacte o prro-mcp em um diretório com o PATH.

Go (requer Go 1.27 ou superior):

go install github.com/prro-cloud/prro-mcp/cmd/prro-mcp@latest

Docker:

docker run -i --rm -e PRRO_TOKEN ghcr.io/prro-cloud/prro-mcp

Verificação: prro-mcp -version.

Configuração dos clientes

Claude Code

claude mcp add prro --env PRRO_TOKEN=ваш_токен -- prro-mcp

Ou para toda a equipe — em .mcp.json na raiz do projeto; cada um obtém o token do seu próprio ambiente, então o arquivo pode ser versionado:

{
  "mcpServers": {
    "prro": {
      "command": "prro-mcp",
      "env": { "PRRO_TOKEN": "${PRRO_TOKEN}" }
    }
  }
}

Claude Desktop

A maneira mais simples — o pacote prro-mcp.mcpb (veja Instalação). Manualmente — em claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "prro": {
      "command": "/повний/шлях/до/prro-mcp",
      "env": { "PRRO_TOKEN": "ваш_токен" }
    }
  }
}

Cursor

~/.cursor/mcp.json (para todos os projetos) ou .cursor/mcp.json no projeto:

{
  "mcpServers": {
    "prro": {
      "command": "prro-mcp",
      "env": { "PRRO_TOKEN": "${env:PRRO_TOKEN}" }
    }
  }
}

Docker em qualquer cliente

{
  "mcpServers": {
    "prro": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "PRRO_TOKEN", "ghcr.io/prro-cloud/prro-mcp"],
      "env": { "PRRO_TOKEN": "ваш_токен" }
    }
  }
}

Variáveis de ambiente

Variável	Finalidade
PRRO_TOKEN	Token de máquina da API. Obrigatório.
PRRO_BASE_URL	Endereço da API em vez de https://api.prro.cloud — para um ambiente local.
PRRO_LANG	Idioma das mensagens de erro da API: uk (padrão) ou en.
PRRO_MCP_LOG_LEVEL	Nível de log: debug, info (padrão), warn, error. O log vai para o stderr; em debug as requisições à API ficam visíveis. O token não aparece no log.

Ferramentas

Todas as ferramentas são somente leitura e marcadas com readOnlyHint. O resultado — dados estruturados (structuredContent conforme o esquema original) mais um breve resumo em texto. Valores monetários como strings, como na API: valores de recibos e dinheiro em hryvnias, valores de cobrança em copeques.

Ferramenta	O que retorna
get_version	Versão do serviço PRRO.cloud, do contrato da API, do prro-mcp e do prro-go.
whoami	Cliente, permissões do token, caixas disponíveis, validade.
get_dps_status	Modo de operação com a autoridade fiscal (online/offline) e telemetria do detector.
list_cash_registers	Caixas disponíveis ao token: identificador, número fiscal, modo, estado.
get_cash_register_state	Estado da caixa: turno (inclusive de teste), resumos do turno, dinheiro, sessão offline, marcação "requer atenção".
get_task	Tarefa fiscal: estado, resultado (número fiscal, link para o recibo) ou descrição da falha da autoridade fiscal.
get_billing_usage	Saldo, limite de bloqueio, quantidade e custo dos recibos no período.
list_invoices	Faturas por períodos de faturamento.
list_webhooks	Webhooks, suas assinaturas e o limite de quantidade.
list_webhook_deliveries	Histórico de entregas do webhook com erros do receptor.

Recurso prro://openapi.yaml — contrato público da API (OpenAPI 3.1), com o qual o servidor foi compilado. O assistente o lê ao escrever código de integração.

Conscientemente não estão incluídas na v0.1 operações de escrita: registro de recibos, abertura e fechamento de turnos, declaração de saldo de dinheiro, gerenciamento de sessões offline, remoção da marcação de atenção, criação, alteração, exclusão e repetição de webhooks.

Exemplos de solicitações

• "Quais caixas meu token vê e há um turno aberto nelas?"
• "Por que a tarefa 0199… terminou com erro e o que fazer a respeito?"
• "Mostre as entregas de webhook com falha no último dia e explique o que há de errado com meu receptor."
• "Quantos recibos emitimos em setembro e quanto custou?"
• "Escreva um manipulador de webhook task.failed em Go conforme o contrato da API."

Desenvolvimento

make test       # тести з -race
make lint       # golangci-lint
make build      # bin/prro-mcp
make sync-spec  # оновити копію контракту з ../prro-go

O teste de contrato compara as ferramentas com internal/spec/openapi.yaml: cada operação do contrato é atendida por uma ferramenta ou explicitamente excluída — uma nova operação no contrato faz o teste falhar.

Release

1. Mover as alterações de [Unreleased] para a seção de versão em CHANGELOG.md.
2. git tag v0.1.0 && git push origin v0.1.0 — o workflow Release compilará os arquivos, a imagem ghcr.io/prro-cloud/prro-mcp, o pacote prro-mcp.mcpb e o server.json com o SHA-256 do pacote, os adicionará ao release, e o workflow MCP Registry publicará o server.json no registro MCP via GitHub OIDC. Repetir a publicação para uma tag já lançada: gh workflow run registry.yml -f tag=v0.1.0.
3. Colocar o server.json do release na raiz do repositório e commitar.

Localmente sem publicação: make snapshot, depois scripts/mcpb.sh 0.0.0.

Licença

Apache 2.0