mcp-pdv-demo

Servidor MCP (Model Context Protocol) que conecta um assistente de IA ao banco de um PDV — ponto de venda de varejo e food service.

Em vez de expor um executar_sql genérico, ele expõe perguntas de negócio: qual foi o faturamento, o que dá mais margem, o que está encalhado no estoque, se o caixa fechou certo. O modelo escolhe a ferramenta; o SQL fica do lado de cá, escrito e testado.

Banco 100% sintético, gerado por seed determinístico. Nenhum dado real de cliente.

Claude / Cursor / qualquer host MCP
        │  stdio
        ▼
   mcp-pdv-demo  ──►  Prisma  ──►  SQLite
   (6 tools de leitura + 1 de escrita, sob flag)

Rodando

npm install
npm run setup     # cria o banco e gera ~96 produtos, 90 dias, ~3.700 vendas
npm run dev       # sobe o servidor MCP no stdio

Conectando no Claude Code

claude mcp add pdv-demo -- npx tsx /caminho/para/mcp-pdv-demo/src/server.ts

Conectando no Claude Desktop

Em claude_desktop_config.json:

{
  "mcpServers": {
    "pdv-demo": {
      "command": "npx",
      "args": ["tsx", "/caminho/para/mcp-pdv-demo/src/server.ts"],
      "env": { "DATABASE_URL": "file:./pdv.db" }
    }
  }
}

Related MCP server: Sales and Stock Analysis MCP Server

As ferramentas

Saída real

resumo_de_vendas:

**Vendas de 2026-08-01 a 2026-08-31**

- Faturamento: **R$ 136.517,91**
- Vendas concluidas: 1345
- Ticket medio: R$ 101,50
- Descontos concedidos: R$ 1.484,56
- Vendas canceladas: 37

| Forma    | Vendas | Valor        | % do total |
| -------- | ------ | ------------ | ---------- |
| PIX      | 459    | R$ 49.385,27 | 36.2%      |
| DEBITO   | 360    | R$ 36.350,09 | 26.6%      |
| CREDITO  | 336    | R$ 32.355,06 | 23.7%      |
| DINHEIRO | 190    | R$ 18.427,49 | 13.5%      |

produtos_encalhados:

5 produto(s) sem vender ha 30+ dias. Capital parado: **R$ 8.690,14**.

| Produto           | Categoria | Estoque | Custo un. | Capital parado |
| ----------------- | --------- | ------- | --------- | -------------- |
| Polenta Frita ... | Porcoes   | 100     | R$ 28,21  | R$ 2.821,00    |
| Misto Quente ...  | Lanches   | 92      | R$ 30,21  | R$ 2.779,32    |
| Creme Dental      | Higiene   | 96      | R$ 18,31  | R$ 1.757,76    |

Decisões de projeto

Dinheiro é Int em centavos, nunca Float. 0.1 + 0.2 !== 0.3 — num PDV isso vira quebra de caixa. A conversão para reais acontece só na formatação da saída.

Read-only por padrão. As tools de escrita não são apenas bloqueadas: elas não são registradas. Se PDV_MCP_READONLY não for explicitamente "false", ajustar_estoque não aparece no listTools — o modelo não pode chamar o que não sabe que existe. A decisão fica no ambiente, fora do alcance do prompt.

Preço e custo são congelados no item da venda. ItemVenda guarda precoUnitario e custoUnitario do momento da venda. Sem isso, mudar o preço de um produto reescreveria o histórico de margem — um relatório de março passaria a mentir porque o custo subiu em agosto.

A saída é markdown, não JSON. O consumidor é um modelo de linguagem. Tabela formatada com R$ e percentual gasta menos contexto e produz menos erro de leitura do que um array de objetos com valores em centavos.

Nada de executar_sql. Uma tool que aceita SQL arbitrário transfere para o modelo a responsabilidade de entender o schema, e transfere para o usuário o risco de um DELETE. Cada tool aqui é uma pergunta fechada com uma query revisada atrás.

Log vai para stderr. No transporte stdio, o stdout é o canal do protocolo — um console.log perdido corrompe a sessão inteira.

Testes

npm test

18 testes que sobem um cliente MCP real ligado ao servidor por transporte em memória — exercitam o protocolo inteiro, não as funções por dentro. Cobrem o contrato (toda tool tem descrição; a de escrita não aparece em modo leitura), a corretude dos números contra o banco, parsing de data em dois formatos, e os casos vazios.

Stack

TypeScript · MCP SDK · Prisma · SQLite · Zod · Vitest

Licença

MIT