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

Servidor MCP (Model Context Protocol) que expõe a API de integração do portal-b2b da Rede ANCORA para clientes de IA — Claude Desktop, Cursor, Cline, Claude Code e qualquer outro cliente compatível com MCP.

Um agente conectado ao servidor pode listar produtos, consultar preços e estoque, gerenciar carrinho e checkout, acompanhar pedidos, NFes, boletos, garantias e muito mais — sempre escopado ao CNPJ do franqueado dono da API key.

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 do portal embarcado no pacote.
2. Gera dinamicamente uma tool MCP para cada endpoint da API de integração.
3. Encaminha cada chamada do agente para a API HTTPS do portal usando a API key do franqueado.
4. Retorna a resposta de volta ao cliente MCP, com modo resumido por padrão para preservar o contexto do LLM.

Pré-requisitos

• Node.js 20 ou superior. O npx precisa de Node 20+ para rodar o pacote.
• API key SARA (variável ANCORA_API_KEY). É a mesma chave usada nas integrações via header X-API-KEY. Solicite ao seu canal de relacionamento da Rede ANCORA caso ainda não tenha.

Instalação

Não precisa instalar nada manualmente. Adicione ao arquivo de configuração do seu 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-franchise": {
      "command": "npx",
      "args": ["-y", "@rede-ancora/mcp-portal-b2b-franchise@latest"],
      "env": {
        "ANCORA_API_KEY": "<sua_api_key>",
        "ANCORA_ENV": "prod"
      }
    }
  }
}

Reinicie o Claude Desktop para carregar.

Cursor

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

{
  "mcpServers": {
    "rede-ancora-franchise": {
      "command": "npx",
      "args": ["-y", "@rede-ancora/mcp-portal-b2b-franchise@latest"],
      "env": { "ANCORA_API_KEY": "<sua_api_key>" }
    }
  }
}

Cline / Claude Code

Mesma estrutura do Claude Desktop, no arquivo de config MCP do cliente.

Variáveis de ambiente

| Variável | Obrigatória | Default | Descrição | |---|---|---|---| | ANCORA_API_KEY | sim | — | API key SARA do franqueado. Identifica a conta e aplica scoping por CNPJ. | | ANCORA_ENV | não | prod | prod ou staging. Determina o host base de produção/homologação. | | 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). Útil para testes pontuais ou ambientes customizados. | | ANCORA_LOG_LEVEL | não | info | error, warn, info, debug. Logs vão para stderr (capturados pelo Claude Desktop em ~/Library/Logs/Claude/mcp-server-*.log). |

Autenticação

Todas as chamadas usam header X-API-KEY: <ANCORA_API_KEY>. O portal valida a chave via SARA SSO, resolve o CNPJ associado e aplica o scoping no nível do framework. O servidor MCP nunca bypassa permissões — se a sua API key não permite uma operação, a tool retorna erro de permissão.

A API key é estática; não há fluxo de refresh. Se precisar trocar, atualize a variável de ambiente e reinicie o cliente MCP.

Modo detail

A maioria das tools de listagem retorna por padrão apenas campos resumidos (id, nome, preço, estoque, etc.) e limita a 50 itens por chamada. Isso protege o contexto do LLM de payloads grandes. Para obter o objeto completo de um item específico, use:

• A tool <recurso>_get(id) correspondente, OU
• Adicione detail: true na chamada de listagem para receber todos os campos.

Exemplo:

products_full_search({ search: "pastilha freio", detail: true })

Tools disponíveis

A listagem abaixo é gerada a partir do snapshot OpenAPI do portal congelado no pacote. Total: 77 tools.

Carrinho de compras (8)

| Tool | Endpoint | Descrição | |---|---|---| | checkout_list | GET /checkout | Cria novo carrinho ou recupera o ativo do cliente. | | checkout_get | GET /checkout/{cartId} | Obtém dados do carrinho. | | checkout_delete | DELETE /checkout/{cartId} | Deleta o carrinho. | | checkout_items_create | POST /checkout/{cartId}/items | Adiciona itens ao carrinho. | | checkout_items_update | PATCH /checkout/{cartId}/items/{itemId} | Atualiza item específico. | | checkout_items_delete | DELETE /checkout/{cartId}/items/{itemId} | Deleta item específico. | | checkout_bulk_items_update | PATCH /checkout/{cartId}/bulk/items | Atualiza múltiplos itens em lote. | | checkout_bulk_items_delete_create | POST /checkout/{cartId}/bulk/items/delete | Deleta múltiplos itens em lote. |

Checkout — fechamento (5)

| Tool | Endpoint | Descrição | |---|---|---| | checkout_review | POST /checkout/{cartId}/review | Revisão do carrinho antes de fechar pedido. | | checkout_payments_create | POST /checkout/{cartId}/payments | Lista formas de pagamento disponíveis. | | checkout_payments_update | PATCH /checkout/{cartId}/payments | Atualiza forma de pagamento. | | checkout_payments_condition_create | POST /checkout/{cartId}/payments/condition | Lista condições de pagamento. | | checkout_order_create | POST /checkout/{cartId}/order | Fecha o pedido a partir do carrinho. |

Produtos (12)

| Tool | Endpoint | Descrição | |---|---|---| | products_list | GET /products | Busca de produtos na base do portal de compras. | | products_full_search | GET /products/full-search | Busca completa (portal + catálogo). | | products_bulk_search | POST /products/bulk-search | Busca em massa. | | products_bulk_create | POST /products/bulk | Dados cadastrais a partir de lote de códigos (CNA/CODE/GTIN). | | products_brands_list | GET /products/brands | Lista de marcas. | | products_lines_list | GET /products/lines | Lista de linhas. | | products_families_list | GET /products/families | Lista de famílias. | | products_prices_stocks_create | POST /products/prices-stocks | Preços e estoques de produtos especificados. | | products_prices_stocks_warehouses_create | POST /products/prices-stocks-warehouses | Preços/estoques em todos os CDs do usuário. | | products_warehouses_create | POST /products/warehouses/{cna} | Outros CDs com estoque do produto. | | products_conditions_get | GET /products/conditions/{cna} | Condições de pagamento, modalidades, preços e estoques por CNA. | | products_similares_create | POST /products/similares | Produtos similares. |

Catálogo de produtos (3)

| Tool | Endpoint | Descrição | |---|---|---| | products_superbusca_create | POST /products/superbusca | Superbusca no catálogo. | | products_aplicacoes_create | POST /products/aplicacoes | Aplicações de um produto pelo ID do catálogo. | | products_vendamais_create | POST /products/vendamais | "Venda mais" relacionados a um produto. |

Pedidos (vendas) (8)

| Tool | Endpoint | Descrição | |---|---|---| | sales_orders_list | GET /sales/orders | Lista de pedidos do franqueado. | | sales_orders_get | GET /sales/orders/{orderId} | Dados de um pedido específico. | | sales_orders_items_list | GET /sales/orders/{orderId}/items | Itens de um pedido. | | sales_orders_items_get | GET /sales/orders/{orderId}/items/{itemId} | Item específico de um pedido. | | sales_orders_cancel | GET /sales/orders/{orderId}/cancel | Cancela um pedido. | | sales_orders_reorder | POST /sales/orders/{orderId}/reorder | Refaz carrinho a partir de pedido existente. | | sales_pendencies_list | GET /sales/pendencies | Pendências de pedidos abertos. | | sales_pendencies_by_orders_list | GET /sales/pendencies/by-orders | Pendências agrupadas por pedido. |

NFe (notas fiscais) (7)

| Tool | Endpoint | Descrição | |---|---|---| | sales_nfe_list | GET /sales/nfe | Notas fiscais disponíveis. | | sales_nfe_selling_order_get | GET /sales/nfe/selling-order/{orderId} | NFes por número do pedido no portal. | | sales_nfe_pdf_get | GET /sales/nfe/pdf/{nfeId} | PDF da NFe por ID. | | sales_nfe_pdf_get | GET /sales/nfe/pdf/{nfeNumber}/{serie}/{uf}/{emitente} | PDF da NFe por número. | | sales_nfe_xml_get | GET /sales/nfe/xml/{nfeId} | XML da NFe por ID. | | sales_nfe_xml_get | GET /sales/nfe/xml/{nfeNumber}/{serie}/{uf}/{emitente} | XML da NFe por número. | | sales_nfe_render_type_nfe_get | GET /sales/nfe/render/type/{type}/nfe/{nfeId} | Conteúdo XML/PDF renderizado. |

Boletos (2)

| Tool | Endpoint | Descrição | |---|---|---| | sales_payment_documents_list | GET /sales/payment-documents | Lista de boletos do franqueado. | | sales_payment_documents_render_type_get | GET /sales/payment-documents/render/{id}/type/{type} | Relatório de aglutinação ou título do boleto. |

Garantias (19)

| Tool | Endpoint | Descrição | |---|---|---| | warranty_list | GET /warranty | Lista ordens de garantia. | | warranty_get | GET /warranty/{warrantyId} | Dados de uma ordem específica. | | warranty_create | POST /warranty | Cria nova ordem. | | warranty_delete | DELETE /warranty/{warrantyId} | Deleta ordem. | | warranty_start | POST /warranty/{warrantyId}/start | Inicia ordem. | | warranty_cancel | POST /warranty/cancel | Cancela ordem. | | warranty_export_pdf_list | GET /warranty/{warrantyId}/export/pdf | Relatório PDF da ordem. | | warranty_types_list_list | GET /warranty/types/list | Tipos de garantia disponíveis. | | warranty_states_list_list | GET /warranty/states/list | Status possíveis. | | warranty_items_list | GET /warranty/{warrantyId}/items | Itens da ordem. | | warranty_items_attach | POST /warranty/{warrantyId}/items/attach | Adiciona item. | | warranty_items_attach_delete | DELETE /warranty/{warrantyId}/items/attach/{itemId} | Remove item. | | warranty_items_products_list | GET /warranty/{warrantyId}/items/products | Produtos do item. | | warranty_items_products_get | GET /warranty/{warrantyId}/items/products/{itemId} | Detalhe de produto do item. | | warranty_items_row_create | POST /warranty/{warrantyId}/items/row/{itemId} | Adiciona row + respostas no checklist. | | warranty_items_product_create | POST /warranty/{warrantyItemId}/items/product/{warrantyItemRowId} | Registra resposta do checklist. | | warranty_item_row_delete | DELETE /warranty/item/{ItemId}/row/{rowId} | Remove row de item. | | warranty_nfe_attach | POST /warranty/{warrantyId}/nfe/attach | Anexa NFe à ordem. | | warranty_<id>_nfe_detach | POST /warranty/<id>/nfe/detach | Remove NFe da ordem. |

Logística (7)

| Tool | Endpoint | Descrição | |---|---|---| | logistics_carriers_create | POST /logistics/carriers | Formas de entrega disponíveis. | | logistics_haulers_list | GET /logistics/haulers | Transportadores associados. | | logistics_haulers_get | GET /logistics/haulers/{id} | Dados de um transportador. | | logistics_haulers_create | POST /logistics/haulers | Cria transportador. | | logistics_haulers_update | PATCH /logistics/haulers/{id} | Atualiza transportador. | | logistics_haulers_delete | DELETE /logistics/haulers/{id} | Deleta transportador. | | logistics_haulers_vehicletypes_list | GET /logistics/haulers/vehicleTypes | Tipos de veículos. |

Solicitações de registro de produto (3)

| Tool | Endpoint | Descrição | |---|---|---| | product_registration_list | GET /product-registration | Lista solicitações. | | product_registration_create | POST /product-registration | Cria solicitação. | | product_registration_types_list | GET /product-registration/types | Tipos de solicitação. |

Outras (3)

| Tool | Endpoint | Descrição | |---|---|---| | profile_list | GET /profile | Dados da conta do franqueado. | | modalities_list | GET /modalities | Modalidades disponíveis. | | sale_offers_brands_list | GET /sale-offers/brands | Ofertas da agenda da semana. |

Erros comuns

| Erro | Significado | Ação | |---|---|---| | Configuração ausente: defina a variável de ambiente ANCORA_API_KEY. | Env var não setada. | Adicione ANCORA_API_KEY no JSON do cliente MCP e reinicie. | | Falha de autenticação: ... | API key inválida ou expirada. | Verifique a key. Se estava válida, contate seu canal Rede ANCORA. | | Limite de requisições atingido. Tentar novamente em Ns. | Rate limit do portal. | Aguarde o tempo informado. O cliente automaticamente faz uma única retentativa em 429. | | Erro da API (HTTP 403). ... | Sem permissão para o recurso. | A API key não tem acesso. Contate seu canal Rede ANCORA. | | Falha de rede ao chamar a API: ... | Problema de conexão. | Verifique conectividade. Servidor faz até 3 retentativas com backoff exponencial. |

Logs detalhados ficam em stderr — ~/Library/Logs/Claude/mcp-server-*.log no macOS. Suba o nível com ANCORA_LOG_LEVEL=debug para ver request/response (com headers sensíveis redacted).

Atualizando para versão mais recente

npx -y @rede-ancora/mcp-portal-b2b-franchise@latest em cada chamada usa cache local após o primeiro download. Para forçar atualização, limpe o cache do npx ou adicione -y (já presente na config exemplo) e reinicie o cliente.

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

Reportando bugs

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

• Versão do pacote (npx @rede-ancora/mcp-portal-b2b-franchise@latest --version).
• Cliente MCP usado (Claude Desktop, Cursor, etc.) e versão.
• ANCORA_LOG_LEVEL=debug rodando + trecho relevante dos logs (com qualquer info sensível redacted).
• Tool chamada + payload (sem credenciais).

Licença

UNLICENSED — uso restrito a franqueados Rede ANCORA. O pacote é distribuído publicamente no npm para facilitar a instalação via npx, mas não há licença permissiva para redistribuição ou modificação.