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.

Related MCP server: calibre-mcp

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

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

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

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.