Look & Charme — Backend + MCP

Backend administrativo da loja Look & Charme: banco de dados, API REST e servidor MCP que expõe a loja como um conjunto de ferramentas que qualquer agente de IA compatível (Claude, ChatGPT, Codex, Gemini, OpenCode) pode operar.

1. Instalação

npm install
cp .env.example .env
npm run seed     # cria o banco store.db, ilhas de Cabo Verde, categorias e o admin padrão
npm run api      # sobe a API REST em http://localhost:4000

Login padrão criado pelo seed (troque a senha em produção, veja .env): admin@lookcharme.cv / MudeEstaSenha123!

Related MCP server: SlimWeb-MCP

2. Rodando o servidor MCP

npm run mcp          # stdio — para uso local (Claude Desktop, Claude Code, OpenCode)
npm run mcp:http      # HTTP — para agentes remotos (ChatGPT, Codex hospedado)

Conectar ao Claude Desktop / Claude Code

Copie claude_desktop_config.example.json para a configuração do seu cliente Claude, ajustando os caminhos absolutos.

Conectar ao OpenCode

O arquivo opencode.json na raiz do projeto já registra o servidor MCP. Basta rodar opencode dentro da pasta do projeto — ele detecta o arquivo automaticamente.

Conectar a agentes remotos (ChatGPT, Codex hospedado, Gemini)

Rode npm run mcp:http, defina MCP_HTTP_TOKEN no .env e aponte o agente para https://seu-servidor/mcp com o header Authorization: Bearer <MCP_HTTP_TOKEN>.

3. Fluxo de trabalho com múltiplos agentes de código (OpenCode + Claude)

Este repositório assume que mais de um agente de IA vai escrever código (não apenas operar a loja via MCP, mas editar o próprio backend). Para isso funcionar com segurança:

1. Nunca commitar direto na main. Todo agente trabalha em uma branch:

   • opencode/<tarefa> — para tarefas feitas pelo OpenCode

   • agent/<tarefa> — para outros agentes automáticos

   • feature/<tarefa> — para você

2. CI roda automaticamente em cada PR (.github/workflows/ci.yml): checa sintaxe de todos os arquivos, roda o seed num banco temporário e confirma que a API sobe (/api/health).

3. PRs de branches opencode/* ou agent/* ficam bloqueados até receberem o label reviewed-by-claude — isso força uma revisão humana ou minha (Claude) antes do merge. Você pode colar o link do PR ou o diff aqui no chat, ou usar o Claude Code apontado para o mesmo repositório.

4. Use .github/PULL_REQUEST_TEMPLATE.md como checklist — ele já lembra de checar segredos vazados, migrações de banco e testes locais.

Exemplo prático de uso do OpenCode:

git checkout -b opencode/adicionar-filtro-de-cor
opencode "adicione um filtro por cor no endpoint GET /api/produtos"
# revise o diff gerado
git push origin opencode/adicionar-filtro-de-cor
# abra o PR — o CI roda, e o PR fica travado até o label reviewed-by-claude

Depois, me mande o link do PR (ou cole o diff) aqui para eu revisar antes do merge.

4. Estrutura

src/
  schema.sql      # schema do banco (SQLite — trocar por Postgres é direto)
  db.js           # conexão + seed inicial
  store.js        # TODA a regra de negócio (única fonte da verdade)
  api.js          # API REST (usa store.js)
  mcp-server.js   # servidor MCP (usa store.js) — stdio e HTTP
openapi.yaml      # especificação OpenAPI da API REST
opencode.json     # registra o MCP server no OpenCode
claude_desktop_config.example.json
.github/workflows/ci.yml
.github/PULL_REQUEST_TEMPLATE.md

api.js e mcp-server.js nunca duplicam lógica — ambos chamam as mesmas funções de store.js. Isso garante que a loja se comporta de forma idêntica não importa se a ação veio do painel admin, da API ou de um agente de IA.

5. Próximos passos sugeridos

• Trocar SQLite por Postgres (Supabase é uma boa opção com Storage + Auth prontos)

• Upload de imagens (Cloudflare R2 ou Supabase Storage)

• Login de cliente com Google OAuth

• Pagamentos: Vinti4/SISP (Cabo Verde) + Stripe (internacional)

• Frontend da loja (Next.js) e painel admin (React)

• Testes automatizados mais completos (Vitest + supertest)

• Deploy via Docker