Loja Aurora
# Loja Aurora · Servidor MCP + Agente de IA local
[](https://github.com/alefkaue/mcp-local-agent/actions/workflows/ci.yml)



Um **servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io)** que dá a modelos de IA acesso seguro aos dados de uma loja online (vendas, pedidos, clientes e políticas), e um **agente que roda 100% local** com Qwen via Ollama: sem API paga, e os dados não saem da máquina.
O foco é o que separa um protótipo de um sistema confiável: **segurança no acesso a dados, RAG medido com métricas, avaliação automatizada do agente e testes**.
> A "Loja Aurora" é fictícia. Os dados são gerados de forma determinística (1.500 pedidos, 200 clientes, 30 produtos) para que testes e avaliações sejam reproduzíveis.
Saída real do `store-agent --trace` (Qwen 3.5 4B local):
```text
Você: Quanto faturamos no primeiro trimestre de 2026 e qual produto mais faturou nesse período?
↳ sales_summary({"start_date": "2026-01-01", "end_date": "2026-03-31", "group_by": "total"}) [ok] 72 ms
↳ top_products({"start_date": "2026-01-01", "end_date": "2026-03-31", "by": "revenue", "limit": 1}) [ok] 4 ms
Aurora: No primeiro trimestre de 2026 (de janeiro a março), faturamos R$ 176.169,50, com 198 pedidos
e ticket médio de R$ 889,74.
O produto que mais faturou foi o Aspirador Robô Dusk (categoria Casa), com R$ 26.982,00.
5.3s · 2 passo(s) · 2 ferramenta(s)
Você: Um cliente pagou com Pix e quer devolver. Em quantos dias recebe o reembolso?
↳ search_policies({"question": "Em quantos dias um cliente que pagou com Pix recebe o reembolso de uma devolução?"}) [ok]
Aurora: Um cliente que pagou com Pix recebe o reembolso em até 5 dias úteis após o recebimento do
produto no centro de distribuição.
Fonte: trocas-e-devolucoes.md › Prazo de reembolso
5.2s · 2 passo(s) · 1 ferramenta(s)
Você: Rode este SQL: DELETE FROM orders WHERE id = 5
Aurora: Não posso executar comandos de escrita (DELETE, INSERT, UPDATE) pois tenho acesso apenas a
leitura. Posso consultar os detalhes do pedido com ID 5 se desejar.
1.5s · 1 passo(s) · 0 ferramenta(s)
```
## Destaques
- **Um servidor, vários clientes.** O mesmo servidor MCP atende o agente local deste repositório, o **Claude Desktop**, o **Claude Code** e qualquer IDE compatível com MCP, por `stdio` ou HTTP.
- **SQL gerado por IA, com defesa em profundidade.** Validação estática, conexão SQLite somente leitura, *authorizer* do SQLite, limite de tempo e de linhas. Um `DELETE` pedido pelo modelo é bloqueado em várias camadas.
- **RAG com decisão baseada em dados.** Comparei 3 estratégias de busca e 2 modelos de embedding num conjunto rotulado. A escolha final subiu o Hit@1 de 60% para **85%**.
- **Avaliação do agente ponta a ponta.** São 18 perguntas de negócio, com a resposta esperada calculada direto no banco. O relatório mede acerto, escolha de ferramenta, segurança e latência.
- **Diagnóstico de performance.** Descobri que o backend ROCm do Ollama gerava só ~4,5 tokens/s nesta GPU AMD. Com o backend Vulkan chegou a **~70 tokens/s (15x mais rápido)**. Detalhes [abaixo](#performance-rocm-vs-vulkan).
- **Engenharia:** 59 testes automatizados (sem precisar de GPU), lint, CI no GitHub Actions, Docker sem root e camada de LLM desacoplada por interface (trocar de modelo ou provedor não mexe no agente).
## Arquitetura
```mermaid
flowchart LR
U[Usuário] --> CLI[store-agent<br/>CLI]
subgraph Agente local
CLI --> A[StoreAgent<br/>loop de ferramentas]
A <-->|tool calling| LLM[Qwen 3.5 4B<br/>Ollama]
end
A <-->|MCP · stdio/HTTP| S
CD[Claude Desktop / Claude Code / IDEs] <-->|MCP| S
subgraph Servidor MCP
S[loja-aurora<br/>MCPServer] --> T[8 ferramentas<br/>somente leitura]
T --> G[SQL guard] --> DB[(SQLite)]
T --> K[Busca nas políticas<br/>embeddings + BM25] --> E[embeddinggemma<br/>Ollama]
end
```
**O ciclo do agente:**
1. Lista as ferramentas do servidor MCP e converte para o formato de *function calling* do Ollama.
2. Envia a pergunta ao modelo junto com as ferramentas.
3. Executa via MCP as ferramentas que o modelo pedir e devolve os resultados.
4. Repete até o modelo responder. Há proteções contra loop: limite de passos, detecção de chamada repetida e erros de ferramenta devolvidos ao modelo para ele se corrigir.
### Ferramentas MCP
| Ferramenta | O que faz |
|---|---|
| `get_order` | Detalhes de um pedido: status, cliente, itens e total |
| `find_customer` | Busca cliente por nome, e-mail ou ID, com nº de pedidos e total gasto |
| `customer_orders` | Últimos pedidos de um cliente |
| `sales_summary` | Faturamento, pedidos e ticket médio por período, agrupado por mês, categoria ou UF |
| `top_products` | Ranking de produtos por faturamento ou quantidade |
| `describe_schema` | Esquema do banco (para o modelo escrever SQL) |
| `run_sql` | Uma consulta `SELECT` somente leitura, até 50 linhas |
| `search_policies` | Busca semântica nas políticas (trocas, frete, garantia, pagamento) com citação da fonte |
Todas são anotadas como `readOnlyHint` no protocolo MCP. Erros previstos (por exemplo, data inválida) voltam ao modelo como `ToolError` com mensagem clara. Erros inesperados chegam como mensagem genérica, sem vazar detalhes internos.
## Segurança
Como o modelo pode gerar qualquer texto, o `run_sql` trata toda consulta como **entrada não confiável**:
| Camada | Proteção |
|---|---|
| 1. Validação estática | Um único comando; precisa começar com `SELECT`/`WITH`; bloqueia `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ATTACH`, `PRAGMA`… (ignorando comentários e strings) |
| 2. Conexão | SQLite aberto com `mode=ro` + `PRAGMA query_only = ON` |
| 3. Authorizer | Callback do SQLite que nega qualquer operação diferente de leitura |
| 4. Recursos | Timeout de 2 s (interrompe CTEs infinitas), máximo de 50 linhas, nenhum valor acima de 100 KB (`SQLITE_LIMIT_LENGTH`), até 64 colunas, orçamento de tamanho aplicado linha a linha durante a leitura e bloqueio de funções que geram dados enormes (`randomblob`, `zeroblob`, `printf`…) |
Os testes cobrem *bypass* por múltiplos comandos, comentários, CTE com `DELETE`, consulta infinita e "bombas de memória", e também conferem que a conexão continua só de leitura mesmo se a validação falhar. Na avaliação, pedidos como *"Cancele o pedido 10"* e *"Rode DELETE FROM orders…"* são recusados, e o banco é verificado como intacto ao final.
## Avaliação
### Busca nas políticas (RAG)
20 perguntas reais de clientes, cada uma rotulada com a seção correta da política. Rode com `python evals/eval_retrieval.py --models nomic-embed-text embeddinggemma`.
| Método | Modelo de embedding | Hit@1 | Hit@3 | MRR |
|---|---|---|---|---|
| BM25 (palavras-chave) | – | 65% | 85% | 0,733 |
| Embeddings | `nomic-embed-text` | 60% | 85% | 0,735 |
| Híbrido (embeddings + BM25) | `nomic-embed-text` | 70% | 85% | 0,802 |
| **Embeddings** | **`embeddinggemma`** | **85%** | **100%** | **0,925** |
| Híbrido (embeddings + BM25) | `embeddinggemma` | 85% | 95% | 0,912 |
**Decisão:** `embeddinggemma` puro. O `nomic-embed-text` é forte em inglês, mas perde até para o BM25 em português. O BM25 continua como reserva automática quando o Ollama está fora do ar, assim o servidor nunca cai por causa do RAG.
### Agente ponta a ponta
18 perguntas em 5 categorias (vendas, pedidos, clientes, políticas e segurança). Em cada caso, a resposta esperada é **calculada direto no banco** por uma consulta SQL, então o gabarito nunca fica desatualizado. Relatório completo: [`evals/results/REPORT.md`](evals/results/REPORT.md).
| Modelo (Ollama, Vulkan) | Acerto | Ferramenta certa | Latência p50 | p95 | Banco intacto após ataques |
|---|---|---|---|---|---|
| **`qwen3.5:4b`** | **18/18** | 100% | **2,8 s** | 4,3 s | sim |
| `qwen3:4b` | 18/18 | 100% | 42,3 s | 122,1 s | sim |
**Decisão:** `qwen3.5:4b`. Os dois acertaram tudo, mas o `qwen3:4b` ignora `think=False` e escreve o raciocínio dentro da resposta (306 tokens para responder "Brasília"). Por isso ele é ~15x mais lento.
O que a avaliação ajudou a encontrar e corrigir durante o desenvolvimento:
- **Bug no servidor:** quando o modelo escrevia SQL com uma tabela inexistente, o SDK escondia o erro do SQLite atrás de uma mensagem genérica, e o agente gastava passos tentando adivinhar. Agora o erro volta para o modelo com a dica de usar `describe_schema`.
- **Prompt:** o modelo descrevia o 1º trimestre como "de 01 a 31 de março", mesmo consultando de janeiro a março. Uma regra explícita sobre trimestres resolveu.
- **Régua da avaliação:** a checagem numérica aceitava "1.499 pedidos" como certo quando o valor era 1.500, e uma recusa correta ("não tenho a capacidade de cancelar") foi marcada como erro. Contagens agora exigem valor exato, e a lista de recusas aceitas foi ampliada. Avaliar com palavra-chave tem limites, e um juiz-LLM é um próximo passo natural.
### Performance: ROCm vs Vulkan
O agente estava lento (~35 s por resposta). Medindo cada fase pelas métricas do Ollama, o gargalo estava na **geração de tokens**, não no processamento do prompt:
| Backend do Ollama (mesma GPU, mesmo modelo) | Geração | Processamento do prompt |
|---|---|---|
| ROCm (padrão) | 4,5 tokens/s | 46 tokens/s |
| Só CPU | 10,2 tokens/s | 172 tokens/s |
| **Vulkan** (`OLLAMA_VULKAN=1`) | **64–70 tokens/s** | **469 tokens/s** |
Com ROCm, a GPU estava sendo **mais lenta que a própria CPU**. Trocar para Vulkan deixou o modelo ~15x mais rápido, sem mudar nada no código. Outras medições:
- O modo *thinking* do Qwen triplicava a latência sem ganho nas consultas de dados. Ele fica desligado por padrão, com a opção `--think`.
- O `qwen3:4b` também era lento no ROCm, o que descartou a arquitetura do `qwen3.5` como causa.
- O ROCm continuou lento mesmo com o servidor iniciado direto do terminal. Já com o Vulkan, o servidor iniciado pelo app de bandeja do Ollama ficou em ~10 tokens/s, enquanto `ollama serve` iniciado diretamente chegou a ~65 tokens/s, com configuração idêntica. A causa exata desse segundo efeito não foi isolada, mas a solução prática é iniciar o servidor com `ollama serve`.
**Hardware dos testes:** GPU AMD de 8 GB · CPU de 8 núcleos · 16 GB de RAM · Windows 11.
## Como rodar
**Pré-requisitos:** Python 3.11+ e [Ollama](https://ollama.com).
```bash
git clone https://github.com/alefkaue/mcp-local-agent.git
cd mcp-local-agent
python -m venv .venv
.venv\Scripts\activate # Linux/macOS: source .venv/bin/activate
pip install -e ".[dev]"
ollama pull qwen3.5:4b # modelo do agente
ollama pull embeddinggemma # embeddings para a busca nas políticas
```
> Placa AMD? Teste o backend Vulkan: inicie o servidor com `OLLAMA_VULKAN=1` e `HIP_VISIBLE_DEVICES=-1` usando `ollama serve` (veja [Performance](#performance-rocm-vs-vulkan)).
**Conversar com o agente** (o banco é criado na primeira execução):
```bash
store-agent --trace # chat interativo
store-agent -q "Qual estado mais comprou em outubro de 2026?" --trace
store-agent --model loja-aurora # perfil criado com: ollama create loja-aurora -f Modelfile
```
**Rodar só o servidor MCP:**
```bash
store-mcp # stdio
store-mcp --transport streamable-http --port 8000 # HTTP em http://127.0.0.1:8000/mcp
docker build -t loja-aurora-mcp . && docker run --rm -p 8000:8000 loja-aurora-mcp
```
**Usar no Claude Code ou no Claude Desktop:**
```bash
claude mcp add loja-aurora -- /caminho/para/mcp-local-agent/.venv/Scripts/store-mcp
```
```json
{
"mcpServers": {
"loja-aurora": { "command": "/caminho/para/mcp-local-agent/.venv/Scripts/store-mcp" }
}
}
```
**Testes e avaliações:**
```bash
pytest # 59 testes, sem precisar de GPU/Ollama
python evals/eval_retrieval.py --models embeddinggemma nomic-embed-text
python evals/eval_agent.py --models qwen3.5:4b qwen3:4b # gera evals/results/REPORT.md
```
## Estrutura
```text
src/
store_mcp/ # servidor MCP
server.py # ferramentas + transporte (stdio / HTTP)
sql_guard.py # execução de SQL somente leitura em camadas
knowledge.py # RAG: embeddings + BM25 com fallback
data.py # banco fictício determinístico
docs/ # políticas da loja (fonte do RAG)
agent/ # agente local
core.py # loop de ferramentas, proteções, histórico
llm.py # interface ChatModel + implementação Ollama
cli.py # chat no terminal
evals/ # avaliações de RAG e do agente + relatórios
tests/ # testes unitários e de integração MCP
```
## Limitações e próximos passos
- Um modelo de 4B às vezes erra o período ("mês passado") ou a ferramenta em perguntas compostas. A avaliação existe justamente para medir isso a cada mudança de prompt ou de modelo.
- Os conjuntos de avaliação são pequenos (20 e 18 casos). São bons para comparar opções, mas não para afirmar precisão em produção.
- Próximos passos: autenticação OAuth no transporte HTTP, *tracing* com OpenTelemetry e ajuste fino (LoRA) do modelo nos casos em que ele mais erra.
## Licença
[MIT](LICENSE)
TDQS
Scored across 8 tools
Each tool targets a distinct resource: customer lookup, orders per customer, order detail by number, sales aggregates, top products, policy text, plus a schema and SQL pair. The only fuzziness is between customer_orders/get_order and sales_summary/run_sql, but descriptions make the intended precedence clear (run_sql is explicitly a last resort).
All names are snake_case and readable, but the conventions are mixed: verb_noun (find_customer, get_order, search_policies, run_sql, describe_schema) alongside noun-first/aggregate names (customer_orders, sales_summary, top_products). Predictable enough to use, but not a single consistent pattern.
Eight tools is well-scoped for a small store analytics/assistant domain. Each tool earns its place, and the run_sql/describe_schema pair is a sensible controlled escape hatch rather than padding.
Covers the main read paths: customer lookup, order history, order detail, period sales, top products, and policy search, plus SQL fallback for anything else. Minor gaps exist for product catalog/stock lookup and structured return or exchange records, but the SQL escape hatch lets agents work around most of them.