diff --git a/CLAUDE.md b/CLAUDE.md index 0971009..0dfd050 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -263,6 +263,8 @@ lab-monitoring metrics node # Search metric names ### Planning When creating implementation plans, the first step should usually be to **checkout an appropriately named feature branch** (e.g., `git checkout -b feature/lab-monitoring`). This keeps work isolated and makes PRs cleaner. +**After implementing a plan**, update the README.md to reflect any new or changed functionality (new servers, tools, CLI commands, configuration options, NixOS module options, etc.). + ### Development Workflow - **Always run `go fmt ./...` before committing Go code** - **Run Go commands using `nix develop -c`** (e.g., `nix develop -c go test ./...`) diff --git a/README.md b/README.md index 569b4a8..a930463 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,21 @@ Both servers share the same database, allowing you to index once and serve both. Search and query Home Manager configuration options across multiple home-manager revisions. Designed to help Claude (and other MCP clients) answer questions about Home Manager configuration. +### Lab Monitoring (`lab-monitoring`) + +Query Prometheus metrics and Alertmanager alerts from your monitoring stack. Unlike other servers, this queries live HTTP APIs — no database or indexing needed. + +- List and inspect alerts from Alertmanager +- Execute PromQL queries against Prometheus +- Search metric names with metadata +- View scrape target health +- Manage alert silences + ### NixOS Options (`nixos-options`) - Legacy Search and query NixOS configuration options. **Note**: Prefer using `nixpkgs-search` instead, which includes this functionality plus package search. -### Shared Features +### Shared Features (nixpkgs-search, hm-options, nixos-options) - Full-text search across option/package names and descriptions - Query specific options/packages with full metadata @@ -36,10 +46,12 @@ Search and query NixOS configuration options. **Note**: Prefer using `nixpkgs-se # Build the packages nix build git+https://git.t-juice.club/torjus/labmcp#nixpkgs-search nix build git+https://git.t-juice.club/torjus/labmcp#hm-options +nix build git+https://git.t-juice.club/torjus/labmcp#lab-monitoring # Or run directly nix run git+https://git.t-juice.club/torjus/labmcp#nixpkgs-search -- --help nix run git+https://git.t-juice.club/torjus/labmcp#hm-options -- --help +nix run git+https://git.t-juice.club/torjus/labmcp#lab-monitoring -- --help ``` ### From Source @@ -47,6 +59,7 @@ nix run git+https://git.t-juice.club/torjus/labmcp#hm-options -- --help ```bash go install git.t-juice.club/torjus/labmcp/cmd/nixpkgs-search@latest go install git.t-juice.club/torjus/labmcp/cmd/hm-options@latest +go install git.t-juice.club/torjus/labmcp/cmd/lab-monitoring@latest ``` ## Usage @@ -78,6 +91,14 @@ Configure in your MCP client (e.g., Claude Desktop): "env": { "HM_OPTIONS_DATABASE": "sqlite:///path/to/hm-options.db" } + }, + "lab-monitoring": { + "command": "lab-monitoring", + "args": ["serve"], + "env": { + "PROMETHEUS_URL": "http://prometheus.example.com:9090", + "ALERTMANAGER_URL": "http://alertmanager.example.com:9093" + } } } } @@ -108,6 +129,14 @@ Alternatively, if you have Nix installed, you can use the flake directly without "env": { "HM_OPTIONS_DATABASE": "sqlite:///path/to/hm-options.db" } + }, + "lab-monitoring": { + "command": "nix", + "args": ["run", "git+https://git.t-juice.club/torjus/labmcp#lab-monitoring", "--", "serve"], + "env": { + "PROMETHEUS_URL": "http://prometheus.example.com:9090", + "ALERTMANAGER_URL": "http://alertmanager.example.com:9093" + } } } } @@ -118,10 +147,11 @@ Alternatively, if you have Nix installed, you can use the flake directly without All servers can run over HTTP with Server-Sent Events (SSE) for web-based MCP clients: ```bash -# Start HTTP server on default address (127.0.0.1:8080) +# Start HTTP server on default address nixpkgs-search options serve --transport http nixpkgs-search packages serve --transport http hm-options serve --transport http +lab-monitoring serve --transport http # Custom address and CORS configuration nixpkgs-search options serve --transport http \ @@ -208,6 +238,26 @@ nixpkgs-search packages get firefox hm-options get programs.git.enable ``` +**Lab Monitoring CLI:** + +```bash +# List alerts +lab-monitoring alerts +lab-monitoring alerts --state active +lab-monitoring alerts --severity critical + +# Execute PromQL queries +lab-monitoring query 'up' +lab-monitoring query 'rate(http_requests_total[5m])' + +# List scrape targets +lab-monitoring targets + +# Search metrics +lab-monitoring metrics node +lab-monitoring metrics -n 20 cpu +``` + **Delete an indexed revision:** ```bash @@ -224,6 +274,8 @@ hm-options delete release-23.11 | `NIXPKGS_SEARCH_DATABASE` | Database connection string for nixpkgs-search | `sqlite://nixpkgs-search.db` | | `HM_OPTIONS_DATABASE` | Database connection string for hm-options | `sqlite://hm-options.db` | | `NIXOS_OPTIONS_DATABASE` | Database connection string for nixos-options (legacy) | `sqlite://nixos-options.db` | +| `PROMETHEUS_URL` | Prometheus base URL for lab-monitoring | `http://localhost:9090` | +| `ALERTMANAGER_URL` | Alertmanager base URL for lab-monitoring | `http://localhost:9093` | ### Database Connection Strings @@ -272,6 +324,19 @@ hm-options -d "sqlite://my.db" index hm-unstable | `list_revisions` | List all indexed revisions | | `delete_revision` | Delete an indexed revision | +### Monitoring Server (lab-monitoring) + +| Tool | Description | +|------|-------------| +| `list_alerts` | List alerts with optional filters (state, severity, receiver) | +| `get_alert` | Get full details for a specific alert by fingerprint | +| `search_metrics` | Search metric names with substring filter, enriched with metadata | +| `get_metric_metadata` | Get type, help text, and unit for a specific metric | +| `query` | Execute an instant PromQL query | +| `list_targets` | List scrape targets with health status | +| `list_silences` | List active/pending alert silences | +| `create_silence` | Create a new alert silence (requires `--enable-silences` flag) | + ## NixOS Modules NixOS modules are provided for running the MCP servers as systemd services. @@ -338,6 +403,31 @@ The `nixpkgs-search` module runs two separate MCP servers (options and packages) } ``` +### lab-monitoring + +```nix +{ + inputs.labmcp.url = "git+https://git.t-juice.club/torjus/labmcp"; + + outputs = { self, nixpkgs, labmcp }: { + nixosConfigurations.myhost = nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; + modules = [ + labmcp.nixosModules.lab-monitoring-mcp + { + services.lab-monitoring = { + enable = true; + prometheusUrl = "http://prometheus.example.com:9090"; + alertmanagerUrl = "http://alertmanager.example.com:9093"; + enableSilences = true; # Optional: enable create_silence tool + }; + } + ]; + }; + }; +} +``` + ### nixos-options (Legacy) ```nix @@ -391,6 +481,26 @@ Both `options.http` and `packages.http` also support: - `sessionTTL` (default: `"30m"`) - `tls.enable`, `tls.certFile`, `tls.keyFile` +#### lab-monitoring + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `enable` | bool | `false` | Enable the service | +| `package` | package | from flake | Package to use | +| `prometheusUrl` | string | `"http://localhost:9090"` | Prometheus base URL | +| `alertmanagerUrl` | string | `"http://localhost:9093"` | Alertmanager base URL | +| `enableSilences` | bool | `false` | Enable the create_silence tool (write operation) | +| `http.address` | string | `"127.0.0.1:8084"` | HTTP listen address | +| `http.endpoint` | string | `"/mcp"` | HTTP endpoint path | +| `http.allowedOrigins` | list of string | `[]` | Allowed CORS origins (empty = localhost only) | +| `http.sessionTTL` | string | `"30m"` | Session timeout (Go duration format) | +| `http.tls.enable` | bool | `false` | Enable TLS | +| `http.tls.certFile` | path | `null` | TLS certificate file | +| `http.tls.keyFile` | path | `null` | TLS private key file | +| `openFirewall` | bool | `false` | Open firewall for HTTP port | + +The lab-monitoring module uses `DynamicUser=true`, so no separate user/group configuration is needed. + #### hm-options-mcp / nixos-options-mcp (Legacy) | Option | Type | Default | Description | @@ -450,6 +560,7 @@ go test -bench=. ./internal/database/... # Build go build ./cmd/nixpkgs-search go build ./cmd/hm-options +go build ./cmd/lab-monitoring ``` ## License