Tizón · Servidor MCP

Un servidor Model Context Protocol para operar un restaurante, con un playground que enseña el JSON-RPC en vivo.

Tizón es ficticio. Es la tercera pieza del mismo restaurante inventado, junto con su sitio y la app de pedidos.

pnpm install
pnpm dev

Instalarlo en un cliente MCP

En Claude Code:

claude mcp add tizon -- npx tsx bin/tizon-mcp.ts

Cualquier host MCP sirve — Claude Code, Cursor, VS Code, el tuyo. El servidor también habla HTTP en /api/mcp, así que se puede consumir remoto.

La superficie es idéntica por los dos transportes: crearServidor() no sabe por dónde lo están hablando. El transporte es detalle de despliegue, no de diseño.

Las cinco herramientas

Herramienta	Qué hace
consultar_carta	Platillos con precio, estación de cocina y si están agotados
pedidos_activos	Comandas en cocina, con minutos de espera y cuáles van retrasadas
resumen_del_turno	Entregadas, retrasadas, espera promedio, qué se cancela más
marcar_disponibilidad	Agotar un platillo o reponerlo
avanzar_pedido	Mover una comanda al siguiente estado

Las decisiones, que es de lo que va el proyecto

Que algo sea un servidor MCP no dice nada. Lo que dice algo es cómo está diseñada la superficie.

Cinco herramientas, no veinte. Cada una responde a una pregunta o hace una acción que alguien en el restaurante haría. Más herramientas no es más capacidad: es más superficie donde el modelo puede elegir mal.

No hay escotilla genérica. No existe ejecutar_consulta ni nada que acepte SQL o un filtro arbitrario. Es la omisión más importante del servidor: una escotilla lo convierte en una API cruda, hace imposible razonar sobre qué puede pasar, y traslada al modelo decisiones que le tocan al servidor. Hay una prueba que verifica que no exista.

Las descripciones dicen cuándo llamar, no solo qué hace la herramienta. Es lo que más mueve la aguja para que el modelo acierte a elegirla, y hay una prueba que falla si alguna se queda demasiado corta.

La salida es texto para leer, no un volcado de JSON. El consumidor es un modelo: un texto compacto y etiquetado cuesta menos tokens y se interpreta mejor que un objeto anidado.

Los errores enseñan. Un folio inexistente devuelve los folios que sí existen; un identificador de platillo inválido devuelve los válidos. Un error que solo dice «no encontrado» obliga al modelo a adivinar otra vez; uno que dice qué sí hay le permite corregirse en el mismo turno.

Fallar claro antes que fingir éxito. Avanzar una comanda ya entregada es un error, no un no-op silencioso. Si el modelo cree que avanzó algo, seguirá razonando sobre algo falso.

Dos superficies sobre un mismo estado. Las herramientas MCP devuelven texto porque su consumidor es un modelo; /api/tablero devuelve JSON porque su consumidor es una interfaz. Hacer que la interfaz parsee el texto pensado para el modelo sería atarlas por el lado equivocado.

El playground

/ es un cliente MCP, no un chat. Pide tools/list al servidor, deja llamar cada herramienta con argumentos reales y enseña el JSON-RPC que va y viene. Al lado, el tablero que esas llamadas modifican.

No hay un modelo de por medio, a propósito. Un playground que enseña el protocolo demuestra más sobre MCP que un chat donde un modelo hace de intermediario y tapa el mecanismo. Para ver el agente de verdad está la instalación por stdio, arriba.

El estado vive en memoria del servidor y se resiembra en cada arranque en frío, así que nadie le arruina la demo a nadie.

Pruebas

pnpm prueba:mcp

Diecisiete comprobaciones que hablan el protocolo de verdad — levantan el servidor por stdio y le mandan JSON-RPC, sin mockear el SDK y sin llamar a ningún modelo. Cubren descubrimiento, lectura, acción, idempotencia y los errores que enseñan. Dos de ellas verifican decisiones de diseño y no implementación: que las descripciones expliquen cuándo usar cada herramienta, y que no haya aparecido una escotilla genérica.

Notas de implementación

Contra la especificación 2026-07-28, que pasó a ser sin estado: no hay handshake de initialize ni sesión a nivel de protocolo. Por eso se construye un servidor por petición y esto escala detrás de un balanceador normal, sin sesiones pegajosas. SDK de TypeScript v2.

Tres cosas que solo salieron probando, por si le ahorran a alguien la tarde:

• createMcpHandler devuelve un objeto { fetch, notify, bus, close }, no una función. Exportarlo directo como route handler compila y revienta en runtime.
• Su .fetch tampoco encaja como route handler de Next: recibe (request, options?) y Next pasa (request, context). Hay que envolverlo.
• En ImageResponse, satori exige display explícito en cualquier div con más de un hijo — y texto + <br/> + texto son tres. El build falla.

Capturas

tools/shot.mjs maneja Chrome por CDP, avisa si algo desborda a lo ancho y guarda la página completa.

pnpm shot http://localhost:3000 capturas/playground.png
ESCALA=2 pnpm shot ...   # doble resolución, para publicar
EVAL='...' pnpm shot ... # ejecuta y muestra lo que devuelva