TowerWatch Ops Agent

Una capa de agente sobre TowerWatch — el proyecto de monitorización de calidad de red — construida para demostrar las tres capacidades que necesita un bucle empresarial de ingeniería de agentes: suites de evaluación, elección de modelo consciente del coste/latencia y recuperación de herramientas. Un repo, una historia coherente:

«Tomé mi proyecto público de monitorización y construí a su alrededor la capa de agente que necesitaría una empresa: un servidor MCP instrumentado con SLI definidos, un harness de evaluación en CI que detecta regresiones sembradas, un enrutador de modelos consciente del coste y recuperación semántica de herramientas con precisión de selección medida.»

De un vistazo

• Runtime: Python 3 + FastMCP, gestionado con uv.

• Dominio: los datos de monitorización de red de TowerWatch, expuestos como herramientas de agente.

• Transporte: stdio primero; HTTP en streaming sin estado como objetivo ambicioso.

• Observabilidad: OpenTelemetry desde la primera llamada a herramienta, hacia una pila Prometheus/Grafana.

• Superficie de herramientas: siete herramientas — query_metrics, analyze_window, compare, query_log_events, get_monitor_status, get_runbook, run_speedtest. Contratos en docs/design/.

• Estado: 🟡 Fase 1 en curso — el servidor funciona y una de las siete herramientas está construida; todavía no se cumple ningún criterio de aceptación de la Fase 1. Ver Estado.

Por qué este proyecto

Llena el vacío entre «leí sobre evaluación y enrutamiento de agentes» y «lo construí y lo medí». Cada artefacto — tablas de evaluación, cifras de benchmarks, gráficas de precision@k — es un número recopilado personalmente, no una afirmación extraída de un estudio. El dominio son datos reales de un proyecto que el autor ya posee, así que la historia es «extendí mi propio sistema de estilo producción», no «hice un tutorial».

La construcción se rige por los Principios de Colaboración con Agentes del propio autor: la definición de terminado de cada fase es un conjunto de artefactos comprobables de forma independiente — un comando que se ejecuta, un archivo que existe, un panel que se renderiza. Nada de «confía en mí, funciona».

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

Las tres fases

El proyecto es una única construcción en tres fases estrictamente secuenciadas. Las especificaciones completas viven en docs/specs/; el plan de construcción es el índice. Los requisitos se definieron de antemano en un proceso de planificación y se construyeron para servir como contrato — las especificaciones llegaron primero, los contratos de herramientas se derivaron de ellas, y los ADR registran cada decisión que dio forma a la superficie.

La secuencia es estricta: las evaluaciones de la Fase 2 puntúan al enrutador de la Fase 3. No las reordenes. La capa transversal es la excepción — llega de forma incremental y no bloquea nada.

Estructura del repositorio

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

Inicio rápido

El servidor funciona y sirve query_metrics. Las otras seis herramientas aún no están construidas.

# 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

Para probar el servidor de forma interactiva (Fase 1), usa el MCP Inspector:

npx @modelcontextprotocol/inspector uv run python -m towerwatch_ops_agent

Estado

🟡 Fase 1 en curso. El servidor MCP se ejecuta sobre stdio y sirve query_metrics de extremo a extremo contra un fixture. Todavía no se cumple ninguno de los cinco criterios de aceptación de la Fase 1 — consulta spec-phase1-mcp-server.md para ver la lista de compuertas.

Construido y en funcionamiento:

• Esqueleto de directorios, pyproject.toml, .gitignore, licencia MIT

• README, CLAUDE.md (con invariantes vinculantes), stub de arquitectura

• El plan de construcción y las cuatro especificaciones de requisitos en docs/specs/

• Contratos de herramientas bloqueados — docs/design/ 00–11: convenciones, siete documentos de herramientas, interfaces de skills, esquema de spans, manifiesto de fixtures, diseño de evaluación

• ADRs — docs/adr/, las decisiones detrás de la superficie de herramientas

• Servidor MCP + raíz de composición — server.py, config.py, transporte stdio

• query_metrics — 1 de 7 herramientas, con el envoltorio data_status aplicado

• FixtureClient + cargador de manifiesto — la costura de doble modo de ADR-0002, solo en el lado de fixtures

• Instrumentación de spans — un span por llamada a herramienta, secretos excluidos estructuralmente

• Workflow de CI — ruff, format, pyright, pytest en cada cabeza de rama de PR

• RATIONALE.md — decisiones deliberadas que un revisor de otro modo reportaría como defectos

Diferido (aún no construido — consulta CLAUDE.md para las compuertas de fase):

• Las seis herramientas restantes — analyze_window, compare, query_log_events, get_monitor_status, get_runbook, run_speedtest

• GrafanaCloudClient — la mitad en vivo del Protocolo DataClient

• Corpus de fixtures curado — fixtures/stub/ es un stub escrito a mano de dos ventanas que solo demuestra el formato, no el corpus determinista real

• Exportador OTel + panel de SLI — los spans se emiten pero no van a ninguna parte; no hay MeterProvider, así que no hay histogramas de duración

• def_tokens.md — la medición del presupuesto de tokens de las definiciones de herramientas (el script existe, nunca se ha ejecutado)

• bench.md — benchmark de coste/latencia entre modelos

• Fase 2 — harness de evaluación + CI + pieza de demostración de regresión sembrada

• Fase 3 — enrutador de modelos + recuperación semántica de herramientas

• Skills en el repo bajo .claude/skills/ — diagnose-rca, evidence-pack, más las skills de camino dorado (add-tool, run-evals) creadas cuando se recorrieron por primera vez manualmente

• Evaluación de onboarding medida (docs/onboarding-eval.md) — primera ejecución después de la Fase 1

Para asistentes de IA

Si eres un agente trabajando en este repo, lee CLAUDE.md primero. Contiene la secuencia de fases, el estándar de trabajo de compuertas sin estado y un mapa explícito de lo que existe frente a lo que sigue siendo un stub, para que no razones sobre código que aún no está ahí. RATIONALE.md registra las decisiones deliberadas que a simple vista se leen como defectos — léelo antes de reportar uno.