@solomonneas/librenms-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solomon Neas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# librenms-mcp
+
+MCP server exposing LibreNMS read + safe-write tools via API token auth. Three-tier write gating: reads are open, writes require `confirm: true`, destructive ops would require `confirm: true` + `destructive: true` (v1 ships tier 1 + tier 2 only; tier 3 destructive ops are deferred).
+
+## Tools
+
+**Reads (8):** `librenms_status`, `librenms_list_devices`, `librenms_get_device`, `librenms_list_ports`, `librenms_port_health`, `librenms_list_alerts`, `librenms_get_alert`, `librenms_alert_history`.
+
+**Safe writes (2, require `confirm: true`):** `librenms_ack_alert`, `librenms_set_maintenance`.
+
+**Destructive (tier 3):** not in v1. Operations like device deletion, alert rule removal, and bulk port resets are intentionally absent until the gate pattern has more field time.
+
+## Configuration
+
+Set the following env vars. Both credential vars are required.
+
+```
+LIBRENMS_URL=https://librenms.example.local
+LIBRENMS_TOKEN=<your-api-token>
+
+# Optional: skip TLS cert validation (homelab self-signed certs).
+# Accepts true/1/yes (case-insensitive). Defaults to false.
+LIBRENMS_TLS_INSECURE=false
+```
+
+Trailing slashes on `LIBRENMS_URL` are stripped. The API token is registered with the redactor on startup and masked from all log + error output.
+
+## Install
+
+```
+npm install -g @solomonneas/librenms-mcp
+```
+
+Or run via npx:
+
+```
+npx -y @solomonneas/librenms-mcp
+```
+
+## Setup
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "librenms": {
+      "command": "npx",
+      "args": ["-y", "@solomonneas/librenms-mcp"],
+      "env": {
+        "LIBRENMS_URL": "https://librenms.example.local",
+        "LIBRENMS_TOKEN": "<your-api-token>",
+        "LIBRENMS_TLS_INSECURE": "false"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add librenms -s user -- npx -y @solomonneas/librenms-mcp
+```
+
+Then export env vars in your shell (`~/.bashrc`, `~/.zshrc`) or pass `--env` flags.
+
+### OpenClaw
+
+Plugin loads automatically once installed. Config goes in your `~/.openclaw/openclaw.json` `plugins.entries.librenms` (or use the bundled `openclaw.plugin.json`):
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "librenms": {
+        "package": "@solomonneas/librenms-mcp",
+        "activation": { "onStartup": true }
+      }
+    }
+  }
+}
+```
+
+Env vars from `~/.openclaw/workspace/.env` are inherited by the plugin.
+
+### Hermes Agent
+
+Add to `~/.config/hermes/agents.yaml`:
+
+```yaml
+mcp_servers:
+  librenms:
+    command: npx
+    args: ["-y", "@solomonneas/librenms-mcp"]
+    env:
+      LIBRENMS_URL: https://librenms.example.local
+      LIBRENMS_TOKEN: <your-api-token>
+      LIBRENMS_TLS_INSECURE: "false"
+```
+
+### Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.librenms]
+command = "npx"
+args = ["-y", "@solomonneas/librenms-mcp"]
+
+[mcp_servers.librenms.env]
+LIBRENMS_URL = "https://librenms.example.local"
+LIBRENMS_TOKEN = "<your-api-token>"
+LIBRENMS_TLS_INSECURE = "false"
+```
+
+## Safety
+
+This MCP uses the same three-tier write-gating pattern as the rest of the `solomonneas/*-mcp` family:
+
+- **Tier 1 (reads):** open. No confirm flag needed. Status, device + port listings, port health, alert listings, alert history.
+- **Tier 2 (safe writes):** require an explicit `confirm: true` arg. The JSON schema documents this on every write tool. Alert acknowledge and device maintenance toggling live here. A hallucinated tool call without the confirm flag throws `WriteGateError` before any HTTP traffic.
+- **Tier 3 (destructive):** not implemented in v1. When added, ops like device deletion, alert rule removal, and bulk port resets will additionally require `destructive: true`. The model cannot bypass either gate from a hallucinated call.
+
+**API token scope recommendation:** start with a "Read Only" token role in LibreNMS (Settings > API > New API Token > Read Only) and verify the read tools work end-to-end. Grade up to "Normal User" or "Global Read/Write" only after you've confirmed the redactor is masking your token in your transcripts and that the model is honoring the confirm gate. Tokens can be revoked instantly from the same Settings > API screen.
+
+The `LIBRENMS_TLS_INSECURE=true` toggle exists for homelab self-signed certs. Leave it `false` in any environment with a real CA-signed cert.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,560 @@
+#!/usr/bin/env node
+
+// index.ts
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+
+// src/config.ts
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+function isTruthy(value) {
+  if (!value) return false;
+  return ["true", "1", "yes"].includes(value.toLowerCase());
+}
+function resolveConfig(env) {
+  const url = env.LIBRENMS_URL;
+  const token = env.LIBRENMS_TOKEN;
+  if (!url) throw new ConfigError("LIBRENMS_URL is required");
+  if (!token) throw new ConfigError("LIBRENMS_TOKEN is required");
+  return {
+    url: url.replace(/\/+$/, ""),
+    token,
+    tlsInsecure: isTruthy(env.LIBRENMS_TLS_INSECURE)
+  };
+}
+
+// src/librenms-client.ts
+import { Agent as UndiciAgent } from "undici";
+var LibreNmsClientError = class extends Error {
+  constructor(status, message) {
+    super(`LibreNMS ${status}: ${message}`);
+    this.status = status;
+    this.name = "LibreNmsClientError";
+  }
+  status;
+};
+var LibreNmsUnreachableError = class extends Error {
+  constructor(cause) {
+    super(`LibreNMS unreachable: ${cause}`);
+    this.name = "LibreNmsUnreachableError";
+  }
+};
+var LibreNmsClient = class {
+  constructor(cfg, opts = {}) {
+    this.cfg = cfg;
+    this.retryDelayMs = opts.retryDelayMs ?? 1e3;
+    if (cfg.tlsInsecure && cfg.url.startsWith("https://")) {
+      this.dispatcher = new UndiciAgent({ connect: { rejectUnauthorized: false } });
+    }
+  }
+  cfg;
+  retryDelayMs;
+  // Node's global fetch (undici) ignores node:https.Agent. To actually skip
+  // cert verification for self-signed LibreNMS hosts we pass an undici Agent
+  // via the `dispatcher` init option.
+  dispatcher;
+  async get(path) {
+    return this.request("GET", path);
+  }
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async put(path, body) {
+    return this.request("PUT", path, body);
+  }
+  async request(method, path, body) {
+    const url = this.cfg.url + "/api/v0" + path;
+    const headers = { "x-auth-token": this.cfg.token };
+    let bodyStr;
+    if (body !== void 0) {
+      headers["content-type"] = "application/json";
+      bodyStr = JSON.stringify(body);
+    }
+    let lastErr;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const init = { method, headers, body: bodyStr };
+        if (this.dispatcher) init.dispatcher = this.dispatcher;
+        const res = await fetch(url, init);
+        if (res.status >= 200 && res.status < 300) {
+          const text = await res.text();
+          if (!text) return void 0;
+          return JSON.parse(text);
+        }
+        if (res.status >= 500) {
+          lastErr = new LibreNmsUnreachableError(`HTTP ${res.status}`);
+          if (attempt === 0) await sleep(this.retryDelayMs);
+          continue;
+        }
+        const errText = await res.text();
+        let msg = errText;
+        try {
+          msg = JSON.parse(errText).message ?? errText;
+        } catch {
+        }
+        throw new LibreNmsClientError(res.status, msg);
+      } catch (e) {
+        if (e instanceof LibreNmsClientError) throw e;
+        lastErr = new LibreNmsUnreachableError(e.message);
+        if (attempt === 0) await sleep(this.retryDelayMs);
+      }
+    }
+    throw lastErr ?? new LibreNmsUnreachableError("unknown");
+  }
+};
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/security.ts
+var SECRETS = /* @__PURE__ */ new Set();
+var BASE64_TOKEN_RE = /[A-Za-z0-9+/=]{12,}/g;
+function registerSecret(s) {
+  if (s && s.length > 0) SECRETS.add(s);
+}
+function maskString(s) {
+  let out = s;
+  for (const secret of SECRETS) {
+    if (out.includes(secret)) out = out.split(secret).join("REDACTED");
+  }
+  out = out.replace(BASE64_TOKEN_RE, (token) => {
+    try {
+      const decoded = Buffer.from(token, "base64").toString("utf8");
+      for (const secret of SECRETS) {
+        if (decoded.includes(secret)) return "REDACTED";
+      }
+    } catch {
+    }
+    return token;
+  });
+  return out;
+}
+function redact(value) {
+  if (typeof value === "string") return maskString(value);
+  if (Array.isArray(value)) return value.map(redact);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = redact(v);
+    return out;
+  }
+  return value;
+}
+
+// src/tools/librenms_status.ts
+import { Type } from "@sinclair/typebox";
+
+// src/tools/_util.ts
+function jsonToolResult(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+  };
+}
+
+// src/tools/librenms_status.ts
+var Schema = Type.Object({}, { additionalProperties: false });
+function createLibrenmsStatusTool(getClient) {
+  return {
+    name: "librenms_status",
+    label: "librenms: status",
+    description: "LibreNMS system health (version, totals, last poll) via GET /api/v0/system.",
+    parameters: Schema,
+    execute: async () => {
+      const client = getClient();
+      const r = await client.get("/system");
+      return jsonToolResult({ system: r.system?.[0] ?? null });
+    }
+  };
+}
+
+// src/tools/librenms_list_devices.ts
+import { Type as Type2 } from "@sinclair/typebox";
+var Schema2 = Type2.Object(
+  {
+    type: Type2.Optional(
+      Type2.Union(
+        [
+          Type2.Literal("all"),
+          Type2.Literal("up"),
+          Type2.Literal("down"),
+          Type2.Literal("ignored"),
+          Type2.Literal("disabled")
+        ],
+        { description: "Device filter type. Default 'all'." }
+      )
+    )
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsListDevicesTool(getClient) {
+  return {
+    name: "librenms_list_devices",
+    label: "librenms: list devices",
+    description: "List devices monitored by LibreNMS via GET /api/v0/devices. Optional type filter (all|up|down|ignored|disabled).",
+    parameters: Schema2,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const path = args.type ? `/devices?type=${args.type}` : "/devices";
+      const client = getClient();
+      const r = await client.get(path);
+      return jsonToolResult({ devices: r.devices ?? [] });
+    }
+  };
+}
+
+// src/tools/librenms_get_device.ts
+import { Type as Type3 } from "@sinclair/typebox";
+var Schema3 = Type3.Object(
+  {
+    hostname: Type3.String({
+      description: "Device hostname or IP as configured in LibreNMS."
+    })
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsGetDeviceTool(getClient) {
+  return {
+    name: "librenms_get_device",
+    label: "librenms: get device",
+    description: "Fetch a single device by hostname via GET /api/v0/devices/{hostname}.",
+    parameters: Schema3,
+    execute: async (_id, raw) => {
+      const args = raw;
+      const client = getClient();
+      const r = await client.get(`/devices/${encodeURIComponent(args.hostname)}`);
+      return jsonToolResult({ device: r.devices?.[0] ?? null });
+    }
+  };
+}
+
+// src/tools/librenms_list_ports.ts
+import { Type as Type4 } from "@sinclair/typebox";
+var Schema4 = Type4.Object(
+  {
+    hostname: Type4.String({
+      description: "Device hostname or IP as configured in LibreNMS."
+    })
+  },
+  { additionalProperties: false }
+);
+var COLUMNS = "ifName,ifAdminStatus,ifOperStatus,ifInErrors,ifOutErrors,ifSpeed,ifDescr";
+function createLibrenmsListPortsTool(getClient) {
+  return {
+    name: "librenms_list_ports",
+    label: "librenms: list ports",
+    description: "List ports on a device via GET /api/v0/devices/{hostname}/ports with a fixed column set (name, status, errors, speed, descr).",
+    parameters: Schema4,
+    execute: async (_id, raw) => {
+      const args = raw;
+      const client = getClient();
+      const r = await client.get(`/devices/${encodeURIComponent(args.hostname)}/ports?columns=${COLUMNS}`);
+      return jsonToolResult({ ports: r.ports ?? [] });
+    }
+  };
+}
+
+// src/tools/librenms_port_health.ts
+import { Type as Type5 } from "@sinclair/typebox";
+var Schema5 = Type5.Object(
+  {
+    limit: Type5.Optional(
+      Type5.Integer({
+        minimum: 1,
+        description: "Number of top ports to return. Default 10."
+      })
+    ),
+    metric: Type5.Optional(
+      Type5.Union(
+        [
+          Type5.Literal("errors_in"),
+          Type5.Literal("errors_out"),
+          Type5.Literal("utilization")
+        ],
+        { description: "Ranking metric. Default 'errors_in'." }
+      )
+    )
+  },
+  { additionalProperties: false }
+);
+var COLUMNS2 = "device_id,ifName,ifInErrors,ifOutErrors,ifSpeed,ifInOctets,ifOutOctets";
+function createLibrenmsPortHealthTool(getClient) {
+  return {
+    name: "librenms_port_health",
+    label: "librenms: port health",
+    description: "Rank ports by errors_in (default), errors_out, or utilization via GET /api/v0/ports with client-side sort.",
+    parameters: Schema5,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const limit = args.limit ?? 10;
+      const metric = args.metric ?? "errors_in";
+      const client = getClient();
+      const r = await client.get(`/ports?columns=${COLUMNS2}`);
+      const ports = r.ports ?? [];
+      const sorted = ports.slice().sort((a, b) => {
+        if (metric === "errors_in") {
+          return (b.ifInErrors ?? 0) - (a.ifInErrors ?? 0);
+        }
+        if (metric === "errors_out") {
+          return (b.ifOutErrors ?? 0) - (a.ifOutErrors ?? 0);
+        }
+        const aUtil = a.ifSpeed ? ((a.ifInOctets ?? 0) + (a.ifOutOctets ?? 0)) / a.ifSpeed : 0;
+        const bUtil = b.ifSpeed ? ((b.ifInOctets ?? 0) + (b.ifOutOctets ?? 0)) / b.ifSpeed : 0;
+        return bUtil - aUtil;
+      });
+      return jsonToolResult({ metric, limit, top: sorted.slice(0, limit) });
+    }
+  };
+}
+
+// src/tools/librenms_list_alerts.ts
+import { Type as Type6 } from "@sinclair/typebox";
+var Schema6 = Type6.Object(
+  {
+    state: Type6.Optional(
+      Type6.Union(
+        [Type6.Literal(0), Type6.Literal(1), Type6.Literal(2)],
+        { description: "Alert state filter: 0=ok, 1=active, 2=ack." }
+      )
+    )
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsListAlertsTool(getClient) {
+  return {
+    name: "librenms_list_alerts",
+    label: "librenms: list alerts",
+    description: "List alerts via GET /api/v0/alerts. Optional state filter (0=ok, 1=active, 2=ack).",
+    parameters: Schema6,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const path = args.state !== void 0 ? `/alerts?state=${args.state}` : "/alerts";
+      const client = getClient();
+      const r = await client.get(path);
+      return jsonToolResult({ alerts: r.alerts ?? [] });
+    }
+  };
+}
+
+// src/tools/librenms_get_alert.ts
+import { Type as Type7 } from "@sinclair/typebox";
+var Schema7 = Type7.Object(
+  {
+    id: Type7.Integer({ minimum: 1, description: "Alert id." })
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsGetAlertTool(getClient) {
+  return {
+    name: "librenms_get_alert",
+    label: "librenms: get alert",
+    description: "Fetch a single alert by id via GET /api/v0/alerts/{id}.",
+    parameters: Schema7,
+    execute: async (_id, raw) => {
+      const args = raw;
+      const client = getClient();
+      const r = await client.get(`/alerts/${args.id}`);
+      return jsonToolResult({ alert: r.alerts?.[0] ?? null });
+    }
+  };
+}
+
+// src/tools/librenms_alert_history.ts
+import { Type as Type8 } from "@sinclair/typebox";
+var Schema8 = Type8.Object(
+  {
+    device_id: Type8.Optional(
+      Type8.Integer({
+        minimum: 1,
+        description: "Optional device id to scope the alert log."
+      })
+    ),
+    limit: Type8.Optional(
+      Type8.Integer({
+        minimum: 1,
+        description: "Max number of log entries. Default 25."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsAlertHistoryTool(getClient) {
+  return {
+    name: "librenms_alert_history",
+    label: "librenms: alert history",
+    description: "Recent alert log entries via GET /api/v0/logs/alertlog (optionally scoped to a device_id).",
+    parameters: Schema8,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const limit = args.limit ?? 25;
+      const path = args.device_id ? `/logs/alertlog/${args.device_id}?limit=${limit}` : `/logs/alertlog?limit=${limit}`;
+      const client = getClient();
+      const r = await client.get(path);
+      return jsonToolResult({
+        count: r.logs?.length ?? 0,
+        logs: r.logs ?? []
+      });
+    }
+  };
+}
+
+// src/tools/librenms_ack_alert.ts
+import { Type as Type9 } from "@sinclair/typebox";
+
+// src/gates.ts
+var WriteGateError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WriteGateError";
+  }
+};
+function assertConfirmedWrite(args, toolName) {
+  if (args.confirm !== true) {
+    throw new WriteGateError(`${toolName} is a write operation. Pass {"confirm": true} to proceed.`);
+  }
+}
+
+// src/tools/librenms_ack_alert.ts
+var Schema9 = Type9.Object(
+  {
+    id: Type9.Integer({ minimum: 1, description: "Alert id to acknowledge." }),
+    note: Type9.Optional(
+      Type9.String({ description: "Optional acknowledgement note." })
+    ),
+    until_clear: Type9.Optional(
+      Type9.Boolean({
+        description: "When true, the ack persists until the alert clears (default LibreNMS behavior: ack until next state change)."
+      })
+    ),
+    confirm: Type9.Boolean({
+      description: "Must be true to write. Tier-2 safe-write gate."
+    })
+  },
+  { additionalProperties: false }
+);
+var NAME = "librenms_ack_alert";
+function createLibrenmsAckAlertTool(getClient) {
+  return {
+    name: NAME,
+    label: "librenms: ack alert",
+    description: "Acknowledge an active alert by id via PUT /api/v0/alerts/{id}. Tier-2 write; requires confirm:true.",
+    parameters: Schema9,
+    execute: async (_id, raw) => {
+      assertConfirmedWrite(raw, NAME);
+      const args = raw;
+      const client = getClient();
+      const body = {};
+      if (args.note !== void 0) body.note = args.note;
+      if (args.until_clear !== void 0) body.until_clear = args.until_clear;
+      const r = await client.put(`/alerts/${args.id}`, body);
+      return jsonToolResult({ alert_id: args.id, acked: true, response: r });
+    }
+  };
+}
+
+// src/tools/librenms_set_maintenance.ts
+import { Type as Type10 } from "@sinclair/typebox";
+var DURATION_RE = /^\d+:\d{2}$/;
+var START_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+var Schema10 = Type10.Object(
+  {
+    hostname: Type10.String({
+      description: "Device hostname or IP as configured in LibreNMS."
+    }),
+    duration: Type10.String({
+      description: "Maintenance duration. LibreNMS format `H:i`, e.g. `2:00` for 2 hours or `0:30` for 30 minutes."
+    }),
+    title: Type10.Optional(
+      Type10.String({ description: "Maintenance window title." })
+    ),
+    notes: Type10.Optional(Type10.String({ description: "Free-text notes." })),
+    start: Type10.Optional(
+      Type10.String({
+        description: "Start time. LibreNMS format `Y-m-d H:i:00`, e.g. `2026-05-17 14:30:00`. Default: server now."
+      })
+    ),
+    confirm: Type10.Boolean({
+      description: "Must be true to write. Tier-2 safe-write gate."
+    })
+  },
+  { additionalProperties: false }
+);
+var NAME2 = "librenms_set_maintenance";
+function createLibrenmsSetMaintenanceTool(getClient) {
+  return {
+    name: NAME2,
+    label: "librenms: set maintenance",
+    description: "Put a device into a maintenance window (suppresses alerts) via POST /api/v0/devices/{hostname}/maintenance. Tier-2 write; requires confirm:true.",
+    parameters: Schema10,
+    execute: async (_id, raw) => {
+      assertConfirmedWrite(raw, NAME2);
+      const args = raw;
+      if (!DURATION_RE.test(args.duration)) {
+        throw new Error(
+          `duration must be H:i format (e.g. "2:00" or "0:30"), got: ${args.duration}`
+        );
+      }
+      if (args.start && !START_RE.test(args.start)) {
+        throw new Error(
+          `start must be Y-m-d H:i:00 format (e.g. "2026-05-17 14:30:00"), got: ${args.start}`
+        );
+      }
+      const client = getClient();
+      const body = { duration: args.duration };
+      if (args.title) body.title = args.title;
+      if (args.notes) body.notes = args.notes;
+      if (args.start) body.start = args.start;
+      const r = await client.post(
+        `/devices/${encodeURIComponent(args.hostname)}/maintenance`,
+        body
+      );
+      return jsonToolResult({ hostname: args.hostname, maintenance: r });
+    }
+  };
+}
+
+// index.ts
+function withRedactedErrors(tool) {
+  const orig = tool.execute.bind(tool);
+  return {
+    ...tool,
+    execute: async (id, args) => {
+      try {
+        return await orig(id, args);
+      } catch (e) {
+        const msg = redact(e.message);
+        return { content: [{ type: "text", text: JSON.stringify({ error: msg }) }], isError: true };
+      }
+    }
+  };
+}
+function makeFactory(cfg) {
+  registerSecret(cfg.token);
+  return () => new LibreNmsClient(cfg);
+}
+var index_default = definePluginEntry({
+  id: "librenms",
+  name: "LibreNMS",
+  description: "LibreNMS read + safe-write tools: system status, devices, ports, alerts, ack, maintenance. Single-instance, X-Auth-Token, optional TLS-insecure. Tier-2 writes gated by confirm:true.",
+  register(api) {
+    if (api.registrationMode !== "full") return;
+    const cfg = resolveConfig(process.env);
+    const getClient = makeFactory(cfg);
+    const register = (t) => api.registerTool(withRedactedErrors(t));
+    register(createLibrenmsStatusTool(getClient));
+    register(createLibrenmsListDevicesTool(getClient));
+    register(createLibrenmsGetDeviceTool(getClient));
+    register(createLibrenmsListPortsTool(getClient));
+    register(createLibrenmsPortHealthTool(getClient));
+    register(createLibrenmsListAlertsTool(getClient));
+    register(createLibrenmsGetAlertTool(getClient));
+    register(createLibrenmsAlertHistoryTool(getClient));
+    register(createLibrenmsAckAlertTool(getClient));
+    register(createLibrenmsSetMaintenanceTool(getClient));
+  }
+});
+export {
+  index_default as default,
+  withRedactedErrors
+};

package/dist/mcp-server.js

@@ -0,0 +1,553 @@
+#!/usr/bin/env node
+
+// mcp-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+// src/config.ts
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+function isTruthy(value) {
+  if (!value) return false;
+  return ["true", "1", "yes"].includes(value.toLowerCase());
+}
+function resolveConfig(env) {
+  const url = env.LIBRENMS_URL;
+  const token = env.LIBRENMS_TOKEN;
+  if (!url) throw new ConfigError("LIBRENMS_URL is required");
+  if (!token) throw new ConfigError("LIBRENMS_TOKEN is required");
+  return {
+    url: url.replace(/\/+$/, ""),
+    token,
+    tlsInsecure: isTruthy(env.LIBRENMS_TLS_INSECURE)
+  };
+}
+
+// src/librenms-client.ts
+import { Agent as UndiciAgent } from "undici";
+var LibreNmsClientError = class extends Error {
+  constructor(status, message) {
+    super(`LibreNMS ${status}: ${message}`);
+    this.status = status;
+    this.name = "LibreNmsClientError";
+  }
+  status;
+};
+var LibreNmsUnreachableError = class extends Error {
+  constructor(cause) {
+    super(`LibreNMS unreachable: ${cause}`);
+    this.name = "LibreNmsUnreachableError";
+  }
+};
+var LibreNmsClient = class {
+  constructor(cfg2, opts = {}) {
+    this.cfg = cfg2;
+    this.retryDelayMs = opts.retryDelayMs ?? 1e3;
+    if (cfg2.tlsInsecure && cfg2.url.startsWith("https://")) {
+      this.dispatcher = new UndiciAgent({ connect: { rejectUnauthorized: false } });
+    }
+  }
+  cfg;
+  retryDelayMs;
+  // Node's global fetch (undici) ignores node:https.Agent. To actually skip
+  // cert verification for self-signed LibreNMS hosts we pass an undici Agent
+  // via the `dispatcher` init option.
+  dispatcher;
+  async get(path) {
+    return this.request("GET", path);
+  }
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async put(path, body) {
+    return this.request("PUT", path, body);
+  }
+  async request(method, path, body) {
+    const url = this.cfg.url + "/api/v0" + path;
+    const headers = { "x-auth-token": this.cfg.token };
+    let bodyStr;
+    if (body !== void 0) {
+      headers["content-type"] = "application/json";
+      bodyStr = JSON.stringify(body);
+    }
+    let lastErr;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const init = { method, headers, body: bodyStr };
+        if (this.dispatcher) init.dispatcher = this.dispatcher;
+        const res = await fetch(url, init);
+        if (res.status >= 200 && res.status < 300) {
+          const text = await res.text();
+          if (!text) return void 0;
+          return JSON.parse(text);
+        }
+        if (res.status >= 500) {
+          lastErr = new LibreNmsUnreachableError(`HTTP ${res.status}`);
+          if (attempt === 0) await sleep(this.retryDelayMs);
+          continue;
+        }
+        const errText = await res.text();
+        let msg = errText;
+        try {
+          msg = JSON.parse(errText).message ?? errText;
+        } catch {
+        }
+        throw new LibreNmsClientError(res.status, msg);
+      } catch (e) {
+        if (e instanceof LibreNmsClientError) throw e;
+        lastErr = new LibreNmsUnreachableError(e.message);
+        if (attempt === 0) await sleep(this.retryDelayMs);
+      }
+    }
+    throw lastErr ?? new LibreNmsUnreachableError("unknown");
+  }
+};
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/security.ts
+var SECRETS = /* @__PURE__ */ new Set();
+var BASE64_TOKEN_RE = /[A-Za-z0-9+/=]{12,}/g;
+function registerSecret(s) {
+  if (s && s.length > 0) SECRETS.add(s);
+}
+function maskString(s) {
+  let out = s;
+  for (const secret of SECRETS) {
+    if (out.includes(secret)) out = out.split(secret).join("REDACTED");
+  }
+  out = out.replace(BASE64_TOKEN_RE, (token) => {
+    try {
+      const decoded = Buffer.from(token, "base64").toString("utf8");
+      for (const secret of SECRETS) {
+        if (decoded.includes(secret)) return "REDACTED";
+      }
+    } catch {
+    }
+    return token;
+  });
+  return out;
+}
+function redact(value) {
+  if (typeof value === "string") return maskString(value);
+  if (Array.isArray(value)) return value.map(redact);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = redact(v);
+    return out;
+  }
+  return value;
+}
+
+// src/tools/librenms_status.ts
+import { Type } from "@sinclair/typebox";
+
+// src/tools/_util.ts
+function jsonToolResult(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+  };
+}
+
+// src/tools/librenms_status.ts
+var Schema = Type.Object({}, { additionalProperties: false });
+function createLibrenmsStatusTool(getClient2) {
+  return {
+    name: "librenms_status",
+    label: "librenms: status",
+    description: "LibreNMS system health (version, totals, last poll) via GET /api/v0/system.",
+    parameters: Schema,
+    execute: async () => {
+      const client = getClient2();
+      const r = await client.get("/system");
+      return jsonToolResult({ system: r.system?.[0] ?? null });
+    }
+  };
+}
+
+// src/tools/librenms_list_devices.ts
+import { Type as Type2 } from "@sinclair/typebox";
+var Schema2 = Type2.Object(
+  {
+    type: Type2.Optional(
+      Type2.Union(
+        [
+          Type2.Literal("all"),
+          Type2.Literal("up"),
+          Type2.Literal("down"),
+          Type2.Literal("ignored"),
+          Type2.Literal("disabled")
+        ],
+        { description: "Device filter type. Default 'all'." }
+      )
+    )
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsListDevicesTool(getClient2) {
+  return {
+    name: "librenms_list_devices",
+    label: "librenms: list devices",
+    description: "List devices monitored by LibreNMS via GET /api/v0/devices. Optional type filter (all|up|down|ignored|disabled).",
+    parameters: Schema2,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const path = args.type ? `/devices?type=${args.type}` : "/devices";
+      const client = getClient2();
+      const r = await client.get(path);
+      return jsonToolResult({ devices: r.devices ?? [] });
+    }
+  };
+}
+
+// src/tools/librenms_get_device.ts
+import { Type as Type3 } from "@sinclair/typebox";
+var Schema3 = Type3.Object(
+  {
+    hostname: Type3.String({
+      description: "Device hostname or IP as configured in LibreNMS."
+    })
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsGetDeviceTool(getClient2) {
+  return {
+    name: "librenms_get_device",
+    label: "librenms: get device",
+    description: "Fetch a single device by hostname via GET /api/v0/devices/{hostname}.",
+    parameters: Schema3,
+    execute: async (_id, raw) => {
+      const args = raw;
+      const client = getClient2();
+      const r = await client.get(`/devices/${encodeURIComponent(args.hostname)}`);
+      return jsonToolResult({ device: r.devices?.[0] ?? null });
+    }
+  };
+}
+
+// src/tools/librenms_list_ports.ts
+import { Type as Type4 } from "@sinclair/typebox";
+var Schema4 = Type4.Object(
+  {
+    hostname: Type4.String({
+      description: "Device hostname or IP as configured in LibreNMS."
+    })
+  },
+  { additionalProperties: false }
+);
+var COLUMNS = "ifName,ifAdminStatus,ifOperStatus,ifInErrors,ifOutErrors,ifSpeed,ifDescr";
+function createLibrenmsListPortsTool(getClient2) {
+  return {
+    name: "librenms_list_ports",
+    label: "librenms: list ports",
+    description: "List ports on a device via GET /api/v0/devices/{hostname}/ports with a fixed column set (name, status, errors, speed, descr).",
+    parameters: Schema4,
+    execute: async (_id, raw) => {
+      const args = raw;
+      const client = getClient2();
+      const r = await client.get(`/devices/${encodeURIComponent(args.hostname)}/ports?columns=${COLUMNS}`);
+      return jsonToolResult({ ports: r.ports ?? [] });
+    }
+  };
+}
+
+// src/tools/librenms_port_health.ts
+import { Type as Type5 } from "@sinclair/typebox";
+var Schema5 = Type5.Object(
+  {
+    limit: Type5.Optional(
+      Type5.Integer({
+        minimum: 1,
+        description: "Number of top ports to return. Default 10."
+      })
+    ),
+    metric: Type5.Optional(
+      Type5.Union(
+        [
+          Type5.Literal("errors_in"),
+          Type5.Literal("errors_out"),
+          Type5.Literal("utilization")
+        ],
+        { description: "Ranking metric. Default 'errors_in'." }
+      )
+    )
+  },
+  { additionalProperties: false }
+);
+var COLUMNS2 = "device_id,ifName,ifInErrors,ifOutErrors,ifSpeed,ifInOctets,ifOutOctets";
+function createLibrenmsPortHealthTool(getClient2) {
+  return {
+    name: "librenms_port_health",
+    label: "librenms: port health",
+    description: "Rank ports by errors_in (default), errors_out, or utilization via GET /api/v0/ports with client-side sort.",
+    parameters: Schema5,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const limit = args.limit ?? 10;
+      const metric = args.metric ?? "errors_in";
+      const client = getClient2();
+      const r = await client.get(`/ports?columns=${COLUMNS2}`);
+      const ports = r.ports ?? [];
+      const sorted = ports.slice().sort((a, b) => {
+        if (metric === "errors_in") {
+          return (b.ifInErrors ?? 0) - (a.ifInErrors ?? 0);
+        }
+        if (metric === "errors_out") {
+          return (b.ifOutErrors ?? 0) - (a.ifOutErrors ?? 0);
+        }
+        const aUtil = a.ifSpeed ? ((a.ifInOctets ?? 0) + (a.ifOutOctets ?? 0)) / a.ifSpeed : 0;
+        const bUtil = b.ifSpeed ? ((b.ifInOctets ?? 0) + (b.ifOutOctets ?? 0)) / b.ifSpeed : 0;
+        return bUtil - aUtil;
+      });
+      return jsonToolResult({ metric, limit, top: sorted.slice(0, limit) });
+    }
+  };
+}
+
+// src/tools/librenms_list_alerts.ts
+import { Type as Type6 } from "@sinclair/typebox";
+var Schema6 = Type6.Object(
+  {
+    state: Type6.Optional(
+      Type6.Union(
+        [Type6.Literal(0), Type6.Literal(1), Type6.Literal(2)],
+        { description: "Alert state filter: 0=ok, 1=active, 2=ack." }
+      )
+    )
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsListAlertsTool(getClient2) {
+  return {
+    name: "librenms_list_alerts",
+    label: "librenms: list alerts",
+    description: "List alerts via GET /api/v0/alerts. Optional state filter (0=ok, 1=active, 2=ack).",
+    parameters: Schema6,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const path = args.state !== void 0 ? `/alerts?state=${args.state}` : "/alerts";
+      const client = getClient2();
+      const r = await client.get(path);
+      return jsonToolResult({ alerts: r.alerts ?? [] });
+    }
+  };
+}
+
+// src/tools/librenms_get_alert.ts
+import { Type as Type7 } from "@sinclair/typebox";
+var Schema7 = Type7.Object(
+  {
+    id: Type7.Integer({ minimum: 1, description: "Alert id." })
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsGetAlertTool(getClient2) {
+  return {
+    name: "librenms_get_alert",
+    label: "librenms: get alert",
+    description: "Fetch a single alert by id via GET /api/v0/alerts/{id}.",
+    parameters: Schema7,
+    execute: async (_id, raw) => {
+      const args = raw;
+      const client = getClient2();
+      const r = await client.get(`/alerts/${args.id}`);
+      return jsonToolResult({ alert: r.alerts?.[0] ?? null });
+    }
+  };
+}
+
+// src/tools/librenms_alert_history.ts
+import { Type as Type8 } from "@sinclair/typebox";
+var Schema8 = Type8.Object(
+  {
+    device_id: Type8.Optional(
+      Type8.Integer({
+        minimum: 1,
+        description: "Optional device id to scope the alert log."
+      })
+    ),
+    limit: Type8.Optional(
+      Type8.Integer({
+        minimum: 1,
+        description: "Max number of log entries. Default 25."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsAlertHistoryTool(getClient2) {
+  return {
+    name: "librenms_alert_history",
+    label: "librenms: alert history",
+    description: "Recent alert log entries via GET /api/v0/logs/alertlog (optionally scoped to a device_id).",
+    parameters: Schema8,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const limit = args.limit ?? 25;
+      const path = args.device_id ? `/logs/alertlog/${args.device_id}?limit=${limit}` : `/logs/alertlog?limit=${limit}`;
+      const client = getClient2();
+      const r = await client.get(path);
+      return jsonToolResult({
+        count: r.logs?.length ?? 0,
+        logs: r.logs ?? []
+      });
+    }
+  };
+}
+
+// src/tools/librenms_ack_alert.ts
+import { Type as Type9 } from "@sinclair/typebox";
+
+// src/gates.ts
+var WriteGateError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WriteGateError";
+  }
+};
+function assertConfirmedWrite(args, toolName) {
+  if (args.confirm !== true) {
+    throw new WriteGateError(`${toolName} is a write operation. Pass {"confirm": true} to proceed.`);
+  }
+}
+
+// src/tools/librenms_ack_alert.ts
+var Schema9 = Type9.Object(
+  {
+    id: Type9.Integer({ minimum: 1, description: "Alert id to acknowledge." }),
+    note: Type9.Optional(
+      Type9.String({ description: "Optional acknowledgement note." })
+    ),
+    until_clear: Type9.Optional(
+      Type9.Boolean({
+        description: "When true, the ack persists until the alert clears (default LibreNMS behavior: ack until next state change)."
+      })
+    ),
+    confirm: Type9.Boolean({
+      description: "Must be true to write. Tier-2 safe-write gate."
+    })
+  },
+  { additionalProperties: false }
+);
+var NAME = "librenms_ack_alert";
+function createLibrenmsAckAlertTool(getClient2) {
+  return {
+    name: NAME,
+    label: "librenms: ack alert",
+    description: "Acknowledge an active alert by id via PUT /api/v0/alerts/{id}. Tier-2 write; requires confirm:true.",
+    parameters: Schema9,
+    execute: async (_id, raw) => {
+      assertConfirmedWrite(raw, NAME);
+      const args = raw;
+      const client = getClient2();
+      const body = {};
+      if (args.note !== void 0) body.note = args.note;
+      if (args.until_clear !== void 0) body.until_clear = args.until_clear;
+      const r = await client.put(`/alerts/${args.id}`, body);
+      return jsonToolResult({ alert_id: args.id, acked: true, response: r });
+    }
+  };
+}
+
+// src/tools/librenms_set_maintenance.ts
+import { Type as Type10 } from "@sinclair/typebox";
+var DURATION_RE = /^\d+:\d{2}$/;
+var START_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+var Schema10 = Type10.Object(
+  {
+    hostname: Type10.String({
+      description: "Device hostname or IP as configured in LibreNMS."
+    }),
+    duration: Type10.String({
+      description: "Maintenance duration. LibreNMS format `H:i`, e.g. `2:00` for 2 hours or `0:30` for 30 minutes."
+    }),
+    title: Type10.Optional(
+      Type10.String({ description: "Maintenance window title." })
+    ),
+    notes: Type10.Optional(Type10.String({ description: "Free-text notes." })),
+    start: Type10.Optional(
+      Type10.String({
+        description: "Start time. LibreNMS format `Y-m-d H:i:00`, e.g. `2026-05-17 14:30:00`. Default: server now."
+      })
+    ),
+    confirm: Type10.Boolean({
+      description: "Must be true to write. Tier-2 safe-write gate."
+    })
+  },
+  { additionalProperties: false }
+);
+var NAME2 = "librenms_set_maintenance";
+function createLibrenmsSetMaintenanceTool(getClient2) {
+  return {
+    name: NAME2,
+    label: "librenms: set maintenance",
+    description: "Put a device into a maintenance window (suppresses alerts) via POST /api/v0/devices/{hostname}/maintenance. Tier-2 write; requires confirm:true.",
+    parameters: Schema10,
+    execute: async (_id, raw) => {
+      assertConfirmedWrite(raw, NAME2);
+      const args = raw;
+      if (!DURATION_RE.test(args.duration)) {
+        throw new Error(
+          `duration must be H:i format (e.g. "2:00" or "0:30"), got: ${args.duration}`
+        );
+      }
+      if (args.start && !START_RE.test(args.start)) {
+        throw new Error(
+          `start must be Y-m-d H:i:00 format (e.g. "2026-05-17 14:30:00"), got: ${args.start}`
+        );
+      }
+      const client = getClient2();
+      const body = { duration: args.duration };
+      if (args.title) body.title = args.title;
+      if (args.notes) body.notes = args.notes;
+      if (args.start) body.start = args.start;
+      const r = await client.post(
+        `/devices/${encodeURIComponent(args.hostname)}/maintenance`,
+        body
+      );
+      return jsonToolResult({ hostname: args.hostname, maintenance: r });
+    }
+  };
+}
+
+// mcp-server.ts
+var cfg = resolveConfig(process.env);
+registerSecret(cfg.token);
+var getClient = () => new LibreNmsClient(cfg);
+var tools = [
+  createLibrenmsStatusTool(getClient),
+  createLibrenmsListDevicesTool(getClient),
+  createLibrenmsGetDeviceTool(getClient),
+  createLibrenmsListPortsTool(getClient),
+  createLibrenmsPortHealthTool(getClient),
+  createLibrenmsListAlertsTool(getClient),
+  createLibrenmsGetAlertTool(getClient),
+  createLibrenmsAlertHistoryTool(getClient),
+  createLibrenmsAckAlertTool(getClient),
+  createLibrenmsSetMaintenanceTool(getClient)
+];
+var toolMap = new Map(tools.map((t) => [t.name, t]));
+var server = new Server({ name: "librenms-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.parameters }))
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const t = toolMap.get(req.params.name);
+  if (!t) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: `unknown tool: ${req.params.name}` }) }], isError: true };
+  }
+  try {
+    return await t.execute(req.params.name, req.params.arguments ?? {});
+  } catch (e) {
+    const msg = redact(e.message);
+    return { content: [{ type: "text", text: JSON.stringify({ error: msg }) }], isError: true };
+  }
+});
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/openclaw.plugin.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "id": "librenms",
+  "name": "LibreNMS",
+  "version": "0.1.0",
+  "description": "LibreNMS read + safe-write tools: devices, ports, alerts, ack, maintenance.",
+  "entry": "./dist/index.js",
+  "activation": { "onStartup": true },
+  "compat": { "openclaw": ">=2026.4.22" },
+  "permissions": [],
+  "configSchema": { "type": "object", "properties": {}, "additionalProperties": false }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@solomonneas/librenms-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing LibreNMS read + safe-write tools",
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.5.17",
+      "pluginSdkVersion": "2026.5.17"
+    }
+  },
+  "bin": { "librenms-mcp": "./dist/mcp-server.js" },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "start": "node dist/mcp-server.js",
+    "dev": "tsx mcp-server.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "files": ["dist", "openclaw.plugin.json", "README.md", "LICENSE"],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "peerDependencies": { "openclaw": "^2026.4.22" },
+  "peerDependenciesMeta": { "openclaw": { "optional": true } },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "openclaw": "^2026.4.22",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/solomonneas/librenms-mcp" }
+}