# Book Store MCP

PoC de um **ChatGPT App** construído sobre o **Model Context Protocol (MCP)**.
O projeto expõe um **MCP Server** com ferramentas voltadas a uma livraria, para
que o ChatGPT possa consultar livros, autores, estoque, preços e, no futuro,
uma base de conhecimento com RAG.

O objetivo desta base é manter a arquitetura simples: o servidor MCP expõe as
tools, os services concentram a regra de negócio e os repositories acessam o
Supabase.

## Visão Geral

```text
Usuário
   │
   ▼
ChatGPT
   │
   ▼
MCP Server (FastMCP)
   │
   ├── Services
   │      └── regra de negócio
   │
   └── Repositories
          └── acesso ao Supabase
```

Princípios da arquitetura:

- As **tools** apenas validam entrada e delegam para services.
- Os **services** concentram a lógica de negócio.
- Os **repositories** são a única camada que conversa com o banco.
- A decisão de qual tool usar é responsabilidade do ChatGPT.

## Status Atual

- As tools estruturadas do catálogo estão implementadas de ponta a ponta.
- O projeto já organiza o código em `app/core`, `app/models`, `app/services`,
  `app/repositories` e `app/mcp`.
- A tool `searchKnowledge` representa a futura camada de RAG e faz parte da
  visão da PoC, mas ainda está em evolução.
- Autenticação, observabilidade completa e versionamento formal de schema são
  tratados como próximos passos, não como requisito desta etapa.

## Estrutura Do Projeto

```text
book-store-mcp/
├── app/
│   ├── core/          configuração, cliente Supabase, container e exceções
│   ├── mcp/           servidor FastMCP e definição das tools
│   ├── models/        modelos Pydantic de domínio, entrada e saída
│   ├── repositories/  acesso a dados via Supabase
│   ├── rag/           base para ingestão e busca semântica
│   └── services/      regra de negócio
├── supabase/
│   └── migrations/    schema, políticas RLS e seed data
├── tests/             testes de serviços e repositórios
├── pyproject.toml
└── README.md
```

## Tecnologias

| Tecnologia | Uso |
|---|---|
| Python 3.13+ | Linguagem |
| MCP Python SDK (`FastMCP`) | Servidor MCP e transporte HTTP |
| Supabase (Postgres) | Persistência dos dados estruturados |
| `pgvector` | Base para a camada vetorial/RAG |
| Pytest | Testes |
| `uv` | Gerenciamento do ambiente e execução local |

## Requisitos

- Python 3.13 ou superior
- `uv`
- Um projeto Supabase com URL e chave `anon`/`publishable`

## Configuração

```bash
# Instala dependências de desenvolvimento
uv sync --extra dev

# Cria o arquivo de ambiente
cp .env.example .env
```

Depois, preencha o `.env` com as variáveis do Supabase e com as configurações
do servidor MCP, se necessário.

## Banco De Dados

As migrações ficam em `supabase/migrations/`:

| Migração | Conteúdo |
|---|---|
| `..._init_schema.sql` | tabelas, índices, restrições e extensões |
| `..._rls_policies.sql` | RLS habilitado e políticas públicas de leitura |
| `..._seed_data.sql` | dados iniciais de livros, autores, editoras, categorias, estoque e avaliações |

Você pode aplicar as migrações com o Supabase CLI:

```bash
supabase db push
```

Ou executar os scripts diretamente no editor SQL do Supabase, na ordem em que
foram criados.

## Como Executar

```bash
uv run book-store-mcp
# ou
uv run python -m app.mcp.server
```

Por padrão, o servidor sobe em `http://127.0.0.1:8000` usando transporte HTTP
compatível com MCP. O comportamento pode ser ajustado por meio de variáveis de
ambiente como `MCP_HOST`, `MCP_PORT` e `MCP_TRANSPORT`.

Para inspecionar a aplicação com a ferramenta de desenvolvimento do MCP:

```bash
uv run mcp dev app/mcp/server.py
```

## Tools

| Tool | Descrição |
|---|---|
| `searchBooks` | Busca livros por título ou palavra-chave. |
| `searchAuthors` | Busca autores por nome ou a partir do título de um livro. |
| `searchPublishers` | Busca ou lista editoras. |
| `searchCategories` | Busca ou lista categorias e gêneros. |
| `searchByISBN` | Localiza um livro pelo ISBN. |
| `getBookSynopsis` | Retorna a sinopse de um livro. |
| `getBookReviews` | Retorna avaliações e nota média de um livro. |
| `recommendBooks` | Recomenda livros por autor, categoria ou gênero. |
| `findSimilarBooks` | Encontra livros semelhantes a um título informado. |
| `checkStock` | Consulta disponibilidade e quantidade em estoque. |
| `getBookPrice` | Consulta o preço de um livro. |
| `getBestSellers` | Lista os livros mais vendidos. |
| `getNewReleases` | Lista os lançamentos mais recentes. |
| `searchKnowledge` | Consulta a base de conhecimento via RAG. |

As tools retornam um JSON estruturado em caso de sucesso e um objeto de erro
previsível em caso de falha, por exemplo:

```json
{"error": "BOOK_NOT_FOUND", "message": "..."}
```

## Testes

```bash
uv run pytest
```

Os testes cobrem as camadas de service e repository com dependências falsas ou
mockadas, sem exigir banco de dados ao rodar localmente.

## Próximos Passos

- Evoluir a tool `searchKnowledge` com ingestão e busca semântica.
- Adicionar avaliação automática das tools com golden set.
- Incluir observabilidade mínima por chamada de tool.
- Definir uma estratégia de autenticação quando o servidor sair do ambiente de desenvolvimento.