Loja Aurora
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Loja Aurora Qual produto mais faturou no primeiro trimestre de 2026?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Loja Aurora · Servidor MCP + Agente de IA local
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
stdioou 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
DELETEpedido 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]
endO ciclo do agente:
Lista as ferramentas do servidor MCP e converte para o formato de function calling do Ollama.
Envia a pergunta ao modelo junto com as ferramentas.
Executa via MCP as ferramentas que o modelo pedir e devolve os resultados.
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 |
| Detalhes de um pedido: status, cliente, itens e total |
| Busca cliente por nome, e-mail ou ID, com nº de pedidos e total gasto |
| Últimos pedidos de um cliente |
| Faturamento, pedidos e ticket médio por período, agrupado por mês, categoria ou UF |
| Ranking de produtos por faturamento ou quantidade |
| Esquema do banco (para o modelo escrever SQL) |
| Uma consulta |
| 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 |
2. Conexão | SQLite aberto com |
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 ( |
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 |
| 60% | 85% | 0,735 |
Híbrido (embeddings + BM25) |
| 70% | 85% | 0,802 |
Embeddings |
| 85% | 100% | 0,925 |
Híbrido (embeddings + BM25) |
| 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 |
| 18/18 | 100% | 2,8 s | 4,3 s | sim |
| 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 ( | 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:4btambém era lento no ROCm, o que descartou a arquitetura doqwen3.5como 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 serveiniciado 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 comollama 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íticasPlaca AMD? Teste o backend Vulkan: inicie o servidor com
OLLAMA_VULKAN=1eHIP_VISIBLE_DEVICES=-1usandoollama 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 ModelfileRodar 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-mcpUsar 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.mdEstrutura
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 MCPLimitaçõ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
Available Tools
8 toolscustomer_ordersARead-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_schemaARead-onlyIdempotent
Mostra as tabelas e colunas do banco. Use antes de escrever uma consulta em run_sql.
Inputs: no named parameters. Returns: object
find_customerARead-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_orderBRead-onlyIdempotent
Detalhes de um pedido pelo número: status, data, cliente, itens e valor total.
Inputs: order_id (required). Returns: object
run_sqlARead-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_summaryARead-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_policiesBRead-onlyIdempotent
Busca nas políticas da loja: trocas, devoluções, frete, prazos, garantia, pagamento e atendimento.
Inputs: question (required). Returns: object
top_productsBRead-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
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.
Maintenance
Related MCP Connectors
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
MerchantFlow is a hosted, read-only ecommerce analytics MCP server for Shopify and WooCommerce. It gives AI assistants tenant-scoped access to revenue, profit and loss, product and SKU profitability, COGS coverage, fulfillment costs, advertising spend, ROAS, marketing performance, cohorts, LTV, and business valuation across connected commerce and marketing platforms. Connect with OAuth over Streamable HTTP. No local server installation is required.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Ask questions across Shopify, Klaviyo, GA4 and 20+ e-commerce sources in plain English.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseAqualityDmaintenanceEnables 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.667 npmMIT
- FlicenseAqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceConnects 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.2Apache 2.0