totvs-tickets-mcp

Servidor MCP (Model Context Protocol) local, somente leitura, que expoe os tickets de suporte da TOTVS (Portal do Cliente / Central de Atendimento, suporte.totvs.com) como tools para LLMs no Claude Code, Claude Desktop e Cursor.

Escrito em Python, mesmo molde do tspace-mcp: keyring nativo do OS pra credenciais, cache de token cifrado (Fernet), headers de browser e re-login transparente.

Escopo: read-only. Lista, filtra e le tickets/comentarios. Nao cria, nao atualiza, nao fecha chamados.

Como autentica (o ponto nao-obvio)

O portal da TOTVS nao usa um bearer/cookie simples. A cadeia e:

Fluig Identity (usuario + senha + MFA/TOTP)  ->  SAML SSO  ->  sessao no portal
                                                                    |
                          GET .../portal/jwt/create  ->  token (JWT Zendesk, ~13h)
                                                                    |
   ti-services.totvs.com.br/customer-portal-backend/help-center/tickets/*
                          (o token vai no BODY do POST, nao em header)

O client.py replica isso automaticamente (login com senha, gera o codigo TOTP a partir do seed do autenticador, faz a danca SAML, emite o token). O token de ~13h fica cacheado cifrado em ~/.totvs-tickets-mcp-token.json, entao a danca so acontece ~1x por turno de trabalho.

Instalacao

pip install -e .          # le pyproject.toml (mcp, httpx, keyring, cryptography, pyotp)

Isso instala os comandos totvs-tickets-mcp, totvs-tickets-setup e totvs-tickets-probe em <python>/Scripts/.

Configuracao (primeira vez)

totvs-tickets-setup

Pede tres coisas, guardadas no keyring do OS (servico totvs-tickets-mcp):

Segredo	O que e
Username	login Fluig (ex: nome.sobrenome)
Senha	senha do acesso TOTVS
Seed TOTP	a chave secreta base32 do app autenticador (a que aparece em "inserir manualmente" ao cadastrar o MFA)

O seed TOTP e o que permite gerar o codigo de 6 digitos sem o app. Se voce so tem o app e nao guardou o seed, precisa re-cadastrar o MFA no Fluig pra obter um seed novo (o app e este MCP passam a usar o mesmo seed).

Depois, teste o login de ponta a ponta:

totvs-tickets-setup --test      # loga e imprime seu userId / customerCode / organizacoes
totvs-tickets-setup --show      # mostra o que esta cadastrado (mascarado)
totvs-tickets-setup --remove    # apaga tudo

Se o login falhar, rode o probe (diagnostico verboso e seguro):

totvs-tickets-probe

Ele executa a cadeia inteira imprimindo apenas o formato das respostas (segredos redigidos como <str:len>), revelando onde quebrou (WAF, captcha, seed) ou confirmando os nomes de campo do fluxo.

Registrar no Claude Code

claude mcp add -s user totvs-tickets -- totvs-tickets-mcp

Apos editar client.py/server.py, reinicie a sessao do Claude Code (o MCP roda em processo persistente e nao recarrega sozinho).

Tools (todas read-only)

Tool	Endpoint	O que faz
totvs_whoami	(token)	userId, customerCode, organizacoes, validade do token
totvs_contato	contact/find-contact	dados cadastrais do contato logado
totvs_tickets_listar	tickets/get-tickets	busca por org + ticket_views (status, datas, produto/modulo/rotina, keywords) + paginacao
totvs_ticket_detalhe	tickets/get-ticket	detalhe de um ticket
totvs_ticket_comentarios	tickets/get-comments	andamentos/comentarios (com anexos)
totvs_tickets_status	tickets/get-tickets/filter-status	lista oficial de status (value+label)
totvs_tickets_filtros	tickets/filter/lookup/{tipo}	opcoes de produto/modulo/rotina pro filtro
totvs_tickets_motivos_prioridade	tickets/priority-reasons	motivos de priorizacao
totvs_notificacoes_count	user-notifications/count	qtd de notificacoes nao lidas
totvs_usuarios_buscar	users/get-users-zendesk-by-term...	busca usuarios/contatos por termo (min 3 chars)
totvs_departamentos	chats-departaments/get-departament-by-area	departamentos/areas de atendimento

Busca de tickets (load-bearing): a org primaria/pessoal do usuario costuma vir VAZIA — configure a org que concentra os chamados via TOTVS_DEFAULT_ORG (id via totvs_whoami). E ticket_views=3 (default) = tickets de outros; 1 = meus, 2 = em copia. Ver CLAUDE.md.

Variaveis de ambiente uteis

• TOTVS_USERNAME / TOTVS_PASSWORD / TOTVS_TOTP_SEED — override do keyring.
• TOTVS_DEFAULT_ORG — org padrao da busca (id Zendesk da org; veja via totvs_whoami). Vazio = todas as orgs visiveis.
• TOTVS_DEBUG=1 — log verboso do login em stderr (formato das respostas).
• TOTVS_NO_TOKEN_CACHE=1 — desliga o cache de token em disco.
• TOTVS_AUDIT_LOG=1 — apende timestamp+verbo+path+status em ~/.totvs-tickets-mcp-audit.log.
• TOTVS_TIMEOUT — timeout de request em segundos (default 60).

Arquivos sensiveis (nao commitar)

.gitignore bloqueia *.har, .totvs-tickets-mcp-token.json, *.env, chaves. O login usa credenciais reais — nunca capture o HAR do login sem cuidado (o request de senha vaza a senha em texto puro; ver docs/CLAUDE.md).

Estado

Funcionando (validado ponta a ponta em 03/07/2026): login automatico Fluig+MFA/TOTP+SAML, cache do token, e as tools totvs_tickets_listar, totvs_ticket_detalhe, totvs_ticket_comentarios, totvs_tickets_status, totvs_contato, totvs_whoami retornando dados reais.

Detalhe nao-obvio do login (o SPA seta o access_token como cookie via JS, que o cloudpass usa pra continuar o SSO) esta documentado em CLAUDE.md.

O esqueleto TypeScript anterior deste projeto esta arquivado em archive-ts/.