@rede-ancora/mcp-portal-b2b-internal

Servidor MCP (Model Context Protocol) que expõe a API ERP do portal-b2b da Rede ANCORA para agents internos via Claude Desktop, Cursor, Cline, Claude Code e outros clientes compatíveis.

Diferente do pacote @rede-ancora/mcp-portal-b2b-franchise (que é escopado por CNPJ e usa API key do franqueado), este servidor opera com JWT bearer no guard auth:erp e expõe a superfície de integração ERP do portal — operações de faturamento, cancelamento de pedidos, callbacks, boletos, consulta global de estoque/preços, e fila de integração de pedidos. Acesso cross-CNPJ por design.

Audiência

Devs e agents internos da Rede ANCORA. Não distribuir credenciais a terceiros. A conta de serviço usada (default [email protected]) tem privilégios significativos no ambiente ERP do portal.

O que é MCP?

MCP é um protocolo aberto que padroniza como agents de IA descobrem e executam "tools" (ações) em sistemas externos. Este pacote roda como um servidor stdio que:

1. Lê o snapshot OpenAPI ERP do portal embarcado no pacote.
2. Gera dinamicamente uma tool MCP para cada endpoint ERP.
3. Faz lazy login ao primeiro uso, cacheia o JWT em memória, re-loga quando expira.
4. Encaminha chamadas para a API HTTPS do portal com Authorization: Bearer <jwt>.

Pré-requisitos

• Node.js 20 ou superior.
• Conta de serviço ERP com permissão no guard auth:erp do portal. Default: [email protected]. Senha provisionada via canal de TI interno.

Instalação

Adicione ao arquivo de configuração do cliente MCP:

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "rede-ancora-internal": {
      "command": "npx",
      "args": ["-y", "@rede-ancora/mcp-portal-b2b-internal@latest"],
      "env": {
        "ANCORA_ERP_USER": "[email protected]",
        "ANCORA_ERP_PASSWORD": "<senha>",
        "ANCORA_ENV": "prod"
      }
    }
  }
}

Reinicie o Claude Desktop.

Cursor

Em ~/.cursor/mcp.json (ou via Settings → MCP):

{
  "mcpServers": {
    "rede-ancora-internal": {
      "command": "npx",
      "args": ["-y", "@rede-ancora/mcp-portal-b2b-internal@latest"],
      "env": {
        "ANCORA_ERP_USER": "[email protected]",
        "ANCORA_ERP_PASSWORD": "<senha>"
      }
    }
  }
}

Cline / Claude Code

Mesma estrutura no arquivo de config MCP do cliente.

Variáveis de ambiente

| Variável | Obrigatória | Default | Descrição | |---|---|---|---| | ANCORA_ERP_USER | sim | — | Usuário da conta de serviço ERP. | | ANCORA_ERP_PASSWORD | sim | — | Senha da conta de serviço ERP. | | ANCORA_ENV | não | prod | prod ou staging. Define o host base. | | ANCORA_API_URL | não | derivado de ANCORA_ENV | Sobrescreve URL base. Use o prefixo de deploy (ex: https://api.redeancora.com.br/b2b/api). | | ANCORA_LOG_LEVEL | não | info | error, warn, info, debug. Logs em stderr. |

NUNCA commit dessas variáveis. Configure-as apenas no JSON local do cliente MCP, que vive fora do controle de versão.

Autenticação

O fluxo é lazy login + re-login on expiry:

1. No primeiro tool call, o servidor faz POST /erp/integration/v1/auth/login com { user, password }.
2. Resposta retorna access_token e expires_in. Token vai pra cache em memória do processo MCP.
3. Cada chamada subsequente injeta Authorization: Bearer <token>.
4. Se o token está perto de expirar (margem de 60s), próximo call dispara um novo auth/login e cacheia o novo token.
5. Se o portal retornar 401 (token revogado server-side), servidor invalida o cache, faz novo login e tenta o request uma vez.

O cache de token vive apenas em memória do processo. Encerrar o cliente MCP descarta tudo.

Concorrência: chamadas paralelas que disparam refresh ao mesmo tempo são serializadas via mutex single-flight — só um login HTTP de fato.

Tools disponíveis

Total: 15 tools geradas a partir do snapshot OpenAPI ERP. Inclui as rotas routes/erp.php do portal mais alguns endpoints de produto que a API ERP compartilha.

Faturamento e cancelamento de pedidos (4)

| Tool | Endpoint | Descrição | |---|---|---| | erp_integration_v1_orders_invoice_create | POST /erp/integration/v1/orders/invoice | Informa faturamento de pedidos pelo ERP, anexando dados da NFe. | | erp_integration_v1_orders_invoice_cancel | POST /erp/integration/v1/orders/invoice/cancel | Cancela uma NFe específica. | | erp_integration_v1_orders_cancel | POST /erp/integration/v1/orders/cancel | Cancela pedido. | | erp_integration_v1_orders_callback_create | POST /erp/integration/v1/orders/callback | Callback do ERP atualizando status do pedido. |

Boletos (2)

| Tool | Endpoint | Descrição | |---|---|---| | erp_integration_v1_bankslip_create | POST /erp/integration/v1/bankslip | Recebe um ou mais boletos do ERP e associa às NFes. | | erp_integration_v1_bankslip_document_update | PATCH /erp/integration/v1/bankslip/document | Atualiza dados de um título já existente. |

Produtos — preços, estoques, aplicações (4)

| Tool | Endpoint | Descrição | |---|---|---| | erp_integration_v1_products_stock_and_prices_list | GET /erp/integration/v1/products/stock-and-prices | Lista de preços e estoques de um produto. | | erp_integration_v1_products_all_prices_stocks_create | POST /erp/integration/v1/products/all-prices-stocks | Preços/estoques em todos os CDs disponíveis. | | erp_integration_v1_products_stock_by_customer_list | GET /erp/integration/v1/products/stock-by-customer | Estoques nos CDs do franqueado, dado o CNPJ. | | erp_integration_v1_products_aplicacoes_create | POST /erp/integration/v1/products/aplicacoes | Aplicações de um produto pelo ID do catálogo. |

Cliente (1)

| Tool | Endpoint | Descrição | |---|---|---| | erp_integration_v1_customers_document_get | GET /erp/integration/v1/customers/document/{document} | Dados do franqueado pelo documento (CNPJ). |

Fila de integração de pedidos (3)

| Tool | Endpoint | Descrição | |---|---|---| | erp_integration_v1_sales_integration_queue_orders_list | GET /erp/integration/v1/sales/integration-queue/orders | Lista paginada da fila de integração. | | erp_integration_v1_sales_integration_queue_summary_list | GET /erp/integration/v1/sales/integration-queue/summary | Resumo agregado (cards/gráficos). | | erp_integration_v1_sales_integration_queue_filters_list | GET /erp/integration/v1/sales/integration-queue/filters | Opções para filtros de UI. |

Importação manual de pedido (1)

| Tool | Endpoint | Descrição | |---|---|---| | erp_integration_v1_orders_manual_create | POST /erp/integration/v1/orders/manual | Importa uma ordem de venda manualmente. |

Nota: os nomes das tools com prefixo erp_integration_v1_ são longos porque os paths OpenAPI do guard erp não são processados pelo redutor de prefix do gerador (que cobre apenas /integration/v1/ e /api/integration/v1/). Há issue planejada para encurtar os nomes em uma versão futura — vai ser breaking change.

Modo detail

A maioria das tools de listagem retorna apenas campos resumidos por padrão (id, nome, status, valores chave) e limita a 50 itens por chamada. Para receber o objeto completo:

• Use a tool <recurso>_get(id) correspondente, OU
• Adicione detail: true na chamada de listagem.

Exemplo:

erp_integration_v1_sales_integration_queue_orders_list({ status: "failed", detail: true })

Erros comuns

| Erro | Significado | Ação | |---|---|---| | Configuração ausente: defina a variável de ambiente ANCORA_ERP_USER. (ou _PASSWORD) | Env var não setada. | Adicione no JSON do cliente MCP e reinicie. | | Falha de autenticação: /erp/integration/v1/auth/login returned 401: ... | Credenciais ERP inválidas. | Verifique usuário e senha. Se mudou recentemente, atualize a config. | | Falha de autenticação: ... (em chamada não-login) | Token cacheado revogado server-side. Servidor já tentou re-login + retry uma vez sem sucesso. | Verifique se a conta foi desabilitada no portal. | | Limite de requisições atingido. | Rate limit. | Aguarde. Servidor faz uma única retentativa em 429. | | Erro da API (HTTP 403). ... | A conta tem credenciais válidas mas sem permissão para o endpoint. | Verifique permissões da conta [email protected] (ou a que estiver usando) no portal. |

Logs estruturados ficam em stderr (com Authorization header e campos password/*token* redacted automaticamente). Capturados pelo Claude Desktop em ~/Library/Logs/Claude/mcp-server-*.log. Suba o nível com ANCORA_LOG_LEVEL=debug para ver request/response.

Segurança operacional

• Conta dedicada. Use sempre uma conta de serviço (default [email protected]), não credenciais pessoais. Permite auditar e revogar sem afetar usuários.
• Senha em env var apenas. Nunca em arquivo committed.
• Rotação periódica. Troque a senha conforme política interna.
• Logs filtrados. Headers sensíveis e campos password/*token* são redacted antes de gravar em stderr.
• Token só em memória. Encerrar o processo descarta o JWT.

Atualizando para versão mais recente

npx -y @rede-ancora/mcp-portal-b2b-internal@latest força fetch da última versão. Reinicie o cliente MCP após atualizar config.

Para pinar versão específica: @rede-ancora/[email protected] no args.

Reportando bugs

Abra issue interna em https://github.com/Rede-Ancora/portal-b2b/issues com tag mcp-internal. Inclua:

• Versão do pacote.
• Cliente MCP + versão.
• ANCORA_LOG_LEVEL=debug rodando + trecho relevante dos logs (com credenciais redacted automaticamente).
• Tool chamada + payload sanitizado.

Licença

UNLICENSED — uso restrito a equipe interna da Rede ANCORA.