@usex/mikrotik-mcp 3.32.1 → 3.33.0

package/README.md

@@ -63,6 +63,9 @@ in memory and auto-reverts if your session drops, so you can't lock yourself out
 - 🖧 **Multiple devices** — define named routers and the AI targets one per call
   (a validated `device` argument). Configure **both ends of a tunnel** from one
   conversation. See **[docs/multi-device.md](docs/multi-device.md)**.
+- 🪜 **SSH jump hosts** — reach a router with no exposed port by tunnelling
+  through another via `jumpVia` (ProxyJump/bastion) — commands, Safe Mode and
+  file upload all ride the hop. No new WAN port.
 - 🤖 **Guided prompts** — 9 built-in workflows (harden, diagnose, guest Wi-Fi, VPNs,
   cross-device tunnels, backup & document) that turn an intent into tool calls.
 
@@ -179,6 +182,17 @@ drives the whole both-ends flow. Full guide: **[docs/multi-device.md](docs/multi
 // create_wireguard_interface { "device": "site-a", "name": "wg-to-b", "listen_port": 13231 }
 ```
 
+**Behind a bastion?** Reach a router with no exposed SSH port by jumping through
+another (OpenSSH-style ProxyJump) — `jumpVia` names a configured device to tunnel
+through; commands, Safe Mode and SFTP upload all ride the hop:
+
+```jsonc
+"home-ax3": { "host": "10.10.30.100", "username": "admin", "jumpVia": "hex" }
+```
+
+The bastion router needs SSH TCP forwarding enabled (`/ip ssh set
+forwarding-enabled=local`). See **[docs/multi-device.md](docs/multi-device.md#ssh-jump-hosts-bastion--proxyjump)**.
+
 ## Built-in prompts
 
 MCP **prompts** are one-click guided workflows. This server ships 9 — authored as
@@ -220,20 +234,21 @@ See **[docs/safe-mode.md](docs/safe-mode.md)**.
 Connection and transport settings come from `MIKROTIK_*` env vars or matching CLI
 flags (highest precedence last: defaults → env → flags).
 
-| Variable                      | Flag               | Default     | Purpose                                                           |
-| ----------------------------- | ------------------ | ----------- | ----------------------------------------------------------------- |
-| `MIKROTIK_HOST`               | `--host`           | `127.0.0.1` | RouterOS host                                                     |
-| `MIKROTIK_USERNAME`           | `--username`       | `admin`     | SSH user                                                          |
-| `MIKROTIK_PORT`               | `--port`           | `22`        | SSH port                                                          |
-| `MIKROTIK_PASSWORD`           | `--password`       | —           | SSH password _(or use a key →)_                                   |
-| `MIKROTIK_KEY_FILENAME`       | `--key-filename`   | —           | SSH private-key file path                                         |
-| `MIKROTIK_PRIVATE_KEY`        | `--private-key`    | —           | Inline private key (PEM)                                          |
-| `MIKROTIK_KEY_PASSPHRASE`     | `--key-passphrase` | —           | Passphrase for an encrypted key                                   |
-| `MIKROTIK_CONFIG_FILE`        | `--config`         | —           | JSON file of named devices ([multi-device](docs/multi-device.md)) |
-| `MIKROTIK_DEVICES`            | `--devices`        | —           | Inline JSON of named devices                                      |
-| `MIKROTIK_MCP__TRANSPORT`     | `--transport`      | `stdio`     | `stdio` / `streamable-http` / `sse`                               |
-| `MIKROTIK_MCP__PORT`          | `--mcp-port`       | `8000`      | HTTP bind port                                                    |
-| `MIKROTIK_DASHBOARD__ENABLED` | `--dashboard`      | `false`     | Real-time observability dashboard ([docs](docs/observability.md)) |
+| Variable                      | Flag               | Default     | Purpose                                                                                              |
+| ----------------------------- | ------------------ | ----------- | ---------------------------------------------------------------------------------------------------- |
+| `MIKROTIK_HOST`               | `--host`           | `127.0.0.1` | RouterOS host                                                                                        |
+| `MIKROTIK_USERNAME`           | `--username`       | `admin`     | SSH user                                                                                             |
+| `MIKROTIK_PORT`               | `--port`           | `22`        | SSH port                                                                                             |
+| `MIKROTIK_PASSWORD`           | `--password`       | —           | SSH password _(or use a key →)_                                                                      |
+| `MIKROTIK_KEY_FILENAME`       | `--key-filename`   | —           | SSH private-key file path                                                                            |
+| `MIKROTIK_PRIVATE_KEY`        | `--private-key`    | —           | Inline private key (PEM)                                                                             |
+| `MIKROTIK_KEY_PASSPHRASE`     | `--key-passphrase` | —           | Passphrase for an encrypted key                                                                      |
+| `MIKROTIK_JUMP_HOST`          | `--jump-host`      | —           | SSH bastion to tunnel through ([jump hosts](docs/multi-device.md#ssh-jump-hosts-bastion--proxyjump)) |
+| `MIKROTIK_CONFIG_FILE`        | `--config`         | —           | JSON file of named devices ([multi-device](docs/multi-device.md))                                    |
+| `MIKROTIK_DEVICES`            | `--devices`        | —           | Inline JSON of named devices                                                                         |
+| `MIKROTIK_MCP__TRANSPORT`     | `--transport`      | `stdio`     | `stdio` / `streamable-http` / `sse`                                                                  |
+| `MIKROTIK_MCP__PORT`          | `--mcp-port`       | `8000`      | HTTP bind port                                                                                       |
+| `MIKROTIK_DASHBOARD__ENABLED` | `--dashboard`      | `false`     | Real-time observability dashboard ([docs](docs/observability.md))                                    |
 
 Full table (incl. HTTP host, allow-lists, timeouts, `MIKROTIK_LOG_LEVEL`):
 **[docs/configuration.md](docs/configuration.md)**.

package/dist/cli.js

@@ -84,7 +84,7 @@ import {
   toggleAaaEntity,
   updateAaaEntity,
   writeBackup
-} from "./shared/cli-t84nm0d4.js";
+} from "./shared/cli-gt8xtjx9.js";
 
 // src/cli.ts
 import { existsSync as existsSync2 } from "fs";
@@ -2231,7 +2231,7 @@ function registerPrompts(server) {
 // package.json
 var package_default = {
   name: "@usex/mikrotik-mcp",
-  version: "3.32.1",
+  version: "3.33.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",
@@ -2707,16 +2707,20 @@ async function main() {
   warnIfPlaintextPasswordInContainer(Object.values(cfg.devices).some((d) => !!d.password));
   const deviceNames = Object.keys(cfg.devices);
   logger.info(`Starting ${SERVER_NAME} v${VERSION} (transport=${cfg.mcp.transport}, ` + `devices=${deviceNames.length === 1 ? deviceNames[0] : deviceNames.join("/")})`);
-  if (cfg.dashboard.enabled) {
+  const startDashboard = async () => {
+    if (!cfg.dashboard.enabled)
+      return;
     try {
       await runDashboard(cfg.dashboard, cfg.mcp.transport);
     } catch (e) {
       logger.error(`Failed to start observability dashboard: ${e instanceof Error ? e.message : String(e)}. ` + "Continuing without it.");
     }
-  }
+  };
   if (cfg.mcp.transport === "stdio") {
     await runStdio();
+    await startDashboard();
   } else {
+    await startDashboard();
     await runHttp(cfg.mcp);
   }
 }

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-/** Connection details for a single MikroTik device. */
 declare const DeviceConfigSchema: unknown;
 type DeviceConfig = z.infer<typeof DeviceConfigSchema>;
 declare const MikrotikConfigSchema: unknown;
@@ -184,15 +183,47 @@ interface SSHClientOptions {
 	/** Passphrase for an encrypted private key. */
 	keyPassphrase?: string;
 	timeoutMs?: number;
+	/**
+	* Optional SSH jump host (bastion / ProxyJump). When set, `connect()` reaches
+	* `host:port` THROUGH this hop: it opens an SSH session to the hop, asks it to
+	* `forwardOut` a TCP channel to the target, then runs the real SSH session
+	* over that channel. So the target never needs a port exposed to the network —
+	* only the bastion is reachable. The hop is itself an SSH endpoint and may
+	* carry its own `jump` for a multi-hop chain (A → B → target).
+	*/
+	jump?: SSHClientOptions;
 }
 declare class MikroTikSSHClient {
 	private client;
+	/**
+	* Open bastion connections, outermost-first, kept alive for the lifetime of
+	* the session (the target's transport rides a channel on the last one). Closed
+	* in reverse on `disconnect()`.
+	*/
+	private bastions;
 	private readonly opts;
 	/** Human-readable reason the last `connect()` failed, if it did. */
 	lastError?: string;
 	constructor(opts: SSHClientOptions);
-	/** Establish the SSH connection. Resolves `true` on success, `false` on failure. */
+	/**
+	* Establish the SSH connection — directly, or through one or more jump hosts
+	* when `opts.jump` is set. Resolves `true` on success, `false` on failure
+	* (with the reason on `lastError`).
+	*/
 	connect(): Promise<boolean>;
+	/**
+	* Open one ssh2 connection. When `sock` is given the connection rides that
+	* stream (a forwarded channel from a jump host) instead of dialling the
+	* network directly. Resolves the ready `Client`; rejects with a clear reason.
+	*/
+	private openClient;
+	/**
+	* Ask a connected jump host to open a TCP channel to `host:port` and resolve
+	* the resulting stream (used as the next hop's transport `sock`). A RouterOS
+	* bastion rejects this unless SSH TCP forwarding is enabled, so the failure
+	* names the exact fix.
+	*/
+	private forwardOut;
 	/** Run a single command on a fresh SSH channel and return its decoded output. */
 	run(command: string, opts?: {
 		maxMs?: number;
@@ -211,7 +242,7 @@ declare class MikroTikSSHClient {
 		cols?: number;
 		rows?: number;
 	}): Promise<ClientChannel>;
-	/** Close the SSH connection. Safe to call multiple times. */
+	/** Close the SSH connection (and any jump hosts). Safe to call multiple times. */
 	disconnect(): void;
 }
 /**

package/dist/index.js

@@ -21,7 +21,7 @@ import {
   resolveDeviceName,
   selectToolModules,
   setConfig
-} from "./shared/library-bj9xrcg0.js";
+} from "./shared/library-aa58hkb4.js";
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -131,7 +131,7 @@ function registerPrompts(server) {
 // package.json
 var package_default = {
   name: "@usex/mikrotik-mcp",
-  version: "3.32.1",
+  version: "3.33.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/shared/{cli-ytn5v321.js → cli-g5kqcrt4.js}

@@ -4,7 +4,7 @@ import {
   allToolModules,
   moduleCatalog,
   selectToolModules
-} from "./cli-t84nm0d4.js";
+} from "./cli-gt8xtjx9.js";
 export {
   selectToolModules,
   moduleCatalog,

package/dist/shared/{cli-t84nm0d4.js → cli-gt8xtjx9.js}

@@ -25,6 +25,16 @@ var McpServerSettingsSchema = z.object({
   toolPageSize: z.coerce.number().int().min(0).default(0),
   appViews: z.boolean().default(true)
 });
+var JumpHostSchema = z.object({
+  host: z.string(),
+  port: z.coerce.number().int().positive().default(22),
+  username: z.string().default("admin"),
+  password: z.string().optional(),
+  keyFilename: z.string().optional(),
+  privateKey: z.string().optional(),
+  keyPassphrase: z.string().optional(),
+  timeoutMs: z.coerce.number().int().positive().optional()
+});
 var DeviceConfigSchema = z.object({
   host: z.string().default("127.0.0.1"),
   username: z.string().default("admin"),
@@ -34,6 +44,8 @@ var DeviceConfigSchema = z.object({
   privateKey: z.string().optional(),
   keyPassphrase: z.string().optional(),
   timeoutMs: z.coerce.number().int().positive().default(1e4),
+  jumpVia: z.string().optional(),
+  jumpHost: JumpHostSchema.optional(),
   mac: z.string().optional(),
   sourceMac: z.string().optional(),
   macHost: z.string().optional(),
@@ -131,6 +143,15 @@ function getConfigSource() {
 function loadConfig(argv = process.argv.slice(2)) {
   const flags = parseFlags(argv);
   const pick = (flag, ...envNames) => flags[flag] ?? env(...envNames);
+  const jumpHostName = pick("jump-host", "MIKROTIK_JUMP_HOST");
+  const jumpHost = jumpHostName ? {
+    host: jumpHostName,
+    port: pick("jump-port", "MIKROTIK_JUMP_PORT"),
+    username: pick("jump-username", "MIKROTIK_JUMP_USERNAME"),
+    password: pick("jump-password", "MIKROTIK_JUMP_PASSWORD"),
+    keyFilename: pick("jump-key-filename", "MIKROTIK_JUMP_KEY_FILENAME"),
+    keyPassphrase: pick("jump-key-passphrase", "MIKROTIK_JUMP_KEY_PASSPHRASE")
+  } : undefined;
   const single = {
     host: pick("host", "MIKROTIK_HOST"),
     username: pick("username", "MIKROTIK_USERNAME"),
@@ -140,6 +161,7 @@ function loadConfig(argv = process.argv.slice(2)) {
     privateKey: pick("private-key", "MIKROTIK_PRIVATE_KEY"),
     keyPassphrase: pick("key-passphrase", "MIKROTIK_KEY_PASSPHRASE"),
     timeoutMs: pick("timeout-ms", "MIKROTIK_TIMEOUT_MS"),
+    jumpHost,
     mac: pick("mac", "MIKROTIK_MAC"),
     sourceMac: pick("source-mac", "MIKROTIK_SOURCE_MAC"),
     macHost: pick("mac-host", "MIKROTIK_MAC_HOST"),
@@ -706,45 +728,72 @@ function decodeOutput(data) {
 
 class MikroTikSSHClient {
   client = null;
+  bastions = [];
   opts;
   lastError;
   constructor(opts) {
     this.opts = { port: 22, timeoutMs: 1e4, ...opts };
   }
-  connect() {
+  async connect() {
     this.lastError = undefined;
-    return new Promise((resolve2) => {
+    try {
+      const hops = [];
+      for (let j = this.opts.jump;j; j = j.jump)
+        hops.unshift(j);
+      const sequence = [...hops, this.opts];
+      let sock;
+      for (let i = 0;i < hops.length; i++) {
+        const client = await this.openClient(hops[i], sock);
+        this.bastions.push(client);
+        const next = sequence[i + 1];
+        sock = await this.forwardOut(client, next.host, next.port ?? 22);
+      }
+      this.client = await this.openClient(this.opts, sock);
+      return true;
+    } catch (e) {
+      this.lastError = e instanceof Error ? e.message : String(e);
+      logger.error(`Failed to connect to MikroTik: ${this.lastError}`);
+      this.disconnect();
+      return false;
+    }
+  }
+  openClient(o, sock) {
+    return new Promise((resolve2, reject) => {
       const client = new Client;
       const cfg = {
-        host: this.opts.host,
-        port: this.opts.port,
-        username: this.opts.username,
-        readyTimeout: this.opts.timeoutMs
+        host: o.host,
+        port: o.port ?? 22,
+        username: o.username,
+        readyTimeout: o.timeoutMs ?? 1e4
       };
-      if (this.opts.privateKey) {
-        cfg.privateKey = this.opts.privateKey;
-      } else if (this.opts.keyFilename) {
+      if (sock)
+        cfg.sock = sock;
+      if (o.privateKey) {
+        cfg.privateKey = o.privateKey;
+      } else if (o.keyFilename) {
         try {
-          cfg.privateKey = readFileSync2(this.opts.keyFilename);
+          cfg.privateKey = readFileSync2(o.keyFilename);
         } catch (e) {
-          this.lastError = `could not read key file ${this.opts.keyFilename}: ${e instanceof Error ? e.message : String(e)}`;
-          logger.error(`Failed to read SSH key file ${this.opts.keyFilename}: ${String(e)}`);
-          resolve2(false);
+          reject(new Error(`could not read key file ${o.keyFilename}: ${e instanceof Error ? e.message : String(e)}`));
           return;
         }
       }
-      if (cfg.privateKey && this.opts.keyPassphrase)
-        cfg.passphrase = this.opts.keyPassphrase;
-      if (this.opts.password)
-        cfg.password = this.opts.password;
-      client.on("ready", () => {
-        this.client = client;
-        resolve2(true);
-      }).on("error", (err) => {
-        this.lastError = err.message;
-        logger.error(`Failed to connect to MikroTik: ${err.message}`);
-        resolve2(false);
-      }).connect(cfg);
+      if (cfg.privateKey && o.keyPassphrase)
+        cfg.passphrase = o.keyPassphrase;
+      if (o.password)
+        cfg.password = o.password;
+      client.on("ready", () => resolve2(client)).on("error", (err) => reject(err)).connect(cfg);
+    });
+  }
+  forwardOut(via, host, port) {
+    return new Promise((resolve2, reject) => {
+      via.forwardOut("127.0.0.1", 0, host, port, (err, stream) => {
+        if (err) {
+          reject(new Error(`jump host could not open a tunnel to ${host}:${port}: ${err.message}. ` + "If the jump router runs RouterOS, enable SSH TCP forwarding on it: " + "/ip ssh set forwarding-enabled=local (or both)."));
+        } else {
+          resolve2(stream);
+        }
+      });
     });
   }
   run(command, opts = {}) {
@@ -863,6 +912,12 @@ class MikroTikSSHClient {
       } catch {}
       this.client = null;
     }
+    for (const b of this.bastions.reverse()) {
+      try {
+        b.end();
+      } catch {}
+    }
+    this.bastions = [];
   }
 }
 
@@ -870,6 +925,43 @@ class MikroTikSSHClient {
 function isMacTelnetDevice(dc) {
   return Boolean(dc.mac);
 }
+function sshOptionsOf(dc) {
+  return {
+    host: dc.host,
+    username: dc.username,
+    password: dc.password,
+    keyFilename: dc.keyFilename,
+    privateKey: dc.privateKey,
+    keyPassphrase: dc.keyPassphrase,
+    port: dc.port,
+    timeoutMs: dc.timeoutMs
+  };
+}
+function resolveJump(dc, seen = new Set) {
+  if (dc.jumpHost) {
+    return {
+      host: dc.jumpHost.host,
+      port: dc.jumpHost.port,
+      username: dc.jumpHost.username,
+      password: dc.jumpHost.password,
+      keyFilename: dc.jumpHost.keyFilename,
+      privateKey: dc.jumpHost.privateKey,
+      keyPassphrase: dc.jumpHost.keyPassphrase,
+      timeoutMs: dc.jumpHost.timeoutMs
+    };
+  }
+  if (!dc.jumpVia)
+    return;
+  if (seen.has(dc.jumpVia)) {
+    throw new Error(`SSH jump-host cycle detected at '${dc.jumpVia}' (a device can't jump through itself).`);
+  }
+  seen.add(dc.jumpVia);
+  const bastion = getDevice(dc.jumpVia);
+  if (isMacTelnetDevice(bastion)) {
+    throw new Error(`Jump host '${dc.jumpVia}' is a MAC-Telnet device; an SSH bastion must be reachable over SSH.`);
+  }
+  return { ...sshOptionsOf(bastion), jump: resolveJump(bastion, seen) };
+}
 function createDeviceClient(dc) {
   if (isMacTelnetDevice(dc)) {
     return new MikroTikMacTelnetClient({
@@ -882,16 +974,7 @@ function createDeviceClient(dc) {
       timeoutMs: dc.timeoutMs
     });
   }
-  return new MikroTikSSHClient({
-    host: dc.host,
-    username: dc.username,
-    password: dc.password,
-    keyFilename: dc.keyFilename,
-    privateKey: dc.privateKey,
-    keyPassphrase: dc.keyPassphrase,
-    port: dc.port,
-    timeoutMs: dc.timeoutMs
-  });
+  return new MikroTikSSHClient({ ...sshOptionsOf(dc), jump: resolveJump(dc) });
 }
 function describeTransport(dc) {
   return dc.mac ? `MAC ${dc.mac} (mac-telnet)` : `${dc.host}:${dc.port}`;
@@ -4487,40 +4570,39 @@ var changePlanTools = [
         return "No commands provided to apply.";
       const device = resolveDeviceName(ctx.device);
       if (getDevice(ctx.device).mac) {
-        return "Safe Mode (and therefore apply_plan) requires SSH; it is not available on a MAC-Telnet device.";
+        throw new Error("Safe Mode (and therefore apply_plan) requires SSH; it is not available on a MAC-Telnet device.");
       }
       const plan = buildChangePlan(commands);
       const safe = getSafeModeManager(device);
       const enabled2 = await safe.enable();
       if (enabled2.startsWith("Error"))
-        return enabled2;
+        throw new Error(enabled2);
       const APPLY_BUDGET_MS = 90000;
       const startedAt = Date.now();
       const overBudget = () => Date.now() - startedAt > APPLY_BUDGET_MS;
-      try {
-        const before = normalizeExport(await safe.execute("/export terse"));
-        const log = [];
-        for (const step of plan.steps) {
-          if (overBudget()) {
-            await safe.rollback();
-            return `Aborted after ${Math.round((Date.now() - startedAt) / 1000)}s (time budget exceeded) \u2014 ` + "the plan was ROLLED BACK (nothing committed). Safe Mode is slow/unresponsive on this " + "device; apply the change with the direct write tools instead.";
-          }
-          const out = await safe.execute(step.command);
-          if (looksLikeError(out)) {
-            await safe.rollback();
-            return `Step ${step.index} failed and the plan was ROLLED BACK (nothing committed):
-` + `  ${step.command}
-  \u2192 ${out.trim()}`;
+      const applyAndDiff = async () => {
+        try {
+          const before = normalizeExport(await safe.execute("/export terse"));
+          const log = [];
+          for (const step of plan.steps) {
+            if (overBudget()) {
+              throw new Error(`aborted after ${Math.round((Date.now() - startedAt) / 1000)}s (time budget exceeded). ` + "Safe Mode is slow/unresponsive on this device; apply the change with the direct write tools instead");
+            }
+            const out = await safe.execute(step.command);
+            if (looksLikeError(out)) {
+              throw new Error(`step ${step.index} failed:
+  ${step.command}
+  \u2192 ${out.trim()}`);
+            }
+            log.push(`  \u2713 ${step.command}`);
           }
-          log.push(`  \u2713 ${step.command}`);
-        }
-        const after = normalizeExport(await safe.execute("/export terse"));
-        const diff = diffLines(before, after, { fromLabel: "before", toLabel: "after" });
-        const reachable = !looksLikeError(await safe.execute("/system identity print"));
-        const planBody = renderPlan(plan).split(`
+          const after = normalizeExport(await safe.execute("/export terse"));
+          const diff = diffLines(before, after, { fromLabel: "before", toLabel: "after" });
+          const reachable2 = !looksLikeError(await safe.execute("/system identity print"));
+          const planBody = renderPlan(plan).split(`
 `).slice(2).join(`
 `);
-        const header = `APPLY PLAN \u2014 ${device}
+          const header2 = `APPLY PLAN \u2014 ${device}
 
 ${planBody}
 
@@ -4530,32 +4612,35 @@ ${log.join(`
 
 ` + `EXACT DIFF (+${diff.summary.added}/-${diff.summary.removed}):
 ${diff.unified || "(no config change)"}`;
-        if (!a.confirm) {
-          await safe.rollback();
-          return `${header}
+          return { header: header2, reachable: reachable2 };
+        } catch (e) {
+          await safe.rollback().catch(() => {});
+          const msg = e instanceof Error ? e.message : String(e);
+          throw new Error(`apply_plan failed and was rolled back (nothing committed): ${msg}`);
+        }
+      };
+      const { header, reachable } = await applyAndDiff();
+      if (!a.confirm) {
+        await safe.rollback();
+        return `${header}
 
 DRY-RUN: all changes rolled back. Re-run with confirm=true to commit.`;
-        }
-        if (!reachable) {
-          await safe.rollback();
-          return `${header}
+      }
+      if (!reachable) {
+        await safe.rollback();
+        throw new Error(`${header}
 
-ABORTED: the device stopped responding after applying \u2014 changes rolled back to avoid a lock-out.`;
-        }
-        const committed = await safe.commit();
-        if (!committed.ok) {
-          return `${header}
+ABORTED: the device stopped responding after applying \u2014 changes rolled back to avoid a lock-out.`);
+      }
+      const committed = await safe.commit();
+      if (!committed.ok) {
+        throw new Error(`${header}
 
-COMMIT FAILED \u2014 changes are NOT saved (still pending in Safe Mode). ` + `${committed.message}`;
-        }
-        return `${header}
+COMMIT FAILED \u2014 changes are NOT saved (still pending in Safe Mode). ${committed.message}`);
+      }
+      return `${header}
 
 COMMITTED: changes are now permanent. ${committed.message}`;
-      } catch (e) {
-        await safe.rollback();
-        const msg = e instanceof Error ? e.message : String(e);
-        return `apply_plan failed and was rolled back: ${msg}`;
-      }
     }
   })
 ];
@@ -5932,7 +6017,7 @@ var cache = null;
 async function gateway() {
   if (cache)
     return cache;
-  const { moduleCatalog } = await import("./cli-ytn5v321.js");
+  const { moduleCatalog } = await import("./cli-g5kqcrt4.js");
   const forIndex = [];
   const byName = new Map;
   for (const mod of moduleCatalog) {

package/dist/shared/{library-bj9xrcg0.js → library-aa58hkb4.js}

@@ -25,6 +25,16 @@ var McpServerSettingsSchema = z.object({
   toolPageSize: z.coerce.number().int().min(0).default(0),
   appViews: z.boolean().default(true)
 });
+var JumpHostSchema = z.object({
+  host: z.string(),
+  port: z.coerce.number().int().positive().default(22),
+  username: z.string().default("admin"),
+  password: z.string().optional(),
+  keyFilename: z.string().optional(),
+  privateKey: z.string().optional(),
+  keyPassphrase: z.string().optional(),
+  timeoutMs: z.coerce.number().int().positive().optional()
+});
 var DeviceConfigSchema = z.object({
   host: z.string().default("127.0.0.1"),
   username: z.string().default("admin"),
@@ -34,6 +44,8 @@ var DeviceConfigSchema = z.object({
   privateKey: z.string().optional(),
   keyPassphrase: z.string().optional(),
   timeoutMs: z.coerce.number().int().positive().default(1e4),
+  jumpVia: z.string().optional(),
+  jumpHost: JumpHostSchema.optional(),
   mac: z.string().optional(),
   sourceMac: z.string().optional(),
   macHost: z.string().optional(),
@@ -128,6 +140,15 @@ var configSource = { path: DEFAULT_CONFIG_FILE, fromFile: false };
 function loadConfig(argv = process.argv.slice(2)) {
   const flags = parseFlags(argv);
   const pick = (flag, ...envNames) => flags[flag] ?? env(...envNames);
+  const jumpHostName = pick("jump-host", "MIKROTIK_JUMP_HOST");
+  const jumpHost = jumpHostName ? {
+    host: jumpHostName,
+    port: pick("jump-port", "MIKROTIK_JUMP_PORT"),
+    username: pick("jump-username", "MIKROTIK_JUMP_USERNAME"),
+    password: pick("jump-password", "MIKROTIK_JUMP_PASSWORD"),
+    keyFilename: pick("jump-key-filename", "MIKROTIK_JUMP_KEY_FILENAME"),
+    keyPassphrase: pick("jump-key-passphrase", "MIKROTIK_JUMP_KEY_PASSPHRASE")
+  } : undefined;
   const single = {
     host: pick("host", "MIKROTIK_HOST"),
     username: pick("username", "MIKROTIK_USERNAME"),
@@ -137,6 +158,7 @@ function loadConfig(argv = process.argv.slice(2)) {
     privateKey: pick("private-key", "MIKROTIK_PRIVATE_KEY"),
     keyPassphrase: pick("key-passphrase", "MIKROTIK_KEY_PASSPHRASE"),
     timeoutMs: pick("timeout-ms", "MIKROTIK_TIMEOUT_MS"),
+    jumpHost,
     mac: pick("mac", "MIKROTIK_MAC"),
     sourceMac: pick("source-mac", "MIKROTIK_SOURCE_MAC"),
     macHost: pick("mac-host", "MIKROTIK_MAC_HOST"),
@@ -703,45 +725,72 @@ function decodeOutput(data) {
 
 class MikroTikSSHClient {
   client = null;
+  bastions = [];
   opts;
   lastError;
   constructor(opts) {
     this.opts = { port: 22, timeoutMs: 1e4, ...opts };
   }
-  connect() {
+  async connect() {
     this.lastError = undefined;
-    return new Promise((resolve2) => {
+    try {
+      const hops = [];
+      for (let j = this.opts.jump;j; j = j.jump)
+        hops.unshift(j);
+      const sequence = [...hops, this.opts];
+      let sock;
+      for (let i = 0;i < hops.length; i++) {
+        const client = await this.openClient(hops[i], sock);
+        this.bastions.push(client);
+        const next = sequence[i + 1];
+        sock = await this.forwardOut(client, next.host, next.port ?? 22);
+      }
+      this.client = await this.openClient(this.opts, sock);
+      return true;
+    } catch (e) {
+      this.lastError = e instanceof Error ? e.message : String(e);
+      logger.error(`Failed to connect to MikroTik: ${this.lastError}`);
+      this.disconnect();
+      return false;
+    }
+  }
+  openClient(o, sock) {
+    return new Promise((resolve2, reject) => {
       const client = new Client;
       const cfg = {
-        host: this.opts.host,
-        port: this.opts.port,
-        username: this.opts.username,
-        readyTimeout: this.opts.timeoutMs
+        host: o.host,
+        port: o.port ?? 22,
+        username: o.username,
+        readyTimeout: o.timeoutMs ?? 1e4
       };
-      if (this.opts.privateKey) {
-        cfg.privateKey = this.opts.privateKey;
-      } else if (this.opts.keyFilename) {
+      if (sock)
+        cfg.sock = sock;
+      if (o.privateKey) {
+        cfg.privateKey = o.privateKey;
+      } else if (o.keyFilename) {
         try {
-          cfg.privateKey = readFileSync2(this.opts.keyFilename);
+          cfg.privateKey = readFileSync2(o.keyFilename);
         } catch (e) {
-          this.lastError = `could not read key file ${this.opts.keyFilename}: ${e instanceof Error ? e.message : String(e)}`;
-          logger.error(`Failed to read SSH key file ${this.opts.keyFilename}: ${String(e)}`);
-          resolve2(false);
+          reject(new Error(`could not read key file ${o.keyFilename}: ${e instanceof Error ? e.message : String(e)}`));
           return;
         }
       }
-      if (cfg.privateKey && this.opts.keyPassphrase)
-        cfg.passphrase = this.opts.keyPassphrase;
-      if (this.opts.password)
-        cfg.password = this.opts.password;
-      client.on("ready", () => {
-        this.client = client;
-        resolve2(true);
-      }).on("error", (err) => {
-        this.lastError = err.message;
-        logger.error(`Failed to connect to MikroTik: ${err.message}`);
-        resolve2(false);
-      }).connect(cfg);
+      if (cfg.privateKey && o.keyPassphrase)
+        cfg.passphrase = o.keyPassphrase;
+      if (o.password)
+        cfg.password = o.password;
+      client.on("ready", () => resolve2(client)).on("error", (err) => reject(err)).connect(cfg);
+    });
+  }
+  forwardOut(via, host, port) {
+    return new Promise((resolve2, reject) => {
+      via.forwardOut("127.0.0.1", 0, host, port, (err, stream) => {
+        if (err) {
+          reject(new Error(`jump host could not open a tunnel to ${host}:${port}: ${err.message}. ` + "If the jump router runs RouterOS, enable SSH TCP forwarding on it: " + "/ip ssh set forwarding-enabled=local (or both)."));
+        } else {
+          resolve2(stream);
+        }
+      });
     });
   }
   run(command, opts = {}) {
@@ -860,6 +909,12 @@ class MikroTikSSHClient {
       } catch {}
       this.client = null;
     }
+    for (const b of this.bastions.reverse()) {
+      try {
+        b.end();
+      } catch {}
+    }
+    this.bastions = [];
   }
 }
 
@@ -867,6 +922,43 @@ class MikroTikSSHClient {
 function isMacTelnetDevice(dc) {
   return Boolean(dc.mac);
 }
+function sshOptionsOf(dc) {
+  return {
+    host: dc.host,
+    username: dc.username,
+    password: dc.password,
+    keyFilename: dc.keyFilename,
+    privateKey: dc.privateKey,
+    keyPassphrase: dc.keyPassphrase,
+    port: dc.port,
+    timeoutMs: dc.timeoutMs
+  };
+}
+function resolveJump(dc, seen = new Set) {
+  if (dc.jumpHost) {
+    return {
+      host: dc.jumpHost.host,
+      port: dc.jumpHost.port,
+      username: dc.jumpHost.username,
+      password: dc.jumpHost.password,
+      keyFilename: dc.jumpHost.keyFilename,
+      privateKey: dc.jumpHost.privateKey,
+      keyPassphrase: dc.jumpHost.keyPassphrase,
+      timeoutMs: dc.jumpHost.timeoutMs
+    };
+  }
+  if (!dc.jumpVia)
+    return;
+  if (seen.has(dc.jumpVia)) {
+    throw new Error(`SSH jump-host cycle detected at '${dc.jumpVia}' (a device can't jump through itself).`);
+  }
+  seen.add(dc.jumpVia);
+  const bastion = getDevice(dc.jumpVia);
+  if (isMacTelnetDevice(bastion)) {
+    throw new Error(`Jump host '${dc.jumpVia}' is a MAC-Telnet device; an SSH bastion must be reachable over SSH.`);
+  }
+  return { ...sshOptionsOf(bastion), jump: resolveJump(bastion, seen) };
+}
 function createDeviceClient(dc) {
   if (isMacTelnetDevice(dc)) {
     return new MikroTikMacTelnetClient({
@@ -879,16 +971,7 @@ function createDeviceClient(dc) {
       timeoutMs: dc.timeoutMs
     });
   }
-  return new MikroTikSSHClient({
-    host: dc.host,
-    username: dc.username,
-    password: dc.password,
-    keyFilename: dc.keyFilename,
-    privateKey: dc.privateKey,
-    keyPassphrase: dc.keyPassphrase,
-    port: dc.port,
-    timeoutMs: dc.timeoutMs
-  });
+  return new MikroTikSSHClient({ ...sshOptionsOf(dc), jump: resolveJump(dc) });
 }
 function connectErrorMessage(name, dc, lastError) {
   const reason = lastError ? ` \u2014 ${lastError}` : "";
@@ -4402,40 +4485,39 @@ var changePlanTools = [
         return "No commands provided to apply.";
       const device = resolveDeviceName(ctx.device);
       if (getDevice(ctx.device).mac) {
-        return "Safe Mode (and therefore apply_plan) requires SSH; it is not available on a MAC-Telnet device.";
+        throw new Error("Safe Mode (and therefore apply_plan) requires SSH; it is not available on a MAC-Telnet device.");
       }
       const plan = buildChangePlan(commands);
       const safe = getSafeModeManager(device);
       const enabled2 = await safe.enable();
       if (enabled2.startsWith("Error"))
-        return enabled2;
+        throw new Error(enabled2);
       const APPLY_BUDGET_MS = 90000;
       const startedAt = Date.now();
       const overBudget = () => Date.now() - startedAt > APPLY_BUDGET_MS;
-      try {
-        const before = normalizeExport(await safe.execute("/export terse"));
-        const log = [];
-        for (const step of plan.steps) {
-          if (overBudget()) {
-            await safe.rollback();
-            return `Aborted after ${Math.round((Date.now() - startedAt) / 1000)}s (time budget exceeded) \u2014 ` + "the plan was ROLLED BACK (nothing committed). Safe Mode is slow/unresponsive on this " + "device; apply the change with the direct write tools instead.";
-          }
-          const out = await safe.execute(step.command);
-          if (looksLikeError(out)) {
-            await safe.rollback();
-            return `Step ${step.index} failed and the plan was ROLLED BACK (nothing committed):
-` + `  ${step.command}
-  \u2192 ${out.trim()}`;
+      const applyAndDiff = async () => {
+        try {
+          const before = normalizeExport(await safe.execute("/export terse"));
+          const log = [];
+          for (const step of plan.steps) {
+            if (overBudget()) {
+              throw new Error(`aborted after ${Math.round((Date.now() - startedAt) / 1000)}s (time budget exceeded). ` + "Safe Mode is slow/unresponsive on this device; apply the change with the direct write tools instead");
+            }
+            const out = await safe.execute(step.command);
+            if (looksLikeError(out)) {
+              throw new Error(`step ${step.index} failed:
+  ${step.command}
+  \u2192 ${out.trim()}`);
+            }
+            log.push(`  \u2713 ${step.command}`);
           }
-          log.push(`  \u2713 ${step.command}`);
-        }
-        const after = normalizeExport(await safe.execute("/export terse"));
-        const diff = diffLines(before, after, { fromLabel: "before", toLabel: "after" });
-        const reachable = !looksLikeError(await safe.execute("/system identity print"));
-        const planBody = renderPlan(plan).split(`
+          const after = normalizeExport(await safe.execute("/export terse"));
+          const diff = diffLines(before, after, { fromLabel: "before", toLabel: "after" });
+          const reachable2 = !looksLikeError(await safe.execute("/system identity print"));
+          const planBody = renderPlan(plan).split(`
 `).slice(2).join(`
 `);
-        const header = `APPLY PLAN \u2014 ${device}
+          const header2 = `APPLY PLAN \u2014 ${device}
 
 ${planBody}
 
@@ -4445,32 +4527,35 @@ ${log.join(`
 
 ` + `EXACT DIFF (+${diff.summary.added}/-${diff.summary.removed}):
 ${diff.unified || "(no config change)"}`;
-        if (!a.confirm) {
-          await safe.rollback();
-          return `${header}
+          return { header: header2, reachable: reachable2 };
+        } catch (e) {
+          await safe.rollback().catch(() => {});
+          const msg = e instanceof Error ? e.message : String(e);
+          throw new Error(`apply_plan failed and was rolled back (nothing committed): ${msg}`);
+        }
+      };
+      const { header, reachable } = await applyAndDiff();
+      if (!a.confirm) {
+        await safe.rollback();
+        return `${header}
 
 DRY-RUN: all changes rolled back. Re-run with confirm=true to commit.`;
-        }
-        if (!reachable) {
-          await safe.rollback();
-          return `${header}
+      }
+      if (!reachable) {
+        await safe.rollback();
+        throw new Error(`${header}
 
-ABORTED: the device stopped responding after applying \u2014 changes rolled back to avoid a lock-out.`;
-        }
-        const committed = await safe.commit();
-        if (!committed.ok) {
-          return `${header}
+ABORTED: the device stopped responding after applying \u2014 changes rolled back to avoid a lock-out.`);
+      }
+      const committed = await safe.commit();
+      if (!committed.ok) {
+        throw new Error(`${header}
 
-COMMIT FAILED \u2014 changes are NOT saved (still pending in Safe Mode). ` + `${committed.message}`;
-        }
-        return `${header}
+COMMIT FAILED \u2014 changes are NOT saved (still pending in Safe Mode). ${committed.message}`);
+      }
+      return `${header}
 
 COMMITTED: changes are now permanent. ${committed.message}`;
-      } catch (e) {
-        await safe.rollback();
-        const msg = e instanceof Error ? e.message : String(e);
-        return `apply_plan failed and was rolled back: ${msg}`;
-      }
     }
   })
 ];
@@ -5847,7 +5932,7 @@ var cache = null;
 async function gateway() {
   if (cache)
     return cache;
-  const { moduleCatalog } = await import("./library-gsvkewg5.js");
+  const { moduleCatalog } = await import("./library-c629x3tn.js");
   const forIndex = [];
   const byName = new Map;
   for (const mod of moduleCatalog) {

package/dist/shared/{library-gsvkewg5.js → library-c629x3tn.js}

@@ -4,7 +4,7 @@ import {
   allToolModules,
   moduleCatalog,
   selectToolModules
-} from "./library-bj9xrcg0.js";
+} from "./library-aa58hkb4.js";
 export {
   selectToolModules,
   moduleCatalog,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usex/mikrotik-mcp",
-  "version": "3.32.1",
+  "version": "3.33.0",
   "description": "MCP server for MikroTik RouterOS — 660+ tools over SSH for firewall, NAT, routing, DHCP, DNS, WireGuard, wireless, QoS and more.",
   "keywords": [
     "ai",

package/schemas/config.schema.json

@@ -53,6 +53,46 @@
             "exclusiveMinimum": 0,
             "maximum": 9007199254740991
           },
+          "jumpVia": {
+            "type": "string"
+          },
+          "jumpHost": {
+            "type": "object",
+            "properties": {
+              "host": {
+                "type": "string"
+              },
+              "port": {
+                "default": 22,
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
+              "username": {
+                "default": "admin",
+                "type": "string"
+              },
+              "password": {
+                "type": "string"
+              },
+              "keyFilename": {
+                "type": "string"
+              },
+              "privateKey": {
+                "type": "string"
+              },
+              "keyPassphrase": {
+                "type": "string"
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "required": ["host", "port", "username"],
+            "additionalProperties": false
+          },
           "mac": {
             "type": "string"
           },