Executando verificação de segurança...
1
felipeorlando
4 min de leitura ·

Pitch: pixcli: por que escrevi uma CLI em Rust para Pix (e adicionei um MCP server para AI agents)

Fala, pessoal. Quero compartilhar um projeto que venho construindo nos últimos meses e as decisões técnicas por trás dele.

O contexto

Se você já integrou com APIs Pix de algum PSP, sabe que a experiência de desenvolvedor é... sofrível. Cada provedor implementa a spec do Bacen de um jeito, os SDKs disponíveis são pesados, e não existe nenhuma ferramenta de terminal para testar cobranças ou debugar webhooks. Eu queria algo como o stripe-cli ou o gh — ferramentas que resolvem o problema direto, sem firula.

O resultado é o pixcli: uma CLI open-source (MIT) para pagamentos Pix, escrita em Rust — e a primeira com integração nativa para AI agents via MCP.

🔗 https://github.com/pixcli/pixcli

Por que Rust?

Decisão pragmática, não hype.

  1. Type safety importa quando se lida com dinheiro. Representar valores, status de pagamento e BR Codes como tipos fortes evita uma classe inteira de bugs. O compilador trabalha a seu favor.

  2. Performance para o MCP server. O pixcli inclui um servidor MCP (Model Context Protocol) que permite AI agents interagirem com Pix. Isso precisa ser rápido e ter baixo consumo de memória — vai rodar como sidecar, não como o processo principal.

  3. Distribuição. Um binário estático, sem runtime, sem dependências. cargo install pixcli e pronto. Não precisa de Node, Python, JVM, nada.

  4. Ecossistema. Crates como clap, reqwest, serde, tokio são maduras e bem mantidas. O workspace system do Cargo facilita projetos modulares.

Dito isso, Rust tem seus custos. Tempo de compilação, curva de aprendizado, e em algumas partes o borrow checker te faz repensar o design inteiro. Mas pra esse tipo de projeto — CLI, networking, tipos de domínio complexos — encaixou bem.

Decisões de arquitetura

O projeto é um Cargo workspace com 8 crates:

  • pix-core: tipos compartilhados (Cobrança, Devolução, Webhook) como traits
  • pix-brcode: geração de BR Codes seguindo spec EMV — isolada pra ser usada em outros projetos
  • pix-provider: trait PixProvider que abstrai qualquer PSP
  • pix-efi: implementação pra Efí/Gerencianet (mTLS, OAuth2, API v2)
  • pix-config: gerenciamento de credenciais (keyring, arquivo, env vars)
  • pix-mcp: MCP server — expõe Pix como ferramentas pra AI agents
  • pix-webhook-server: servidor local pra receber callbacks
  • pixcli: a CLI em si (clap v4)

A separação em crates não é capricho — cada uma pode ser versionada, testada e publicada independentemente. Alguém que só quer gerar BR Codes não precisa trazer a integração com Efí. Alguém que quer adicionar suporte ao Itaú implementa o trait PixProvider sem tocar no resto.

O MCP server: AI agents que fazem pagamentos

Essa foi a feature que mais mudou minha visão do projeto.

MCP (Model Context Protocol) é o padrão da Anthropic para AI agents chamarem ferramentas externas. Com o pix-mcp rodando, um agent compatível com MCP (Claude Code, OpenClaw, e outros) consegue criar cobranças Pix, verificar pagamentos e gerenciar webhooks sem nenhum código customizado do seu lado.

// Adicionar no .mcp.json do seu projeto
{
  "mcpServers": {
    "pixcli": {
      "command": "pixcli",
      "args": ["mcp", "serve"]
    }
  }
}

Pronto. A partir daí, o agent tem as ferramentas Pix disponíveis nativamente.

Os casos de uso concretos que me fizeram construir isso:

  • E-commerce autônomo: agent que cria cobranças, monitora pagamentos, e dispara fulfillment sozinho
  • Suporte com autonomia: agent que emite reembolso Pix na hora, sem escalar para humano
  • Billing automatizado: pipelines financeiros que entendem contexto e reagem a inadimplência

Até onde sei, o pixcli é a primeira ferramenta Pix com integração nativa para AI agents. MCP está ganhando adoção rápida no ecossistema de AI agents — faz sentido construir a camada de pagamentos já preparada pra esse mundo.

Lições aprendidas

mTLS em Rust é trabalhoso. A maioria dos PSPs exige certificados client-side. Configurar isso com reqwest + native-tls ou rustls envolve converter formatos de certificado, lidar com PKCS#12 vs PEM, e testar em ambientes que nem sempre suportam. Gastei mais tempo nisso do que gostaria.

A spec do Bacen é boa, as implementações nem sempre. O padrão Pix é bem definido, mas cada PSP adiciona campos extras, muda nomes, ou interpreta de formas diferentes. O layer de abstração (pix-provider) nasceu dessa dor.

Testes são inegociáveis. Com 210+ testes, posso refatorar sem medo. Isso é especialmente importante num projeto financeiro onde um bug pode significar cobrança errada. Cada PR roda CI completo.

MCP muda o que é possível. Integrar o Model Context Protocol fez o projeto ganhar outra dimensão — deixou de ser só uma CLI e virou infraestrutura que AI agents podem usar diretamente.

Estado atual

  • CLI funcional com criação de cobranças, consulta, QR codes, webhook server
  • MCP server operacional — pronto pra uso com Claude Code, OpenClaw e outros runtimes
  • 210+ testes, CI green
  • Docs em construção (Fumadocs + Next.js)
  • Suporte a Efí/Gerencianet, com mais PSPs no roadmap

Quer contribuir?

O projeto é MIT e está aberto. Contribuições de qualquer nível são bem-vindas — desde correção de typos até implementação de novos provedores ou novas ferramentas MCP. Se você usa Pix no dia a dia (quem não usa?) e gosta de Rust ou de AI agents, dá uma olhada.

Feedback honesto também é muito apreciado. O que funciona? O que não funciona? O que falta?

🔗 https://github.com/pixcli/pixcli

Carregando publicação patrocinada...