AgentCart es una interfaz de comercio hecha para agentes de IA, no para humanos. Es un backend puro (sin frontend) que expone un servidor MCP (Model Context Protocol) y una pequeña API de administración, para que un agente —Claude, ChatGPT, Gemini o uno propio— pueda buscar, comparar, cotizar, armar carrito y comprar contra tiendas reales como Tiendanube/Nuvemshop y MercadoLibre, todo detrás de un único esquema normalizado.
No hay pantallas, ni carrito visual, ni checkout para personas. El "usuario" de AgentCart es el agente.
Construido con Express 5 · TypeScript, corriendo como un proceso Node persistente (no serverless). Desplegable en cualquier host Node (Render, Fly.io, Railway, un contenedor, o Vercel como Node server).
La tesis: el próximo comprador no es una persona haciendo clic, es un agente actuando en su nombre. Las tiendas de hoy están diseñadas para ojos y clics humanos y quedan ciegas frente a un agente que quiere operar de forma programática.
AgentCart es la capa intermedia que le da a cualquier agente una forma limpia, tipada y segura de comprar en las plataformas de eCommerce que ya existen en LATAM, sin que cada agente tenga que aprender la API propia de cada plataforma. Un solo contrato MCP → muchos backends de comercio por debajo.
- Interfaz 100% agent-first — la superficie de uso es un servidor MCP con herramientas (
tools), recursos (resources) y prompts. Nada de UI humana. - Un esquema, muchas tiendas — una capa de adaptadores normaliza MercadoLibre, Tiendanube/Nuvemshop y un backend demo a los mismos DTOs (
AgentProduct,Cart,CheckoutResult, …). Cambiar de tienda no cambia las herramientas que ve el agente. - Conectar con eCommerce reales de LATAM — adaptadores contra las APIs reales de MercadoLibre y Tiendanube (mapeo de campos real, auth OAuth2/token), conectables en runtime sin redeploy.
- Cero fricción para arrancar — corre con el backend
demosin ninguna credencial; el agente puede probar el flujo completo (buscar → inventario → envío → carrito → checkout → tracking) offline. - Proceso persistente — servidor Express de larga duración, así el estado de conexión de los adaptadores (tokens conectados en runtime) sobrevive entre requests, algo que un entorno serverless no garantiza. JSON-RPC sobre HTTP con CORS, listo para que un agente remoto lo consuma directo.
- Servidor MCP funcional (
/api/mcp) — JSON-RPC 2.0:initialize,tools/list,tools/call,resources/list,resources/read,prompts/list. - 7 herramientas de comercio —
searchProducts,getProduct,compareProducts,checkInventory,calculateShipping,createCart,checkout,trackOrder. - Capa de adaptadores con contrato único (
CommerceAdapter) y 3 backends: demo, MercadoLibre, Tiendanube. - API de administración (
/api/adapter) — listar adaptadores, elegir el activo y conectar credenciales en runtime. - OAuth completo end-to-end para MercadoLibre y Tiendanube (hoy: token/credenciales; falta el callback de OAuth).
- Escritura real de órdenes en Tiendanube (creación de order) y hand-off de checkout en MercadoLibre.
- Autenticación del propio servidor MCP (API keys / scopes por agente).
- Más plataformas (Shopify, WooCommerce) sobre el mismo contrato.
pnpm install
pnpm dev # tsx watch → http://localhost:3000Arranca con el backend demo — no requiere ninguna credencial. Para apuntar a una tienda real, copiá .env.example → .env.local y completá el token del adaptador (o conectalo en runtime, ver abajo).
pnpm build && pnpm start # tsc → node dist/server.jsEl puerto se controla con la variable de entorno PORT (default 3000).
| Ruta | Método | Qué hace |
|---|---|---|
/ |
GET |
Manifiesto del servicio (versión, endpoint MCP, herramientas, adaptadores) |
/api/mcp |
GET |
Descripción rápida del servidor MCP |
/api/mcp |
POST |
Endpoint JSON-RPC 2.0 del servidor MCP |
/api/adapter |
GET |
Lista adaptadores y cuál está activo |
/api/adapter |
POST |
Cambia el adaptador activo ({ id }) |
/api/adapter/connect |
POST |
Conecta/desconecta credenciales en runtime ({ id, token, storeId? }) |
searchProducts · getProduct · compareProducts · checkInventory · calculateShipping · createCart · checkout · trackOrder
Flujo típico de un agente: searchProducts → checkInventory / calculateShipping → createCart → checkout → trackOrder.
# Listar herramientas
curl -X POST localhost:3000/api/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# Buscar productos
curl -X POST localhost:3000/api/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"searchProducts","arguments":{"query":"drill","limit":3}}}'Para dirigir una request a un backend específico sin cambiar el activo, mandá el header x-agentcart-adapter: mercadolibre (o tiendanube / demo).
Agente (Claude / ChatGPT / Gemini / propio)
│ JSON-RPC 2.0 / MCP
▼
Express (src/server.ts)
│
/api/mcp ──► handler MCP ──► tools (7) ──► CommerceAdapter (contrato único)
│
┌────────────────────────────────────────────────┼────────────────────────────┐
▼ ▼ ▼
DemoAdapter MercadoLibreAdapter TiendanubeAdapter
(catálogo en memoria) (api.mercadolibre.com) (api.tiendanube.com)
src/server.ts— la app Express: CORS, parseo JSON, monta las rutas y el manifiesto en/.src/routes/mcp.ts— endpoint HTTP del servidor MCP (GETinfo ·POSTJSON-RPC).src/routes/adapter.ts— API para listar/cambiar el adaptador activo y conectar credenciales.src/mcp/handler.ts— el dispatcher MCP (JSON-RPC), agnóstico del framework HTTP.src/lib/commerce/adapter.ts— el contratoCommerceAdapterque implementa todo backend.src/lib/commerce/types.ts— los DTOs normalizados (AgentProduct,Cart,CheckoutResult, …) que el agente ve, sin depender de ninguna plataforma.src/lib/commerce/tools.ts— la definición de las 7 herramientas MCP y su JSON Schema.src/lib/commerce/{demo,mercadolibre,tiendanube}-adapter.ts— los 3 backends. Los reales traen el mapeo de campos y los endpoints de la API oficial de cada plataforma.src/lib/commerce/registry.ts— registro de adaptadores, adaptador activo y conexión en runtime.
Express 5 · TypeScript · Node.js. tsx para desarrollo, tsc para el build. Una sola dependencia de runtime (express). Sin frontend.