Aplicación de Lista de Compras

Una aplicación simple de lista de compras construida con Next.js 15 (App Router). Cada producto pertenece a una persona, se puede marcar como comprado y se puede eliminar.

Este proyecto es intencionalmente pequeño — es un proyecto de aprendizaje/ejercicio para IMS Praxis 5.

Funcionalidades

• Agregar productos, marcarlos como comprados, eliminarlos

• Filtrar por persona

• Persistencia mediante un archivo JSON simple (no requiere servidor de base de datos)

• Tres formas de trabajar con los datos:

  • Server Actions – utilizadas directamente por el frontend (src/app/actions.ts)

  • API REST – disponible en /api/products, por ejemplo para clientes externos o curl

  • Servidor MCP – expone los mismos datos como herramientas MCP (por ejemplo para ChatGPT) llamando a la API REST

Related MCP server: LystBot

Stack Tecnológico

• Next.js 15 / React 19, App Router

• TypeScript

• Sin base de datos, sin ORM – persistencia mediante un archivo JSON (data/products.json)

• MCP TypeScript SDK a través de mcp-handler, usando el transporte Streamable HTTP

Primeros Pasos

npm install
npm run dev

Abre la aplicación en http://localhost:3000.

No se necesita configuración ni archivo .env para ejecutar la aplicación localmente. Consulta Variables de Entorno para la única configuración opcional utilizada por el servidor MCP.

Estructura del Proyecto

src/
  app/
    page.tsx            # Home page (Server Component), loads products server-side
    actions.ts           # Server Actions: addProductAction, togglePurchasedAction, deleteProductAction
    api/
      products/
        route.ts          # GET /api/products, POST /api/products
        [id]/route.ts      # GET/PATCH/DELETE /api/products/:id
      [transport]/
        route.ts          # MCP endpoint (Streamable HTTP), served at /api/mcp
  components/
    ProductForm.tsx        # Add-product form (uses a Server Action)
    ProductList.tsx        # List incl. toggle/delete (uses Server Actions)
  lib/
    productRepository.ts   # the only place that touches the filesystem (data/products.json)
    mcp/
      server.ts             # registers the MCP tools
      shoppingApiClient.ts   # MCP's only way to reach the data — calls the REST API, never the repository directly
  types/
    product.ts             # Product type

data/
  products.json            # data store (created automatically if missing)

Modelo de Datos

interface Product {
  id: string;
  name: string;
  person: string;
  purchased: boolean;
  createdAt: string; // ISO date
}

Persistencia

Todos los productos residen en data/products.json. Todo el acceso a archivos está encapsulado en src/lib/productRepository.ts — ni la interfaz de usuario ni las rutas de la API leen o escriben el archivo directamente. El repositorio expone:

getProducts()
getProductsByPerson(person)
getProductById(id)
addProduct(product)
updateProduct(id, changes)
deleteProduct(id)

Nota: Esta persistencia basada en archivos es intencionalmente solo una solución de prototipo/desarrollo. En Vercel (y otras plataformas serverless) el sistema de archivos local no es persistentemente confiable entre solicitudes o despliegues — las escrituras pueden perderse. Para uso en producción, productRepository.ts debe reemplazarse con una base de datos real y persistente (por ejemplo Turso). Dado que el resto de la aplicación (UI, Server Actions, rutas API) solo se comunica con los datos a través de las funciones exportadas del repositorio, ese cambio solo afecta a este archivo.

Frontend ↔ Backend

El frontend (page.tsx, ProductForm, ProductList) utiliza Next.js Server Actions (src/app/actions.ts) para crear, actualizar y eliminar productos. No hay ninguna llamada fetch en el cliente — las Server Actions llaman al repositorio directamente y luego activan una actualización de los datos renderizados en el servidor mediante revalidatePath("/").

La API REST en /api/products es independiente y puede usarse por separado (por ejemplo, por herramientas externas, scripts, o para pruebas) — lee y escribe la misma fuente de datos.

API REST

Leer productos

GET /api/products
GET /api/products?person=Rinaldo   # filter by person, case-insensitive
GET /api/products/:id

Agregar un producto

POST /api/products
Content-Type: application/json

{ "name": "Milk", "person": "Rinaldo" }

id, purchased (false) y createdAt se establecen automáticamente.

Actualizar un producto

PATCH /api/products/:id
Content-Type: application/json

{ "purchased": true }

No es necesario proporcionar todos los campos (name, person, purchased son cada uno opcionales y actualizables de forma independiente).

Eliminar un producto

DELETE /api/products/:id

Respuestas de error

{ "error": "Product not found" }

Ejemplos con curl

# Add a product
curl -X POST http://localhost:3000/api/products \
  -H "Authorization: Bearer $SHOPPING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Milk","person":"Rinaldo"}'

# List a person's products
curl "http://localhost:3000/api/products?person=Rinaldo" \
  -H "Authorization: Bearer $SHOPPING_API_KEY"

# Mark a product as purchased
curl -X PATCH http://localhost:3000/api/products/PRODUCT_ID \
  -H "Authorization: Bearer $SHOPPING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purchased":true}'

# Delete a product
curl -X DELETE http://localhost:3000/api/products/PRODUCT_ID \
  -H "Authorization: Bearer $SHOPPING_API_KEY"

Servidor MCP

Un servidor Model Context Protocol expone la lista de compras a clientes MCP (por ejemplo, ChatGPT). Se comunica solo con la API REST anterior — nunca directamente con productRepository.ts o data/products.json — por lo que se mantiene independiente del backend de persistencia que utilice la API.

MCP client → MCP server → REST API → productRepository → data/products.json

Endpoint: /api/mcp (transporte Streamable HTTP), implementado en src/app/api/[transport]/route.ts a través de mcp-handler.

Herramientas:

Requiere el mismo token bearer que la API REST (consulta Autenticación). Pruébalo localmente con el MCP Inspector:

npx @modelcontextprotocol/inspector --cli http://localhost:3000/api/mcp --method tools/list \
  --header "Authorization: Bearer $SHOPPING_API_KEY"

Variables de Entorno

Consulta .env.example.

Autenticación

La API REST y el endpoint MCP requieren un token bearer — un único secreto compartido configurado mediante SHOPPING_API_KEY. No hay inicio de sesión por usuario; esta es una verificación de token estático simple adecuada para un prototipo, no para OAuth completo.

curl http://localhost:3000/api/products \
  -H "Authorization: Bearer $SHOPPING_API_KEY"

Una solicitud con un token faltante o incorrecto recibe 401 No Autorizado. Si SHOPPING_API_KEY no está configurado en el servidor, las solicitudes son rechazadas con 500 (fallo cerrado, no abierto).

Las Server Actions (src/app/actions.ts) no se ven afectadas — llaman a productRepository directamente en el servidor y nunca pasan por la API REST, por lo que no necesitan un token.

Limitaciones Conocidas

• Sin autenticación/autorización ni en la API REST ni en el servidor MCP — cualquiera puede ver y editar todos los productos. Planificado como seguimiento.

• Las escrituras concurrentes se serializan dentro de un solo proceso (una cola simple en productRepository.ts), lo cual está bien para un prototipo pero no para despliegues multi-instancia en producción.

• Como se señaló anteriormente, la persistencia no es segura para despliegue en plataformas serverless como Vercel — una base de datos real (por ejemplo Turso) es el siguiente paso previsto.

Despliegue

La aplicación se puede desplegar como cualquier proyecto Next.js, por ejemplo en Vercel. Antes de usarla en producción, la capa de persistencia de datos (ver arriba) debe reemplazarse por una base de datos real.

Más sobre Next.js: Documentación de Next.js · Aprende Next.js