@usex/mikrotik-mcp 3.25.0 → 3.27.0

package/dist/cli.js

@@ -22,7 +22,8 @@ var McpServerSettingsSchema = z.object({
   port: z.coerce.number().int().positive().default(8000),
   allowedHosts: z.string().default(""),
   allowedOrigins: z.string().default(""),
-  corsOrigins: z.string().default("")
+  corsOrigins: z.string().default(""),
+  toolPageSize: z.coerce.number().int().min(0).default(0)
 });
 var DeviceConfigSchema = z.object({
   host: z.string().default("127.0.0.1"),
@@ -185,7 +186,8 @@ function loadConfig(argv = process.argv.slice(2)) {
     port: pick("mcp-port", "MIKROTIK_MCP__PORT"),
     allowedHosts: pick("mcp-allowed-hosts", "MIKROTIK_MCP__ALLOWED_HOSTS"),
     allowedOrigins: pick("mcp-allowed-origins", "MIKROTIK_MCP__ALLOWED_ORIGINS"),
-    corsOrigins: pick("mcp-cors-origins", "MIKROTIK_MCP__CORS_ORIGINS")
+    corsOrigins: pick("mcp-cors-origins", "MIKROTIK_MCP__CORS_ORIGINS"),
+    toolPageSize: pick("tool-page-size", "MIKROTIK_MCP__TOOL_PAGE_SIZE")
   };
   const isTruthy = (v) => /^(1|true|yes|on)$/i.test(v ?? "");
   const readOnly = isTruthy(pick("read-only", "MIKROTIK_READ_ONLY"));
@@ -269,6 +271,24 @@ function resolveDeviceName(name) {
   }
   return active.defaultDevice in active.devices ? active.defaultDevice : Object.keys(active.devices)[0] ?? active.defaultDevice;
 }
+function deviceTarget(dc) {
+  if (!dc)
+    return "?";
+  return dc.mac ? `MAC ${dc.mac}` : `${dc.host}:${dc.port ?? 22}`;
+}
+function deviceDirectory() {
+  return Object.entries(active.devices).map(([key, dc]) => ({
+    key,
+    label: dc.description?.trim() || undefined,
+    target: deviceTarget(dc),
+    isDefault: key === active.defaultDevice
+  }));
+}
+function resolvedTarget(name) {
+  const key = resolveDeviceName(name);
+  const dc = active.devices[key];
+  return { key, label: dc?.description?.trim() || undefined, target: deviceTarget(dc) };
+}
 function getDevice(name) {
   if (name && !(name in active.devices) && !deviceKeyForLabel(name)) {
     throw new Error(`Unknown device '${name}'. Configured devices: ${Object.keys(active.devices).join(", ")}`);
@@ -1681,6 +1701,16 @@ function effectiveUi(def) {
   }
   return { ui: undefined, auto: false };
 }
+function deviceSelectorDescription(selectorNames, directory) {
+  if (directory && directory.length > 0) {
+    const rows = directory.map((d) => `\u2022 ${d.key}${d.label && d.label !== d.key ? ` ("${d.label}")` : ""} \u2192 ${d.target}${d.isDefault ? " [default]" : ""}`).join(`
+`);
+    return "Which configured MikroTik device to run this on. Pass the EXACT config key (or its label) " + "that matches the user's wording \u2014 these are different physical routers, so never substitute " + `one for another (e.g. "Ali Home" is NOT "home"). Configured devices:
+` + `${rows}
+` + "Omit only when the user did not name a device (uses the default).";
+  }
+  return `Which configured MikroTik device to run this on. One of: ${selectorNames.join(", ")} ` + "(a config key or its label). Omit to use the default device.";
+}
 var READ = {
   readOnlyHint: true,
   idempotentHint: true,
@@ -1713,19 +1743,25 @@ function defineTool(def) {
     inputSchema: def.inputSchema,
     ui: def.ui,
     register(server, opts = {}) {
-      const { sendLog, deviceNames, deviceAliases } = opts;
+      const { sendLog, deviceNames, deviceAliases, deviceDirectory: deviceDirectory2 } = opts;
       const multiDevice = !!deviceNames && deviceNames.length > 1;
       const { ui, auto } = effectiveUi(def);
       const selectorNames = multiDevice && deviceNames ? [...new Set([...deviceNames, ...deviceAliases ?? []])] : [];
       const inputSchema = multiDevice ? {
         ...def.inputSchema,
-        device: z2.enum(selectorNames).optional().describe(`Which configured MikroTik device to run this on. One of: ${selectorNames.join(", ")} (a config key or its label). Omit to use the default device.`)
+        device: z2.enum(selectorNames).optional().describe(deviceSelectorDescription(selectorNames, deviceDirectory2))
       } : def.inputSchema;
       const risk = riskOf(def.annotations);
       const callback = async (args) => {
         const { device, ...rest } = args;
         const deviceName = typeof device === "string" ? device : undefined;
         const ctx = createContext(sendLog, deviceName);
+        const deviceStamp = multiDevice && risk !== "READ" ? (() => {
+          const t = resolvedTarget(deviceName);
+          const label = t.label && t.label !== t.key ? ` "${t.label}"` : "";
+          const how = deviceName === undefined ? " \u2014 DEFAULT (no device specified)" : "";
+          return `\u21B3 executed on device: ${t.key}${label}${how} \u2192 ${t.target}`;
+        })() : null;
         const startedAt = Date.now();
         let outText = "";
         let isErr = false;
@@ -1754,6 +1790,8 @@ function defineTool(def) {
             result.structuredContent = out.structuredContent;
             hasStructured = true;
           }
+          if (deviceStamp)
+            result.content.push({ type: "text", text: deviceStamp });
           return result;
         } catch (e) {
           const msg = e instanceof Error ? e.message : String(e);
@@ -1762,7 +1800,10 @@ function defineTool(def) {
           errMsg = msg;
           outText = `Error: ${msg}`;
           return {
-            content: [{ type: "text", text: `Error: ${msg}` }],
+            content: [
+              { type: "text", text: `Error: ${msg}` },
+              ...deviceStamp ? [{ type: "text", text: deviceStamp }] : []
+            ],
             isError: true
           };
         } finally {
@@ -3815,19 +3856,28 @@ ${details}` : "Certificate creation completed but unable to verify.";
     name: "sign_certificate",
     title: "Sign Certificate",
     annotations: WRITE,
-    description: "Signs an existing certificate template (`/certificate sign`) to produce a valid certificate. " + "Omit `ca` to produce a self-signed certificate; supply the name of an existing CA certificate in `ca` " + "to issue it under that CA. " + "The certificate template to sign must already exist \u2014 create it first with `create_certificate`. " + "Optionally override the common name at signing time via `common_name`. " + "May run for several seconds while the device generates key material. " + "Returns the signing operation output from the device.",
+    description: "Signs an existing certificate template (`/certificate sign`) to produce a valid certificate. " + "Omit `ca` to produce a self-signed certificate; supply the name of an existing CA certificate in `ca` " + "to issue it under that CA. " + "IMPORTANT: certificate stores are PER-DEVICE \u2014 the template (and the `ca`, if given) must live on the " + "SAME router this runs on. A 'CA not found' error almost always means the template or CA was created on a " + "different device; verify with list_certificates on this device first (and check the targeting). " + "Set the common name (CN) when you create the template (create_certificate), not here \u2014 `/certificate sign` " + "has no CN option. " + "May run for several seconds while the device generates key material. " + "Returns the signing operation output from the device.",
     inputSchema: {
-      name: z9.string().describe("Name of the certificate to sign"),
-      ca: z9.string().optional().describe("Name of the CA certificate to sign with (omit to self-sign)"),
-      common_name: z9.string().optional().describe("Override the common name when signing")
+      name: z9.string().describe("Name of the certificate template to sign"),
+      ca: z9.string().optional().describe("Name of the CA certificate to sign with (must exist on THIS device; omit to self-sign)")
     },
     async handler(a, ctx) {
-      ctx.info(`Signing certificate: name=${a.name}`);
-      const cmd = new Cmd("/certificate sign").raw(a.name).opt("ca", a.ca).opt("common-name", a.common_name).build();
+      ctx.info(`Signing certificate: name=${a.name}${a.ca ? ` ca=${a.ca}` : " (self-signed)"}`);
+      const templateCount = await executeMikrotikCommand(`/certificate print count-only where name="${a.name}"`, ctx);
+      if (templateCount.trim() === "0") {
+        return `Certificate template '${a.name}' was not found on this device. Certificate stores are per-device \u2014 ` + `create the template here first (create_certificate), and make sure you are targeting the router that holds it ` + `(use list_certificates / list_mikrotik_devices to confirm).`;
+      }
+      if (a.ca) {
+        const caCount = await executeMikrotikCommand(`/certificate print count-only where name="${a.ca}"`, ctx);
+        if (caCount.trim() === "0") {
+          return `CA certificate '${a.ca}' was not found on this device. The signing CA must exist on the SAME router as ` + `the template (certificate stores are per-device). Omit 'ca' to self-sign, or create/import the CA on this device first.`;
+        }
+      }
+      const cmd = new Cmd("/certificate sign").raw(a.name).opt("ca", a.ca).build();
       const result = await executeMikrotikCommand(cmd, ctx);
       if (looksLikeError(result))
         return `Failed to sign certificate: ${result}`;
-      return `Signing certificate '${a.name}'...
+      return `Signing certificate '${a.name}'${a.ca ? ` with CA '${a.ca}'` : " (self-signed)"}\u2026
 
 ${result}`;
     }
@@ -4698,7 +4748,7 @@ var deviceTools = [
     name: "list_mikrotik_devices",
     title: "List Configured MikroTik Devices",
     annotations: READ,
-    description: "List all MikroTik devices registered in this server's configuration (server-side metadata \u2014 no RouterOS command is run, no SSH connection is opened). " + "Use this to discover the exact device name strings required by the `device` argument on every other tool, especially when working across multiple routers (e.g. building a tunnel between two devices). " + "Returns each device's name, username, host, port, auth method (key / password / none), optional description, and which entry is the default. " + "Credentials and private-key material are never included in the output.",
+    description: "List all MikroTik devices registered in this server's configuration (server-side metadata \u2014 no RouterOS command is run, no SSH connection is opened). " + "Use this to discover the exact device name strings required by the `device` argument on every other tool, especially when working across multiple routers (e.g. building a tunnel between two devices). " + "Returns each device's name, username, host, port, auth method (key / password / none), optional description, and which entry is the default. " + "This name \u2192 host:port mapping is FIXED for the life of the server process \u2014 it does NOT change mid-session, so a given device name always reaches the same physical router. " + "Call this to verify the exact target before any write/destructive change when several routers are configured. " + "Credentials and private-key material are never included in the output.",
     handler(_a, ctx) {
       ctx.info("Listing configured MikroTik devices");
       const { names, default: def } = listDevices();
@@ -12048,7 +12098,7 @@ ${details}`;
     },
     async handler(a, ctx) {
       ctx.info(`Creating L2TP client: name=${a.name}, connect_to=${a.connect_to}`);
-      const cmd = new Cmd("/interface l2tp-client add").set("name", a.name).set("connect-to", a.connect_to).set("user", a.user).set("password", a.password).opt("profile", a.profile).bool("add-default-route", a.add_default_route).opt("default-route-distance", a.default_route_distance).opt("use-ipsec", a.use_ipsec).opt("ipsec-secret", a.ipsec_secret).opt("allow", a.allow).bool("use-peer-dns", a.use_peer_dns).bool("dial-on-demand", a.dial_on_demand).opt("keepalive-timeout", a.keepalive_timeout).opt("max-mtu", a.max_mtu).opt("max-mru", a.max_mru).opt("mrru", a.mrru).opt("comment", a.comment).flag("disabled", a.disabled).build();
+      const cmd = new Cmd("/interface l2tp-client add").set("name", a.name).set("connect-to", a.connect_to).set("user", a.user).set("password", a.password).opt("profile", a.profile).bool("add-default-route", a.add_default_route).opt("default-route-distance", a.default_route_distance).opt("use-ipsec", a.use_ipsec).opt("ipsec-secret", a.ipsec_secret).opt("allow", a.allow).bool("use-peer-dns", a.use_peer_dns).bool("dial-on-demand", a.dial_on_demand).opt("keepalive-timeout", a.keepalive_timeout).opt("max-mtu", a.max_mtu).opt("max-mru", a.max_mru).opt("mrru", a.mrru).opt("comment", a.comment).bool("disabled", a.disabled).build();
       const result = await executeMikrotikCommand(cmd, ctx);
       if (looksLikeError(result))
         return `Failed to create L2TP client: ${redactSecrets(result)}`;
@@ -14511,7 +14561,7 @@ ${details}`;
     },
     async handler(a, ctx) {
       ctx.info(`Adding OpenVPN server: name=${a.name}`);
-      const cmd = new Cmd("/interface ovpn-server server add").set("name", a.name).opt("port", a.port).opt("protocol", a.protocol).opt("mode", a.mode).opt("netmask", a.netmask).opt("mac-address", a.mac_address).opt("certificate", a.certificate).opt("auth", a.auth).opt("cipher", a.cipher).opt("tls-version", a.tls_version).opt("max-mtu", a.max_mtu).opt("default-profile", a.default_profile).bool("require-client-certificate", a.require_client_certificate).opt("comment", a.comment).flag("disabled", a.disabled).build();
+      const cmd = new Cmd("/interface ovpn-server server add").set("name", a.name).opt("port", a.port).opt("protocol", a.protocol).opt("mode", a.mode).opt("netmask", a.netmask).opt("mac-address", a.mac_address).opt("certificate", a.certificate).opt("auth", a.auth).opt("cipher", a.cipher).opt("tls-version", a.tls_version).opt("max-mtu", a.max_mtu).opt("default-profile", a.default_profile).bool("require-client-certificate", a.require_client_certificate).opt("comment", a.comment).bool("disabled", a.disabled).build();
       const result = await executeMikrotikCommand(cmd, ctx);
       if (containsRawParserError(result)) {
         return "Failed to add OpenVPN server: this RouterOS build does not support named OpenVPN" + " server instances (the multi-server model requires RouterOS 7.17+). Use set_ovpn_server" + ` to configure the single legacy server instead.
@@ -14664,7 +14714,7 @@ ${details}`;
     },
     async handler(a, ctx) {
       ctx.info(`Creating OpenVPN client: name=${a.name}, connect_to=${a.connect_to}`);
-      const cmd = new Cmd("/interface ovpn-client add").set("name", a.name).set("connect-to", a.connect_to).opt("port", a.port).opt("user", a.user).opt("password", a.password).opt("certificate", a.certificate).opt("cipher", a.cipher).opt("auth", a.auth).opt("tls-version", a.tls_version).opt("mode", a.mode).opt("protocol", a.protocol).opt("mac-address", a.mac_address).opt("max-mtu", a.max_mtu).opt("profile", a.profile).bool("add-default-route", a.add_default_route).bool("route-nopull", a.route_nopull).bool("use-peer-dns", a.use_peer_dns).bool("verify-server-certificate", a.verify_server_certificate).opt("comment", a.comment).flag("disabled", a.disabled).build();
+      const cmd = new Cmd("/interface ovpn-client add").set("name", a.name).set("connect-to", a.connect_to).opt("port", a.port).opt("user", a.user).opt("password", a.password).opt("certificate", a.certificate).opt("cipher", a.cipher).opt("auth", a.auth).opt("tls-version", a.tls_version).opt("mode", a.mode).opt("protocol", a.protocol).opt("mac-address", a.mac_address).opt("max-mtu", a.max_mtu).opt("profile", a.profile).bool("add-default-route", a.add_default_route).bool("route-nopull", a.route_nopull).bool("use-peer-dns", a.use_peer_dns).bool("verify-server-certificate", a.verify_server_certificate).opt("comment", a.comment).bool("disabled", a.disabled).build();
       const result = await executeMikrotikCommand(cmd, ctx);
       if (looksLikeError(result))
         return `Failed to create OpenVPN client: ${redactSecrets(result)}`;
@@ -15203,7 +15253,7 @@ ${details}`;
     },
     async handler(a, ctx) {
       ctx.info(`Creating PPTP client: name=${a.name}, connect_to=${a.connect_to}`);
-      const cmd = new Cmd("/interface pptp-client add").set("name", a.name).set("connect-to", a.connect_to).set("user", a.user).set("password", a.password).opt("profile", a.profile).bool("add-default-route", a.add_default_route).opt("default-route-distance", a.default_route_distance).opt("allow", a.allow).bool("dial-on-demand", a.dial_on_demand).opt("max-mtu", a.max_mtu).opt("max-mru", a.max_mru).opt("mrru", a.mrru).opt("keepalive-timeout", a.keepalive_timeout).opt("comment", a.comment).flag("disabled", a.disabled).build();
+      const cmd = new Cmd("/interface pptp-client add").set("name", a.name).set("connect-to", a.connect_to).set("user", a.user).set("password", a.password).opt("profile", a.profile).bool("add-default-route", a.add_default_route).opt("default-route-distance", a.default_route_distance).opt("allow", a.allow).bool("dial-on-demand", a.dial_on_demand).opt("max-mtu", a.max_mtu).opt("max-mru", a.max_mru).opt("mrru", a.mrru).opt("keepalive-timeout", a.keepalive_timeout).opt("comment", a.comment).bool("disabled", a.disabled).build();
       const result = await executeMikrotikCommand(cmd, ctx);
       if (looksLikeError(result))
         return `Failed to create PPTP client: ${redactSecrets(result)}`;
@@ -19773,7 +19823,7 @@ ${details}`;
     async handler(a, ctx) {
       ctx.info(`Creating SSTP client: name=${a.name}, connect_to=${a.connect_to}`);
       const { host, port } = splitHostPort(a.connect_to);
-      const cmd = new Cmd("/interface sstp-client add").set("name", a.name).set("connect-to", host).opt("port", a.port ?? port).set("user", a.user).set("password", a.password).opt("profile", a.profile).opt("certificate", a.certificate).bool("verify-server-certificate", a.verify_server_certificate).opt("authentication", a.authentication).opt("tls-version", a.tls_version).bool("pfs", a.pfs).bool("add-default-route", a.add_default_route).opt("default-route-distance", a.default_route_distance).bool("dial-on-demand", a.dial_on_demand).opt("max-mtu", a.max_mtu).opt("max-mru", a.max_mru).opt("mrru", a.mrru).opt("keepalive-timeout", a.keepalive_timeout).opt("http-proxy", a.http_proxy).opt("comment", a.comment).flag("disabled", a.disabled).build();
+      const cmd = new Cmd("/interface sstp-client add").set("name", a.name).set("connect-to", host).opt("port", a.port ?? port).set("user", a.user).set("password", a.password).opt("profile", a.profile).opt("certificate", a.certificate).bool("verify-server-certificate", a.verify_server_certificate).opt("authentication", a.authentication).opt("tls-version", a.tls_version).bool("pfs", a.pfs).bool("add-default-route", a.add_default_route).opt("default-route-distance", a.default_route_distance).bool("dial-on-demand", a.dial_on_demand).opt("max-mtu", a.max_mtu).opt("max-mru", a.max_mru).opt("mrru", a.mrru).opt("keepalive-timeout", a.keepalive_timeout).opt("http-proxy", a.http_proxy).opt("comment", a.comment).bool("disabled", a.disabled).build();
       const result = await executeMikrotikCommand(cmd, ctx);
       if (looksLikeError(result))
         return `Failed to create SSTP client: ${redactSecrets(result)}`;
@@ -19820,7 +19870,7 @@ ${redactSecrets(result)}`;
     name: "remove_sstp_client",
     title: "Remove SSTP Client Interface",
     annotations: DESTRUCTIVE,
-    description: "Permanently delete an SSTP client tunnel interface (`/interface sstp-client remove [find name=...]`) by interface name. " + "First verifies the interface exists (count-only check), then removes it; the tunnel is torn down immediately and the action is irreversible. " + "Use `list_sstp_clients` to confirm the interface name before calling this tool. " + "For L2TP, OpenVPN, or PPTP client interfaces see their respective tool scopes (`create_l2tp_client`, `create_ovpn_client`, `create_pptp_client`). " + "To disable the interface without deleting it, no dedicated enable/disable tool exists in this scope \u2014 set `disabled=yes` via RouterOS directly. " + "Returns a confirmation message on success or a not-found message if the name does not exist.",
+    description: "Permanently delete an SSTP client tunnel interface (`/interface sstp-client remove [find name=...]`) by interface name. " + "First verifies the interface exists (count-only check), then removes it; the tunnel is torn down immediately and the action is irreversible. " + "Use `list_sstp_clients` to confirm the interface name before calling this tool. " + "For L2TP, OpenVPN, or PPTP client interfaces see their respective tool scopes (`create_l2tp_client`, `create_ovpn_client`, `create_pptp_client`). " + "To deactivate the interface without deleting it use `disable_sstp_client` (re-activate with `enable_sstp_client`). " + "Returns a confirmation message on success or a not-found message if the name does not exist.",
     inputSchema: { name: z97.string() },
     async handler(a, ctx) {
       ctx.info(`Removing SSTP client: name=${a.name}`);
@@ -19832,6 +19882,40 @@ ${redactSecrets(result)}`;
         return `Failed to remove SSTP client: ${result}`;
       return `SSTP client '${a.name}' removed successfully.`;
     }
+  }),
+  defineTool({
+    name: "enable_sstp_client",
+    title: "Enable SSTP Client Interface",
+    annotations: WRITE_IDEMPOTENT,
+    description: "Enables a disabled SSTP client interface (`/interface sstp-client enable [find name=...]`), " + "causing the router to dial out and attempt the TLS connection to the remote SSTP server. " + "Use to activate a tunnel that was created disabled or stopped with `disable_sstp_client`. " + "For L2TP/PPTP/OpenVPN tunnels use their own enable tools. " + "Identifies the interface by name \u2014 create one with `create_sstp_client`.",
+    inputSchema: { name: z97.string() },
+    async handler(a, ctx) {
+      ctx.info(`Enabling SSTP client: name=${a.name}`);
+      const count = await executeMikrotikCommand(`/interface sstp-client print count-only where name="${a.name}"`, ctx);
+      if (count.trim() === "0")
+        return `SSTP client '${a.name}' not found.`;
+      const result = await executeMikrotikCommand(`/interface sstp-client enable [find name="${a.name}"]`, ctx);
+      if (looksLikeError(result))
+        return `Failed to enable SSTP client: ${result}`;
+      return `SSTP client '${a.name}' enabled successfully.`;
+    }
+  }),
+  defineTool({
+    name: "disable_sstp_client",
+    title: "Disable SSTP Client Interface",
+    annotations: WRITE_IDEMPOTENT,
+    description: "Disables an active SSTP client interface (`/interface sstp-client disable [find name=...]`), " + "tearing down the tunnel without removing its configuration. " + "Use to temporarily stop a tunnel while preserving its settings for later reuse. " + "To re-enable use `enable_sstp_client`; to permanently remove use `remove_sstp_client`.",
+    inputSchema: { name: z97.string() },
+    async handler(a, ctx) {
+      ctx.info(`Disabling SSTP client: name=${a.name}`);
+      const count = await executeMikrotikCommand(`/interface sstp-client print count-only where name="${a.name}"`, ctx);
+      if (count.trim() === "0")
+        return `SSTP client '${a.name}' not found.`;
+      const result = await executeMikrotikCommand(`/interface sstp-client disable [find name="${a.name}"]`, ctx);
+      if (looksLikeError(result))
+        return `Failed to disable SSTP client: ${result}`;
+      return `SSTP client '${a.name}' disabled successfully.`;
+    }
   })
 ];
 
@@ -24328,7 +24412,7 @@ function selectToolModules(filter = {}, catalog = moduleCatalog) {
 // src/observability/dashboard.ts
 import { readFileSync as readFileSync6 } from "fs";
 import { homedir as homedir2, networkInterfaces } from "os";
-import { join as join6 } from "path";
+import { dirname as dirname6, join as join6 } from "path";
 var {serve } = globalThis.Bun;
 import { z as z114 } from "zod";
 
@@ -24975,6 +25059,245 @@ async function openSqliteStore(path) {
   return new SqliteEventStore(db);
 }
 
+// src/observability/usage-store.ts
+import { mkdirSync as mkdirSync6 } from "fs";
+import { dirname as dirname5 } from "path";
+function dayOf(ts) {
+  return new Date(ts).toISOString().slice(0, 10);
+}
+function dailyUsageFromSamples(samples) {
+  const byDay = new Map;
+  for (let i = 1;i < samples.length; i++) {
+    const prev = samples[i - 1];
+    const cur = samples[i];
+    const dRx = cur.rx >= prev.rx ? cur.rx - prev.rx : cur.rx;
+    const dTx = cur.tx >= prev.tx ? cur.tx - prev.tx : cur.tx;
+    const day = dayOf(cur.ts);
+    const acc = byDay.get(day) ?? { rx: 0, tx: 0 };
+    acc.rx += dRx;
+    acc.tx += dTx;
+    byDay.set(day, acc);
+  }
+  return [...byDay.entries()].map(([day, v]) => ({ day, rx: v.rx, tx: v.tx })).sort((a, b) => a.day.localeCompare(b.day));
+}
+var SCHEMA_STATEMENTS3 = [
+  `CREATE TABLE IF NOT EXISTS usage_samples (
+     device TEXT NOT NULL,
+     subject TEXT NOT NULL,
+     ts INTEGER NOT NULL,
+     rx INTEGER NOT NULL,
+     tx INTEGER NOT NULL
+   )`,
+  "CREATE INDEX IF NOT EXISTS idx_usage_sub ON usage_samples(device, subject, ts)",
+  "CREATE INDEX IF NOT EXISTS idx_usage_ts ON usage_samples(ts)",
+  `CREATE TABLE IF NOT EXISTS vpn_sessions (
+     device TEXT NOT NULL,
+     session_id TEXT NOT NULL,
+     user TEXT NOT NULL,
+     service TEXT,
+     nas TEXT,
+     started INTEGER NOT NULL,
+     day TEXT NOT NULL,
+     rx INTEGER NOT NULL,
+     tx INTEGER NOT NULL,
+     PRIMARY KEY (device, session_id)
+   )`,
+  "CREATE INDEX IF NOT EXISTS idx_sess_user ON vpn_sessions(device, user, day)",
+  "CREATE INDEX IF NOT EXISTS idx_sess_day ON vpn_sessions(device, day)"
+];
+
+class SqliteUsageStore {
+  db;
+  constructor(db) {
+    this.db = db;
+    db.run("PRAGMA journal_mode = WAL");
+    db.run("PRAGMA synchronous = NORMAL");
+    for (const stmt of SCHEMA_STATEMENTS3)
+      db.run(stmt);
+  }
+  recordClientSamples(device, ts, samples) {
+    if (samples.length === 0)
+      return;
+    const insert = this.db.query("INSERT INTO usage_samples (device, subject, ts, rx, tx) VALUES ($d,$s,$ts,$rx,$tx)");
+    const tx = this.db.transaction((rows) => {
+      for (const r of rows) {
+        insert.run({ $d: device, $s: r.ip, $ts: ts, $rx: r.rx, $tx: r.tx });
+      }
+    });
+    tx(samples);
+  }
+  upsertSessions(device, sessions) {
+    if (sessions.length === 0)
+      return 0;
+    const stmt = this.db.query(`INSERT INTO vpn_sessions (device, session_id, user, service, nas, started, day, rx, tx)
+       VALUES ($d,$id,$u,$svc,$nas,$st,$day,$rx,$tx)
+       ON CONFLICT(device, session_id) DO UPDATE SET rx=excluded.rx, tx=excluded.tx`);
+    let n = 0;
+    const tx = this.db.transaction((rows) => {
+      for (const s of rows) {
+        stmt.run({
+          $d: device,
+          $id: s.sessionId,
+          $u: s.user,
+          $svc: s.service ?? null,
+          $nas: s.nas ?? null,
+          $st: s.started,
+          $day: dayOf(s.started),
+          $rx: s.rx,
+          $tx: s.tx
+        });
+        n++;
+      }
+    });
+    tx(sessions);
+    return n;
+  }
+  clientDailyUsage(device, ip, sinceTs) {
+    const rows = this.db.query("SELECT ts, rx, tx FROM usage_samples WHERE device=$d AND subject=$s AND ts>=$since ORDER BY ts ASC").all({ $d: device, $s: ip, $since: sinceTs });
+    return dailyUsageFromSamples(rows);
+  }
+  umUserDailyUsage(device, user, sinceTs) {
+    const rows = this.db.query(`SELECT day, SUM(rx) AS rx, SUM(tx) AS tx FROM vpn_sessions
+         WHERE device=$d AND user=$u AND started>=$since GROUP BY day ORDER BY day ASC`).all({ $d: device, $u: user, $since: sinceTs });
+    return rows.map((r) => ({ day: r.day, rx: Number(r.rx), tx: Number(r.tx) }));
+  }
+  umUsers(device) {
+    const rows = this.db.query("SELECT DISTINCT user FROM vpn_sessions WHERE device=$d ORDER BY user ASC").all({ $d: device });
+    return rows.map((r) => r.user);
+  }
+  heatmap(device, user, sinceTs) {
+    const sinceDay = dayOf(sinceTs);
+    const rows = user ? this.db.query("SELECT day, COUNT(*) AS count FROM vpn_sessions WHERE device=$d AND user=$u AND day>=$since GROUP BY day").all({ $d: device, $u: user, $since: sinceDay }) : this.db.query("SELECT day, COUNT(*) AS count FROM vpn_sessions WHERE device=$d AND day>=$since GROUP BY day").all({ $d: device, $since: sinceDay });
+    return rows.map((r) => ({ day: r.day, count: Number(r.count) }));
+  }
+  pruneSamples(olderThanTs) {
+    const res = this.db.query("DELETE FROM usage_samples WHERE ts < $t").run({ $t: olderThanTs });
+    return Number(res.changes ?? 0);
+  }
+  close() {
+    this.db.close();
+  }
+}
+async function openUsageStore(path) {
+  if (path !== ":memory:") {
+    try {
+      mkdirSync6(dirname5(path), { recursive: true });
+    } catch {}
+  }
+  const { Database } = await import("bun:sqlite");
+  const db = new Database(path, { create: true });
+  return new SqliteUsageStore(db);
+}
+
+// src/observability/usage-sampler.ts
+var SERVER_TAG = "mikrotik-mcp";
+var USAGE_RETENTION_MS = 93 * 24 * 60 * 60 * 1000;
+var DEFAULT_USAGE_INTERVAL_MS = 60000;
+var MIN_USAGE_INTERVAL_MS = 30000;
+var MAX_USAGE_INTERVAL_MS = 6 * 60 * 60000;
+var timer2 = null;
+var inFlight2 = false;
+var currentStore = null;
+var currentIntervalMs = DEFAULT_USAGE_INTERVAL_MS;
+function clampInterval(ms) {
+  if (!Number.isFinite(ms))
+    return DEFAULT_USAGE_INTERVAL_MS;
+  return Math.max(MIN_USAGE_INTERVAL_MS, Math.min(MAX_USAGE_INTERVAL_MS, Math.round(ms)));
+}
+function bytesOf(v) {
+  return parseSize(v) ?? parseLeadingNumber(v) ?? 0;
+}
+function ipOf(target) {
+  return (target ?? "").split("/")[0]?.trim() ?? "";
+}
+async function sampleClients(store2, device, ts) {
+  const ctx = createContext(undefined, device);
+  const out = await executeMikrotikCommand("/queue simple print stats detail", ctx);
+  if (isEmpty(out) || looksLikeError(out) || commandUnsupported(out))
+    return;
+  const samples = [];
+  for (const row of parseRecords(out).rows) {
+    const ip = ipOf(row.target ?? "");
+    if (!ip)
+      continue;
+    const [tx, rx] = (row.bytes ?? "0/0").split("/");
+    samples.push({ ip, rx: bytesOf(rx), tx: bytesOf(tx) });
+  }
+  store2.recordClientSamples(device, ts, samples);
+}
+async function ingestSessions(store2, device) {
+  const ctx = createContext(undefined, device);
+  const out = await executeMikrotikCommand("/user-manager session print detail", ctx);
+  if (isEmpty(out) || looksLikeError(out) || commandUnsupported(out))
+    return;
+  const sessions = [];
+  for (const row of parseRecords(out).rows) {
+    const user = row.user ?? "";
+    const started = parseRouterosDate(row.started ?? row["start-time"]);
+    if (!user || started == null)
+      continue;
+    const sessionId = row["acct-session-id"] || `${user}|${started}|${row["calling-station-id"] ?? row["nas-port-id"] ?? ""}`;
+    sessions.push({
+      sessionId,
+      user,
+      service: row.service,
+      nas: row["nas-ip-address"] ?? row["nas-port-id"],
+      started,
+      rx: bytesOf(row.download),
+      tx: bytesOf(row.upload)
+    });
+  }
+  store2.upsertSessions(device, sessions);
+}
+async function sampleUsageOnce(store2) {
+  if (inFlight2)
+    return;
+  inFlight2 = true;
+  const ts = Date.now();
+  try {
+    const cfg = getConfig();
+    await Promise.all(Object.entries(cfg.devices).map(async ([name, dc]) => {
+      if (dc.mac)
+        return;
+      try {
+        await sampleClients(store2, name, ts);
+        await ingestSessions(store2, name);
+      } catch (e) {
+        logger.warn(`[${SERVER_TAG}] usage sample failed for '${name}': ${String(e)}`);
+      }
+    }));
+    store2.pruneSamples(ts - USAGE_RETENTION_MS);
+  } finally {
+    inFlight2 = false;
+  }
+}
+function startUsageSampler(store2, intervalMs = DEFAULT_USAGE_INTERVAL_MS) {
+  currentStore = store2;
+  currentIntervalMs = clampInterval(intervalMs);
+  sampleUsageOnce(store2);
+  timer2 = setInterval(() => void sampleUsageOnce(store2), currentIntervalMs);
+}
+function getUsageSamplerInterval() {
+  return currentIntervalMs;
+}
+function setUsageSamplerInterval(intervalMs) {
+  currentIntervalMs = clampInterval(intervalMs);
+  if (timer2)
+    clearInterval(timer2);
+  if (currentStore) {
+    const store2 = currentStore;
+    timer2 = setInterval(() => void sampleUsageOnce(store2), currentIntervalMs);
+  }
+  return currentIntervalMs;
+}
+function stopUsageSampler() {
+  if (timer2) {
+    clearInterval(timer2);
+    timer2 = null;
+  }
+  currentStore = null;
+}
+
 // src/observability/stats.ts
 function percentile(values, p) {
   if (values.length === 0)
@@ -25069,7 +25392,7 @@ function computeStats(events, opts) {
 }
 
 // src/observability/dashboard.ts
-var SERVER_TAG = "mikrotik-mcp";
+var SERVER_TAG2 = "mikrotik-mcp";
 var JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
 function json(body, status = 200) {
   return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
@@ -25170,7 +25493,7 @@ function devicesPayload(store2) {
       avgMs: 0
     }
   }));
-  return { server: SERVER_TAG, defaultDevice: cfg.defaultDevice, devices };
+  return { server: SERVER_TAG2, defaultDevice: cfg.defaultDevice, devices };
 }
 function topologyPayload() {
   const cfg = getConfig();
@@ -25183,7 +25506,7 @@ function topologyPayload() {
   for (const { name } of devices)
     neighborsByDevice[name] = getDeviceNeighbors(name);
   return {
-    server: SERVER_TAG,
+    server: SERVER_TAG2,
     defaultDevice: cfg.defaultDevice,
     generatedAt: Date.now(),
     ...buildTopology({ devices, neighborsByDevice })
@@ -25528,6 +25851,64 @@ async function aaaRoutes(req, url) {
   }
   return null;
 }
+var usageStore = null;
+function daysParam(url, fallback, max) {
+  const n = Number(url.searchParams.get("days"));
+  return Number.isFinite(n) && n > 0 ? Math.min(n, max) : fallback;
+}
+async function usageRoutes(req, url) {
+  const p = url.pathname;
+  if (!p.startsWith("/api/usage"))
+    return null;
+  if (p === "/api/usage/sampler") {
+    if (req.method === "GET")
+      return json({ intervalMs: getUsageSamplerInterval() });
+    if (req.method === "POST") {
+      const b = await readJson(req);
+      const applied = setUsageSamplerInterval(Number(b?.intervalMs));
+      return json({ intervalMs: applied });
+    }
+    return null;
+  }
+  if (req.method !== "GET")
+    return null;
+  if (!usageStore)
+    return json({ error: "usage store not active" }, 503);
+  const device = resolveDeviceName(url.searchParams.get("device") ?? undefined);
+  const sinceTs = (days) => Date.now() - days * 86400000;
+  if (p === "/api/usage/um-users") {
+    return json({ users: usageStore.umUsers(device) });
+  }
+  if (p === "/api/usage/client") {
+    const ip = url.searchParams.get("ip");
+    if (!ip)
+      return json({ error: "ip required" }, 400);
+    const series = usageStore.clientDailyUsage(device, ip, sinceTs(daysParam(url, 90, 400)));
+    return json(withTotals(series));
+  }
+  if (p === "/api/usage/um-user") {
+    const user = url.searchParams.get("user");
+    if (!user)
+      return json({ error: "user required" }, 400);
+    const series = usageStore.umUserDailyUsage(device, user, sinceTs(daysParam(url, 90, 400)));
+    return json(withTotals(series));
+  }
+  if (p === "/api/usage/heatmap") {
+    const user = url.searchParams.get("user");
+    const days = usageStore.heatmap(device, user || null, sinceTs(daysParam(url, 371, 400)));
+    const total = days.reduce((s, d) => s + d.count, 0);
+    const max = days.reduce((m, d) => Math.max(m, d.count), 0);
+    return json({ days, total, max });
+  }
+  return null;
+}
+function withTotals(series) {
+  return {
+    series,
+    totalRx: series.reduce((s, d) => s + d.rx, 0),
+    totalTx: series.reduce((s, d) => s + d.tx, 0)
+  };
+}
 var snapStorePromise = null;
 function snapStore() {
   if (!snapStorePromise)
@@ -25746,11 +26127,17 @@ async function runDashboard(cfg, transportLabel) {
     transport: transportLabel
   });
   startHealthChecks(30000);
+  try {
+    usageStore = await openUsageStore(join6(dirname6(cfg.dbPath), "usage.db"));
+    startUsageSampler(usageStore);
+  } catch (e) {
+    logger.warn(`[${SERVER_TAG2}] usage history disabled: ${String(e)}`);
+  }
   try {
     if (isEmpty2())
       recordVersion(getConfig(), "auto", Date.now(), "baseline");
   } catch (e) {
-    logger.warn(`[${SERVER_TAG}] could not seed config history baseline: ${String(e)}`);
+    logger.warn(`[${SERVER_TAG2}] could not seed config history baseline: ${String(e)}`);
   }
   const configAdmin = createConfigAdmin({
     getConfig,
@@ -25808,6 +26195,9 @@ async function runDashboard(cfg, transportLabel) {
       const aaaResp = await aaaRoutes(req, url);
       if (aaaResp)
         return aaaResp;
+      const usageResp = await usageRoutes(req, url);
+      if (usageResp)
+        return usageResp;
       const featureResp = await featureRoutes(req, url);
       if (featureResp)
         return featureResp;
@@ -25894,8 +26284,11 @@ async function runDashboard(cfg, transportLabel) {
     store: store2,
     stop() {
       stopHealthChecks();
+      stopUsageSampler();
       server.stop(true);
       store2.close();
+      usageStore?.close();
+      usageStore = null;
     }
   };
 }
@@ -25946,6 +26339,7 @@ function corsHeaders(origin, configured) {
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/prompts/index.ts
 import { readFileSync as readFileSync7, readdirSync as readdirSync3 } from "fs";
@@ -26052,7 +26446,7 @@ function registerPrompts(server) {
 // package.json
 var package_default = {
   name: "@usex/mikrotik-mcp",
-  version: "3.25.0",
+  version: "3.27.0",
   description: "MCP server for MikroTik RouterOS \u2014 660+ tools over SSH for firewall, NAT, routing, DHCP, DNS, WireGuard, wireless, QoS and more.",
   keywords: [
     "ai",
@@ -26257,12 +26651,37 @@ function createServer(opts = {}) {
     sendLog,
     deviceNames: names,
     deviceAliases: deviceLabels(),
+    deviceDirectory: deviceDirectory(),
     readOnly
   });
   const promptCount = registerPrompts(server);
   const uiViewCount = registerUiResources(server);
+  installToolPagination(server, getConfig().mcp.toolPageSize);
   return { server, toolCount, promptCount, uiViewCount, readOnly };
 }
+function installToolPagination(server, pageSize) {
+  if (pageSize <= 0)
+    return;
+  const low = server.server;
+  const sdkHandler = low._requestHandlers?.get("tools/list");
+  if (typeof sdkHandler !== "function")
+    return;
+  let cache = null;
+  server.server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+    if (!cache)
+      cache = (await sdkHandler(request, extra)).tools ?? [];
+    const total = cache.length;
+    const cursor = request.params?.cursor;
+    let start = 0;
+    if (typeof cursor === "string") {
+      const n = Number.parseInt(cursor, 10);
+      start = Number.isFinite(n) && n > 0 ? Math.min(n, total) : 0;
+    }
+    const tools = cache.slice(start, start + pageSize);
+    const end = start + tools.length;
+    return end < total ? { tools, nextCursor: String(end) } : { tools };
+  });
+}
 
 // src/transport/http.ts
 var LOCALHOST = new Set(["127.0.0.1", "localhost", "::1", "0.0.0.0"]);