Ops Lense

Ops Lense es un servidor del Protocolo de Contexto de Modelo (MCP) para operaciones de comercio alojado de forma remota. Ayuda a un especialista en operaciones a investigar pedidos atascados, entender qué salió mal y tomar la siguiente acción segura sin necesidad de un ingeniero para cada incidente.

Esta tarea se centra intencionadamente en un flujo de trabajo en profundidad: la investigación y corrección de pedidos atascados en pedidos, pagos, inventario y cumplimiento.

Qué demuestra

Un operador puede preguntar a un cliente de IA habilitado para MCP cosas como:

¿Por qué este pedido pagado sigue atascado?

La IA puede usar Ops Lense para:

1. encontrar el pedido;

2. inspeccionar su línea de tiempo operativa;

3. diagnosticar la probable falla a partir de los datos del backend;

4. determinar qué tan seguro se puede realizar la acción propuesta;

5. previsualizar y ejecutar una corrección acotada después de la confirmación del operador; o

6. enviar una acción de alto riesgo a una cola de revisión manual en lugar de ejecutarla.

Por lo tanto, el MCP es la interfaz principal del producto, no una integración adicional alrededor de una aplicación separada.

Modelo de seguridad

No todas las operaciones de comercio deberían tener el mismo nivel de autonomía de IA. Ops Lense separa las acciones en tres categorías.

Flujo de confirmación

resync_inventory_reservation es una operación de escritura protegida.

Primera llamada:

confirmed=false

El servidor valida el pedido y devuelve el efecto propuesto sin cambiar la base de datos.

Después de que el operador aprueba explícitamente la acción, el cliente puede llamar:

confirmed=true

El servidor entonces realiza la mutación acotada y registra una entrada de auditoría.

Flujo de revisión manual

Las acciones críticas no están disponibles intencionadamente como mutaciones directas del MCP. request_manual_review crea una entrada de auditoría pending_review.

El proceso separado donde otro operador revisa, aprueba y ejecuta esas solicitudes está deliberadamente fuera del alcance de esta tarea. Las solicitudes pendientes permanecen visibles a través de list_manual_reviews.

Herramientas MCP

Recurso MCP

Ops Lense expone un recurso operativo:

ops://action-policy

Describe las tres categorías de acción y las reglas que un cliente MCP debe seguir al elegir o ejecutar herramientas.

Elegí un recurso en lugar de un prompt MCP porque esta es una política operativa estable que debería estar disponible independientemente de cómo formule el usuario su solicitud. Un prompt dedicado añadiría poco valor a este flujo de trabajo deliberadamente limitado.

Ejemplo de flujo de trabajo completo

Un incidente representativo es un pedido donde el pago se capturó con éxito pero falta el paso de reserva de inventario.

1. El operador pregunta por qué un pedido está atascado.

2. La IA usa search_orders si necesita localizar el pedido.

3. Llama a get_order_timeline para inspeccionar lo que ha ocurrido.

4. Llama a diagnose_order para correlacionar el pago y el estado operativo.

5. El diagnóstico identifica INVENTORY_RESERVATION_MISSING y recomienda resync_inventory_reservation.

6. La IA llama a la herramienta con confirmed=false y muestra la corrección propuesta al operador.

7. El operador la aprueba.

8. La IA llama a la herramienta de nuevo con confirmed=true.

9. El MCP realiza la corrección y escribe un registro de auditoría.

10. La IA llama a get_order_timeline de nuevo para verificar el estado resultante.

Una solicitud de alto riesgo sigue un camino diferente. Por ejemplo, si un operador solicita un reembolso, el MCP crea una solicitud de revisión manual en lugar de modificar el estado del pago. La solicitud puede entonces inspeccionarse con list_manual_reviews.

Esto le da a la demo una historia coherente que cubre investigación → diagnóstico → confirmación humana → mutación → verificación → escalamiento.

Arquitectura

MCP-enabled AI client
        |
        | Streamable HTTP
        v
   Ops Lense MCP
        |
        +-- Investigation tools
        +-- Diagnostic logic
        +-- Safety / action policy
        +-- Guarded actions
        |
        v
   Neon PostgreSQL
   synthetic commerce data

Tecnología:

• TypeScript

• Bun para desarrollo local y scripts

• Node.js 24 en Heroku

• Paquetes del servidor del Protocolo de Contexto de Modelo

• Transporte HTTP Express

• Neon PostgreSQL

• Validación de entrada Zod

Los datos sintéticos modelan los sistemas backend mínimos necesarios para el flujo de trabajo: clientes, pedidos, pagos, inventario, cumplimiento, eventos operativos, historial de investigación y registros de auditoría de acciones.

Ejecutar localmente

Prerrequisitos

Necesitas:

• Bun

• una base de datos PostgreSQL; Neon funciona bien para la demo alojada

1. Instalar dependencias

bun install

2. Configurar variables de entorno

Crea un archivo .env en la raíz del proyecto:

DATABASE_URL=postgresql://YOUR_DATABASE_URL
MCP_AUTH_TOKEN=YOUR_STRONG_RANDOM_TOKEN
PORT=3000

3. Crear la base de datos sintética

bun scripts/setup-db.ts

Este comando elimina y recrea las tablas de la tarea. No lo ejecutes contra una base de datos que contenga datos que necesites conservar.

4. Sembrar datos de demostración

bun scripts/seed-db.ts

Todos los registros sembrados de clientes, pedidos, pagos, inventario y cumplimiento son sintéticos.

5. Compilar e iniciar el servidor MCP

bun run build
bun run start

bun run build compila TypeScript en dist/. El comando de inicio ejecuta entonces el servidor compilado con Node, coincidiendo con la ruta de tiempo de ejecución de Heroku.

El endpoint local del MCP es:

http://localhost:3000/mcp

Desplegar en Heroku

El repositorio incluye un Procfile que inicia el dyno web con npm start. Heroku compila el proyecto TypeScript y ejecuta el servidor Node.js compilado.

1. Crear la aplicación en Heroku

heroku create YOUR_APP_NAME

2. Configurar la base de datos

Establece la cadena de conexión PostgreSQL y un token bearer fuerte utilizado para proteger el endpoint del MCP:

heroku config:set DATABASE_URL="YOUR_DATABASE_URL" MCP_AUTH_TOKEN="YOUR_STRONG_RANDOM_TOKEN" -a YOUR_APP_NAME

Heroku proporciona PORT automáticamente, por lo que no es necesario configurarlo manualmente.

3. Desplegar

git push heroku HEAD:main

Durante el despliegue, Heroku instala las dependencias de Node y ejecuta el script build. Entonces el dyno web se inicia:

node dist/index.js

El endpoint del MCP alojado será:

https://YOUR_APP_NAME.herokuapp.com/mcp

Si tu aplicación de Heroku usa un dominio personalizado, usa ese dominio con /mcp en su lugar.

4. Verificar el despliegue

heroku logs --tail -a YOUR_APP_NAME

Deberías ver que el servidor MCP se inicia y se vincula al puerto asignado por Heroku.

La base de datos sintética se puede inicializar antes del despliegue desde tu máquina local usando la misma DATABASE_URL, o ejecutando los scripts de configuración y siembra como comandos únicos de Heroku si Bun está disponible en ese entorno. Para la ruta de despliegue más simple, inicializa y siembra Neon localmente antes de desplegar el servidor.

Conectar desde un cliente de IA

Ops Lense usa un endpoint HTTP MCP remoto. En un cliente MCP que soporte servidores HTTP remotos/transmisibles, añade el endpoint y el token bearer:

{
  "serverUrl": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_STRONG_RANDOM_TOKEN"
  }
}

Para una instancia desplegada, reemplaza la URL local con la URL MCP alojada y usa el mismo token configurado como MCP_AUTH_TOKEN en el servidor.

Después de conectarse, el cliente debería descubrir las herramientas y el recurso ops://action-policy automáticamente.

Entonces puedes empezar de forma natural, por ejemplo:

Show me recent orders that may need attention.

Why is this order stuck? Investigate it and tell me what we can safely do.

Show me all actions currently waiting for manual review.

Para operaciones que requieren confirmación, la IA debería presentar la vista previa al operador y obtener aprobación explícita antes de hacer la segunda llamada a la herramienta con confirmed=true.

Conectar con MCP Inspector

MCP Inspector es útil para probar el servidor independientemente de un cliente de chat.

Con el servidor local en ejecución:

npx @modelcontextprotocol/inspector

En Inspector, conéctate a:

http://localhost:3000/mcp

Entonces puedes inspeccionar las herramientas/recursos descubiertos e invocar el flujo de trabajo manualmente.

Verificación

Verifica los tipos del proyecto con:

npm run typecheck

Ejecuta la suite de integración enfocada de Vitest contra la base de datos sintética configurada:

npm test

Las pruebas en tests/operations.test.ts crean registros temporales aislados, ejercitan las funciones reales de las herramientas contra PostgreSQL y eliminan esos registros después. Verifican:

• un pago capturado con una reserva faltante produce INVENTORY_RESERVATION_MISSING;

• los pedidos terminales no se diagnostican como fallas de inventario activas;

• confirmed=false no realiza ninguna mutación;

• confirmed=true realiza la corrección de inventario acotada y registra una entrada de auditoría;

• repetir una resincronización ya completada es un no-op seguro;

• una solicitud de reembolso se pone en cola para revisión sin cambiar el estado del pago;

• las solicitudes de revisión pendientes duplicadas se suprimen.

La suite contiene actualmente 8 pruebas de integración. Una ejecución exitosa informa 8 passed.

Estas pruebas están intencionadamente centradas en el flujo de trabajo y los límites de seguridad, más que en métricas de cobertura amplias.

Decisiones clave del producto

Mantener el flujo de trabajo limitado

La tarea no intenta construir un backend de comercio completo. Las operaciones de pedidos atascados fueron seleccionadas porque proporcionan un flujo de trabajo compacto que involucra múltiples sistemas, diagnóstico, corrección, seguridad y verificación.

Dar a la IA autonomía útil, no acceso de escritura sin restricciones

Hacer que cada operación sea de solo lectura dejaría al operador dependiente de otro sistema para resolver incluso incidentes simples. Permitir cada mutación crearía un riesgo operativo innecesario.

El modelo de tres niveles proporciona un punto intermedio: la investigación es automática, la corrección acotada requiere confirmación del operador y las acciones consecuentes permanecen detrás de una revisión manual.

Mantener las acciones críticas fuera de la ejecución del MCP

Los reembolsos y operaciones similares podrían representarse técnicamente como mutaciones de base de datos en este proyecto sintético, pero hacerlo demostraría el comportamiento de producción incorrecto. El MCP en su lugar crea una solicitud de revisión y hace explícito el límite.

Mantener la superficie del MCP pequeña

Cada herramienta expuesta tiene un rol claro en el flujo de trabajo elegido. El objetivo es que un cliente de IA seleccione herramientas de manera confiable, no maximizar el número de herramientas disponibles.

Alcance y suposiciones

Incluido:

• datos de comercio sintéticos

• investigación de pedidos

• diagnóstico determinista de la condición de pedido atascado compatible

• corrección de inventario protegida

• registro de auditoría

• cola de revisión manual

• interfaz MCP accesible de forma remota

Excluido intencionadamente:

• frontend/panel de administración

• datos reales de clientes

• credenciales de pago o almacén de producción

• cuentas de usuario, sesiones, OAuth y control de acceso basado en roles

• ejecución directa de reembolsos

• interfaz de aprobación/ejecución de revisión manual

• backend de comercio completo

• flujos de trabajo amplios de devoluciones, fraude, catálogo y soporte al cliente

El servidor de asignaciones alojado utiliza un único token de portador para evitar exponer el MCP públicamente. Para un sistema de producción, sería necesario añadir autenticación consciente de la identidad, autorización/RBAC, rotación de secretos, controles de concurrencia más sólidos, integraciones específicas del proveedor, observabilidad y un flujo de trabajo de revisión completo.

Estructura del repositorio

src/
  index.ts
  db.ts
  resources.ts
  tools/
    diagnose-order.ts
    get-stats.ts
    get-timeline.ts
    list-manual-reviews.ts
    request-manual-review.ts
    resync-inventory.ts
    search-orders.ts
scripts/
  setup-db.ts
  seed-db.ts
tests/
  operations.test.ts
vitest.config.ts

Registro de trabajo de IA

Esta sección debe contener el uso real de la IA de la tarea antes de la entrega:

• Herramientas de codificación de IA y modelos exactos utilizados

• por qué se eligió cada modelo para su tarea

• cómo se planificó y descompuso el trabajo

• responsabilidades manejadas por la IA frente al desarrollador

• prompts/contexto importantes proporcionados a la IA

• al menos una sugerencia de IA que fue rechazada o modificada sustancialmente

• cómo se revisó y verificó el trabajo generado por IA

• riesgos restantes o trabajo pendiente

Una decisión de producto que cambió durante el desarrollo fue el tratamiento de las operaciones consecuenciales. En lugar de exponer reembolsos y acciones críticas similares como herramientas MCP ejecutables, se movieron detrás de una cola de revisión manual. Esto preserva una autonomía útil de la IA mientras mantiene las decisiones financiera o operativamente consecuenciales fuera de la ejecución directa del modelo.

Entrega

La entrega final debe incluir:

• URL del MCP alojado

• URL del repositorio fuente

• este README

• verificación/pruebas para el comportamiento importante del flujo de trabajo

• registro de trabajo de IA completado

• demostración asíncrona de 4 a 5 minutos

La demostración debe priorizar el flujo de trabajo real del producto sobre las explicaciones de código: investigar un pedido, diagnosticarlo, previsualizar una remediación segura, confirmarla, verificar el resultado, luego mostrar cómo una acción crítica se dirige a revisión manual.