@usex/mikrotik-mcp 3.26.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.`;
+    }
   })
 ];
 
@@ -25108,8 +25192,18 @@ async function openUsageStore(path) {
 // 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;
 }
@@ -25177,15 +25271,31 @@ async function sampleUsageOnce(store2) {
     inFlight2 = false;
   }
 }
-function startUsageSampler(store2, intervalMs = 10 * 60000) {
+function startUsageSampler(store2, intervalMs = DEFAULT_USAGE_INTERVAL_MS) {
+  currentStore = store2;
+  currentIntervalMs = clampInterval(intervalMs);
   sampleUsageOnce(store2);
-  timer2 = setInterval(() => void sampleUsageOnce(store2), intervalMs);
+  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
@@ -25746,10 +25856,20 @@ function daysParam(url, fallback, max) {
   const n = Number(url.searchParams.get("days"));
   return Number.isFinite(n) && n > 0 ? Math.min(n, max) : fallback;
 }
-function usageRoutes(req, url) {
+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)
@@ -26075,7 +26195,7 @@ async function runDashboard(cfg, transportLabel) {
       const aaaResp = await aaaRoutes(req, url);
       if (aaaResp)
         return aaaResp;
-      const usageResp = usageRoutes(req, url);
+      const usageResp = await usageRoutes(req, url);
       if (usageResp)
         return usageResp;
       const featureResp = await featureRoutes(req, url);
@@ -26219,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";
@@ -26325,7 +26446,7 @@ function registerPrompts(server) {
 // package.json
 var package_default = {
   name: "@usex/mikrotik-mcp",
-  version: "3.26.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",
@@ -26530,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"]);

package/dist/index.d.ts

@@ -46,6 +46,35 @@ interface UiLink {
 	*/
 	visibility?: ("model" | "app")[];
 }
+declare function setConfig(cfg: MikrotikConfig): void;
+declare function getConfig(): MikrotikConfig;
+/** Names of every configured device, plus which one is the default. */
+declare function listDevices(): {
+	names: string[];
+	default: string;
+};
+/**
+* Resolve a (possibly undefined) device name to a concrete, existing config key.
+* Accepts a config key OR a device's free-text label; falls back to the default.
+*
+* Matching is EXACT (key first, then label) — never fuzzy/substring — so a name
+* like "Ali Home" can never collapse onto a different device such as "home".
+*/
+declare function resolveDeviceName(name?: string): string;
+/** One row of the human-facing device directory shown in the `device` selector. */
+interface DeviceDirectoryEntry {
+	key: string;
+	label?: string;
+	/** Where it connects: `host:port`, or `MAC <addr>` for a MAC-Telnet device. */
+	target: string;
+	isDefault: boolean;
+}
+/**
+* Return the connection config for a device by key or label (or the default when
+* `name` is undefined). Throws if an explicit name matches neither a key nor a
+* label.
+*/
+declare function getDevice(name?: string): DeviceConfig;
 /** Options threaded into every tool registration. */
 interface RegisterOptions {
 	sendLog?: SendLog;
@@ -59,6 +88,12 @@ interface RegisterOptions {
 	*/
 	deviceAliases?: string[];
 	/**
+	* Human-facing directory of every device (key → label → target), used to make
+	* the `device` selector's description unambiguous so the model can tell
+	* similarly-named routers apart and never substitute one for another.
+	*/
+	deviceDirectory?: DeviceDirectoryEntry[];
+	/**
 	* Read-only mode: register only tools annotated `readOnlyHint`. Used to
 	* withhold every write/destructive tool from a publicly-exposed surface (e.g.
 	* a ChatGPT Apps connector) until authentication is in place.
@@ -110,24 +145,6 @@ declare function defineTool<Shape extends ZodRawShape>(def: ToolDef<Shape>): Reg
 type ToolModule = RegisterableTool[];
 /** Register every tool from every module, returning the total count. */
 declare function registerTools(server: McpServer, modules: ToolModule[], opts?: RegisterOptions): number;
-declare function setConfig(cfg: MikrotikConfig): void;
-declare function getConfig(): MikrotikConfig;
-/** Names of every configured device, plus which one is the default. */
-declare function listDevices(): {
-	names: string[];
-	default: string;
-};
-/**
-* Resolve a (possibly undefined) device name to a concrete, existing config key.
-* Accepts a config key OR a device's free-text label; falls back to the default.
-*/
-declare function resolveDeviceName(name?: string): string;
-/**
-* Return the connection config for a device by key or label (or the default when
-* `name` is undefined). Throws if an explicit name matches neither a key nor a
-* label.
-*/
-declare function getDevice(name?: string): DeviceConfig;
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 interface CreatedServer {
 	server: McpServer2;