Skip to main content
Glama
InfoCAIJ MCP

InfoCAIJ MCP

by VitorTosti

InfoCAIJ MCP

Pergunte ao Claude como está a operação, em português, e receba a resposta calculada a partir dos dados reais do sistema.

Testes MCP dependências somente leitura

No Claude Desktop, a pergunta sobre o tempo da venda até a máquina ficar pronta é respondida pela ferramenta tempo_entre_etapas, com o aviso de que 93 de 135 máquinas pularam a etapa Pronta

Gravação real no Claude Desktop, com o banco da operação. Esperas aceleradas.

Servidor Model Context Protocol que conecta o InfoCAIJ, a plataforma interna que acompanha cerca de 300 máquinas por mês na CAIJ Informática, ao Claude e a qualquer outro cliente MCP. A gestão deixa de abrir telas e montar planilhas para perguntar coisas como:

"Onde a nossa fila está travando no último mês? Compare com a última semana."

O Claude chama tempo_por_etapa({"dias": 30}), tempo_por_etapa({"dias": 7}) e resumo_fila({}) e responde:

A fila trava em "Aguardando nota fiscal", tanto no último mês quanto na última semana. A mediana de cerca de 22 a 25 horas equivale a mais da metade do tempo de venda até a entrega, que é de 42 a 48 horas. [...] Das 27 máquinas em aberto, 15 estão aguardando nota fiscal.

Ver as sessões completas →

O que ele responde

Pergunta de negócio

Ferramenta

Como calcula

"Como está a bancada agora?"

resumo_fila

Máquinas por etapa, prioritárias e a mais antiga de cada etapa

"O que está travado há mais de 2 dias?"

itens_parados

Tempo desde a última mudança de etapa, filtrável por etapa

"Quanto tempo da venda até a máquina ficar pronta?"

tempo_entre_etapas

Média, mediana e p90 entre dois pontos da fila, por técnico, plataforma ou empresa; conta quem pulou etapas

"Onde a fila trava? Está melhorando?"

tempo_por_etapa

Mediana e p90 de cada etapa, reconstruídos do histórico, e o gargalo; com por_semana, a evolução semana a semana

"Quantas máquinas a bancada fechou esta semana?"

produtividade

Máquinas que chegaram a Pronta e a Entregue, por técnico e por dia

"Quanto vendemos por plataforma?"

vendas

Pedidos, máquinas, cancelamentos e devoluções por plataforma, empresa, vendedor ou dia

"Temos ThinkPad pronto?"

estoque

Unidades por situação e loja, e modelos disponíveis

"Em que pé está a máquina CN27YDZ?"

consultar_maquina

Dossiê por serial, código ou OS: venda, nota, checklist, garantia e histórico

E três prompts prontos, que o usuário escolhe no menu do Claude:

Prompt

O que entrega

relatorio_semanal

Relatório para a gestão: entregas, gargalo da semana contra o mês, máquinas paradas, ritmo por técnico, vendas e uma recomendação baseada em número

diagnostico_gargalo

Investigação de uma etapa: tempos, máquinas presas e o padrão no histórico das mais antigas, com a hipótese marcada como hipótese

status_pedido

Resposta para o vendedor, em até 3 frases, no tom de uma mensagem de WhatsApp

Horas corridas ou úteis

itens_parados, tempo_por_etapa e tempo_entre_etapas aceitam horas: "uteis". Uma máquina que entra em "Aguardando nota fiscal" na sexta às 17h e continua lá na segunda às 11h está há 66 h corridas, mas só 4 h úteis. O padrão é segunda a sexta, 08:00 às 18:00, fuso de Brasília, sem expediente nos feriados nacionais (inclusive a Sexta-feira Santa, calculada a partir da Páscoa). Se a segunda do exemplo fosse 12 de outubro, sobraria 1 h útil. Dá para mudar com INFOCAIJ_HORARIO_UTIL, INFOCAIJ_DIAS_UTEIS, INFOCAIJ_FUSO, INFOCAIJ_FERIADOS e INFOCAIJ_FERIADOS_NACIONAIS (ver Configuração). O resultado informa em horas qual medida foi usada e, em horas úteis, o expediente aplicado.

Tendência semana a semana

tempo_por_etapa com por_semana: true devolve, além do período inteiro, uma lista semanas: blocos de 7 dias terminando agora, do mais antigo ao mais recente, cada um com o gargalo, o tempo por etapa e o tempo da venda até a entrega. Assim "está melhorando?" e "o gargalo mudou?" se respondem numa chamada só, e o prompt relatorio_semanal usa isso para comparar a semana com as três anteriores. Um teste confere que as semanas somam exatamente as passagens do período e que a mais recente bate com dias: 7.

Saída estruturada

Toda ferramenta devolve o resultado em dois formatos: o texto JSON de sempre e o structuredContent, descrito por um outputSchema. O cliente pode validar o resultado e o modelo recebe campos tipados. Clientes do protocolo anterior a 2025-06-18 continuam recebendo só o texto. Um teste confere, para cada ferramenta, que o resultado real cumpre o esquema anunciado.

Related MCP server: mcp-pdv-demo

Como funciona

flowchart LR
    U(["Gestão e vendedores"]) -- "pergunta em português" --> C["Claude<br/>(Desktop, Code ou outro cliente MCP)"]
    C -- "JSON-RPC por stdio" --> S["infocaij-mcp<br/>8 ferramentas · 3 prompts"]
    S -- "somente leitura" --> DB[("Banco do InfoCAIJ<br/>SQLite ou PostgreSQL")]
    APP["InfoCAIJ<br/>(app web)"] -- "grava" --> DB

O ponto central é o tempo_por_etapa. O InfoCAIJ não guarda quanto tempo cada máquina ficou em cada etapa; ele guarda um histórico de eventos como Status alterado de Aguardando retirada para Aguardando nota fiscal.. O servidor reconstrói a linha do tempo de cada máquina a partir desses eventos e calcula mediana e percentil 90 por etapa. Foi assim que a pergunta "onde a fila trava?" ganhou resposta com número.

Decisões de projeto

Somente leitura em três camadas. O arquivo é aberto com readOnly pelo driver, a conexão recebe PRAGMA query_only (no PostgreSQL, default_transaction_read_only) e o adaptador recusa qualquer SQL que não seja um único SELECT ou WITH. Um teste roda todas as ferramentas e confere que o hash do banco não muda.

Nenhum dado pessoal de cliente. O banco tem nomes, e-mails e telefones de clientes em garantias e cadastros. Nenhuma consulta seleciona essas colunas, e não há SELECT *. O banco de demonstração planta dados pessoais falsos, e um teste consulta todas as 314 máquinas com garantia para provar que nada vaza.

Ferramentas de negócio, não SQL livre. Uma ferramenta "execute este SQL" seria mais flexível e muito menos segura: o modelo poderia ler qualquer tabela. Cada ferramenta responde a uma pergunta que a operação faz de verdade, com argumentos validados (enums, limites e tamanho máximo).

A descrição da ferramenta é o prompt. O modelo escolhe a ferramenta lendo a descrição, então cada uma diz quando usá-la, com exemplos de pergunta. Erros de argumento voltam como resultado com isError, para o modelo corrigir a chamada sozinho em vez de a conversa quebrar.

Zero dependências. O protocolo MCP (JSON-RPC 2.0 por stdio) está implementado em cerca de 200 linhas, com o node:sqlite embutido no Node. Para um servidor que lê dados da empresa, isso significa nada de terceiros para auditar e instalação com um git clone.

Avaliado com o modelo, não só com testes

Além dos 65 testes automatizados, o servidor foi conectado ao Claude Code e testado com perguntas reais. Uma das sessões mostrou um problema que nenhum teste unitário pegaria:

Pergunta

"Quantas máquinas vendemos por plataforma nos últimos 30 dias, e onde há mais devolução?"

Antes

O modelo respondeu certo, mas avisou: "não sei se a ferramenta conta a devolução pela data da venda ou pela data da devolução."

Causa

A descrição de vendas não dizia qual data define o período.

Correção

A descrição passou a dizer que o período é pela data da venda e como calcular a taxa de devolução.

Depois

O modelo passou a calcular a taxa por plataforma direto ("Cassio: 3 devoluções em 62 máquinas, 4,8%") e deixou de hesitar.

O segundo problema só apareceu com o banco real:

Sintoma

Nos dados de demonstração, o gargalo era claro. No banco real, o servidor apontou "Pronta", uma etapa com mediana de 0,8 h.

Causa

O gargalo era escolhido pela mediana. Em "Aguardando retirada", a maioria das máquinas passava em menos de 1 h, mas os 10% piores esperavam mais de 3 dias. A mediana escondia essa cauda.

Correção

O gargalo passou a ser a etapa onde as máquinas somam mais horas paradas, com a participação de cada etapa no total. A ferramenta também passou a listar etapas que a equipe não usa.

Garantia

Um teste reproduz o caso: 9 máquinas passam em 1 h e 1 fica 100 h, e o gargalo tem de ser essa etapa.

Instalação

Requer Node.js 22.18 ou superior (roda TypeScript direto, sem build). Nada para instalar além disso.

git clone https://github.com/VitorTosti/infocaij-mcp.git
cd infocaij-mcp
npm test          # 65 testes
npm run seed      # cria demo/infocaij-demo.sqlite com dados fictícios

Claude Code

claude mcp add infocaij \
  -e INFOCAIJ_DB_PATH=/caminho/para/controle-vendas-os.sqlite \
  -- node --disable-warning=ExperimentalWarning /caminho/para/infocaij-mcp/src/server.ts

Claude Desktop

Em claude_desktop_config.json (no Windows, %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "infocaij": {
      "command": "node",
      "args": ["--disable-warning=ExperimentalWarning", "C:\\caminho\\para\\infocaij-mcp\\src\\server.ts"],
      "env": { "INFOCAIJ_DB_PATH": "C:\\caminho\\para\\controle-vendas-os.sqlite" }
    }
  }
}

PostgreSQL

O InfoCAIJ em produção usa PostgreSQL. Instale o driver (é opcional, o servidor continua sem dependências para quem usa SQLite) e use INFOCAIJ_DATABASE_URL no lugar de INFOCAIJ_DB_PATH:

npm install pg
claude mcp add infocaij \
  -e INFOCAIJ_DATABASE_URL=postgres://leitura:senha@servidor:5432/infocaij \
  -- node --disable-warning=ExperimentalWarning /caminho/para/infocaij-mcp/src/server.ts

A sessão abre com default_transaction_read_only=on e statement_timeout, e o adaptador só aceita SELECT. Crie também um papel do banco só com SELECT nas tabelas usadas (sales, sale_items, item_history, stock_units, stock_lots, product_suggestions, machine_lifecycle_events e warranties), para a trava existir também do lado do banco. Dê SELECT apenas nas colunas que o servidor consulta, se quiser excluir de vez os dados pessoais das garantias.

Banco em servidor remoto

Se o banco está numa VPS, o cliente pode iniciar o servidor por SSH. Nenhuma porta nova é aberta, e o banco nunca sai do servidor:

{
  "mcpServers": {
    "infocaij": {
      "command": "ssh",
      "args": ["-T", "usuario@servidor", "INFOCAIJ_DB_PATH=/srv/infocaij/data/controle-vendas-os.sqlite node --disable-warning=ExperimentalWarning /srv/infocaij-mcp/src/server.ts"]
    }
  }
}

Para testar sem o banco real

npm run seed
claude mcp add infocaij-demo \
  -e INFOCAIJ_DB_PATH=$PWD/demo/infocaij-demo.sqlite \
  -e INFOCAIJ_MCP_NOW=2026-10-28T21:00:00.000Z \
  -- node --disable-warning=ExperimentalWarning $PWD/src/server.ts

O banco de demonstração simula 45 dias de operação (cerca de 480 máquinas e 4.600 eventos) com o mesmo esquema do InfoCAIJ. Todos os nomes são inventados.

Configuração

Variável

Para quê

Padrão

INFOCAIJ_DB_PATH

Arquivo SQLite do InfoCAIJ

(use esta ou a URL)

INFOCAIJ_DATABASE_URL

URL do PostgreSQL do InfoCAIJ (exige npm install pg)

INFOCAIJ_MCP_TIMEOUT_MS

Tempo máximo de uma consulta

30000

INFOCAIJ_HORARIO_UTIL

Expediente para horas úteis

08:00-18:00

INFOCAIJ_DIAS_UTEIS

Dias úteis (1 = segunda, 7 = domingo)

1-5

INFOCAIJ_FUSO

Fuso do expediente

-03:00

INFOCAIJ_FERIADOS

Outras datas sem expediente: AAAA-MM-DD (uma vez) ou MM-DD (todo ano), separadas por vírgula. Ex.: Carnaval e feriado municipal

(nenhuma)

INFOCAIJ_FERIADOS_NACIONAIS

nao deixa de descontar os feriados nacionais

sim

INFOCAIJ_MCP_NOW

Data e hora fixas, para demonstrações e testes

agora

Robustez

  • Tempo limite: uma consulta que passa do limite volta como erro para o modelo (que pode tentar um período menor), e, no PostgreSQL, o statement_timeout da sessão interrompe a consulta no próprio banco.

  • Tamanho: uma resposta maior que 200 mil caracteres é recusada com orientação, em vez de estourar o contexto do modelo.

  • Concorrência e cancelamento: os pedidos rodam em paralelo, então uma consulta lenta não trava um ping. Um notifications/cancelled do cliente descarta a resposta.

  • Encerramento: ao fechar a entrada, o servidor termina o que está em andamento antes de sair.

  • Entrada: uma linha maior que 1 MB é recusada sem derrubar o servidor, e uma configuração inválida impede a partida com uma mensagem clara.

  • Conexão PostgreSQL reaproveitada: a conexão fica aberta entre as perguntas, em vez de abrir e autenticar a cada chamada. Se o banco reiniciar ou a rede cair, a próxima chamada abre outra, e uma falha ao conectar não fica guardada.

  • Só o histórico necessário: tempo_por_etapa e tempo_entre_etapas carregam as máquinas em aberto e as que mudaram de etapa no período, não o histórico inteiro do banco. Com 7 dias, o banco de demonstração lê 446 linhas de histórico em vez de 3.183, com resultado idêntico (conferido em 390 combinações de argumentos).

  • Ordem determinística: toda consulta com empate tem desempate explícito, para SQLite e PostgreSQL darem o mesmo resultado.

Estrutura

src/
  server.ts     transporte stdio, configuração e encerramento
  protocol.ts   MCP: initialize, tools/*, prompts/*, tempo limite, cancelamento, erros JSON-RPC
  tools.ts      definição, descrição, validação e esquema de saída das 8 ferramentas
  queries.ts    consultas e reconstrução da linha do tempo por máquina
  horario.ts    horas úteis, feriados e leitura do expediente
  prompts.ts    os 3 prompts prontos
  db.ts         acesso somente leitura (SQLite) e a interface comum
  postgres.ts   adaptador PostgreSQL (driver pg opcional)
  domain.ts     etapas e vocabulário do InfoCAIJ
scripts/seed-demo.ts   banco de demonstração com o mesmo esquema
test/                  protocolo, cálculos com valores conhecidos, segurança e privacidade,
                       saída estruturada, horas úteis, PostgreSQL (driver falso) e robustez
docs/demonstracao.md   sessões reais com o Claude

Limitações

  • Os feriados nacionais são descontados; estaduais, municipais e pontos facultativos (Carnaval, Corpus Christi) entram só se listados em INFOCAIJ_FERIADOS.

  • O técnico de produtividade é o responsável atual da máquina, não necessariamente quem a moveu de etapa. O item_history do InfoCAIJ não grava quem fez cada mudança de status, então atribuir pelo evento exigiria o sistema registrar o autor.

  • O adaptador PostgreSQL foi validado contra um PostgreSQL em memória (pg-mem) com o mesmo esquema do InfoCAIJ e contra um driver falso nos testes, mas ainda não contra o banco de produção. Rode primeiro contra uma cópia.

Autoria

Vitor Tosti: levantamento das perguntas da operação, desenho das ferramentas e prompts, implementação, testes e avaliação com o modelo. Construído com o Claude Code.

LinkedIn · Estudo de caso do InfoCAIJ

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language analysis of automotive sales data stored in MariaDB using Google Gemini AI to automatically generate and execute SQL queries from Portuguese language questions.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query a retail and food-service point-of-sale database through predefined business tools for sales summaries, top products, margins, stagnant inventory, cash reconciliation, and optional stock adjustments, returning formatted markdown answers.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects to your own company's Protheus ERP via the official REST API, enabling read-only natural-language queries of branches, customers, products, stock, sales, orders, invoice totals, production orders, and MRP purchasing. It also maps which APIs your installation answers and can call custom REST routes, without writing to the ERP.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude to answer questions about a small business's own data by providing predefined sales, customer, refund, and inventory tools, plus a guarded read-only SQL query tool with audit logging.
      6
      MIT