mcp-pedidos

Servidor MCP para que un cliente consulte sus pedidos desde Claude o ChatGPT: estado, ítems, total e historial, con permisos por cliente. SQLite, cero dependencias, sin API key.

Cliente:  ¿Dónde está mi pedido P-0001?
Agente:   P-0001 está enviado desde el 13/11 14:30.
          - 4 x Bolsas de harina 000 x 25 kg  $98.000,00
          - 10 x Levadura fresca x 1 kg        $18.900,00
          Total: $116.900,00
          Historial: pendiente → preparando → enviado

El problema

Un negocio chico recibe "¿llegó mi pedido?" por WhatsApp todo el día. La respuesta ya está en el sistema, pero nadie quiere abrir el sistema. Con este servidor, el cliente conecta su cuenta a un agente y pregunta en lenguaje natural; el agente consulta el pedido real, no inventa.

Lo importante no es el CRUD: es el límite. Una instancia de cliente no puede ver pedidos de otro, y el modelo no puede elegir el token: viene en la configuración del cliente MCP. Si el modelo insiste, el servidor responde "no existe".

Related MCP server: Shopify MCP Demo

Qué expone

Instalación

Necesitás Node 22.13+. No hay dependencias.

git clone https://github.com/lucabaello1998/mcp-pedidos.git
cd mcp-pedidos
node cli.js semilla
PEDIDOS_TOKEN=cli_laespiga_demo_2026 node cli.js listar

Conectarlo a un cliente MCP

{
  "mcpServers": {
    "pedidos": {
      "command": "node",
      "args": ["C:/ruta/a/mcp-pedidos/server.js"],
      "env": {
        "PEDIDOS_DB": "C:/ruta/a/pedidos.db",
        "PEDIDOS_TOKEN": "cli_laespiga_demo_2026"
      }
    }
  }
}

Para la instancia del dueño, el mismo servidor con otro token:

"env": {
  "PEDIDOS_DB": "C:/ruta/a/pedidos.db",
  "PEDIDOS_TOKEN": "<token de admin>",
  "PEDIDOS_ADMIN_TOKEN": "<token de admin>"
}

Variables:

Modelo de datos

clientes (id, nombre, email, token)
pedidos  (id, numero, cliente_id, estado, total_centavos, nota, fechas)
items    (id, pedido_id, descripcion, cantidad, precio_centavos)
eventos  (id, pedido_id, estado, nota, creado_en)   -- historial

El dinero va en centavos enteros, nunca en float: 0.1 + 0.2 no es 0.3, y un total no puede depender de eso. La API expone precio_centavos y devuelve total_centavos; el total en pesos es solo para mostrar.

Máquina de estados

pendiente → preparando → enviado → entregado
     ↘          ↘
      cancelado  cancelado

Un pedido entregado no vuelve atrás: si hay que corregir algo, se hace una devolución, no se reescribe la historia. Las transiciones inválidas devuelven el motivo y las opciones posibles, no un "error 400".

Decisiones y por qué

El token no es un argumento de la herramienta. Si el token viajara en el prompt, el modelo podría cambiarlo o el usuario podría pedirle "probá con otro". Va en la configuración del cliente MCP: una instancia = una identidad. Es la diferencia entre autenticación y "confiar en el modelo".

Pedido ajeno = "no existe". Responder "no autorizado" confirma que el número existe; con números correlativos eso es un oráculo. Mismo criterio que un login.

Comparación de tokens en tiempo constante. No es paranoia de más: es la misma razón por la que no se compara una contraseña con ===.

Máquina de estados explícita. Un UPDATE estado = ? sin validar permite "entregado → pendiente" y rompe cualquier reporte. Las transiciones están en una tabla de 5 líneas, legibles y testeables.

Centavos enteros. Un pedido con precios en float acumula centavos perdidos; el bug aparece recién cuando el contador cuadra mal.

Sin ORM. Cuatro tablas y cinco consultas: un ORM agregaría una capa para ahorrar veinte líneas de SQL.

Límites honestos

• No hay usuarios ni contraseñas. El token es la identidad; para producción haría falta rotación, expiración y un registro de accesos.

• Un solo negocio por base. No hay tenant_id; para varios negocios se agrega la columna y se filtra igual que por cliente.

• Sin pagos ni stock. El total se calcula, no se cobra ni se descuenta.

• SQLite. Bien para una pyme; para varias instancias escribiendo a la vez hace falta un motor con más concurrencia.

Tests

npm test

55 tests con node --test, sin frameworks:

• creación: total en centavos exacto, número correlativo, evento inicial y rechazo de ítems inválidos (cantidad, precio con decimales, descripción vacía);

• permisos: el cliente ve lo suyo, el ajeno responde "no existe", el admin ve todo, el cliente no cambia estados ni ve el resumen;

• máquina de estados: recorrido completo, saltos rechazados, estados finales;

• protocolo MCP por stdio: handshake, tools/list, -32601, -32700, notificaciones sin respuesta y stdout solo con JSON-RPC;

• CLI: semilla idempotente, listar, consultar, resumen y códigos de salida.

Licencia

MIT. Ver LICENSE.