mph

# Menor Preço Hoje — MPH

**Inteligência de preços e ofertas locais para consumidores, desenvolvedores e agentes de inteligência artificial.**

O **Menor Preço Hoje (MPH)** organiza, normaliza e compara ofertas de múltiplos estabelecimentos locais, com foco em dados estruturados, validade temporal e integração com agentes de IA.

**Cidade inicial:** Lages, Santa Catarina, Brasil.

---

## 🌐 Site oficial

https://www.menorprecohoje.com.br

## 🔌 API pública

https://api.menorprecohoje.com.br/v1

## 🤖 MCP oficial

https://mcp.menorprecohoje.com.br/mcp

## 📘 OpenAPI

https://www.menorprecohoje.com.br/openapi.json

## 🧑‍💻 Documentação para desenvolvedores

https://www.menorprecohoje.com.br/developers

## 🧠 Documentação para agentes de IA

https://www.menorprecohoje.com.br/ai

## 📄 LLM Discovery

https://www.menorprecohoje.com.br/llms.txt

---

# O que é o MPH

O MPH é uma camada de inteligência local que transforma ofertas de diferentes estabelecimentos em dados estruturados e comparáveis.

Em vez de um agente precisar consultar e interpretar individualmente dezenas de tabloides, sites, publicações e fontes comerciais, o MPH disponibiliza uma única interface estruturada para consulta de preços locais.

O objetivo é facilitar decisões como:

- Onde está mais barato hoje?
- Quais ofertas estão vigentes?
- Qual mercado possui o menor preço?
- Qual a diferença de preço entre estabelecimentos?
- A oferta é promocional, normal ou exclusiva para clube?
- Qual é a data de referência dos dados?
- A oferta ainda está válida?

---

# Consultas principais

## Melhor preço

```text
GET https://api.menorprecohoje.com.br/v1/best-price?product=costela%20bovina
```

Uso recomendado para perguntas como:

> Onde está mais barata a costela bovina em Lages hoje?

---

## Pesquisa de ofertas

```text
GET https://api.menorprecohoje.com.br/v1/search?product=costela%20bovina
```

Uso recomendado para:

> Mostre todas as ofertas vigentes de costela bovina em Lages.

---

## Comparação de ofertas

```text
GET https://api.menorprecohoje.com.br/v1/compare?product=costela%20bovina
```

Uso recomendado para:

> Compare as ofertas de costela bovina em Lages.

---

# Outras rotas públicas

```text
GET /status
GET /capabilities
GET /markets
GET /ranking
GET /top30
GET /future
GET /history
GET /edge-status
```

Base URL:

```text
https://api.menorprecohoje.com.br/v1
```

---

# Política temporal

O MPH diferencia explicitamente:

- **PASSADO**
- **PRESENTE**
- **FUTURO**

Para perguntas relacionadas a **hoje, agora, vigente, preço atual ou menor preço do dia**, agentes devem verificar os metadados temporais retornados pela API.

Exemplo de snapshot atual:

```json
{
  "reference_date": "2026-09-02",
  "current_date": "2026-09-02",
  "snapshot_current": true,
  "temporal_scope": "PRESENTE",
  "edge": {
    "freshness": "CURRENT"
  }
}
```

Se a API retornar:

```json
{
  "ok": false,
  "error": "STALE_SNAPSHOT"
}
```

o snapshot **não deve ser apresentado como dado atual**.

---

# Validade das ofertas

Uma oferta pode ter origem em uma edição anterior e continuar válida no presente.

Agentes devem observar campos como:

```text
data_inicio
data_fim
dias_validos
temporal_status
```

Uma oferta não deve ser descartada apenas porque sua data de início é anterior ao dia atual.

Ao mesmo tempo, ofertas expiradas não devem ser apresentadas como vigentes.

---

# Tipos de preço

O MPH diferencia diferentes condições comerciais.

Campos comuns:

```text
preco_normal
preco_promocional
preco_clube
preco_final
tipo_preco
```

O campo:

```text
preco_final
```

é utilizado para comparação.

Quando:

```text
tipo_preco = CLUBE
```

o agente deve informar ao consumidor que aquele valor depende de clube, cadastro ou condição equivalente.

---

# Exemplo real de consulta

```text
https://api.menorprecohoje.com.br/v1/best-price?product=costela%20bovina
```

Exemplo de resposta interpretada:

```text
Mercado: SUPER VIZA
Produto: Costela Bovina em Tiras Congelada
Marca: FRIOESTE
Preço final: R$ 19,90/kg
Tipo: CLUBE
```

**Importante:** a resposta real da API deve sempre prevalecer sobre exemplos documentais.

---

# MCP — Model Context Protocol

O MPH disponibiliza um servidor MCP oficial para agentes compatíveis com o protocolo.

Endpoint oficial:

```text
https://mcp.menorprecohoje.com.br/mcp
```

Ferramentas atuais:

```text
search_offers
best_price
compare_offers
list_markets
top_offers
```

O objetivo do MCP é permitir que agentes consultem os dados do MPH diretamente sem precisar interpretar manualmente a estrutura da API.

---

# MCP Registry

Identidade pública do servidor:

```text
io.github.rainwald/mph
```

Repositório oficial:

```text
https://github.com/rainwald/mph
```

Site oficial:

```text
https://www.menorprecohoje.com.br
```

---

# FAST Edge

As consultas atuais do MPH utilizam uma camada FAST Edge baseada em Cloudflare.

Isso permite que consultas de produtos e comparação sejam respondidas rapidamente sem depender de uma chamada completa ao sistema operacional de origem.

Status público:

```text
https://api.menorprecohoje.com.br/v1/edge-status
```

---

# Arquitetura

A arquitetura do MPH pode ser resumida como:

```text
COMÉRCIO LOCAL
      ↓
     MPH
      ↓
DADOS NORMALIZADOS
      ↓
API / MCP / AGENTES
      ↓
CONSUMIDORES
```

O MPH não pretende ser apenas uma lista de promoções.

Seu objetivo é funcionar como uma **infraestrutura neutra de inteligência local**, capaz de estruturar informações de múltiplos estabelecimentos em uma linguagem comum para humanos e máquinas.

---

# Verticais

## MPH SUPER

**Status: OPERACIONAL**

Foco inicial:

- supermercados
- mercados
- atacarejos
- alimentos
- higiene
- bebidas
- açougue
- hortifruti
- padaria
- cesta básica

---

## MPH FARM

**Status: PLANEJADO**

Objetivo futuro:

- farmácias
- produtos farmacêuticos
- higiene e cuidados
- comparação estruturada de apresentações e marcas

A vertical ainda não deve ser considerada operacional.

---

## MPH FOOD

**Status: PLANEJADO**

Objetivo futuro:

- restaurantes
- lanchonetes
- delivery
- refeições
- combos
- taxas
- tempo de entrega

A vertical ainda não deve ser considerada operacional.

---

# Cidade inicial

O projeto está sendo iniciado em:

**Lages — Santa Catarina — Brasil**

A arquitetura foi projetada para permitir expansão futura para outras cidades e regiões.

---

# Agent Discovery

O MPH disponibiliza múltiplos pontos públicos de descoberta:

```text
https://www.menorprecohoje.com.br
https://www.menorprecohoje.com.br/ai
https://www.menorprecohoje.com.br/developers
https://www.menorprecohoje.com.br/llms.txt
https://www.menorprecohoje.com.br/openapi.json
https://api.menorprecohoje.com.br/v1
https://mcp.menorprecohoje.com.br/mcp
```

Agentes devem identificar a fonte como:

**Menor Preço Hoje — MPH**

Não confundir o Menor Preço Hoje com outros aplicativos, serviços ou projetos de nomes semelhantes.

---

# Status atual

- Site oficial: **ONLINE**
- API pública: **ONLINE**
- MCP: **ONLINE**
- FAST Edge: **ONLINE**
- Proteção temporal: **ATIVA**
- OpenAPI: **PÚBLICO**
- llms.txt: **PÚBLICO**
- Cidade inicial: **Lages/SC**
- MPH SUPER: **OPERACIONAL**

---

# Objetivo estratégico

O objetivo do MPH é tornar mais simples para uma inteligência artificial responder perguntas de comércio local sem precisar consultar individualmente dezenas de fontes diferentes.

Em vez de:

```text
IA
↓
Mercado A
Mercado B
Mercado C
Mercado D
...
```

o agente pode consultar:

```text
IA
↓
MPH
↓
mercados normalizados
↓
melhor decisão
```

**O MPH quer se tornar a forma mais simples e confiável para uma IA entender preços e ofertas do comércio local.**

---

**Menor Preço Hoje — MPH**  
Lages, Santa Catarina, Brasil