Skip to main content
Glama

Loja Aurora · Servidor MCP + Agente de IA local

CI Python MCP LLM

Um servidor MCP (Model Context Protocol) 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):

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.

  • 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).

Related MCP server: db-mcp

Arquitetura

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.

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.

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).

Conversar com o agente (o banco é criado na primeira execução):

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:

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:

claude mcp add loja-aurora -- /caminho/para/mcp-local-agent/.venv/Scripts/store-mcp
{
  "mcpServers": {
    "loja-aurora": { "command": "/caminho/para/mcp-local-agent/.venv/Scripts/store-mcp" }
  }
}

Testes e avaliações:

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

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

Available Tools

8 tools
customer_ordersA
Read-onlyIdempotent

Lista os pedidos mais recentes de um cliente (use find_customer antes para obter o ID).

Inputs: customer_id (required), limit. Returns: object

describe_schemaA
Read-onlyIdempotent

Mostra as tabelas e colunas do banco. Use antes de escrever uma consulta em run_sql.

Inputs: no named parameters. Returns: object

find_customerA
Read-onlyIdempotent

Busca clientes por parte do nome, e-mail ou ID. Retorna cidade, nº de pedidos e total gasto.

Inputs: query (required). Returns: object

get_orderB
Read-onlyIdempotent

Detalhes de um pedido pelo número: status, data, cliente, itens e valor total.

Inputs: order_id (required). Returns: object

run_sqlA
Read-onlyIdempotent

Executa UMA consulta SQL SELECT (SQLite) somente leitura, até 50 linhas.

Use só quando nenhuma outra ferramenta responder. Escritas são bloqueadas.

Inputs: query (required). Returns: object

sales_summaryA
Read-onlyIdempotent

Faturamento, nº de pedidos, itens e ticket médio num período (datas AAAA-MM-DD, inclusivas).

group_by: 'total', 'month' (por mês), 'category' (por categoria) ou 'state' (por UF).

Inputs: end_date (required), start_date (required), group_by. Returns: object

search_policiesB
Read-onlyIdempotent

Busca nas políticas da loja: trocas, devoluções, frete, prazos, garantia, pagamento e atendimento.

Inputs: question (required). Returns: object

top_productsB
Read-onlyIdempotent

Produtos mais vendidos num período (datas AAAA-MM-DD), por faturamento ou quantidade.

Inputs: end_date (required), start_date (required), by, limit. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 8 tools

    Disambiguation4/5

    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).

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables e-commerce shop owners to query their business data using natural language through local AI models. Provides secure, privacy-focused access to sales reports, inventory management, customer analytics, and order data without sending sensitive information to external services.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to safely interact with a SQLite shop database through schema discovery, read-only SQL queries, and pre-built analytics reports like top customers, top products, and revenue summaries.
      6
      67 npm
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI agents to answer analytical questions about an online store's SQLite database through specialized read-only tools, without any risk of modifying the underlying data.
      8
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects Claude, ChatGPT, Cursor, or any MCP client to a Shopify store, enabling read-only access to themes, Liquid files, catalogue data, and store configuration through 122 tools.
      2
      Apache 2.0