# Integração Nucleo Pay via MCP / LLM

Este guia permite que assistentes de IA integrem sua aplicação com a Nucleo Pay usando o **Model Context Protocol (MCP)** ou o manifesto JSON da API.

Compatível com **Cursor**, **Claude Desktop**, **Lovable**, **Trae** e outras ferramentas com suporte a MCP ou leitura de API.

## O que é

O MCP expõe ferramentas tipadas que o LLM pode chamar: criar cobrança PIX, consultar status, gerenciar webhooks e validar assinaturas — sem você copiar documentação manualmente.

## Pré-requisitos

1. Conta na Nucleo Pay com **token de API** (painel → Integração API).
2. Python 3.10+ instalado na **sua** máquina.
3. Cópia local deste repositório (clone ou download ZIP) — cada pessoa tem um caminho diferente no disco.

## Instalação (qualquer computador)

O `deploy-backend` **não fica no servidor da Nucleo Pay**. Você roda o MCP/CLI **no seu PC**, como o Stripe CLI ou o servidor MCP de outros gateways.

1. Baixe ou clone o repositório para uma pasta sua (ex.: `~/projetos/minha-loja` ou `C:\projetos\minha-loja`).
2. Abra o terminal **nessa pasta** (não use `C:\Windows\System32`).
3. Entre em `deploy-backend` e instale as dependências **uma vez**:

**Windows (PowerShell) — recomendado (gera a config MCP automaticamente):**
```powershell
cd "C:\projetos\minha-loja\deploy-backend"
powershell -ExecutionPolicy Bypass -File mcp_server\setup-mcp.ps1
```

O script instala o MCP, testa o módulo e imprime o JSON pronto para colar no Cursor/Trae/Claude.

**Windows (manual):**
```powershell
cd "C:\projetos\minha-loja\deploy-backend"
python -m pip install -e .
```

**macOS / Linux:**
```bash
cd ~/projetos/minha-loja/deploy-backend
python3 -m pip install -r requirements-mcp.txt
```

**Conferir:** dentro de `deploy-backend` deve existir o arquivo `requirements-mcp.txt`. Se der "arquivo não encontrado", você está na pasta errada.

**Descobrir o caminho absoluto (para o MCP):**
- Windows: `(Get-Location).Path` no PowerShell, estando dentro de `deploy-backend`
- macOS/Linux: `pwd`

Use esse caminho em `"cwd"` na configuração do Cursor/Trae/Claude.

## Dependências MCP (referência)

```bash
# Execute dentro da pasta deploy-backend do SEU computador
python -m pip install -r requirements-mcp.txt
```

## Configuração base (todas as ferramentas)

Use este bloco em qualquer cliente MCP. Ajuste `cwd` para o caminho absoluto da pasta `deploy-backend` e defina seu token.

**Windows — use caminho completo do `python.exe` em `command` (não use só `"python"`).**

```json
{
  "mcpServers": {
    "nucleopay": {
      "command": "C:\\Python311\\python.exe",
      "args": ["-m", "mcp_server"],
      "cwd": "C:\\projetos\\minha-loja\\deploy-backend",
      "env": {
        "NUCLEOPAY_API_BASE_URL": "https://nucleopay.com.br",
        "NUCLEOPAY_API_TOKEN": "seu_token",
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      }
    }
  }
}
```

**macOS / Linux:**

```json
{
  "mcpServers": {
    "nucleopay": {
      "command": "python3",
      "args": ["-m", "mcp_server"],
      "cwd": "/projetos/minha-loja/deploy-backend",
      "env": {
        "NUCLEOPAY_API_BASE_URL": "https://nucleopay.com.br",
        "NUCLEOPAY_API_TOKEN": "seu_token"
      }
    }
  }
}
```

## Cursor

1. Instale o MCP localmente (uma vez): `mcp_server\setup-mcp.ps1` no Windows ou `pip install -e .` dentro de `deploy-backend`.
2. Abra **Cursor Settings → MCP**.
3. Cole o JSON gerado pelo script (ou a configuração base acima).
4. **Windows:** não use `"command": "python"` — o Cursor pode usar o Python interno do Hermes (`hermes-agent\venv`) e falhar com `No module named mcp_server`.
5. Confirme que `cwd` aponta para a pasta `deploy-backend` do **seu** projeto (não use o caminho de exemplo).
6. Reinicie o Cursor se necessário.

Exemplo em `mcp_server/cursor-mcp.example.json`.

### Cursor — erros comuns

| Erro | Solução |
|------|---------|
| `No module named mcp_server` | `cwd` errado **ou** Python errado. Use `setup-mcp.ps1` e cole o JSON gerado |
| Python `hermes-agent\venv` no log | Troque `"command": "python"` pelo caminho completo do seu `python.exe` |
| `No module named mcp` | Rode `pip install -e .` na pasta `deploy-backend` com o **mesmo** python do MCP |
| Token inválido | Gere token no painel Nucleo Pay → API e Webhooks |

## Claude Desktop

1. Edite o arquivo de configuração do Claude Desktop:
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
2. Cole o bloco `mcpServers` da configuração base.
3. Reinicie o Claude Desktop.

## Trae

1. Instale as dependências (uma vez):
   ```bash
   cd deploy-backend
   pip install -r requirements-mcp.txt
   ```
2. Abra **Trae → Settings → MCP → Configure Manually** (config global: `%APPDATA%\Trae\User\mcp.json` no Windows).
3. **Não** adicione só a URL `https://nucleopay.com.br/api/integrations/mcp/manifest` como servidor — ela é documentação da API. O MCP do Trae precisa de um **processo local** (stdio).
4. Use o launcher Windows (recomendado) ou `py -3`:

**Windows (Trae — use python.exe direto, NÃO use .bat):**

Descubra seu Python: `python -c "import sys; print(sys.executable)"`

```json
{
  "mcpServers": {
    "nucleopay": {
      "command": "C:\\Python311\\python.exe",
      "args": ["-m", "mcp_server"],
      "cwd": "C:\\projetos\\minha-loja\\deploy-backend",
      "env": {
        "NUCLEOPAY_API_BASE_URL": "https://nucleopay.com.br",
        "NUCLEOPAY_API_TOKEN": "seu_token",
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      }
    }
  }
}
```

> **Erro `spawn cmd.exe ENOENT` no Trae?** Você usou `.bat` ou `command: python` sem caminho. O Trae precisa do **caminho completo** do `python.exe` (veja comando acima).

**Alternativa (se tiver `py` no PATH):**

```json
{
  "mcpServers": {
    "nucleopay": {
      "command": "py",
      "args": ["-3", "-m", "mcp_server"],
      "cwd": "C:\\projetos\\minha-loja\\deploy-backend",
      "env": {
        "NUCLEOPAY_API_BASE_URL": "https://nucleopay.com.br",
        "NUCLEOPAY_API_TOKEN": "seu_token",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

5. Reinicie o Trae por completo após salvar.
6. Em **MCP**, o servidor `nucleopay` deve aparecer conectado (verde).

### Trae — erros comuns

| Erro | Solução |
|------|---------|
| `spawn cmd.exe ENOENT` | **Não use `.bat`** no Trae. Use caminho completo do `python.exe` |
| `python` não encontrado | Use caminho absoluto: `python -c "import sys; print(sys.executable)"` |
| `No module named mcp` | Rode `pip install -r requirements-mcp.txt` na pasta `deploy-backend` |
| Servidor não inicia | Confirme `cwd` ou caminho do `.bat` com pasta `deploy-backend` |
| URL do manifesto no MCP | Remova — use JSON stdio acima, não a URL HTTP |
| Token inválido | Gere token no painel Nucleo Pay → API e Webhooks |

Exemplo completo: `mcp_server/trae-mcp.example.json`.

## Lovable

O Lovable gera apps a partir de prompts. Duas formas de integrar:

**Opção A — Manifesto como contexto**

Informe ao Lovable a URL do manifesto para ele entender a API:

```
https://nucleopay.com.br/api/integrations/mcp/manifest
```

**Opção B — Prompt direto**

> Integre pagamentos PIX com a Nucleo Pay. Base URL: https://nucleopay.com.br. Autenticação: Bearer token. Criar cobrança: POST /api/pix/charge/create com value e title. Webhook: header X-NucleoPay-Signature (HMAC SHA256).

Se o Lovable suportar MCP no seu ambiente, use a configuração base acima.

## Ferramentas disponíveis

| Ferramenta | Descrição |
|------------|-----------|
| `get_integration_manifest` | Endpoints, webhooks e fluxo completo |
| `create_pix_charge` | Cria cobrança PIX |
| `get_pix_charge_status` | Consulta status |
| `list_pix_charges` | Lista cobranças recentes |
| `list_webhooks` / `create_webhook` / `test_webhook` | Gerencia webhooks |
| `verify_webhook_signature` | Valida HMAC do webhook recebido |
| `generate_integration_snippet` | Gera código em Python, JS, cURL, PHP, Go |
| `list_api_tokens` | Lista tokens da conta |

## Manifesto HTTP

Para qualquer LLM ou ferramenta que leia JSON:

- `GET /api/integrations/mcp/manifest` — manifesto completo
- `GET /api/integrations/mcp/guide` — este guia em Markdown

## Exemplos de prompt

**Bot / automação:**
> Integre meu bot com a Nucleo Pay: crie uma cobrança de R$ 29,90 quando o usuário pedir /pagar, e me mostre o código do webhook para confirmar pagamento.

**Lovable / site:**
> Adicione checkout PIX na minha landing page usando a API da Nucleo Pay. Ao clicar em Comprar, gere uma cobrança e mostre o QR code.

**Trae / Cursor:**
> Configure webhooks da Nucleo Pay no meu backend e valide a assinatura HMAC no endpoint /webhook/nucleopay.

## Segurança

- Nunca commite tokens no Git.
- Use variáveis de ambiente (`NUCLEOPAY_API_TOKEN`).
- Revogue tokens que não estiver mais usando no painel da Nucleo Pay.