latam-market

API e servidor MCP para o mercado de jogadores do Ragnarok Online LATAM (servidor FREYA). Os mesmos dados por dois canais: HTTP para aplicações, MCP para agentes de IA.

🔗 https://mercado.latam-tools.com.br

API REST  →  https://mercado.latam-tools.com.br/api/v1
MCP       →  https://mercado.latam-tools.com.br/mcp

Sem cadastro, sem chave de API, sem login. Licença MIT.

O que dá para perguntar

Conectado a um agente (Claude, por exemplo), o MCP responde coisas assim:

"Quanto custa um Elixir Dourado?" "Quero comprar uma Boina — me lista quem está vendendo e por quanto." "Vender minha Escama Invertida por 500 mil é bom negócio?" "O preço da Ração Luxuosa subiu esse mês?" "Tem alguma pechincha no mercado agora?" "Toma meu replay: quanto vale tudo que eu tenho? O que dá para vender com lucro?"

Related MCP server: EVE Tycoon MCP Server

Recursos

• Preço de qualquer item — a faixa histórica publicada pelo site e o resumo das lojas abertas na última coleta, que são coisas diferentes e vêm separadas.

• Ofertas ativas — quem está vendendo, por quanto, em que loja e em que mapa.

• Histórico próprio — construído acumulando nossas coletas, com retenção em camadas (anúncio cru por um dia, resumo por 30 dias, resumo diário para sempre).

• Avaliação de preço — quantas lojas estão mais baratas, quanto pedir para ser o mais barato, e como o preço se compara à média dos últimos dias.

• Pechinchas e maiores variações — varreduras sobre o mercado inteiro.

• Leitura de replay .rrf — inventário, carrinho de mercador e equipamento, com preço de mercado em cada item.

• Consulta ao vivo — quando o dado coletado não basta, consulta o site na hora. É o caminho caro, e está marcado como tal.

• Links prontos — todo item vem com a página no Divine Pride e a busca ao vivo no site oficial.

Usando a API

# buscar um item
curl 'https://mercado.latam-tools.com.br/api/v1/items?q=elixir'

# preço (aceita id ou nome)
curl 'https://mercado.latam-tools.com.br/api/v1/items/Elixir%20Dourado'

# quem está vendendo
curl 'https://mercado.latam-tools.com.br/api/v1/items/1100005/offers?limit=10'

# vale a pena vender a 2600?
curl 'https://mercado.latam-tools.com.br/api/v1/items/1100005/appraise?price=2600'

# avaliar um replay
curl -X POST --data-binary @replay.rrf \
  -H 'content-type: application/octet-stream' \
  https://mercado.latam-tools.com.br/api/v1/replay

Quando um nome casa com vários itens, a resposta é 300 com a lista de candidatos — o serviço não escolhe por você.

Conectando o MCP

Em clientes com suporte a MCP remoto (Claude Desktop, Claude Code):

{
  "mcpServers": {
    "mercado-ro": {
      "type": "http",
      "url": "https://mercado.latam-tools.com.br/mcp"
    }
  }
}

⚠️ refresh_live gasta uma requisição ao site e pode ser bloqueada por limite de taxa. As descrições das ferramentas dizem isso ao agente, para ele preferir os dados já coletados — que costumam ter menos de uma hora.

Como funciona

                      ┌──────────────────────────────────┐
   Caddy ──── :8788 ──│  API REST  ─┐                    │
                      │             ├─→  core/  ─→ cache │
                      │  MCP       ─┘         ↑          │
                      └───────────────────────│──────────┘
                                              │
                          SQLite  ←──── worker do crawl
                                              │
                                    EgressPool (lanes)
                                              │
                                     ro.gnjoylatam.com

Um processo só. api/ e mcp/ são casca fina sobre core/ e não podem ler o banco direto — é isso que garante que os dois canais respondam a mesma coisa, e há um teste de paridade que quebra se alguém contornar.

O mercado inteiro cabe na memória (~5 mil itens com preço, ~20 mil anúncios), então nenhuma leitura toca o disco. O SQLite existe para o histórico e para sobreviver a reinício.

Coleta e rotação de IP

O site limita a ~50 requisições por minuto por IP e por endpoint, e o bloqueio dura mais de cinco minutos. A saída é ter várias identidades de rede.

Cada "lane" é uma conta Cloudflare WARP anônima dentro da sua própria network namespace do Linux. Isso importa porque o servidor é compartilhado: um warp-cli connect trocaria a rota da máquina inteira e derrubaria as conexões dos outros serviços a cada rotação. Dentro da namespace, a rota do host nunca é tocada.

Duas outras decisões que caem daí:

• A rotação é fora-de-lugar. A saída nova é criada e publicada antes de a antiga ser encerrada, e o encerramento espera as requisições em andamento terminarem. Trocar no lugar mataria justamente as requisições que provocaram o bloqueio.

• A saída direta é reservada para consultas ao vivo. O crawl roda só nas lanes de túnel, então um bloqueio na coleta nunca deixa um usuário esperando — e vice-versa.

Detalhes de medição e de operação do coletor estão em docs/scraper.md.

Rodando localmente

Precisa de Node 22.5+ (por causa do node:sqlite) e pnpm.

pnpm install
pnpm import --run-id full   # carrega os NDJSON já coletados no SQLite
pnpm dev                    # sobe em http://127.0.0.1:8788

Sem dados em data/raw/, o serviço sobe com o mercado vazio — colete primeiro com pnpm crawl (veja docs/scraper.md).

Variáveis úteis: PORT, DB_PATH, DATA_DIR, EGRESS_LANES, CRAWL_ENABLED, ALLOWED_HOSTS, ALLOWED_ORIGINS (veja src/server/config.ts).

Estrutura

src/
  scraper/   coletor: cobertura de termos, cliente HTTP, extração do payload RSC
  egress/    pool de saídas de rede, lanes e rotação de IP
  store/     SQLite, cache quente e retenção
  replay/    leitura de arquivos .rrf (inventário, carrinho, equipamento)
  core/      a lógica de mercado — a única camada que API e MCP enxergam
  api/       rotas REST
  mcp/       ferramentas MCP
  server/    processo HTTP
  worker/    coleta periódica em worker thread
  cli/       comandos de linha
infra/       systemd, Caddy e provisionamento das lanes
docs/        documentação do coletor

Deploy

Push na main dispara o GitHub Actions: typecheck, testes, bundle com esbuild, envio por scp para o EC2, rsync em /opt/latam-market e reinício do systemd. A verificação bate no /healthz, faz uma chamada MCP real e uma consulta REST — se qualquer uma falhar, o deploy falha.

O banco fica em /var/lib/latam-market/market.db, fora de /opt, porque o deploy usa rsync --delete e levaria o histórico junto.

Arquivos de infraestrutura em infra/, com o provisionamento manual necessário documentado no topo de cada um.

Limites conhecidos

• Só FREYA, e só o lado de quem está vendendo (storeType=BUY; SELL não retorna nada nesse site).

• Refino, cartas e bônus aleatórios não são precificados. O mercado agrega por id de item, então uma arma +9 encantada aparece com o preço da arma base — as respostas avisam quando é o caso, em vez de fingir precisão.

• O histórico começa quando começamos a coletar. O site não publica série temporal; o que ele dá é um agregado acumulado, e o resto é medição nossa.

• O retrato de um replay é do início da gravação. Itens pegos ou gastos durante a gravação não aparecem.

• Alguns containers de item do .rrf ainda não foram identificados (provavelmente armazém da Kafra). Eles vêm à parte, em unidentified, e não entram no total.

Créditos

Catálogo de itens em pt-BR do projeto irmão latam-ro-calc (simulador de dano). A leitura de .rrf é portada de lá, que por sua vez segue o Rrf-Parser do Tokeiburu.

Projeto não-oficial, feito para a comunidade. Sem vínculo com a Gravity ou a Gnjoy.

Licença

MIT.