# Jueri MCP Server

Conecta o Claude ao sistema de gestao Jueri (semijoias / consignacao), para
perguntar diretamente sobre pecas (produtos), consultoras (revendedores),
clientes e pedidos.

## O que este servidor faz

Ele expoe 8 ferramentas MCP que chamam a API oficial do Jueri
(`https://jueri.com.br/sis/docs/`):

| Ferramenta | Endpoint Jueri |
|---|---|
| `listar_pecas` | `GET /produto` |
| `buscar_peca` | `GET /produto/{id}` |
| `listar_categorias_pecas` | `GET /produto/categoria` |
| `listar_consultoras` | `GET /revendedor` |
| `buscar_consultora` | `GET /revendedor/{id}` |
| `listar_niveis_consultora` | `GET /revendedor/nivel` |
| `listar_clientes` | `GET /cliente` |
| `buscar_cliente` | `GET /cliente/{id}` |
| `listar_pedidos` | `GET /pedido` |
| `buscar_pedido` | `GET /pedido/{id}` |

O token do Jueri fica guardado apenas no servidor (variavel de ambiente),
nunca e enviado de volta para o Claude nem aparece na conversa.

Esta primeira versao e somente leitura (GET). Se depois voce quiser criar
pedidos ou alterar produtos direto pelo Claude, da para adicionar essas
ferramentas depois — foi deixado de fora agora por seguranca (evita que uma
pergunta ambigua vire uma alteracao real no seu estoque).

## 1. Gerar um token novo no Jueri

Importante: um token ja foi colado nesta conversa em texto puro em algum
momento. Antes de colocar qualquer token em producao, gere um **novo** token
em Jueri > Configuracoes > API > Gerar token, e use apenas esse novo valor
aqui.

## 2. Hospedar o servidor

Voce precisa de um lugar na internet que rode este Node.js 24 horas por dia,
com uma URL publica. Três caminhos, do mais simples ao mais tecnico:

### Opcao A — Render (recomendado, tem plano gratuito)

1. Suba esta pasta (`jueri-mcp`) para um repositorio no GitHub.
2. Crie uma conta em render.com e clique em "New +" -> "Web Service".
3. Aponte para o repositorio. Configuracao:
   - Build command: `npm install`
   - Start command: `npm start`
4. Em "Environment", adicione as variaveis: `JUERI_TOKEN`,
   `JUERI_CLIENTE_SISTEMA` (11224), e opcionalmente `MCP_SHARED_SECRET`.
5. Depois do deploy, o Render te da uma URL tipo
   `https://jueri-mcp-server.onrender.com`. A URL do conector sera essa +
   `/mcp`.

Limitacao do plano gratuito: o servidor "dorme" depois de alguns minutos sem
uso, e a primeira chamada depois disso demora ~30s para acordar. Para o seu
uso (perguntar de vez em quando sobre pecas/consultoras) isso normalmente e
aceitavel.

### Opcao B — VPS na Hostinger (se o seu plano for VPS)

Isso so funciona se sua assinatura Hostinger for especificamente do tipo
**VPS** (planos de hospedagem compartilhada/Web/Cloud normais nao rodam
processos Node.js persistentes). Se for VPS:

1. Acesse o VPS via SSH.
2. Instale Node 18+ (`curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt install -y nodejs`).
3. Copie esta pasta para o servidor (`scp` ou `git clone`).
4. `npm install`
5. Configure as variaveis de ambiente (crie um `.env` a partir do
   `.env.example`, ou exporte no shell).
6. Rode com um gerenciador de processos para manter no ar, por exemplo:
   `npm install -g pm2 && pm2 start server.js --name jueri-mcp`
7. Configure um dominio/subdominio apontando para o VPS e, idealmente, um
   proxy reverso com HTTPS (Nginx + Certbot). O conector do Claude deve
   apontar para `https://seu-dominio.com/mcp`.

### Opcao C — Railway / Fly.io

Processo parecido com o Render (conectar repositorio, configurar variaveis
de ambiente, pegar a URL publica). Hoje esses provedores nao tem mais planos
realmente gratuitos, apenas creditos iniciais — considere apenas se preferir
a experiencia deles a do Render.

## 3. Registrar como conector no Claude

1. No Claude, va em Customize (ou Configuracoes) -> Connectors -> Add custom
   connector.
2. Cole a URL do servidor + `/mcp` (ex:
   `https://jueri-mcp-server.onrender.com/mcp`).
3. Se voce configurou `MCP_SHARED_SECRET`, informe esse valor onde o Claude
   pedir autenticacao/token do conector.
4. Salve. A partir dai, basta perguntar coisas como "quantas pecas de ouro eu
   tenho em estoque?" ou "quais consultoras estao ativas?" que o Claude vai
   chamar essas ferramentas automaticamente.

## Rodando localmente (para testar antes de hospedar)

```bash
cd jueri-mcp
npm install
cp .env.example .env
# edite o .env com o token novo
npm start
```

O servidor sobe em `http://localhost:3000/mcp`. Voce pode testar com
qualquer cliente MCP compativel com Streamable HTTP, ou simplesmente
verificar que `http://localhost:3000/` responde `{"status":"ok"}`.

## Proximos passos possiveis

- Adicionar ferramentas de escrita (`criar_pedido`, `alterar_produto`, etc.)
  quando/se voce quiser que o Claude tambem registre vendas, nao so consulte.
- Adicionar um endpoint de webhook separado (`/webhook/jueri`) para receber
  eventos em tempo real do Jueri (ex: pedido criado), caso queira alertas
  automaticos alem das consultas sob demanda.