@usex/mikrotik-mcp 3.18.0 → 3.19.0

package/dist/cli.js

@@ -2174,7 +2174,7 @@ ${result}`;
     name: "create_export",
     title: "Create Full Configuration Export",
     annotations: READ,
-    description: "Exports the complete device configuration to a `.rsc` plain-text script file (`/export" + " file=<name>`), re-applicable via `import_configuration`. Unlike `create_backup`, the result" + " is human-readable plain text \u2014 not a binary snapshot \u2014 and passwords are hidden by default" + " (`hide_sensitive=true`). `file_format` changes only the file extension used when looking up" + " the saved file \u2014 no `format=` flag is ever sent to RouterOS, so the content is always" + " RouterOS script text regardless of the chosen extension; selecting `json` or `xml` will also" + " cause the post-export file lookup to fail because RouterOS saves the file as `.rsc`. Use the" + " `compact` boolean to omit default values, or `verbose` to include all parameters;" + " `export_type` only controls where the `file=` argument is positioned in the command and" + " does not independently drive compactness or verbosity. For a single subsection only use" + " `export_section`. Returns file details of the created export file.",
+    description: "Exports the complete device configuration to a `.rsc` plain-text script file (`/export" + " file=<name>`), re-applicable via `import_configuration`. Unlike `create_backup`, the result" + " is human-readable plain text \u2014 not a binary snapshot \u2014 and passwords are hidden by default" + " (`hide_sensitive=true`). `file_format` changes only the file extension used when looking up" + " the saved file \u2014 no `format=` flag is ever sent to RouterOS, so the content is always" + " RouterOS script text regardless of the chosen extension; selecting `json` or `xml` will also" + " cause the post-export file lookup to fail because RouterOS saves the file as `.rsc`." + " ALWAYS default to a FULL configuration export: leave `compact` and `verbose` off (the plain" + " full export) unless the user explicitly asks for less or more. Set `compact` ONLY when the" + " user wants a smaller diff that omits default values, or `verbose` ONLY when they want every" + " parameter (including defaults). `export_type` only controls where the `file=` argument is" + " positioned in the command and does not independently drive compactness or verbosity. For a" + " single subsection only use `export_section`. Returns file details of the created export file.",
     inputSchema: {
       name: z4.string().optional(),
       file_format: z4.enum(["rsc", "json", "xml"]).default("rsc"),
@@ -2367,6 +2367,12 @@ ${result}`;
 // src/tools/local-backup.ts
 import { z as z5 } from "zod";
 
+// src/core/slug.ts
+function deviceSlug(name) {
+  const s = (name ?? "").replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return s || "device";
+}
+
 // src/backups/vault.ts
 import {
   existsSync,
@@ -2487,15 +2493,17 @@ function labelSlug(label) {
   const s = (label ?? "").replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
   return s ? `_${s}` : "";
 }
+function buildExportCommand(opts = {}) {
+  return new Cmd("/export").raw(opts.verbose ? "verbose" : opts.compact ? "compact" : undefined).raw(opts.terse ? "terse" : undefined).raw(opts.showSensitive ? "show-sensitive" : undefined).build();
+}
 async function createLocalBackup(ctx, opts = {}) {
   const device = resolveDeviceName(ctx.device);
-  const cmd = new Cmd("/export").raw(opts.showSensitive ? "show-sensitive" : undefined).build();
-  const body = await executeMikrotikCommand(cmd, ctx);
+  const body = await executeMikrotikCommand(buildExportCommand(opts), ctx);
   if (isEmpty(body) || looksLikeError(body)) {
     return { ok: false, device, error: body.trim() || "(empty export)" };
   }
   const stamp = await deviceDateStamp(ctx);
-  const name = `${device}_${stamp}${labelSlug(opts.label)}.rsc`;
+  const name = `${deviceSlug(device)}_${stamp}${labelSlug(opts.label)}.rsc`;
   return { ok: true, device, name: writeBackup(name, body), bytes: Buffer.byteLength(body) };
 }
 
@@ -2566,13 +2574,22 @@ var localBackupTools = [
     name: "create_local_backup",
     title: "Create Local Config Backup (host vault)",
     annotations: WRITE,
-    description: "Captures the device's full configuration with `/export` and saves it as a timestamped " + "plain-text `.rsc` file in the MCP server's LOCAL backup vault (default " + "`~/.mikrotik-mcp/backups/`, override with the `MIKROTIK_BACKUP_DIR` env var) \u2014 NOT on the " + "device and NOT in S3. The filename is `<device>_<date_time>.rsc` stamped in the device's " + "local clock (24-hour; Jalali for the Tehran timezone, Gregorian otherwise). This is a " + "host-side, human-readable, diffable copy you can restore later with restore_local_backup. " + "Compare: create_backup makes a binary `/system backup` file ON the device; " + "capture_config_snapshot stores an export in the local snapshot database; upload_backup_to_s3 " + "pushes to S3. show_sensitive=true includes secrets (keys/passwords) in the export. " + "Returns the saved filename, byte size and vault path.",
+    description: "Captures the device's full configuration with `/export` and saves it as a timestamped " + "plain-text `.rsc` file in the MCP server's LOCAL backup vault (default " + "`~/.mikrotik-mcp/backups/`, override with the `MIKROTIK_BACKUP_DIR` env var) \u2014 NOT on the " + "device and NOT in S3. The filename is `<device-slug>_<date_time>.rsc` \u2014 the device name is " + "slugified (spaces/underscores/etc \u2192 dash) \u2014 stamped in the device's local clock (24-hour; " + "Jalali for the Tehran timezone, Gregorian otherwise). This is a host-side, human-readable, " + "diffable copy you can restore later with restore_local_backup. Compare: create_backup makes " + "a binary `/system backup` file ON the device; capture_config_snapshot stores an export in " + "the local snapshot database; upload_backup_to_s3 pushes to S3. ALWAYS default to a FULL " + "backup of the complete configuration: call this with no option flags (the bare `/export`) " + "unless the user explicitly asks for less or more. Narrow it ONLY on request \u2014 set compact to " + "drop default values, or use export_section for a single subsection. Broaden it ONLY on " + "request \u2014 set verbose to include every parameter (even defaults), show_sensitive to include " + "secrets (keys/passwords), or use create_backup for a binary full-system snapshot. terse just " + "changes the text to one machine-readable line per item. Returns the saved filename, byte size " + "and vault path.",
     inputSchema: {
       label: z5.string().optional().describe('Optional label appended to the filename, e.g. "pre-upgrade".'),
-      show_sensitive: z5.boolean().default(false).describe("Include secrets (keys/passwords) in the export. Default false.")
+      show_sensitive: z5.boolean().default(false).describe("Include secrets (keys/passwords) in the export. Default false."),
+      verbose: z5.boolean().default(false).describe("Include every parameter, even defaults (RouterOS `verbose`)."),
+      compact: z5.boolean().default(false).describe("Export only non-default values (RouterOS `compact`; ignored if verbose)."),
+      terse: z5.boolean().default(false).describe("One self-contained, machine-readable line per item (RouterOS `terse`).")
     },
     async handler(a, ctx) {
-      const r = await createLocalBackup(ctx, { label: a.label, showSensitive: a.show_sensitive });
+      const r = await createLocalBackup(ctx, {
+        label: a.label,
+        showSensitive: a.show_sensitive,
+        verbose: a.verbose,
+        compact: a.compact,
+        terse: a.terse
+      });
       if (!r.ok)
         return `Failed to capture export for a local backup: ${r.error}`;
       return `Saved local backup '${r.name}' (${r.bytes} bytes) for device '${r.device}' to ` + `${backupDir()}. Restore it with restore_local_backup name=${r.name}.`;
@@ -2708,7 +2725,7 @@ function trimSlashes(s) {
   return s.replace(/^\/+|\/+$/g, "");
 }
 function s3DevicePrefix(device) {
-  const segments = [getS3Config()?.prefix ?? "", device ?? ""].map(trimSlashes).filter(Boolean);
+  const segments = [getS3Config()?.prefix ?? "", device ? deviceSlug(device) : ""].map(trimSlashes).filter(Boolean);
   return segments.length ? `${segments.join("/")}/` : "";
 }
 function s3Key(name, device) {
@@ -23449,7 +23466,10 @@ async function featureRoutes(req, url) {
     const ctx = createContext(undefined, b?.device);
     const r = await createLocalBackup(ctx, {
       label: b?.label,
-      showSensitive: b?.show_sensitive === true
+      showSensitive: b?.show_sensitive === true,
+      verbose: b?.verbose === true,
+      compact: b?.compact === true,
+      terse: b?.terse === true
     });
     return r.ok ? json(r) : json({ error: r.error ?? "export failed" }, 502);
   }
@@ -23768,7 +23788,7 @@ function registerPrompts(server) {
 // package.json
 var package_default = {
   name: "@usex/mikrotik-mcp",
-  version: "3.18.0",
+  version: "3.19.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",

package/dist/index.js

@@ -2186,7 +2186,7 @@ ${result}`;
     name: "create_export",
     title: "Create Full Configuration Export",
     annotations: READ,
-    description: "Exports the complete device configuration to a `.rsc` plain-text script file (`/export" + " file=<name>`), re-applicable via `import_configuration`. Unlike `create_backup`, the result" + " is human-readable plain text \u2014 not a binary snapshot \u2014 and passwords are hidden by default" + " (`hide_sensitive=true`). `file_format` changes only the file extension used when looking up" + " the saved file \u2014 no `format=` flag is ever sent to RouterOS, so the content is always" + " RouterOS script text regardless of the chosen extension; selecting `json` or `xml` will also" + " cause the post-export file lookup to fail because RouterOS saves the file as `.rsc`. Use the" + " `compact` boolean to omit default values, or `verbose` to include all parameters;" + " `export_type` only controls where the `file=` argument is positioned in the command and" + " does not independently drive compactness or verbosity. For a single subsection only use" + " `export_section`. Returns file details of the created export file.",
+    description: "Exports the complete device configuration to a `.rsc` plain-text script file (`/export" + " file=<name>`), re-applicable via `import_configuration`. Unlike `create_backup`, the result" + " is human-readable plain text \u2014 not a binary snapshot \u2014 and passwords are hidden by default" + " (`hide_sensitive=true`). `file_format` changes only the file extension used when looking up" + " the saved file \u2014 no `format=` flag is ever sent to RouterOS, so the content is always" + " RouterOS script text regardless of the chosen extension; selecting `json` or `xml` will also" + " cause the post-export file lookup to fail because RouterOS saves the file as `.rsc`." + " ALWAYS default to a FULL configuration export: leave `compact` and `verbose` off (the plain" + " full export) unless the user explicitly asks for less or more. Set `compact` ONLY when the" + " user wants a smaller diff that omits default values, or `verbose` ONLY when they want every" + " parameter (including defaults). `export_type` only controls where the `file=` argument is" + " positioned in the command and does not independently drive compactness or verbosity. For a" + " single subsection only use `export_section`. Returns file details of the created export file.",
     inputSchema: {
       name: z5.string().optional(),
       file_format: z5.enum(["rsc", "json", "xml"]).default("rsc"),
@@ -2379,6 +2379,12 @@ ${result}`;
 // src/tools/local-backup.ts
 import { z as z6 } from "zod";
 
+// src/core/slug.ts
+function deviceSlug(name) {
+  const s = (name ?? "").replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return s || "device";
+}
+
 // src/backups/vault.ts
 import {
   existsSync,
@@ -2499,15 +2505,17 @@ function labelSlug(label) {
   const s = (label ?? "").replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
   return s ? `_${s}` : "";
 }
+function buildExportCommand(opts = {}) {
+  return new Cmd("/export").raw(opts.verbose ? "verbose" : opts.compact ? "compact" : undefined).raw(opts.terse ? "terse" : undefined).raw(opts.showSensitive ? "show-sensitive" : undefined).build();
+}
 async function createLocalBackup(ctx, opts = {}) {
   const device = resolveDeviceName(ctx.device);
-  const cmd = new Cmd("/export").raw(opts.showSensitive ? "show-sensitive" : undefined).build();
-  const body = await executeMikrotikCommand(cmd, ctx);
+  const body = await executeMikrotikCommand(buildExportCommand(opts), ctx);
   if (isEmpty(body) || looksLikeError(body)) {
     return { ok: false, device, error: body.trim() || "(empty export)" };
   }
   const stamp = await deviceDateStamp(ctx);
-  const name = `${device}_${stamp}${labelSlug(opts.label)}.rsc`;
+  const name = `${deviceSlug(device)}_${stamp}${labelSlug(opts.label)}.rsc`;
   return { ok: true, device, name: writeBackup(name, body), bytes: Buffer.byteLength(body) };
 }
 
@@ -2578,13 +2586,22 @@ var localBackupTools = [
     name: "create_local_backup",
     title: "Create Local Config Backup (host vault)",
     annotations: WRITE,
-    description: "Captures the device's full configuration with `/export` and saves it as a timestamped " + "plain-text `.rsc` file in the MCP server's LOCAL backup vault (default " + "`~/.mikrotik-mcp/backups/`, override with the `MIKROTIK_BACKUP_DIR` env var) \u2014 NOT on the " + "device and NOT in S3. The filename is `<device>_<date_time>.rsc` stamped in the device's " + "local clock (24-hour; Jalali for the Tehran timezone, Gregorian otherwise). This is a " + "host-side, human-readable, diffable copy you can restore later with restore_local_backup. " + "Compare: create_backup makes a binary `/system backup` file ON the device; " + "capture_config_snapshot stores an export in the local snapshot database; upload_backup_to_s3 " + "pushes to S3. show_sensitive=true includes secrets (keys/passwords) in the export. " + "Returns the saved filename, byte size and vault path.",
+    description: "Captures the device's full configuration with `/export` and saves it as a timestamped " + "plain-text `.rsc` file in the MCP server's LOCAL backup vault (default " + "`~/.mikrotik-mcp/backups/`, override with the `MIKROTIK_BACKUP_DIR` env var) \u2014 NOT on the " + "device and NOT in S3. The filename is `<device-slug>_<date_time>.rsc` \u2014 the device name is " + "slugified (spaces/underscores/etc \u2192 dash) \u2014 stamped in the device's local clock (24-hour; " + "Jalali for the Tehran timezone, Gregorian otherwise). This is a host-side, human-readable, " + "diffable copy you can restore later with restore_local_backup. Compare: create_backup makes " + "a binary `/system backup` file ON the device; capture_config_snapshot stores an export in " + "the local snapshot database; upload_backup_to_s3 pushes to S3. ALWAYS default to a FULL " + "backup of the complete configuration: call this with no option flags (the bare `/export`) " + "unless the user explicitly asks for less or more. Narrow it ONLY on request \u2014 set compact to " + "drop default values, or use export_section for a single subsection. Broaden it ONLY on " + "request \u2014 set verbose to include every parameter (even defaults), show_sensitive to include " + "secrets (keys/passwords), or use create_backup for a binary full-system snapshot. terse just " + "changes the text to one machine-readable line per item. Returns the saved filename, byte size " + "and vault path.",
     inputSchema: {
       label: z6.string().optional().describe('Optional label appended to the filename, e.g. "pre-upgrade".'),
-      show_sensitive: z6.boolean().default(false).describe("Include secrets (keys/passwords) in the export. Default false.")
+      show_sensitive: z6.boolean().default(false).describe("Include secrets (keys/passwords) in the export. Default false."),
+      verbose: z6.boolean().default(false).describe("Include every parameter, even defaults (RouterOS `verbose`)."),
+      compact: z6.boolean().default(false).describe("Export only non-default values (RouterOS `compact`; ignored if verbose)."),
+      terse: z6.boolean().default(false).describe("One self-contained, machine-readable line per item (RouterOS `terse`).")
     },
     async handler(a, ctx) {
-      const r = await createLocalBackup(ctx, { label: a.label, showSensitive: a.show_sensitive });
+      const r = await createLocalBackup(ctx, {
+        label: a.label,
+        showSensitive: a.show_sensitive,
+        verbose: a.verbose,
+        compact: a.compact,
+        terse: a.terse
+      });
       if (!r.ok)
         return `Failed to capture export for a local backup: ${r.error}`;
       return `Saved local backup '${r.name}' (${r.bytes} bytes) for device '${r.device}' to ` + `${backupDir()}. Restore it with restore_local_backup name=${r.name}.`;
@@ -2720,7 +2737,7 @@ function trimSlashes(s) {
   return s.replace(/^\/+|\/+$/g, "");
 }
 function s3DevicePrefix(device) {
-  const segments = [getS3Config()?.prefix ?? "", device ?? ""].map(trimSlashes).filter(Boolean);
+  const segments = [getS3Config()?.prefix ?? "", device ? deviceSlug(device) : ""].map(trimSlashes).filter(Boolean);
   return segments.length ? `${segments.join("/")}/` : "";
 }
 function s3Key(name, device) {
@@ -22171,7 +22188,7 @@ function selectToolModules(filter = {}, catalog = moduleCatalog) {
 // package.json
 var package_default = {
   name: "@usex/mikrotik-mcp",
-  version: "3.18.0",
+  version: "3.19.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",