observability-mcp: Instructions file for Claude Code

Observability-MCP Development Guide

Docker-First Development

This project is fully containerized. Never run npm install on the host machine.

Quick Start

docker compose --profile demo up --build

The demo stack brings up:

• a single-node k3s cluster (rancher/k3s in a privileged container)
• the three chaos-able example services (api-gateway, payment-service, order-service) as Kubernetes Deployments inside k3s (namespace omcp-demo)
• Prometheus, Loki, Promtail (on the docker-compose side) scraping k3s NodePorts and pod logs
• the MCP server with the kubernetes topology source pre-wired against k3s
• the autonomous agent

The same Deployments that emit metrics and logs are what shows up in the topology graph — that is what lets the agent correlate a metric/log anomaly with the underlying host via get_blast_radius.

Without --profile demo, only mcp-server runs — for production deployments where Prometheus/Loki are managed elsewhere.

Rebuild a Single Service

docker-compose build mcp-server
docker-compose up -d mcp-server

View Logs

docker compose logs -f agent          # Agent detection loop
docker compose logs -f mcp-server     # MCP server

# Example services run inside k3s now — use kubectl to follow their logs:
docker exec observability-mcp-k3s-1 \
  kubectl -n omcp-demo logs -f deployment/payment-service

Run Unit Tests

docker run --rm -w /app -v "$(pwd)/mcp-server:/app" node:22-alpine \
  sh -c "npm install --silent && npx tsx --test src/analysis/*.test.ts"

Trigger Chaos (Demo)

curl -X POST http://localhost:8081/chaos/high-cpu
curl -X POST http://localhost:8081/chaos/error-spike
curl -X POST http://localhost:8081/chaos/slow-responses
curl -X POST http://localhost:8081/chaos/memory-leak
curl -X POST http://localhost:8081/chaos/reset

Chaos modes are correlated: error-spike also increases CPU + latency + error logs. Memory-leak generates OOM warnings.