# AdvinPay MCP

Servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io) oficial da [AdvinPay](https://advinpay.com). Conecte o Claude, Cursor ou qualquer cliente MCP à sua conta AdvinPay para **criar cobranças PIX, consultar transações e tirar dúvidas da documentação** direto do assistente.

- 📚 Documentação da API embutida e pesquisável (funciona sem credenciais)
- 💸 Criar QR Code PIX e consultar transações com suas chaves de API
- 🔒 Saques **desabilitados por padrão** — opt-in explícito
- 📦 Zero configuração: roda com `npx advinpay-mcp`

## Configuração

Gere suas credenciais no dashboard (**Dashboard → API**) e configure no seu cliente MCP:

### Claude Code

```bash
claude mcp add advinpay \
  -e ADVINPAY_ACCESS_KEY=ak_sua_chave \
  -e ADVINPAY_SECRET_KEY=sk_seu_secret \
  -- npx -y advinpay-mcp
```

### Claude Desktop / Cursor (JSON)

```json
{
  "mcpServers": {
    "advinpay": {
      "command": "npx",
      "args": ["-y", "advinpay-mcp"],
      "env": {
        "ADVINPAY_ACCESS_KEY": "ak_sua_chave",
        "ADVINPAY_SECRET_KEY": "sk_seu_secret"
      }
    }
  }
}
```

> Sem credenciais, o servidor ainda funciona — apenas as ferramentas de
> documentação e de consulta pública ficam disponíveis.

## Ferramentas

| Ferramenta | Credenciais | Descrição |
|---|---|---|
| `search_docs` | não | Busca na documentação oficial da API |
| `read_docs` | não | Lê uma seção da documentação (ou o guia completo) |
| `get_public_charge` | não | Consulta pública de uma cobrança (checkout) |
| `create_pix_deposit` | API Key | Cria cobrança PIX e retorna o copia-e-cola |
| `get_transaction` | API Key | Consulta status/detalhes de uma transação |
| `create_pix_withdrawal` | API Key | ⚠️ Saque PIX real — **desabilitada por padrão** |

O servidor também expõe a documentação completa como resource MCP (`advinpay://docs/llms.txt`).

## Habilitando saques (opcional)

`create_pix_withdrawal` **movimenta dinheiro de verdade** e por isso só é
registrada quando você define explicitamente:

```
ADVINPAY_MCP_ALLOW_WITHDRAWALS=true
```

Recomendações antes de habilitar:
- Use credenciais com escopo mínimo (`transactions:withdrawal` só se necessário).
- Prefira uma conta com limites configurados.
- Confirme sempre valor e chave PIX antes de aprovar a chamada no seu cliente MCP.

## Variáveis de ambiente

| Variável | Obrigatória | Descrição |
|---|---|---|
| `ADVINPAY_ACCESS_KEY` | para tools de API | Access Key (`ak_...`) |
| `ADVINPAY_SECRET_KEY` | para tools de API | Secret Key (`sk_...`) |
| `ADVINPAY_MCP_ALLOW_WITHDRAWALS` | não | `true` habilita a tool de saque |
| `SITE_URL` / `baseUrl` | não | Padrão: `https://api.advinpay.com/v1` |

## Exemplos de uso (no chat)

- “Crie uma cobrança PIX de R$ 250 para o cliente João Silva, CPF 123.456.789-09, referente ao pedido 442.”
- “Qual o status da transação a1b2c3d4-…?”
- “Como funciona o retry dos webhooks da AdvinPay?”
- “Me mostre como autenticar na API e quais escopos existem.”

## Desenvolvimento

```bash
pnpm install   # usa o SDK local via override (../advinpay-sdk) enquanto `advinpay` não está no npm
pnpm test
pnpm build
node dist/index.js   # roda o servidor em stdio
```

> O `pnpm-workspace.yaml` contém um override `advinpay: link:../advinpay-sdk`
> para desenvolvimento. Depois que o pacote `advinpay` for publicado no npm,
> o override pode ser removido.

## Licença

MIT © AdvinPay