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).

Related MCP server: appd-mcp

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)

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.