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

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

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

# 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:

supabase db push

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

Como Executar

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:

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:

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

Testes

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.