@usex/mikrotik-mcp 3.28.0 → 3.29.0

package/dist/cli.js

@@ -779,6 +779,29 @@ class MikroTikSSHClient {
       });
     });
   }
+  uploadFile(remotePath, data) {
+    if (!this.client) {
+      return Promise.reject(new Error("Not connected to MikroTik device"));
+    }
+    const openSftp = this.client.sftp.bind(this.client);
+    return new Promise((resolve2, reject) => {
+      openSftp((err, sftp) => {
+        if (err) {
+          reject(new Error(`SFTP subsystem unavailable: ${err.message}`));
+          return;
+        }
+        sftp.writeFile(remotePath, data, (werr) => {
+          try {
+            sftp.end();
+          } catch {}
+          if (werr)
+            reject(new Error(`SFTP write failed: ${werr.message}`));
+          else
+            resolve2();
+        });
+      });
+    });
+  }
   shell(opts = {}) {
     if (!this.client) {
       return Promise.reject(new Error("Not connected to MikroTik device"));
@@ -911,13 +934,13 @@ class SafeModeManager {
       }
       this.ssh = ssh;
       this.channel = await ssh.shell({ term: "dumb", cols: 220, rows: 50 });
-      const initial = await this.readUntilPrompt(20000);
+      const initial = (await this.readUntilPrompt(20000)).text;
       if (!PROMPT_RE.test(initial)) {
         this.cleanup();
         return `Error: Timed out waiting for MikroTik shell prompt. Got: ${JSON.stringify(initial.slice(0, 300))}`;
       }
       this.channel.write(CTRL_X);
-      const response = await this.readUntilPrompt(1e4, (c) => isSafeModeActivated(c));
+      const response = (await this.readUntilPrompt(1e4, (c) => isSafeModeActivated(c))).text;
       if (!isSafeModeActivated(response)) {
         this.cleanup();
         return `Error: Safe mode did not activate. Response: ${JSON.stringify(response.slice(0, 300))}`;
@@ -933,8 +956,11 @@ class SafeModeManager {
       }
       this.channel.write(`${command}
 `);
-      const raw = await this.readUntilPrompt();
-      return this.extractOutput(raw, command);
+      const { text, timedOut } = await this.readUntilPrompt();
+      if (timedOut) {
+        throw new Error(`Safe Mode shell did not return a prompt within 15s (command: ${command}). The interactive ` + "session appears wedged \u2014 some RouterOS builds/terminals don't support Safe Mode over SSH. " + "Apply the change with the direct write tools instead (verify each with a read).");
+      }
+      return this.extractOutput(text, command);
     });
   }
   commit() {
@@ -989,7 +1015,7 @@ class SafeModeManager {
   readUntilPrompt(timeoutMs = 15000, isDone = (c) => PROMPT_RE.test(c)) {
     const channel = this.channel;
     if (!channel)
-      return Promise.resolve("");
+      return Promise.resolve({ text: "", timedOut: false });
     return new Promise((resolve2) => {
       let buf = "";
       let timer;
@@ -997,14 +1023,14 @@ class SafeModeManager {
         buf += decodeOutput(chunk);
         const cleaned = stripAnsi(buf);
         if (isDone(cleaned))
-          finish(cleaned);
+          finish(cleaned, false);
       }
-      function finish(result) {
+      function finish(result, timedOut) {
         clearTimeout(timer);
         channel.removeListener("data", onData);
-        resolve2(result);
+        resolve2({ text: result, timedOut });
       }
-      timer = setTimeout(() => finish(stripAnsi(buf)), timeoutMs);
+      timer = setTimeout(() => finish(stripAnsi(buf), true), timeoutMs);
       channel.on("data", onData);
     });
   }
@@ -1014,10 +1040,10 @@ class SafeModeManager {
     const token = "__MCP_SAFEMODE_PROBE__";
     this.channel.write(`:put "${token}"
 `);
-    const out = await this.readUntilPrompt(8000, (cleaned) => {
+    const out = (await this.readUntilPrompt(8000, (cleaned) => {
       const i = cleaned.lastIndexOf(token);
       return i >= 0 && PROMPT_RE.test(cleaned.slice(i));
-    });
+    })).text;
     return classifyPrompt(out);
   }
   extractOutput(raw, command) {
@@ -1090,6 +1116,31 @@ async function executeMikrotikCommand(command, ctx, opts) {
   ctx.info(`[${deviceName}] Executing MikroTik command: ${command}`);
   return runOnce(command, ctx.device, opts);
 }
+async function uploadFileToDevice(deviceName, remotePath, data) {
+  const name = resolveDeviceName(deviceName);
+  const dc = getDevice(deviceName);
+  if (isMacTelnetDevice(dc)) {
+    throw new Error(`Cannot transfer a file to '${name}': it is reached over Layer-2 MAC-Telnet, which has no file ` + "transfer. Configure SSH (host + credentials) for this device, or have the router pull the file " + "itself with /tool fetch from a URL it can reach.");
+  }
+  const ssh = 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
+  });
+  if (!await ssh.connect()) {
+    throw new Error(connectErrorMessage(name, dc, ssh.lastError));
+  }
+  try {
+    await ssh.uploadFile(remotePath, data);
+  } finally {
+    ssh.disconnect();
+  }
+}
 
 // src/core/registry.ts
 import { z as z2 } from "zod";
@@ -2803,21 +2854,29 @@ ${fileDetails}` : `Section export '${name}.rsc' created successfully.`;
   }),
   defineTool({
     name: "upload_file",
-    title: "Upload File to Device (Simulated)",
+    title: "Upload File to Device",
     annotations: WRITE,
-    description: "Accepts a base64-encoded file intended for the device filesystem. NOTE: the current handler" + " only validates the base64 encoding and returns a simulated success \u2014 it does not transfer" + " bytes to the device over SSH. Once a `.backup` file is present on the device apply it with" + " `restore_backup`; for `.rsc` configuration scripts use `import_configuration`.",
+    description: "Transfer a file to the device filesystem over SFTP (the file subsystem RouterOS exposes on its SSH" + " server) \u2014 this actually pushes the bytes, then verifies the file appears in `/file`. Use it to put" + " a file on the router before another tool can use it: a `.rsc` config script (then apply with" + " `import_configuration`), a `.backup` file (then `restore_backup`), or a certificate/key (then" + " `import_certificate`). `filename` is the DESTINATION path on the device \u2014 root by default" + " (e.g. `config.rsc`), or an external-disk path (e.g. `disk1/cert.pem`). `content_base64` is the file's" + " raw bytes, base64-encoded (binary-safe \u2014 works for `.backup`/cert files, not just text). Overwrites" + " any existing file of the same name. NOT available on MAC-Telnet devices (Layer-2 has no file" + " transfer) \u2014 there, have the router pull the file itself with `/tool fetch` from a reachable URL.",
     inputSchema: {
-      filename: z5.string(),
-      content_base64: z5.string()
+      filename: z5.string().describe("Destination path on the device, e.g. 'config.rsc' or 'disk1/cert.pem'"),
+      content_base64: z5.string().describe("File bytes, base64-encoded (binary-safe)")
     },
     async handler(a, ctx) {
       ctx.info(`Uploading file: filename=${a.filename}`);
+      const data = Buffer.from(a.content_base64, "base64");
+      if (data.length === 0) {
+        return "Nothing to upload: content_base64 is empty or decoded to 0 bytes.";
+      }
       try {
-        Buffer.from(a.content_base64, "base64").toString("utf8");
+        await uploadFileToDevice(ctx.device, a.filename, data);
       } catch (e) {
-        return `Failed to decode file content: ${e instanceof Error ? e.message : String(e)}`;
+        return `Failed to upload '${a.filename}': ${e instanceof Error ? e.message : String(e)}`;
+      }
+      const verify = await executeMikrotikCommand(`/file print count-only where name="${a.filename}"`, ctx);
+      if (verify.trim() === "0") {
+        return `File '${a.filename}' was transferred (${data.length} bytes) but did not appear in /file under ` + "that exact name \u2014 RouterOS may have stored it at a slightly different path. Run list_files to " + "confirm, then apply it (import_configuration / restore_backup / import_certificate).";
       }
-      return `File '${a.filename}' uploaded successfully (simulated).`;
+      return `File '${a.filename}' uploaded successfully (${data.length} bytes) and is now in /file. Apply it: ` + "import_configuration for a `.rsc`, restore_backup for a `.backup`, or import_certificate for a cert.";
     }
   }),
   defineTool({
@@ -4383,10 +4442,17 @@ var changePlanTools = [
       const enabled2 = await safe.enable();
       if (enabled2.startsWith("Error"))
         return 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();
@@ -27001,7 +27067,7 @@ function registerPrompts(server) {
 // package.json
 var package_default = {
   name: "@usex/mikrotik-mcp",
-  version: "3.28.0",
+  version: "3.29.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.d.ts

@@ -182,6 +182,14 @@ declare class MikroTikSSHClient {
 	run(command: string, opts?: {
 		maxMs?: number;
 	}): Promise<string>;
+	/**
+	* Upload a file's bytes to the device over SFTP — the file-transfer subsystem
+	* RouterOS exposes on its SSH server. `remotePath` is relative to the SFTP
+	* default directory (the flash root), so `config.rsc` lands at the root and
+	* appears in `/file`; a path like `disk1/config.rsc` targets external disk.
+	* Resolves on success; rejects with a clear reason on failure.
+	*/
+	uploadFile(remotePath: string, data: Buffer): Promise<void>;
 	/** Open a persistent interactive shell channel (used by Safe Mode). */
 	shell(opts?: {
 		term?: string;
@@ -215,7 +223,14 @@ declare class SafeModeManager {
 	private lock;
 	/** Open a persistent SSH shell and activate MikroTik Safe Mode. */
 	enable(): Promise<string>;
-	/** Execute a command through the safe-mode persistent shell session. */
+	/**
+	* Execute a command through the safe-mode persistent shell session.
+	*
+	* If the shell never returns a prompt within the timeout, the interactive
+	* Safe-Mode session is wedged — this throws immediately so the caller aborts
+	* instead of issuing more commands that would each also burn the full timeout
+	* (the cumulative effect of which is a multi-minute "hang" to the MCP client).
+	*/
 	execute(command: string): Promise<string>;
 	/**
 	* Send Ctrl+X again to exit Safe Mode and persist all changes. Returns a

package/dist/index.js

@@ -771,6 +771,29 @@ class MikroTikSSHClient {
       });
     });
   }
+  uploadFile(remotePath, data) {
+    if (!this.client) {
+      return Promise.reject(new Error("Not connected to MikroTik device"));
+    }
+    const openSftp = this.client.sftp.bind(this.client);
+    return new Promise((resolve2, reject) => {
+      openSftp((err, sftp) => {
+        if (err) {
+          reject(new Error(`SFTP subsystem unavailable: ${err.message}`));
+          return;
+        }
+        sftp.writeFile(remotePath, data, (werr) => {
+          try {
+            sftp.end();
+          } catch {}
+          if (werr)
+            reject(new Error(`SFTP write failed: ${werr.message}`));
+          else
+            resolve2();
+        });
+      });
+    });
+  }
   shell(opts = {}) {
     if (!this.client) {
       return Promise.reject(new Error("Not connected to MikroTik device"));
@@ -897,13 +920,13 @@ class SafeModeManager {
       }
       this.ssh = ssh;
       this.channel = await ssh.shell({ term: "dumb", cols: 220, rows: 50 });
-      const initial = await this.readUntilPrompt(20000);
+      const initial = (await this.readUntilPrompt(20000)).text;
       if (!PROMPT_RE.test(initial)) {
         this.cleanup();
         return `Error: Timed out waiting for MikroTik shell prompt. Got: ${JSON.stringify(initial.slice(0, 300))}`;
       }
       this.channel.write(CTRL_X);
-      const response = await this.readUntilPrompt(1e4, (c) => isSafeModeActivated(c));
+      const response = (await this.readUntilPrompt(1e4, (c) => isSafeModeActivated(c))).text;
       if (!isSafeModeActivated(response)) {
         this.cleanup();
         return `Error: Safe mode did not activate. Response: ${JSON.stringify(response.slice(0, 300))}`;
@@ -919,8 +942,11 @@ class SafeModeManager {
       }
       this.channel.write(`${command}
 `);
-      const raw = await this.readUntilPrompt();
-      return this.extractOutput(raw, command);
+      const { text, timedOut } = await this.readUntilPrompt();
+      if (timedOut) {
+        throw new Error(`Safe Mode shell did not return a prompt within 15s (command: ${command}). The interactive ` + "session appears wedged \u2014 some RouterOS builds/terminals don't support Safe Mode over SSH. " + "Apply the change with the direct write tools instead (verify each with a read).");
+      }
+      return this.extractOutput(text, command);
     });
   }
   commit() {
@@ -975,7 +1001,7 @@ class SafeModeManager {
   readUntilPrompt(timeoutMs = 15000, isDone = (c) => PROMPT_RE.test(c)) {
     const channel = this.channel;
     if (!channel)
-      return Promise.resolve("");
+      return Promise.resolve({ text: "", timedOut: false });
     return new Promise((resolve2) => {
       let buf = "";
       let timer;
@@ -983,14 +1009,14 @@ class SafeModeManager {
         buf += decodeOutput(chunk);
         const cleaned = stripAnsi(buf);
         if (isDone(cleaned))
-          finish(cleaned);
+          finish(cleaned, false);
       }
-      function finish(result) {
+      function finish(result, timedOut) {
         clearTimeout(timer);
         channel.removeListener("data", onData);
-        resolve2(result);
+        resolve2({ text: result, timedOut });
       }
-      timer = setTimeout(() => finish(stripAnsi(buf)), timeoutMs);
+      timer = setTimeout(() => finish(stripAnsi(buf), true), timeoutMs);
       channel.on("data", onData);
     });
   }
@@ -1000,10 +1026,10 @@ class SafeModeManager {
     const token = "__MCP_SAFEMODE_PROBE__";
     this.channel.write(`:put "${token}"
 `);
-    const out = await this.readUntilPrompt(8000, (cleaned) => {
+    const out = (await this.readUntilPrompt(8000, (cleaned) => {
       const i = cleaned.lastIndexOf(token);
       return i >= 0 && PROMPT_RE.test(cleaned.slice(i));
-    });
+    })).text;
     return classifyPrompt(out);
   }
   extractOutput(raw, command) {
@@ -1076,6 +1102,31 @@ async function executeMikrotikCommand(command, ctx, opts) {
   ctx.info(`[${deviceName}] Executing MikroTik command: ${command}`);
   return runOnce(command, ctx.device, opts);
 }
+async function uploadFileToDevice(deviceName, remotePath, data) {
+  const name = resolveDeviceName(deviceName);
+  const dc = getDevice(deviceName);
+  if (isMacTelnetDevice(dc)) {
+    throw new Error(`Cannot transfer a file to '${name}': it is reached over Layer-2 MAC-Telnet, which has no file ` + "transfer. Configure SSH (host + credentials) for this device, or have the router pull the file " + "itself with /tool fetch from a URL it can reach.");
+  }
+  const ssh = 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
+  });
+  if (!await ssh.connect()) {
+    throw new Error(connectErrorMessage(name, dc, ssh.lastError));
+  }
+  try {
+    await ssh.uploadFile(remotePath, data);
+  } finally {
+    ssh.disconnect();
+  }
+}
 // src/core/registry.ts
 import { z as z2 } from "zod";
 
@@ -2816,21 +2867,29 @@ ${fileDetails}` : `Section export '${name}.rsc' created successfully.`;
   }),
   defineTool({
     name: "upload_file",
-    title: "Upload File to Device (Simulated)",
+    title: "Upload File to Device",
     annotations: WRITE,
-    description: "Accepts a base64-encoded file intended for the device filesystem. NOTE: the current handler" + " only validates the base64 encoding and returns a simulated success \u2014 it does not transfer" + " bytes to the device over SSH. Once a `.backup` file is present on the device apply it with" + " `restore_backup`; for `.rsc` configuration scripts use `import_configuration`.",
+    description: "Transfer a file to the device filesystem over SFTP (the file subsystem RouterOS exposes on its SSH" + " server) \u2014 this actually pushes the bytes, then verifies the file appears in `/file`. Use it to put" + " a file on the router before another tool can use it: a `.rsc` config script (then apply with" + " `import_configuration`), a `.backup` file (then `restore_backup`), or a certificate/key (then" + " `import_certificate`). `filename` is the DESTINATION path on the device \u2014 root by default" + " (e.g. `config.rsc`), or an external-disk path (e.g. `disk1/cert.pem`). `content_base64` is the file's" + " raw bytes, base64-encoded (binary-safe \u2014 works for `.backup`/cert files, not just text). Overwrites" + " any existing file of the same name. NOT available on MAC-Telnet devices (Layer-2 has no file" + " transfer) \u2014 there, have the router pull the file itself with `/tool fetch` from a reachable URL.",
     inputSchema: {
-      filename: z6.string(),
-      content_base64: z6.string()
+      filename: z6.string().describe("Destination path on the device, e.g. 'config.rsc' or 'disk1/cert.pem'"),
+      content_base64: z6.string().describe("File bytes, base64-encoded (binary-safe)")
     },
     async handler(a, ctx) {
       ctx.info(`Uploading file: filename=${a.filename}`);
+      const data = Buffer.from(a.content_base64, "base64");
+      if (data.length === 0) {
+        return "Nothing to upload: content_base64 is empty or decoded to 0 bytes.";
+      }
       try {
-        Buffer.from(a.content_base64, "base64").toString("utf8");
+        await uploadFileToDevice(ctx.device, a.filename, data);
       } catch (e) {
-        return `Failed to decode file content: ${e instanceof Error ? e.message : String(e)}`;
+        return `Failed to upload '${a.filename}': ${e instanceof Error ? e.message : String(e)}`;
+      }
+      const verify = await executeMikrotikCommand(`/file print count-only where name="${a.filename}"`, ctx);
+      if (verify.trim() === "0") {
+        return `File '${a.filename}' was transferred (${data.length} bytes) but did not appear in /file under ` + "that exact name \u2014 RouterOS may have stored it at a slightly different path. Run list_files to " + "confirm, then apply it (import_configuration / restore_backup / import_certificate).";
       }
-      return `File '${a.filename}' uploaded successfully (simulated).`;
+      return `File '${a.filename}' uploaded successfully (${data.length} bytes) and is now in /file. Apply it: ` + "import_configuration for a `.rsc`, restore_backup for a `.backup`, or import_certificate for a cert.";
     }
   }),
   defineTool({
@@ -4396,10 +4455,17 @@ var changePlanTools = [
       const enabled2 = await safe.enable();
       if (enabled2.startsWith("Error"))
         return 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();
@@ -24979,7 +25045,7 @@ function selectToolModules(filter = {}, catalog = moduleCatalog) {
 // package.json
 var package_default = {
   name: "@usex/mikrotik-mcp",
-  version: "3.28.0",
+  version: "3.29.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usex/mikrotik-mcp",
-  "version": "3.28.0",
+  "version": "3.29.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/tool-catalog.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "3.27.0",
+  "version": "3.28.0",
   "generated": "by scripts/gen-schemas.ts — do not edit by hand",
   "toolCount": 758,
   "tools": [
@@ -25552,22 +25552,24 @@
     },
     {
       "name": "upload_file",
-      "title": "Upload File to Device (Simulated)",
+      "title": "Upload File to Device",
       "risk": "write",
       "annotations": {
         "destructiveHint": false,
         "openWorldHint": false
       },
-      "description": "Accepts a base64-encoded file intended for the device filesystem. NOTE: the current handler only validates the base64 encoding and returns a simulated success — it does not transfer bytes to the device over SSH. Once a `.backup` file is present on the device apply it with `restore_backup`; for `.rsc` configuration scripts use `import_configuration`.",
+      "description": "Transfer a file to the device filesystem over SFTP (the file subsystem RouterOS exposes on its SSH server) — this actually pushes the bytes, then verifies the file appears in `/file`. Use it to put a file on the router before another tool can use it: a `.rsc` config script (then apply with `import_configuration`), a `.backup` file (then `restore_backup`), or a certificate/key (then `import_certificate`). `filename` is the DESTINATION path on the device — root by default (e.g. `config.rsc`), or an external-disk path (e.g. `disk1/cert.pem`). `content_base64` is the file's raw bytes, base64-encoded (binary-safe — works for `.backup`/cert files, not just text). Overwrites any existing file of the same name. NOT available on MAC-Telnet devices (Layer-2 has no file transfer) — there, have the router pull the file itself with `/tool fetch` from a reachable URL.",
       "inputSchema": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",
         "properties": {
           "filename": {
-            "type": "string"
+            "type": "string",
+            "description": "Destination path on the device, e.g. 'config.rsc' or 'disk1/cert.pem'"
           },
           "content_base64": {
-            "type": "string"
+            "type": "string",
+            "description": "File bytes, base64-encoded (binary-safe)"
           }
         },
         "required": ["filename", "content_base64"],

package/schemas/tools/upload_file.json

@@ -4,10 +4,12 @@
   "type": "object",
   "properties": {
     "filename": {
-      "type": "string"
+      "type": "string",
+      "description": "Destination path on the device, e.g. 'config.rsc' or 'disk1/cert.pem'"
     },
     "content_base64": {
-      "type": "string"
+      "type": "string",
+      "description": "File bytes, base64-encoded (binary-safe)"
     }
   },
   "required": ["filename", "content_base64"],