Multi-MCP Enterprise Operations Copilot

Ein Copilot für Anlagenbetreiber. Er beantwortet Fragen in natürlicher Sprache, indem er eine Alarm-Management-API über speziell entwickelte MCP-Server aufruft, relevante Passagen aus einem Dokumentenkorpus für Betriebsanweisungen abruft und beides zu einer einzigen, belegten Antwort zusammenführt, die Zitate und eine sichtbare Ausführungsablaufverfolgung enthält.

git clone <repository-url> && cd senior-copilot-mcp-rag-assignment
cp .env.example .env
docker compose up --build

Öffnen Sie dann http://localhost:5173 und stellen Sie die Akzeptanzfrage. Es ist kein API-Schlüssel erforderlich – der Stack verwendet standardmäßig einen deterministischen Anbieter, der denselben Workflow ohne LLM ausführt. Setzen Sie LLM_PROVIDER=anthropic und ANTHROPIC_API_KEY für generierten Prosa.

1 · Ausgewählter Anwendungsfall

Multi-MCP Enterprise Operations Copilot. Der Copilot entdeckt und koordiniert Werkzeuge über zwei MCP-Server hinweg, anstatt Integrationen fest zu codieren, und kombiniert diese strukturierten Daten mit unstrukturierten Dokumentennachweisen in einem Workflow.

Das obligatorische Akzeptanzszenario:

Untersuchen Sie wiederkehrende Alarme mit hohem Schweregrad für die Speisewasserpumpe 101 der letzten 90 Tage, identifizieren Sie wahrscheinliche beitragende Faktoren, rufen Sie die relevante Betriebsanweisung ab und geben Sie empfohlene Maßnahmen mit Quellennachweisen an.

Dieses Szenario wird als automatisierter Test ausgeführt (tests/e2e/test_acceptance_scenario.py), der über die echte HTTP-Oberfläche bestätigt, dass fünf Schritte ausgeführt werden, dass Schritt 2 die von Schritt 1 erzeugte Asset-ID erhalten hat, dass der Abruf durch den von Schritt 1 aufgelösten Asset-Namen eingegrenzt wurde und dass die Antwort sowohl eine [tool: …]- als auch eine [source: …]-Markierung enthält.

Ein Hinweis zum Quellsystem

Die im Kurzbericht beschriebene Alarm-Management-API existiert nicht als laufender Dienst – die mitgelieferten Postman-Collections sind ihre Spezifikation. Daher wird sie auch hier erstellt, als services/alarm-simulator/: 15 Endpunkte, Bearer-Auth, Trace-Header, ein Fehler-Envelope und deterministische, gesäte Daten, die so konstruiert sind, dass jede Verkettungsbehauptung in den mitgelieferten Collections nicht-leere Ergebnisse liefert. make contract führt alle drei Collections dagegen aus; CI tut dasselbe bei jedem Push.

2 · Hauptfunktionen

• Chat in natürlicher Sprache über Live-Alarmdaten und Betriebsdokumente

• Laufzeit-Werkzeugerkennung über zwei MCP-Server – keine fest codierte Werkzeugliste

• Mehrstufige Werkzeugverkettung, bei der die Ausgabe eines Werkzeugs zur Eingabe des nächsten Werkzeugs wird

• Hybrider Dokumentenabruf (BM25 + dichte Vektoren, fusioniert durch reziproken Rang) mit Inline-Zitaten

• Eine Antwort, die strukturierte Werkzeugergebnisse und unstrukturierte Dokumentennachweise kombiniert

• Vollständige Ausführungsablaufverfolgung: welcher Server, welches Werkzeug, welche Argumente, wie lange, welches Ergebnis

• Explizite menschliche Bestätigung vor jedem Schreibvorgang, durchgesetzt im Werkzeugvertrag

• Graceful Degradation bei Werkzeugfehler, Zeitüberschreitung, ungültigem Schema, leerem Abruf, Modellverweigerung oder fehlendem API-Schlüssel

3 · Technologie-Stack

4 · Architekturübersicht

Fünf Dienste. Die GUI kommuniziert mit einem FastAPI-Orchestrator über REST und SSE. Der Orchestrator plant eine Abfolge von Schritten gegen ein Werkzeugregister, das er zur Laufzeit von zwei MCP-Servern entdeckt hat, löst die Argumente jedes Schritts auf (einschließlich Werten, die von früheren Schritten erzeugt wurden), führt den Dokumentenabruf als einen dieser Schritte durch und setzt eine zitierte Antwort zusammen.

Browser ──HTTP/SSE──▶ backend ──MCP──▶ mcp-alarm-management ──HTTPS+bearer──▶ alarm-simulator
                         │      └────▶ mcp-github-issues    ──────────────▶ GitHub (mocked)
                         └─embedded──▶ Chroma index over rag/documents

Nur die MCP-Server enthalten Anmeldeinformationen für die dahinterliegenden Systeme. Der Copilot ruft die Alarm-Management-API niemals direkt auf, daher hat das Sprachmodell keinen Codepfad zum Bearer-Token – es kann ihn weder lesen, anfordern noch durch Prompt-Injection preisgeben.

• Anfragefluss Ende-zu-Ende: docs/architecture.md

• Komponenten, ADRs, NFRs, Risiken, Rückverfolgbarkeit: docs/hld.md

• Schemata, Signaturen, Algorithmen, Zustandsautomaten: docs/lld.md

5 · MCP-Server und Werkzeuge

Zwei kandidatengebaute Server. Vollständige Verträge – einschließlich Eingabe-/Ausgabeschemata, Auth-Verhalten, Fehlerverhalten, Zeitüberschreitungen und echter Beispielanfragen und -antworten – befinden sich in docs/mcp-tool-catalog.md, das aus einem Live-list_tools()-Aufruf generiert und in CI eingecheckt wird, sodass es nicht vom Code abweichen kann.

alarm-management – 14 Werkzeuge

github-issues – 3 Werkzeuge

Eigenständig ausführen

python -m alarm_mcp                      # stdio, for a local MCP client
python -m alarm_mcp --transport http     # streamable HTTP, as in compose
python scripts/mcp_smoke.py              # chain two tools, no GUI and no LLM

6 · RAG-Korpus und -Aufnahme

10 Markdown-Dokumente (Betriebsanweisungen, Fehlerbehebungsleitfäden, Standards, eine Sicherheitsanweisung, ein Herstellerrundschreiben) → 49 überschriftenausgerichtete Blöcke → eingebetteter Chroma-Index.

python -m rag.ingestion.cli --docs ./rag/documents --reset

Der Abruf fusioniert BM25 mit dichten Vektoren, filtert nach dem Asset, das ein früherer Werkzeugaufruf aufgelöst hat, und meldet low_confidence, anstatt eine schwache Übereinstimmung zu beschönigen. Ein Korpusdokument enthält eine Live-Prompt-Injection-Nutzlast, sodass die Vertrauensgrenze getestet und nicht nur behauptet wird.

Vollständiges Design – Blockbildung, Metadaten, Fusion, Zitaterstellung, Konfidenz, Injektionsabwehr, Aktualisierung: docs/rag-design.md.

7 · Konfiguration

Jeder Wert ist eine Umgebungsvariable. .env.example dokumentiert jeden Schlüssel mit einem sicheren Platzhalter; es wird kein Geheimnis committet und keines wird benötigt, um die Demo auszuführen.

Vollständige Referenz mit Typen, Standardwerten und verbrauchendem Dienst: docs/lld.md §9.

8 · Erstellen und Ausführen

make ist kanonisch und wird von CI verwendet. Unter Windows ohne make stellt tasks.ps1 dieselben Zielnamen bereit.

Ports: GUI 5173, Backend 8080, Simulator 8000 (freigegeben, damit die Postman-Collections dagegen ausgeführt werden können), MCP-Server 9000 / 9001 (intern).

Wenn einer davon bereits belegt ist, überschreiben Sie die Host-Seite in .env – die Container-Ports ändern sich nie. Setzen Sie VITE_API_BASE_URL so, dass es mit dem Backend-Port übereinstimmt, da Vite ihn zur Build-Zeit in die GUI einbettet:

BACKEND_HOST_PORT=8090 VITE_API_BASE_URL=http://localhost:8090 docker compose up --build

Ohne Docker: make install, dann führen Sie die vier Python-Dienste in separaten Terminals aus – uvicorn alarm_simulator.main:app --port 8000, python -m alarm_mcp --transport http, python -m github_mcp --transport http, make ingest, uvicorn copilot_backend.api.app:app --port 8080 – und npm run dev in apps/frontend.

9 · Tests

make contract erfordert newman (npm install -g newman) und einen laufenden Simulator.

269 Tests, alle bestanden, 89 % Codeabdeckung — Aufschlüsselung in docs/coverage.md. Was sie abdecken:

Das LLM wird überall simuliert, einschließlich Ende-zu-Ende, daher ist die Testsuite schnell, kostenlos und wiederholbar. Siehe docs/known-limitations.md für die Bedeutung.

10 · Beispielinteraktionen

Wiederkehrende Alarme (das Akzeptanzszenario). Fünf Schritte: Anlage auflösen → ihre Alarme mit hoher Schwere zusammenfassen → gleichzeitig auftretende Paare korrelieren → Rationalisierungskandidaten finden → das Verfahren abrufen, gefiltert nach der gerade aufgelösten Anlage. Die Antwort berichtet, dass Niedriger Austrittsdruck gefolgt von hohem Saugkorb-Druckabfall 31 Mal auftritt (Lift 2,29, mittlere Verzögerung 393s) [tool: alarm-management/get_alarm_correlation] und kombiniert es mit den Isolations- und Inspektionsschritten aus [source: OP-BFP-101#…].

Effizienz der Bedienerantwort. generate_calculation → execute_calculation (verkettet über calculation_id) → Trend der Bestätigungsverzögerung → der anwendbare Standard aus STD-OPRESP.

Eskalation. Aktive Alarme → Prioritätsbewertung für den wichtigsten → empfohlene Aktionen mit Kontext zu verwandten Alarmen → der passende Abschnitt der Alarmphilosophie.

Ein Issue melden. Alarmzusammenfassung → Duplikatprüfung → draft_issue. create_issue stoppt den Durchlauf mit confirmation.required; die GUI zeigt die genauen Argumente und fährt nur nach Genehmigung fort. Der MCP-Server lehnt unabhängig vom UI ab.

Eine Frage ohne unterstützendes Dokument. Die Abfrage meldet low_confidence; die Antwort sagt klar, dass kein relevantes Verfahren gefunden wurde, anstatt allgemeines Wissen zu ersetzen.

11 · Repository-Layout

apps/backend/          FastAPI orchestrator, MCP client, LLM providers
apps/frontend/         React + TypeScript GUI
mcp-servers/           alarm-management (14 tools), github-issues (3 tools)
services/              alarm-simulator — the candidate-built source system
connectors/alarm_api/  Reusable HTTP client, deliberately separate from the MCP server
packages/schemas/      Shared Pydantic tool contracts
rag/                   documents, ingestion, retrieval, tests
tests/                 unit, integration, e2e
docs/                  architecture, HLD, LLD, tool catalog, RAG design, decisions, limits
postman/               The supplied collections — the Alarm API specification

Zwei dokumentierte Abweichungen von der Struktur in den Einreichungsrichtlinien §3:

• services/alarm-simulator/ — die Aufgabenstellung fordert separat ein vom Kandidaten erstelltes Backend, das nicht in den vorgegebenen Ordnern enthalten ist. Den Simulator (das zu integrierende System) getrennt von connectors/ (dem Client, der darauf zugreift) zu halten, ist eine sauberere Trennung als beide zusammenzulegen.

• docs/hld.md und docs/lld.md — wurden neben der erforderlichen docs/architecture.md hinzugefügt, die der Einstiegspunkt bleibt.

Die Richtlinien erlauben gleichwertige Strukturen, wenn sie klar dokumentiert sind. Da die vorgeschriebenen Verzeichnisnamen mit Bindestrichen versehen und daher keine gültigen Python-Paketnamen sind, enthält jedes ein korrekt benanntes Paket (mcp-servers/alarm-management/alarm_mcp/), das in pyproject.toml einem Import auf oberster Ebene zugeordnet ist.

12 · Annahmen

1. Die Alarm Management API existiert nicht, daher werden die Postman-Sammlungen als ihre Spezifikation behandelt und der Simulator wird so gebaut, dass sie genau erfüllt werden. Wo die Sammlungen schwiegen (z. B. die Filter, die nur in der Verkettungssammlung erscheinen), gelten die Behauptungen der Sammlung als autoritativ.

2. Alarm-IDs, Anlagen-IDs und Zeitstempel sind reproduzierbar. Der Seed ist festgelegt, sodass eine Demo, ein Test und ein Postman-Durchlauf dieselben Daten sehen.

3. Korrelation bedeutet gleichzeitiges Auftreten innerhalb eines Verzögerungsfensters auf derselben Anlage. Statistische Signifikanztests sind für synthetische Daten nicht vorgesehen.

4. Ein Mandant, ein Standort. Es wird kein Mandantenkennung durch Abfrage oder Tool-Autorisierung geleitet.

5. Der Sprung von der GUI zum Backend ist nicht authentifiziert, was für eine lokale Demo akzeptabel ist und in den Einschränkungen erwähnt wird.

6. docker compose up ist der unterstützte Pfad. Der manuelle Pfad ist in §8 dokumentiert, aber die Compose-Datei wird von CI verwendet.

13 · Bekannte Einschränkungen und zukünftige Verbesserungen

Ehrliche Bereichsgrenzen, jeweils mit dem, was mit mehr Zeit anders gemacht würde: docs/known-limitations.md. Was als Nächstes kommt, in der Reihenfolge, in der ich es tun würde: docs/future-improvements.md.

14 · Demo

Screenshots

Aufgenommen aus dem laufenden Stack mit make screenshots, sodass sie neu generiert werden können, anstatt zu veralten: docs/screenshots/.

Ebenfalls aufgenommen: der leere Zustand und die Antwort mit Zitations-Chips.

Video

Link: wird noch hinzugefügt — siehe docs/demo.md für das aufgezeichnete Walkthrough-Skript.

Es deckt das Akzeptanzszenario von Anfang bis Ende ab, die Tool-Erkennung mit Schema-Inspektion, die Ausführungszeitachse, Zitations-Chips, die zu Beweisen führen, die Schreibbestätigungssperre und dann den Fehlerpfad — der Simulator wird mitten in der Sitzung gestoppt, um Wiederholungen, verschlechterte Antworten und ehrliche Lücken zu zeigen.

Lizenz

MIT — siehe LICENSE.