docs: add lab-monitoring to README and update CLAUDE.md planning notes

Add comprehensive lab-monitoring documentation to README including MCP server description, installation, MCP client config examples, CLI usage, environment variables, MCP tools table, NixOS module example, and module options. Also add a reminder in CLAUDE.md to update the README after implementing a plan. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-04 23:54:13 +01:00
parent b491a60105
commit f4f859fefa
2 changed files with 115 additions and 2 deletions
--- 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 ./...`)
--- 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