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.