TowerWatch Ops Agent

Eine Agent-Schicht über TowerWatch — das Netzwerkqualitäts-Monitoring-Projekt — gebaut, um die drei Fähigkeiten zu demonstrieren, die eine Enterprise-Agent-Engineering-Schleife benötigt: Evaluations-Suites, kosten-/latenzbewusste Modellwahl und Tool-Retrieval. Ein Repository, eine kohärente Geschichte:

„Ich habe mein öffentliches Monitoring-Projekt genommen und die Agent-Schicht gebaut, die ein Unternehmen darum herum benötigen würde: einen instrumentierten MCP-Server mit definierten SLIs, einen Evaluations-Harness in CI, der gesäte Regressionen erkennt, einen kostenbewussten Modell-Router und semantisches Tool-Retrieval mit gemessener Auswahlpräzision.“

Auf einen Blick

• Runtime: Python 3 + FastMCP, verwaltet mit uv.

• Domäne: TowerWatchs Netzwerk-Monitoring-Daten, bereitgestellt als Agent-Tools.

• Transport: stdio zuerst; zustandsloses streambares HTTP als Dehnungsziel.

• Observability: OpenTelemetry ab dem ersten Tool-Aufruf, in einen Prometheus/Grafana-Stack.

• Tool-Oberfläche: sieben Tools — query_metrics, analyze_window, compare, query_log_events, get_monitor_status, get_runbook, run_speedtest. Verträge in docs/design/.

• Status: 🟡 Phase 1 läuft — der Server läuft und eines von sieben Tools ist gebaut; noch kein Phase-1-Abnahmekriterium erfüllt. Siehe Status.

Warum dieses Projekt

Es füllt die Lücke zwischen „Ich habe über Agent-Evaluierung und Routing gelesen“ und „Ich habe es gebaut und gemessen.“ Jedes Artefakt — Evaluierungstabellen, Benchmark-Zahlen, Präzision@k-Diagramme — ist eine persönlich gesammelte Zahl, keine Behauptung aus einer Studie. Die Domäne sind echte Daten aus einem Projekt, das der Autor bereits besitzt, also ist die Geschichte „Ich habe mein eigenes produktionsnahes System erweitert“, nicht „Ich habe ein Tutorial gemacht“.

Der Build läuft unter den eigenen Agent Collaboration Principles des Autors: Die Definition-of-Done jeder Phase ist eine Reihe unabhängig prüfbarer Artefakte — ein Befehl, der läuft, eine Datei, die existiert, ein Dashboard, das rendert. Kein „Vertrau mir, es funktioniert“.

Related MCP server: production-grade-mcp-agentic-system

Die drei Phasen

Das Projekt ist ein Build in drei streng aufeinanderfolgenden Phasen. Vollständige Spezifikationen finden sich in docs/specs/; der Build-Plan ist der Index. Die Anforderungen wurden im Voraus in einem Planungsprozess definiert und als Vertrag gebaut — die Spezifikationen kamen zuerst, die Tool-Verträge wurden daraus abgeleitet, und die ADRs dokumentieren jede Entscheidung, die die Oberfläche geprägt hat.

Die Reihenfolge ist streng: Die Evaluierungen von Phase 2 bewerten den Router von Phase 3. Nicht umsortieren. Die Querschnittsschicht ist die Ausnahme — sie wird inkrementell eingeführt und blockiert nichts.

Repository-Struktur

towerwatch-ops-agent/
├── README.md                       # this file — human-facing
├── CLAUDE.md                       # agent-facing anchor (read first if you're an agent)
├── pyproject.toml                  # PEP 621 single source of truth — deps, tooling config
├── docs/
│   ├── architecture.md             # intended shape (stub — not built yet)
│   ├── specs/                      # the governing build plan + 4 requirement specs
│   ├── design/                     # locked tool contracts (00–11) — authoritative
│   ├── adr/                        # architecture decision records
│   └── production-path.md          # personal-scale choices vs. enterprise needs
├── src/towerwatch_ops_agent/       # server, config, domain/, tools/, telemetry/
├── tests/                          # pytest suite — 95 tests
├── fixtures/stub/                  # hand-authored stub corpus (not the real one)
└── RATIONALE.md                    # deliberate choices that read as defects

Schnellstart

Der Server läuft und bedient query_metrics. Die anderen sechs Tools sind noch nicht gebaut.

# From repo root. uv manages the environment and lockfile.
uv sync                            # create .venv, install deps from pyproject.toml
uv run python -m towerwatch_ops_agent   # (Phase 1) launch the MCP server over stdio

Das interaktive Testen des Servers (Phase 1) verwendet den MCP Inspector:

npx @modelcontextprotocol/inspector uv run python -m towerwatch_ops_agent

Status

🟡 Phase 1 läuft. Der MCP-Server läuft über stdio und bedient query_metrics Ende-zu-Ende gegen eine Fixture. Noch keines der fünf Abnahmekriterien von Phase 1 ist erfüllt — siehe spec-phase1-mcp-server.md für die Torliste.

Gebaut und laufend:

• Verzeichnis-Skelett, pyproject.toml, .gitignore, MIT-Lizenz

• README, CLAUDE.md (mit bindenden Invarianten), Architektur-Stub

• Der Build-Plan und alle vier Anforderungsspezifikationen in docs/specs/

• Gesperrte Tool-Verträge — docs/design/ 00–11: Konventionen, sieben Tool-Dokumente, Skills-Schnittstellen, Span-Schema, Fixture-Manifest, Evaluierungsdesign

• ADRs — docs/adr/, die Entscheidungen hinter der Tool-Oberfläche

• MCP-Server + Kompositionswurzel — server.py, config.py, stdio-Transport

• query_metrics — 1 von 7 Tools, mit dem data_status-Envelope erzwungen

• FixtureClient + Manifest-Loader — ADR-0002s Dual-Mode-Naht, nur Fixture-Seite

• Span-Instrumentierung — ein Span pro Tool-Aufruf, Geheimnisse strukturell ausgeschlossen

• CI-Workflow — ruff, format, pyright, pytest auf jedem PR-Branch-Head

• RATIONALE.md — bewusste Entscheidungen, die ein Reviewer sonst als Fehler melden würde

Verschoben (noch nicht gebaut — siehe CLAUDE.md für die Phasentore):

• Sechs verbleibende Tools — analyze_window, compare, query_log_events, get_monitor_status, get_runbook, run_speedtest

• GrafanaCloudClient — die Live-Hälfte des DataClient-Protokolls

• Kuratierter Fixture-Korpus — fixtures/stub/ ist ein von Hand erstellter Zwei-Fenster-Stub, der nur das Format beweist, nicht den echten deterministischen Korpus

• OTel-Exporter + SLI-Dashboard — Spans werden emittiert, gehen aber nirgendwohin; kein MeterProvider, also keine Dauer-Histogramme

• def_tokens.md — die Tool-Def-Token-Budget-Messung (Skript existiert, nie ausgeführt)

• bench.md — Cross-Model-Kosten/Latenz-Bench

• Phase 2 — Evaluierungs-Harness + CI + Seeded-Regressions-Showpiece

• Phase 3 — Modell-Router + semantisches Tool-Retrieval

• In-Repo-Skills unter .claude/skills/ — diagnose-rca, evidence-pack, plus die Golden-Path-Skills (add-tool, run-evals), die beim ersten manuellen Durchlauf erstellt wurden

• Gemessene Onboarding-Evaluierung (docs/onboarding-eval.md) — erster Lauf nach Phase 1

Für KI-Assistenten

Wenn Sie ein Agent sind, der in diesem Repository arbeitet, lesen Sie zuerst CLAUDE.md. Es enthält die Phasenreihenfolge, den Arbeitsstandard der zustandslosen Tore und eine explizite Karte dessen, was existiert und was noch ein Stub ist, damit Sie nicht über Code nachdenken, der noch nicht da ist. RATIONALE.md dokumentiert die bewussten Entscheidungen, die auf den ersten Blick wie Fehler wirken — lesen Sie es, bevor Sie einen melden.