Mostrador MCP · Stock, precios y presupuestos de una ferretería, como tools para agentes

Servidor MCP en TypeScript (SDK oficial) para una ferretería ficticia: busca productos, consulta stock, calcula el precio con las reglas de descuento y arma presupuestos. Lo usan Claude Desktop o Claude Code por stdio y un chat de mostrador en Next.js por HTTP, con un agente que trabaja solo con esas tools. · English version

Proyecto de demostración. "Ferretería El Tornillo" es una marca ficticia. Los 300 productos, las marcas, los precios y los clientes (@example.com) son inventados y se generan por script.

El problema

En el mostrador de una ferretería la pregunta es siempre la misma: ¿tienen esto?, ¿cuánto sale?, ¿hay stock?, ¿me hacés un presupuesto?. La respuesta está en el sistema de stock, pero hay que buscarla a mano, aplicar los descuentos por cantidad y por medio de pago, y pasarla a un presupuesto. Un asistente de IA puede hacerlo, siempre que lea los datos reales y no invente precios.

Related MCP server: helios-mcp-server

La solución

• Servidor MCP con el SDK oficial de TypeScript (v2). Cuatro tools y dos resources:

  Tool	Qué hace	Tipo
  buscar_producto(q, categoria?, limit, offset)	Busca por nombre, marca o categoría sin importar acentos; máximo 50 por página, con next_offset	lectura
  consultar_stock(sku)	Stock actual, con salida estructurada	lectura
  precio(sku, cantidad, medio_pago)	Precio final con el detalle de las reglas (volumen, medio de pago, tope)	lectura
  crear_presupuesto(items, cliente_ficticio, medio_pago)	Guarda un presupuesto válido por 7 días; valida stock	escritura, solo con FLAG_WRITE=true

  Resources: catalogo://categorias (JSON) y politicas://envios (markdown).

• Reglas de precio (función pura con tests): 5 % desde 10 unidades y 10 % desde 50; efectivo −10 %, transferencia −5 %, débito igual, crédito en 3 cuotas +10 %. Los descuentos se combinan con un tope de 15 %.

• Dos transportes: stdio (Claude Desktop y Claude Code lo lanzan como subproceso) y HTTP streamable con token Bearer (el chat web). Guía: docs/claude-desktop.md.

• Chat de mostrador (Next.js): el agente (Gemini con tool use) recibe la lista de tools que anuncia el servidor, llama a las que necesita por HTTP y contesta con una función de salida estructurada (responder_al_cliente: respuesta + SKUs). El tablero perforado muestra los productos con el precio y el stock que devolvieron las tools, nunca los del texto del modelo, y el presupuesto con su número. Cada respuesta muestra las llamadas al servidor con su argumento principal y el JSON de los argumentos. Antes de la primera consulta, el tablero muestra un ejemplo grabado de una respuesta real (se graba con node scripts/grabar-ejemplo.mjs). En español y en inglés (/en).

• Base: Postgres. Con DATABASE_URL usa Supabase u otro Postgres; sin ella, PGlite (Postgres en WASM) con la misma migración, así corre en cualquier PC sin cuentas.

Demo

Capturas en inglés en docs/capturas/en/. Las respuestas son reales del agente.

Arquitectura

flowchart LR
  CL[Claude Desktop / Claude Code] -->|stdio| SRV
  subgraph WEB[App Next.js]
    UI[Chat de mostrador + tablero] -->|POST /api/chat| AG[Agente: Gemini con tool use]
    AG -->|HTTP streamable + Bearer| EP["/api/mcp"]
  end
  EP --> SRV[Servidor MCP<br/>tools + resources]
  SRV --> DB[(Postgres / PGlite:<br/>productos, presupuestos)]
  SRV --> AUD[(Auditoría:<br/>tool, args, ok, duración)]

sequenceDiagram
  participant C as Cliente
  participant A as Agente (Gemini)
  participant M as Servidor MCP
  C->>A: "¿Cuánto salen 12 martillos ET-HM-0001 con transferencia?"
  A->>M: tools/list
  M-->>A: buscar_producto, consultar_stock, precio, crear_presupuesto
  A->>M: tools/call precio {sku, cantidad: 12, medio_pago: transferencia}
  M->>M: Zod (strictObject) → reglas → auditoría
  M-->>A: structuredContent {total: 99148, descuento_total_pct: 9.8, ...}
  A-->>C: responder_al_cliente {respuesta, skus: [ET-HM-0001]}
  Note over C: El tablero dibuja el precio del structuredContent, no del texto

Seguridad

• Solo lectura por defecto. crear_presupuesto se registra únicamente con FLAG_WRITE=true; sin el flag ni aparece en tools/list (lo cubre un test). En la demo web está prendido sobre una base en memoria con datos ficticios, que se reinicia sola.

• Validación estricta. Todas las entradas son z.strictObject (un argumento de más se rechaza), los SKU tienen formato fijo, las cantidades van de 1 a 1000, los resultados se cortan en 50 y las respuestas largas se recortan. Los presupuestos solo aceptan emails @example.com y validan stock antes de guardar.

• Auditoría. Cada llamada a una tool queda registrada con sus argumentos, si salió bien o mal, el detalle y la duración y el transporte.

• HTTP con token. /api/mcp exige Authorization: Bearer <MCP_TOKEN> (comparación en tiempo constante); sin token configurado, no atiende a nadie. El servidor HTTP propio escucha solo en 127.0.0.1 y valida Host y Origin.

• Errores que guían. Los errores dicen cómo seguir ("buscalo con buscar_producto") en lugar de devolver trazas.

• Chat: entradas de hasta 600 caracteres, límite de 12 pedidos por minuto por IP, y la clave de Gemini solo en el servidor. El prompt le prohíbe decir que hizo algo que ninguna tool hizo (por ejemplo, mandar el presupuesto por mail).

• Consultas parametrizadas en todas las tools; ninguna arma SQL con texto del usuario.

Stack y skills demostradas

MCP (servidor y cliente con el SDK oficial v2, stdio y HTTP streamable, tools con outputSchema y anotaciones, resources) · agente con tool use y salida estructurada (Gemini) con modelo de respaldo · Zod 4 · Postgres / PGlite · Next.js 16 (App Router, route handlers) · TypeScript estricto · Tailwind 4 · ES/EN · Vitest · Playwright · axe-core · Lighthouse.

Cómo correrlo

npm install
npm test                 # 16 tests con el cliente MCP del SDK en memoria y PGlite, sin red
npm run build            # servidor MCP en dist/
npm run cliente          # cliente de prueba por stdio: lista las tools y ejecuta buscar_producto y precio

Para Claude Desktop o Claude Code, ver docs/claude-desktop.md.

Chat web (necesita una clave de Gemini, gratis en aistudio.google.com):

cp .env.example .env.local   # GEMINI_API_KEY y un MCP_TOKEN largo; npm run check-env dice OK/FALTA sin mostrar valores
npm run build:web
npm run start:web            # http://localhost:3208 (y /en)
npm run casos                # los 10 casos del agente
npm run test:e2e             # e2e y axe (Brave o Chrome)
npm run lighthouse           # móvil, mediana de 3

Tests y resultados medidos (01/11/2026)

Costos de operación estimados

Límites y próximos pasos

• En la web, la base es PGlite en memoria por instancia: los presupuestos de la demo no se comparten entre visitas. Con DATABASE_URL (Supabase) se vuelven persistentes.

• El agente usa Gemini; el servidor MCP es el mismo para cualquier cliente (Claude, OpenAI Agents, etc.).

• Siguiente: OAuth para el endpoint HTTP en lugar del token fijo, más tools (pedidos, proveedores) y un stock que se descuente al confirmar el presupuesto.

Autoría

Desarrollado por Germán Schouabs.

Licencia

MIT. Ver LICENSE.