@solomonneas/librenms-mcp 0.1.0 → 0.2.0

package/README.md

@@ -4,9 +4,9 @@ MCP server exposing LibreNMS read + safe-write tools via API token auth. Three-t
 
 ## 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`.
+**Reads (10):** `librenms_status`, `librenms_list_devices`, `librenms_get_device`, `librenms_list_ports`, `librenms_get_port`, `librenms_port_health`, `librenms_list_alerts`, `librenms_get_alert`, `librenms_alert_history`, `librenms_event_log`.
 
-**Safe writes (2, require `confirm: true`):** `librenms_ack_alert`, `librenms_set_maintenance`.
+**Safe writes (3, require `confirm: true`):** `librenms_ack_alert`, `librenms_unmute_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.
 
@@ -120,8 +120,8 @@ LIBRENMS_TLS_INSECURE = "false"
 
 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 1 (reads):** open. No confirm flag needed. Status, device + port listings, single-port detail, port health, alert listings, alert history, event log.
+- **Tier 2 (safe writes):** require an explicit `confirm: true` arg. The JSON schema documents this on every write tool. Alert acknowledge/unmute and entering device maintenance 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.

package/dist/index.js

@@ -65,6 +65,9 @@ var LibreNmsClient = class {
   async put(path, body) {
     return this.request("PUT", path, body);
   }
+  async delete(path) {
+    return this.request("DELETE", path);
+  }
   async request(method, path, body) {
     const url = this.cfg.url + "/api/v0" + path;
     const headers = { "x-auth-token": this.cfg.token };
@@ -514,6 +517,106 @@ function createLibrenmsSetMaintenanceTool(getClient) {
   };
 }
 
+// src/tools/librenms_get_port.ts
+import { Type as Type11 } from "@sinclair/typebox";
+var Schema11 = Type11.Object(
+  {
+    port_id: Type11.Integer({
+      minimum: 1,
+      description: "LibreNMS internal port id (from librenms_list_ports response rows)."
+    })
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsGetPortTool(getClient) {
+  return {
+    name: "librenms_get_port",
+    label: "librenms: get port",
+    description: "Single-port detail via GET /api/v0/ports/{port_id}. Returns full column set (admin/oper state, traffic + error counters, ifAlias, etc.).",
+    parameters: Schema11,
+    execute: async (_id, raw) => {
+      const args = raw;
+      const client = getClient();
+      const r = await client.get(`/ports/${args.port_id}`);
+      return jsonToolResult({ port: r.port?.[0] ?? null });
+    }
+  };
+}
+
+// src/tools/librenms_event_log.ts
+import { Type as Type12 } from "@sinclair/typebox";
+var Schema12 = Type12.Object(
+  {
+    device_id: Type12.Optional(
+      Type12.Integer({
+        minimum: 1,
+        description: "Optional device id to scope the event log."
+      })
+    ),
+    limit: Type12.Optional(
+      Type12.Integer({
+        minimum: 1,
+        description: "Max number of log entries. Default 25."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsEventLogTool(getClient) {
+  return {
+    name: "librenms_event_log",
+    label: "librenms: event log",
+    description: "Recent device events via GET /api/v0/logs/eventlog (optionally scoped to a device_id). Covers device up/down, syslog ingestion, etc. Distinct from alertlog.",
+    parameters: Schema12,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const limit = args.limit ?? 25;
+      const path = args.device_id ? `/logs/eventlog/${args.device_id}?limit=${limit}` : `/logs/eventlog?limit=${limit}`;
+      const client = getClient();
+      const r = await client.get(path);
+      return jsonToolResult({
+        count: r.logs?.length ?? 0,
+        logs: r.logs ?? []
+      });
+    }
+  };
+}
+
+// src/tools/librenms_unmute_alert.ts
+import { Type as Type13 } from "@sinclair/typebox";
+var Schema13 = Type13.Object(
+  {
+    id: Type13.Integer({ minimum: 1, description: "Alert id to unmute." }),
+    note: Type13.Optional(
+      Type13.String({
+        description: "Optional note appended to the alert audit trail (LibreNMS prefixes it with the API user + timestamp)."
+      })
+    ),
+    confirm: Type13.Boolean({
+      description: "Must be true to write. Tier-2 safe-write gate."
+    })
+  },
+  { additionalProperties: false }
+);
+var NAME3 = "librenms_unmute_alert";
+function createLibrenmsUnmuteAlertTool(getClient) {
+  return {
+    name: NAME3,
+    label: "librenms: unmute alert",
+    description: "Unmute an alert by id via PUT /api/v0/alerts/unmute/{id} (companion to librenms_ack_alert). Tier-2 write; requires confirm:true.",
+    parameters: Schema13,
+    execute: async (_id, raw) => {
+      assertConfirmedWrite(raw, NAME3);
+      const args = raw;
+      const client = getClient();
+      const body = {};
+      if (args.note !== void 0) body.note = args.note;
+      const r = await client.put(`/alerts/unmute/${args.id}`, body);
+      return jsonToolResult({ alert_id: args.id, unmuted: true, response: r });
+    }
+  };
+}
+
 // index.ts
 function withRedactedErrors(tool) {
   const orig = tool.execute.bind(tool);
@@ -552,6 +655,9 @@ var index_default = definePluginEntry({
     register(createLibrenmsAlertHistoryTool(getClient));
     register(createLibrenmsAckAlertTool(getClient));
     register(createLibrenmsSetMaintenanceTool(getClient));
+    register(createLibrenmsGetPortTool(getClient));
+    register(createLibrenmsEventLogTool(getClient));
+    register(createLibrenmsUnmuteAlertTool(getClient));
   }
 });
 export {

package/dist/mcp-server.js

@@ -67,6 +67,9 @@ var LibreNmsClient = class {
   async put(path, body) {
     return this.request("PUT", path, body);
   }
+  async delete(path) {
+    return this.request("DELETE", path);
+  }
   async request(method, path, body) {
     const url = this.cfg.url + "/api/v0" + path;
     const headers = { "x-auth-token": this.cfg.token };
@@ -516,6 +519,106 @@ function createLibrenmsSetMaintenanceTool(getClient2) {
   };
 }
 
+// src/tools/librenms_get_port.ts
+import { Type as Type11 } from "@sinclair/typebox";
+var Schema11 = Type11.Object(
+  {
+    port_id: Type11.Integer({
+      minimum: 1,
+      description: "LibreNMS internal port id (from librenms_list_ports response rows)."
+    })
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsGetPortTool(getClient2) {
+  return {
+    name: "librenms_get_port",
+    label: "librenms: get port",
+    description: "Single-port detail via GET /api/v0/ports/{port_id}. Returns full column set (admin/oper state, traffic + error counters, ifAlias, etc.).",
+    parameters: Schema11,
+    execute: async (_id, raw) => {
+      const args = raw;
+      const client = getClient2();
+      const r = await client.get(`/ports/${args.port_id}`);
+      return jsonToolResult({ port: r.port?.[0] ?? null });
+    }
+  };
+}
+
+// src/tools/librenms_event_log.ts
+import { Type as Type12 } from "@sinclair/typebox";
+var Schema12 = Type12.Object(
+  {
+    device_id: Type12.Optional(
+      Type12.Integer({
+        minimum: 1,
+        description: "Optional device id to scope the event log."
+      })
+    ),
+    limit: Type12.Optional(
+      Type12.Integer({
+        minimum: 1,
+        description: "Max number of log entries. Default 25."
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+function createLibrenmsEventLogTool(getClient2) {
+  return {
+    name: "librenms_event_log",
+    label: "librenms: event log",
+    description: "Recent device events via GET /api/v0/logs/eventlog (optionally scoped to a device_id). Covers device up/down, syslog ingestion, etc. Distinct from alertlog.",
+    parameters: Schema12,
+    execute: async (_id, raw) => {
+      const args = raw ?? {};
+      const limit = args.limit ?? 25;
+      const path = args.device_id ? `/logs/eventlog/${args.device_id}?limit=${limit}` : `/logs/eventlog?limit=${limit}`;
+      const client = getClient2();
+      const r = await client.get(path);
+      return jsonToolResult({
+        count: r.logs?.length ?? 0,
+        logs: r.logs ?? []
+      });
+    }
+  };
+}
+
+// src/tools/librenms_unmute_alert.ts
+import { Type as Type13 } from "@sinclair/typebox";
+var Schema13 = Type13.Object(
+  {
+    id: Type13.Integer({ minimum: 1, description: "Alert id to unmute." }),
+    note: Type13.Optional(
+      Type13.String({
+        description: "Optional note appended to the alert audit trail (LibreNMS prefixes it with the API user + timestamp)."
+      })
+    ),
+    confirm: Type13.Boolean({
+      description: "Must be true to write. Tier-2 safe-write gate."
+    })
+  },
+  { additionalProperties: false }
+);
+var NAME3 = "librenms_unmute_alert";
+function createLibrenmsUnmuteAlertTool(getClient2) {
+  return {
+    name: NAME3,
+    label: "librenms: unmute alert",
+    description: "Unmute an alert by id via PUT /api/v0/alerts/unmute/{id} (companion to librenms_ack_alert). Tier-2 write; requires confirm:true.",
+    parameters: Schema13,
+    execute: async (_id, raw) => {
+      assertConfirmedWrite(raw, NAME3);
+      const args = raw;
+      const client = getClient2();
+      const body = {};
+      if (args.note !== void 0) body.note = args.note;
+      const r = await client.put(`/alerts/unmute/${args.id}`, body);
+      return jsonToolResult({ alert_id: args.id, unmuted: true, response: r });
+    }
+  };
+}
+
 // mcp-server.ts
 var cfg = resolveConfig(process.env);
 registerSecret(cfg.token);
@@ -530,10 +633,13 @@ var tools = [
   createLibrenmsGetAlertTool(getClient),
   createLibrenmsAlertHistoryTool(getClient),
   createLibrenmsAckAlertTool(getClient),
-  createLibrenmsSetMaintenanceTool(getClient)
+  createLibrenmsSetMaintenanceTool(getClient),
+  createLibrenmsGetPortTool(getClient),
+  createLibrenmsEventLogTool(getClient),
+  createLibrenmsUnmuteAlertTool(getClient)
 ];
 var toolMap = new Map(tools.map((t) => [t.name, t]));
-var server = new Server({ name: "librenms-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+var server = new Server({ name: "librenms-mcp", version: "0.2.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.parameters }))
 }));

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "id": "librenms",
   "name": "LibreNMS",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "LibreNMS read + safe-write tools: devices, ports, alerts, ack, maintenance.",
   "entry": "./dist/index.js",
   "activation": { "onStartup": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solomonneas/librenms-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server exposing LibreNMS read + safe-write tools",
   "type": "module",
   "openclaw": {