Ops Lense

Ops Lense ist ein remote gehosteter Model Context Protocol (MCP)-Server für Commerce-Operationen. Er hilft einem Operations-Spezialisten, feststeckende Bestellungen zu untersuchen, zu verstehen, was schiefgelaufen ist, und den nächsten sicheren Schritt zu unternehmen, ohne für jeden Vorfall einen Ingenieur zu benötigen.

Diese Aufgabe konzentriert sich bewusst auf einen Workflow in der Tiefe: Untersuchung und Behebung von feststeckenden Bestellungen über Bestellungen, Zahlungen, Inventar und Fulfillment hinweg.

Was es demonstriert

Ein Operator kann einem MCP-fähigen KI-Client Fragen stellen wie:

Warum steckt diese bezahlte Bestellung immer noch fest?

Die KI kann Ops Lense verwenden, um:

1. die Bestellung finden;

2. ihren Betriebszeitplan überprüfen;

3. den wahrscheinlichen Fehler aus den Backend-Daten diagnostizieren;

4. bestimmen, wie sicher die vorgeschlagene Aktion durchgeführt werden kann;

5. nach Bestätigung durch den Operator eine begrenzte Behebung in der Vorschau anzeigen und ausführen; oder

6. eine risikoreiche Aktion an eine manuelle Prüfwarteschlange senden, anstatt sie auszuführen.

Das MCP ist daher die Kernproduktschnittstelle, nicht eine zusätzliche Integration um eine separate Anwendung.

Sicherheitsmodell

Nicht jede Commerce-Operation sollte das gleiche Maß an KI-Autonomie haben. Ops Lense unterteilt Aktionen in drei Kategorien.

Bestätigungsablauf

resync_inventory_reservation ist eine geschützte Schreiboperation.

Erster Aufruf:

confirmed=false

Der Server validiert die Bestellung und gibt den vorgeschlagenen Effekt zurück, ohne die Datenbank zu ändern.

Nachdem der Operator die Aktion explizit genehmigt hat, kann der Client aufrufen:

confirmed=true

Der Server führt dann die begrenzte Mutation durch und zeichnet einen Audit-Eintrag auf.

Manueller Prüfablauf

Kritische Aktionen sind absichtlich nicht als direkte MCP-Mutationen verfügbar. request_manual_review erstellt stattdessen einen Audit-Eintrag vom Typ pending_review.

Der separate Prozess, in dem ein anderer Operator diese Anfragen überprüft, genehmigt und ausführt, liegt bewusst außerhalb des Aufgabenumfangs. Ausstehende Anfragen bleiben über list_manual_reviews sichtbar.

MCP-Werkzeuge

MCP-Ressource

Ops Lense stellt eine betriebliche Ressource bereit:

ops://action-policy

Sie beschreibt die drei Aktionskategorien und die Regeln, die ein MCP-Client bei der Auswahl oder Ausführung von Werkzeugen befolgen sollte.

Ich habe mich für eine Ressource und nicht für einen MCP-Prompt entschieden, da dies eine stabile Betriebsrichtlinie ist, die unabhängig davon verfügbar sein sollte, wie der Benutzer seine Anfrage formuliert. Ein dedizierter Prompt würde diesem bewusst engen Workflow nur wenig Mehrwert bringen.

Beispiel für einen durchgehenden Workflow

Ein repräsentativer Vorfall ist eine Bestellung, bei der die Zahlung erfolgreich erfasst wurde, der Inventarreservierungsschritt jedoch fehlt.

1. Der Operator fragt, warum eine Bestellung feststeckt.

2. Die KI verwendet search_orders, wenn sie die Bestellung lokalisieren muss.

3. Sie ruft get_order_timeline auf, um zu überprüfen, was passiert ist.

4. Sie ruft diagnose_order auf, um den Zahlungs- und Betriebszustand zu korrelieren.

5. Die Diagnose identifiziert INVENTORY_RESERVATION_MISSING und empfiehlt resync_inventory_reservation.

6. Die KI ruft das Werkzeug mit confirmed=false auf und zeigt dem Operator die vorgeschlagene Behebung an.

7. Der Operator genehmigt sie.

8. Die KI ruft das Werkzeug erneut mit confirmed=true auf.

9. Das MCP führt die Behebung durch und schreibt einen Audit-Datensatz.

10. Die KI ruft get_order_timeline erneut auf, um den resultierenden Zustand zu überprüfen.

Eine risikoreiche Anfrage folgt einem anderen Weg. Wenn ein Operator beispielsweise eine Rückerstattung anfordert, erstellt das MCP einen manuellen Prüfantrag, anstatt den Zahlungsstatus zu ändern. Der Antrag kann dann mit list_manual_reviews eingesehen werden.

Dies verleiht der Demo eine zusammenhängende Geschichte, die Untersuchung → Diagnose → menschliche Bestätigung → Mutation → Überprüfung → Eskalation abdeckt.

Architektur

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

Technologie:

• TypeScript

• Bun für lokale Entwicklung und Skripte

• Node.js 24 auf Heroku

• Model Context Protocol Server-Pakete

• Express HTTP-Transport

• Neon PostgreSQL

• Zod-Eingabevalidierung

Die synthetischen Daten modellieren die minimalen Backend-Systeme, die für den Workflow benötigt werden: Kunden, Bestellungen, Zahlungen, Inventar, Fulfillment, Betriebsereignisse, Untersuchungsverlauf und Aktionsauditdatensätze.

Lokal ausführen

Voraussetzungen

Sie benötigen:

• Bun

• eine PostgreSQL-Datenbank; Neon eignet sich gut für die gehostete Demo

1. Abhängigkeiten installieren

bun install

2. Umgebungsvariablen konfigurieren

Erstellen Sie eine .env-Datei im Projektstammverzeichnis:

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

3. Erstellen Sie die synthetische Datenbank

bun scripts/setup-db.ts

Dieser Befehl löscht und erstellt die Aufgabentabellen neu. Führen Sie ihn nicht gegen eine Datenbank aus, die Daten enthält, die Sie behalten möchten.

4. Seed-Demo-Daten

bun scripts/seed-db.ts

Alle gesäten Kunden-, Bestellungs-, Zahlungs-, Inventar- und Fulfillment-Datensätze sind synthetisch.

5. Erstellen und starten Sie den MCP-Server

bun run build
bun run start

bun run build kompiliert TypeScript in dist/. Der Startbefehl führt dann den kompilierten Server mit Node aus, entsprechend dem Heroku-Laufzeitpfad.

Der lokale MCP-Endpunkt ist:

http://localhost:3000/mcp

Auf Heroku bereitstellen

Das Repository enthält eine Procfile, die den Web-Dyno mit npm start startet. Heroku erstellt das TypeScript-Projekt und führt den kompilierten Node.js-Server aus.

1. Erstellen Sie die Heroku-App

heroku create YOUR_APP_NAME

2. Konfigurieren Sie die Datenbank

Setzen Sie die PostgreSQL-Verbindungszeichenfolge und ein starkes Bearer-Token, das zum Schutz des MCP-Endpunkts verwendet wird:

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

Heroku stellt PORT automatisch bereit, sodass Sie es nicht manuell konfigurieren müssen.

3. Bereitstellen

git push heroku HEAD:main

Während der Bereitstellung installiert Heroku die Node-Abhängigkeiten und führt das build-Skript aus. Der Web-Dyno startet dann:

node dist/index.js

Der gehostete MCP-Endpunkt wird sein:

https://YOUR_APP_NAME.herokuapp.com/mcp

Wenn Ihre Heroku-App eine benutzerdefinierte Domain verwendet, verwenden Sie diese Domain mit /mcp stattdessen.

4. Überprüfen Sie die Bereitstellung

heroku logs --tail -a YOUR_APP_NAME

Sie sollten sehen, wie der MCP-Server startet und an den zugewiesenen Port von Heroku bindet.

Die synthetische Datenbank kann vor der Bereitstellung von Ihrem lokalen Rechner aus mit derselben DATABASE_URL initialisiert werden, oder indem Sie die Setup- und Seed-Skripte als einmalige Heroku-Befehle ausführen, wenn Bun in dieser Umgebung verfügbar ist. Für den einfachsten Bereitstellungspfad initialisieren und seeden Sie Neon lokal, bevor Sie den Server bereitstellen.

Von einem KI-Client aus verbinden

Ops Lense verwendet einen entfernten HTTP-MCP-Endpunkt. Fügen Sie in einem MCP-Client, der entfernte/streamable HTTP-Server unterstützt, den Endpunkt und das Bearer-Token hinzu:

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

Ersetzen Sie bei einer bereitgestellten Instanz die lokale URL durch die gehostete MCP-URL und verwenden Sie dasselbe Token, das auf dem Server als MCP_AUTH_TOKEN konfiguriert ist.

Nach der Verbindung sollte der Client die Werkzeuge und die Ressource ops://action-policy automatisch erkennen.

Sie können dann natürlich beginnen, zum Beispiel:

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.

Bei bestätigungspflichtigen Operationen sollte die KI dem Operator die Vorschau präsentieren und die explizite Zustimmung einholen, bevor der zweite Werkzeugaufruf mit confirmed=true erfolgt.

Mit MCP Inspector verbinden

MCP Inspector ist nützlich, um den Server unabhängig von einem Chat-Client zu testen.

Bei laufendem lokalem Server:

npx @modelcontextprotocol/inspector

In Inspector verbinden Sie sich mit:

http://localhost:3000/mcp

Sie können dann die entdeckten Werkzeuge/Ressourcen überprüfen und den Workflow manuell aufrufen.

Überprüfung

Typüberprüfung des Projekts mit:

npm run typecheck

Führen Sie die fokussierte Vitest-Integrationssuite gegen die konfigurierte synthetische Datenbank aus:

npm test

Die Tests in tests/operations.test.ts erstellen isolierte temporäre Datensätze, führen die echten Werkzeugfunktionen gegen PostgreSQL aus und entfernen diese Datensätze anschließend. Sie überprüfen:

• erfasste Zahlung mit fehlender Reservierung erzeugt INVENTORY_RESERVATION_MISSING;

• terminale Bestellungen werden nicht als aktive Inventarfehler diagnostiziert;

• confirmed=false führt keine Mutation durch;

• confirmed=true führt die begrenzte Inventarbereinigung durch und zeichnet einen Audit-Eintrag auf;

• das Wiederholen einer bereits abgeschlossenen Resynchronisation ist ein sicherer No-Op;

• eine Rückerstattungsanfrage wird zur Überprüfung in die Warteschlange gestellt, ohne den Zahlungsstatus zu ändern;

• doppelte ausstehende Prüfanfragen werden unterdrückt.

Die Suite enthält derzeit 8 Integrationstests. Ein erfolgreicher Lauf meldet 8 passed.

Diese Tests konzentrieren sich bewusst auf den Workflow und die Sicherheitsgrenzen und nicht auf breite Abdeckungsmetriken.

Wichtige Produktentscheidungen

Halten Sie den Workflow schmal

Die Aufgabe versucht nicht, ein vollständiges Commerce-Backend zu erstellen. Feststeckende Bestellungsvorgänge wurden ausgewählt, da sie einen kompakten Workflow bieten, der mehrere Systeme, Diagnose, Behebung, Sicherheit und Überprüfung umfasst.

Geben Sie der KI nützliche Autonomie, keinen uneingeschränkten Schreibzugriff

Jede Operation schreibgeschützt zu machen, würde den Operator von einem anderen System abhängig machen, um selbst einfache Vorfälle zu lösen. Jede Mutation zuzulassen, würde unnötiges operationelles Risiko schaffen.

Das Drei-Ebenen-Modell bietet einen Mittelweg: Untersuchung ist automatisch, begrenzte Behebung erfordert Bestätigung durch den Operator, und folgenreiche Aktionen bleiben hinter manueller Prüfung zurück.

Halten Sie kritische Aktionen außerhalb der MCP-Ausführung

Rückerstattungen und ähnliche Operationen könnten technisch als Datenbankmutationen in diesem synthetischen Projekt dargestellt werden, aber das würde das falsche Produktionsverhalten demonstrieren. Das MCP erstellt stattdessen eine Prüfanfrage und macht die Grenze explizit.

Halten Sie die MCP-Oberfläche klein

Jedes exponierte Werkzeug hat eine klare Rolle im gewählten Workflow. Das Ziel ist, dass ein KI-Client Werkzeuge zuverlässig auswählt, nicht die Anzahl der verfügbaren Werkzeuge zu maximieren.

Umfang und Annahmen

Enthalten:

• synthetische Commerce-Daten

• Bestellungsuntersuchung

• deterministische Diagnose der unterstützten Bedingung für feststeckende Bestellungen

• geschützte Inventarbereinigung

• Audit-Protokollierung

• manuelle Prüfwarteschlange

• remote zugängliche MCP-Schnittstelle

Absichtlich ausgeschlossen:

• Frontend/Admin-Dashboard

• echte Kundendaten

• Produktionszahlungs- oder Lageranmeldedaten

• Benutzerkonten, Sitzungen, OAuth und rollenbasierte Zugriffskontrolle

• direkte Ausführung von Rückerstattungen

• Benutzeroberfläche für manuelle Prüfungsgenehmigung/-ausführung

• vollständiges Commerce-Backend

• umfassende Retouren-, Betrugs-, Katalog- und Kundensupport-Workflows

Der gehostete Assignment-Server verwendet ein einzelnes Bearer-Token, um den MCP nicht öffentlich zu exponieren. Für ein Produktionssystem müssten identitätsbewusste Authentifizierung, Autorisierung/RBAC, geheime Rotation, stärkere Nebenläufigkeitskontrollen, anbieterspezifische Integrationen, Beobachtbarkeit und ein vollständiger Überprüfungsworkflow hinzugefügt werden.

Repository-Struktur

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

KI-Arbeitsprotokoll

Dieser Abschnitt sollte die tatsächliche KI-Nutzung aus dem Assignment vor der Einreichung enthalten:

• KI-Codierungstools und genaue verwendete Modelle

• warum jedes Modell für seine Aufgabe ausgewählt wurde

• wie die Arbeit geplant und zerlegt wurde

• Verantwortlichkeiten, die von KI übernommen wurden, im Vergleich zum Entwickler

• wichtige Prompts/Kontext, die der KI zur Verfügung gestellt wurden

• mindestens ein KI-Vorschlag, der abgelehnt oder wesentlich geändert wurde

• wie KI-generierte Arbeit überprüft und verifiziert wurde

• verbleibende Risiken oder unfertige Arbeit

Eine Produktentscheidung, die sich während der Entwicklung änderte, war die Behandlung von folgenschweren Operationen. Anstatt Rückerstattungen und ähnliche kritische Aktionen als ausführbare MCP-Tools zu exponieren, wurden sie hinter eine manuelle Überprüfungswarteschlange verschoben. Dies bewahrt nützliche KI-Autonomie, während finanziell oder operativ folgenschwere Entscheidungen außerhalb der direkten Modellausführung bleiben.

Einreichung

Die endgültige Einreichung sollte Folgendes enthalten:

• gehostete MCP-URL

• Quell-Repository-URL

• diese README

• Verifizierung/Tests für das wichtige Workflow-Verhalten

• abgeschlossenes KI-Arbeitsprotokoll

• 4–5-minütige asynchrone Demo

Die Demo sollte den tatsächlichen Produktworkflow über Code-Durchläufe priorisieren: eine Bestellung untersuchen, sie diagnostizieren, eine sichere Abhilfe in der Vorschau anzeigen, sie bestätigen, das Ergebnis verifizieren und dann zeigen, wie eine kritische Aktion zur manuellen Überprüfung weitergeleitet wird.