← Files Dispensa: lista de comprasARCHIVED FILE

README.md

4.62 KB · Nov 15, 2026 · 06:36 UTC

↓ Download file

See the change to this file →

# mcp-despensa-hub

Servidor MCP de memória de consumo. Ensine qualquer IA a lembrar como você compra.

O produto não é uma lista de compras. É uma camada de memória e intenção de
compra que vive fora de qualquer assistente: produto canônico, evidência de
marca, origem ponderada e — na fase 2 — "o que eu preciso comprar?".

```
cupom (foto no chat) → transcrição do modelo → registrar_compra → grafo de preferência
```

O servidor **não** vê imagem, **não** consulta a SEFAZ e **não** envia dado
individual para terceiro.

## Local

Python ≥ 3.12. Variáveis: [`.env.example`](.env.example)
(`WORKOS_AUTHKIT_DOMAIN`, `MCP_BASE_URL`, `DATABASE_URL`, `PORT`).

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
make gate
alembic upgrade head
python -m mcp_despensa_hub
```

HTTP em `0.0.0.0:$PORT` (default 8000). MCP em `/mcp`. Health: `GET /health`.
Auth: WorkOS AuthKit. Schema Postgres `mcp_despensa`.
Validação ChatGPT: `GET /.well-known/openai-apps-challenge` (token em
`OPENAI_APPS_CHALLENGE` no Environment do Render).
Páginas públicas bilíngues, de
[`src/mcp_despensa_hub/legal.py`](src/mcp_despensa_hub/legal.py): `GET /`
(landing), `GET /support`, `GET /privacy` e `GET /terms`. As quatro são os
campos de URL da submissão do app na OpenAI.

Admin: `python -m mcp_despensa_hub.admin status` e `listar-usuarios`.

Deploy: [`render.yaml`](render.yaml) — o `startCommand` é
`alembic upgrade head && python -m mcp_despensa_hub`.

## Revisão ChatGPT

Conta de demonstração dos revisores da OpenAI. Tem de entrar com e-mail e
senha e cair direto na conta: sem MFA, sem código por e-mail, sem cadastro
e sem nenhum passo de configuração.

| Campo | Valor |
|---|---|
| Login | `https://creative-mermaid-77-staging.authkit.app/` |
| Tenant | `Despensa Hub - Demo` |
| Usuário | `reviewer@onrender.com` |
| Senha | gerenciador de senhas — nunca neste repositório |

Criar ou recriar o usuário já verificado. O `email_verified: true` é o que
evita a tela de código por e-mail que reprovou a v0.1.0:

```bash
curl -X POST https://api.workos.com/user_management/users \
  -H "Authorization: Bearer $WORKOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "reviewer@onrender.com",
    "password": "'"$WORKOS_REVIEWER_PASSWORD"'",
    "email_verified": true,
    "first_name": "OpenAI",
    "last_name": "Reviewer"
  }'
```

`WORKOS_API_KEY` é a chave secreta do ambiente (`sk_test_…` em staging,
`sk_live_…` em produção) e dá acesso total a usuários: exportar no shell a
partir do gerenciador de senhas, nunca versionar nem colar em formulário.

Senha só com ASCII visível. Caractere invisível ou espaço nas pontas passa
despercebido na criação e quebra o copiar-colar do revisor sem mensagem de
erro — foi o que quase derrubou a segunda submissão.

Antes de submeter, testar o fluxo inteiro em janela anônima: e-mail →
senha → dentro, e os 5 test cases rodando com dados de exemplo já na conta.

Semente da conta, os 5 test cases, os negativos e os erros a não repetir:
[`docs/REVIEW-CHATGPT.md`](docs/REVIEW-CHATGPT.md).

## Tools

Peça em português; o assistente usa o nome da tool. Identificadores públicos:
`LIS-…` (lista) e `CMP-…` (compra). Nunca o id numérico.

| Tool | Entrega |
|---|---|
| `ping_despensa` | Contadores, versão do motor, estado do perfil |
| `adicionar_item` | Canonicaliza, adiciona, devolve a preferência conhecida |
| `ver_lista` | Lista aberta com preferência de cada item |
| `remover_item` | Tira da lista (`LIS-…`) |
| `registrar_compra` | Lote. Transcrição do cupom. `chave_nfe` dá idempotência |
| `corrigir_compra` | Conserta transcrição; evidência de peso máximo |
| `ver_historico` | O que foi comprado, quando, por quanto |
| `ver_preferencia` | Cartão de evidência (ou incerteza declarada) |
| `ajustar_preferencia` | Correção explícita do usuário |
| `o_que_esta_faltando` | Frequência × última compra × quantidade típica |
| `exportar_meus_dados` | Dump do titular |
| `apagar_meus_dados` | Apaga todas as linhas do usuário (`confirmar=true`) |

Origem de compra: `transcricao`, `manual` ou `correcao`. Sem origem a compra
não entra. Preferência exige pelo menos 3 compras e proporção ≥ 0,6.

Autor / “desenvolvido por”: [`plugin.json`](plugin.json) (Cursor, ChatGPT e
quem segue Agent Plugins) e [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json)
(Claude Code). Os dois `mcp.json` / `.mcp.json` têm de ser iguais.

Onde o resto vive: contrato de cada tool em [`plans/`](plans/); método
(R1–R8) em [`docs/METODO.md`](docs/METODO.md); gate em [`CLAUDE.md`](CLAUDE.md)
e `make gate`.

SHA-256: 69f39726b3364af4c9dba796d6614fb8d954f0b7ef177e6bcc43beac22eddfc5