# velora-mcp-demo

Free, always-on **public demo** of the [Velora](https://www.somosvelora.com) agentic-commerce
MCP toolkit — hosted on Vercel's free Hobby plan, $0/month, no card, no billing cycle.

Serves `tools.somosvelora.com` — the production Cloud Run backend that used to live there is
**paused on purpose** (cost), so this demo replaces the old 404 with something real: a live
MCP server, Streamable HTTP transport, real tool schemas, and an explicit honesty design
instead of a dead link.

## Endpoints

- `/api/mcp` — full tool surface (~49 tools, mirrored from the real production tool set).
- `/api/mcp/public` — read-only subset with zero side effects (matches the URL already printed
  in the `latam-tools` repo).

## Three honesty levels (see `lib/shared/types.ts` and `lib/shared/register.ts`)

1. **Pure** — `validate_cuit` runs the real Argentine AFIP/ARCA check-digit algorithm for real,
   against whatever CUIT/CUIL you send it. No fixture involved.
2. **Read** — tools that only look something up (catalog, customers, caja balance, sales
   metrics, shipping quotes, connection status, the `open_*` MCP Apps widgets, …) return a
   fixed, fictional dataset (**"Almacén Demo SRL"**). Every response carries a
   `[DEMO] Datos de muestra — el backend de producción está pausado.` banner and
   `_demo: true` in its JSON body — never mistakable for a real business.
3. **Refuse** — tools with a real side effect in production (`emit_invoice`, `emit_nota`,
   `register_sale`, `create_tracked_payment_link`, `send_whatsapp_text`,
   `caja_ciclo_caja`, `connect_mercadopago`, …) return `isError: true` with an honest
   explanation. **No fabricated CAE, payment id, tracking number, or credential — ever.** The
   tool's name, description, and input schema are still the real production ones; only the
   execution is disabled.

## Where the tool names/schemas came from

Every tool name, description, and Zod input shape here is copied/trimmed from the
currently-registered tools in the private `velora-track3-repo` production codebase
(`src/lib/mcp/*.ts`), verified file-by-file — not invented. One known gap, found while
building this: the developer-facing `/developers` catalog page in that repo lists ~60 tool
names (CUIT/CUIL/CBU validators, `format_ars`, `split_iva`, `to_afip_date`, `build_afip_qr`,
`describe_invoice_type`, `consultar_comprobante`, `consultar_padron`) that are **not** actually
registered as MCP tools anywhere in the codebase — they exist only on the marketing page. This
demo mirrors the ~49 tools that are actually real and registered, not the marketing count.

## Stack

Next.js (App Router) + [`mcp-handler`](https://github.com/vercel/mcp-handler) 2.x +
`@modelcontextprotocol/server` 2.x + Zod 4. Deployed on Vercel Hobby.

## Local dev

```bash
npm install
npm run dev
# http://localhost:3000/api/mcp
```

## Status

Demo endpoint — sample data only. The real Velora product lives at
[somosvelora.com](https://www.somosvelora.com); this repo is a portfolio/demo piece, not the
production system.