Forem: Ricardo Cuba

Shipping an MCP server: parallel search, JSON output, and what broke along the way

Ricardo Cuba — Thu, 21 May 2026 01:57:06 +0000

CLI Market hit 3,760 retailers this week. With that scale came problems.

Here's what we fixed and what we learned.

[Problem 1: Search timeout][...]

[Problem 2: --json flag that didn't work][...]

[Problem 3: Session loss on cloud deploys][...]

[What we learned about Render vs Railway][...]

[Full changelog + code links]

pip install cli-market
github.com/Treevu-ai/cli-market-world

How I registered an MCP server for 3,760 retailers — and what I learned

Ricardo Cuba — Wed, 20 May 2026 00:08:56 +0000

Yesterday CLI Market was a PyPI package.
This week it's an official MCP Registry server:

Here's what it took to get listed, what the registry validation looks like, and why MCP is the missing layer between e-commerce and AI agents.

The MCP Registry: what it took to get listed

**
The Model Context Protocol Registry at registry.modelcontextprotocol.io is the canonical
directory of MCP servers. Getting listed isn't just about having a working server — the registry validates ownership, checks schema compliance, and verifies that the package actually exists.

*Step 1: The mcp.json file
*
Every MCP server needs a mcp.json at the repo root. Ours:
{ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json" , "name": "io.github.Treevu-ai/cli-market", "title": "CLI Market", "version": "1.0.1", "description": "12 MCP tools for search, compare, purchase across 3,760 retailers in 67 c ountries", "repository": { "url": "https://github.com/Treevu-ai/cli-market-world", "source": "github" }, "packages": [{ "registryType": "pypi", "identifier": "cli-market", "version": "1.0.17", "transport": { "type": "stdio" } }] }

Key decisions:

Name format: io.github.{org}/{project} — reverse-DNS, org-scoped
registryType: pypi — CLI Market is a Python package on PyPI
transport: stdio — the MCP server communicates over standard input/output
version locked — no ranges, exact version matching

*Step 2: Proving ownership
*
The registry doesn't trust that cli-market on PyPI belongs to Treevu-ai on GitHub. It validates by scanning the PyPI package README for a specific HTML comment:

<!-- mcp-name: io.github.Treevu-ai/cli-market -->

This line must appear in the README that renders on PyPI. The registry fetches the package, parses the README, and checks that the annotation matches the server name. If it doesn't match — rejected.

We added this to our README, bumped the version to 1.0.17, and uploaded to PyPI. The registry validated it in under a second.

*Step 3: Schema validation
*
The publish endpoint runs the full ServerJSON schema validator. Every field is checked:

description max 100 characters, name must match ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$,
packages[].identifier must resolve in the registry, packages[].transport.type must be stdio/
streamable-http/sse.

One thing that tripped us up: the schema changed between mcp.json (the repo-side format) and ServerJSON (the registry API format). In the repo, you declare command, args, type. In the registry API, those go inside packages[].transport and packages[] requires registryType + identifier + transport. Getting this right took a few rounds.

*Step 4: Authentication
*
The registry uses GitHub OAuth. We exchanged a GitHub token for a registry JWT:
POST /v0.1/auth/github-at → { registry_token: "eyJ..." }

Then published:
POST /v0.1/publish → { server: {...}, _meta: { status: "active" } }

The token expires, so for updates you re-authenticate. The whole flow is scriptable in under 10 lines of bash.

The 12 tools: architecture

All 12 tools sit on top of a unified VTEX connector that normalizes 3,760 retailer APIs into a single JSON schema.

_Four tools deserve special attention:
_

- market_compare — Not a simple price fetch. It first normalizes SKUs across retailers (the same product has different internal IDs at Carrefour Brazil and Sainsbury's UK), deduplicates, and returns a canonical price set. Three steps under one MCP call.
market_checkout — Chains: cart validation → stock verification → payment method resolution → order confirmation. All in one invocation. But it never completes autonomously — V1 requires explicit human approval before execution.
market_ask — The most composite tool. Natural language input → semantic search → cross-retailer comparison → cart building → checkout readiness. "Buy rice" walks the full pipeline.

The composition pattern — Tools are atomic enough to compose, composite enough to not drown the agent. 12 tools. Not 1 mega-tool. Not 100 individual REST endpoints.

───

What I'd do differently

Read the OpenAPI spec first. The publish endpoint schema is documented at /docs. I guessed from the mcp.json format and hit 5 validation errors before getting it right.
Set up the PyPI annotation early. The mcp-name comment is the ownership proof. Add it to your README before you publish to the registry.
Script the auth flow. GitHub token → registry JWT → publish. Three curl calls. Wrap them in a Makefile target and forget about it.

───

CLI Market is on the registry.
The agent can now search, compare, and buy across 3,760 retailers in 67 countries — all via structured tool calls with zero scraping.

pip install cli-market
io.github.Treevu-ai/cli-market
github.com/Treevu-ai/cli-market-world

Ricardo Cuba
Founder & Product Lead | CLI Market
CEO Sinapsis Innovadora
Trujillo, Perú

The VTEX public API is the same for 3,760 retailers — but no one aggregated it. Until now.

Ricardo Cuba — Tue, 19 May 2026 01:15:27 +0000

VTEX runs e-commerce for Nike, Carrefour, Samsung, Motorola, and 3,760+ other brands. Every one exposes the same search and catalog API endpoints. Same JSON schema. Same pagination rules.

For years, if you wanted to query products across retailers, you had to scrape or make separate API calls per store. There was no aggregation layer.

VTEX powers e-commerce for Nike, Carrefour, Samsung, and 3,760+ brands.
All share the same public API — but no one had built the aggregation layer for programmatic access. Until now.

pip install cli-market and your terminal becomes a commerce engine across 67 countries.

So I built one.
gifsicle --optimize=3 --lossy=80 demo.gif -o demo-small.gif

Technical details:

Single Python connector that maps VTEX's public search/catalog/checkout endpoints
Each retailer = one config line: {domain, country, currency, line}
SQLite price snapshots for historical data
Rich terminal UI + REST API + MCP server (12 tools)
JSON output saves ~85% context window tokens vs raw HTML

Everything is indexed and queryable cross-retailer. Search "milk" and get results from Carrefour Brazil, Sainsbury's UK, Wong Peru, in one response.

GitHub: https://github.com/Treevu-ai/cli-market-world
Live: https://cli-market.dev

Stack: Python, FastAPI, Rich, SQLite, Next.js. MIT license.

Curious what the community thinks about e-commerce APIs being still optimized for browsers instead of programmatic access.

Conecta tus agentes de IA a +2000 retailers de LATAM con una sola API

Ricardo Cuba — Mon, 18 May 2026 04:14:09 +0000

En este post te presento CLI Market, una infraestructura de comercio open source que conecta 100 retailers en 12 países de LATAM a través de una sola API y una CLI para agentes de IA.

¿Qué es CLI Market?
CLI Market unifica catálogos, precios y disponibilidad de múltiples retailers para que tus agentes de IA puedan buscar, comparar y simular compras sin integrar tienda por tienda.

2000+ retailers conectados
40+ países en el mundo
Una API y una CLI open source

👉 Sitio: https://cli-market.dev/
👉 Repo: https://github.com/Treevu-ai/cli-market-world

Cómo empezar?

git clone https://github.com/Treevu-ai/cli-market-latam.git
cd cli-market-latam
npm install
npm run cli

Ejemplo rápido para listar retailers por país:

cli-market retailers list --country=PE

Con esto ya puedes exponer catálogos como herramientas para tus agentes (HTTP, JSON, MCP) y construir asistentes que optimicen compras en retail sobre una sola capa de infraestructura.

first create post dev test

Ricardo Cuba — Mon, 11 May 2026 02:41:34 +0000

One of the most powerful things I've learned a few days ago is the possibilities to vibe coding from ubuntu and docker containers