protheus-mcp-server (piloto)

Conector MCP somente-leitura para consulta ao Protheus (TOTVS) da DFL. Expõe 10 endpoints GET como tools MCP, com autenticação OAuth2 (password grant + refresh automático) e tratamento amigável de respostas vazias/erros.

Este conector apenas consulta (GET). Não altera nada no Protheus. Os fontes .prw são usados só como referência de contrato — nunca são modificados.

Configuração

Copie .env.example para .env e preencha:

• PROTHEUS_BASE_URL — base REST (inclui /rest/03).
• PROTHEUS_USER / PROTHEUS_PASSWORD — credenciais OAuth2. Use um usuário de serviço só-leitura.
• PROTHEUS_TENANT_ID — empresa,filial (ex.: 03,01). Deixe vazio para não enviar o header.
• PROTHEUS_DFL_TOKEN — token dos WS customizados (só se a MV DFL_TOKEN estiver ligada).

Build e execução

npm install
npm run build
node dist/index.js        # inicia o servidor MCP via stdio

As variáveis de ambiente precisam estar carregadas (via .env do seu runner, Docker, ou export).

Tools (10 endpoints do piloto)

Tool	Endpoint	Observação
protheus_limite_credito_cliente	/api/fat/v1/CustomerCreditLimit	✅ com dados
protheus_condicoes_pagamento	/api/fat/v1/paymentcondition	✅ com dados
protheus_produtos_mrp	/api/pcp/v1/mrpproduct	base pode estar vazia
protheus_saldo_estoque_mrp	/api/pcp/v1/mrpstockbalance	base pode estar vazia
protheus_armazens_mrp	/api/pcp/v1/mrpwarehouse	base pode estar vazia
protheus_solicitacoes_compra_mrp	/api/pcp/v1/mrppurchaseorder	= Solicitações (ambiente DFL)
protheus_pedidos_compra_mrp	/api/pcp/v1/mrppurchaserequest	= Pedidos (ambiente DFL)
protheus_folha_pagamento	/payment/...	RH — dado sensível (LGPD)
protheus_clientes_por_vendedor	/WSRCLIENTE?email=	e-mail do VENDEDOR
protheus_saldo_cliente	/WSRSALDOCLIENTE?cliente=	saldo em aberto (SE1)

Tratamento amigável de respostas

Regra geral aplicada a toda tool (protheusClient.normalize):

• Lista vazia (items: []), 404 "Nenhum registro foi encontrado" → mensagem "Nenhum registro encontrado para os filtros informados." (não é erro).
• 500 (inclui o comportamento conhecido de alguns WS customizados quando não há registro ou falta parâmetro) → mensagem explicativa pedindo revisão dos parâmetros.
• 401 → renova o token uma vez e repete; persistindo, retorna erro de autorização.
• Formatos: envelope padrão {hasNext, items} e o formato custom dos WSR* são ambos aceitos.

Regra de autenticação (token/refresh)

O endpoint OAuth2 do Protheus é sensível à codificação dos parâmetros: se username/password/ refresh_token forem 100% percent-encoded (ex.: @ → %40), a autenticação falha. Por isso o cliente monta as URLs de token e refresh com os parâmetros direto na URL, escapando apenas o que quebraria a própria URL (#, &, +, espaço e %) e preservando @, !, etc. Ver ProtheusClient.encTokenParam. Não trocar por URLSearchParams — ele reescapa o @ e volta a dar erro de autenticação.

Contratos

Os contratos completos (rotas, parâmetros, campos de retorno, bugs conhecidos) estão em ../protheus-piloto-contratos.json e ../Protheus_Piloto_Spec_10_Endpoints.md.