@usex/mikrotik-mcp 4.15.0 → 4.17.0

package/README.md

@@ -385,6 +385,7 @@ source** (`bun run gen:schemas`) so they can never drift:
 | **[Firewall Audit](docs/firewall-audit.md)**                  | Shadowed/broad/dead rules, risk-scored                                |
 | **[Security Hardening](docs/security-hardening.md)**          | Per-category audit+remediate, fix by finding_id, snapshot + Safe-Mode |
 | **[Port-Scan Detection](docs/port-scan-detection.md)**        | Detect+tag six scan signatures behind a trust-excluding jump-gate     |
+| **[CAPsMAN Orchestrator](docs/capsman.md)**                   | Wi-Fi fabric audit: coverage/co-channel, weak signal, load, FT & HA   |
 | **[Packet Capture Studio](docs/packet-capture.md)**           | Live TZSP capture + pcap export                                       |
 | **[Discovery](docs/discovery.md)**                            | `bun run discover`, MNDP neighbours, topology map                     |
 | **[Config Studio](docs/config-studio.md)**                    | Edit config in the dashboard with autocomplete                        |

package/dist/cli.js

@@ -25,11 +25,19 @@ import {
   allToolModules,
   allowDevice,
   analyzeDrift,
+  applyWritesSafely,
   attributeChanges,
   backupDir,
   blockDevice,
   buildChangePlan,
+  buildChannelPlanCommands,
+  buildFtCommands,
+  buildHaCommands,
+  buildLoadBalanceCommands,
+  buildSteerCommands,
+  capsmanOverview,
   capture,
+  captureSnapshot,
   checkForUpdate,
   closeAll,
   closeMemoryStore,
@@ -46,6 +54,7 @@ import {
   diffLines,
   executeMikrotikCommand,
   fetchAllReleases,
+  fetchCapsmanState,
   fetchDevices,
   fetchLatestRelease,
   getConfig,
@@ -55,6 +64,7 @@ import {
   getRadiusIncoming,
   getS3Client,
   getUmSettings,
+  haGuidance,
   isEmpty,
   isMacTelnetDevice,
   isPoolEnabled,
@@ -62,6 +72,7 @@ import {
   listAaaEntity,
   listBackups,
   listDevices,
+  loadBalancePlan,
   loadConfig,
   loadFileCacheSync,
   logger,
@@ -87,10 +98,12 @@ import {
   renameBackup,
   renderPlan,
   reopenMemoryStore,
+  reportWeakClients,
   resetRadiusCounters,
   resolveDeviceName,
   restoreLocalBackup,
   riskOf,
+  runCapsmanAudit,
   s3Target,
   sampleAllTraffic,
   sampleDeviceTraffic,
@@ -102,13 +115,14 @@ import {
   setRadiusIncoming,
   setUmSettings,
   splitCommands,
+  steerAlreadyPresent,
   subscribe,
   subscriberCount,
   toggleAaaEntity,
   updateAaaEntity,
   updateSummaryLine,
   writeBackup
-} from "./shared/cli-w6ecrhxa.js";
+} from "./shared/cli-v75jtv6p.js";
 
 // src/cli.ts
 import { existsSync as existsSync2 } from "fs";
@@ -117,7 +131,7 @@ import { existsSync as existsSync2 } from "fs";
 import { spawn } from "child_process";
 import { readFileSync as readFileSync3 } from "fs";
 import { homedir, networkInterfaces } from "os";
-import { dirname as dirname4, join as join3 } from "path";
+import { dirname as dirname5, join as join3 } from "path";
 var {serve } = globalThis.Bun;
 import { z as z2 } from "zod";
 
@@ -1018,9 +1032,172 @@ async function openSqliteStore(path) {
   return new SqliteEventStore(db);
 }
 
-// src/observability/usage-store.ts
+// src/observability/capsman-store.ts
 import { mkdirSync as mkdirSync4 } from "fs";
 import { dirname as dirname3 } from "path";
+function summariseRadioSamples(rows) {
+  const byRadio = new Map;
+  for (const r of rows) {
+    const list = byRadio.get(r.radioId);
+    if (list)
+      list.push(r);
+    else
+      byRadio.set(r.radioId, [r]);
+  }
+  const series = [];
+  for (const [radioId, list] of byRadio) {
+    list.sort((a, b) => a.ts - b.ts);
+    const last = list[list.length - 1];
+    const points = list.map((r) => ({ ts: r.ts, clients: r.clients, channel: r.channel }));
+    const peak = points.reduce((m, p) => Math.max(m, p.clients), 0);
+    const total = points.reduce((s, p) => s + p.clients, 0);
+    series.push({
+      radioId,
+      cap: last.cap,
+      band: last.band,
+      points,
+      peak,
+      avg: points.length ? Math.round(total / points.length) : 0
+    });
+  }
+  return series.sort((a, b) => a.radioId.localeCompare(b.radioId));
+}
+var SCHEMA_STATEMENTS2 = [
+  `CREATE TABLE IF NOT EXISTS capsman_samples (
+     device TEXT NOT NULL,
+     radio_id TEXT NOT NULL,
+     cap TEXT NOT NULL,
+     band TEXT NOT NULL,
+     ts INTEGER NOT NULL,
+     clients INTEGER NOT NULL,
+     channel INTEGER
+   )`,
+  "CREATE INDEX IF NOT EXISTS idx_capsman_radio ON capsman_samples(device, radio_id, ts)",
+  "CREATE INDEX IF NOT EXISTS idx_capsman_ts ON capsman_samples(ts)"
+];
+
+class SqliteCapsmanStore {
+  db;
+  constructor(db) {
+    this.db = db;
+    db.run("PRAGMA journal_mode = WAL");
+    db.run("PRAGMA synchronous = NORMAL");
+    for (const stmt of SCHEMA_STATEMENTS2)
+      db.run(stmt);
+  }
+  recordRadioSamples(device, ts, samples) {
+    if (samples.length === 0)
+      return;
+    const insert = this.db.query(`INSERT INTO capsman_samples (device, radio_id, cap, band, ts, clients, channel)
+       VALUES ($d,$r,$cap,$band,$ts,$c,$ch)`);
+    const tx = this.db.transaction((rows) => {
+      for (const r of rows) {
+        insert.run({
+          $d: device,
+          $r: r.radioId,
+          $cap: r.cap,
+          $band: r.band,
+          $ts: ts,
+          $c: r.clients,
+          $ch: r.channel ?? null
+        });
+      }
+    });
+    tx(samples);
+  }
+  radioSeries(device, sinceTs) {
+    const rows = this.db.query(`SELECT radio_id AS radioId, cap, band, ts, clients, channel
+         FROM capsman_samples WHERE device=$d AND ts>=$since ORDER BY ts ASC`).all({ $d: device, $since: sinceTs });
+    return summariseRadioSamples(rows);
+  }
+  pruneSamples(olderThanTs) {
+    const res = this.db.query("DELETE FROM capsman_samples WHERE ts < $t").run({ $t: olderThanTs });
+    return Number(res.changes ?? 0);
+  }
+  close() {
+    this.db.close();
+  }
+}
+async function openCapsmanStore(path) {
+  if (path !== ":memory:") {
+    try {
+      mkdirSync4(dirname3(path), { recursive: true });
+    } catch {}
+  }
+  const { Database } = await import("bun:sqlite");
+  const db = new Database(path, { create: true });
+  return new SqliteCapsmanStore(db);
+}
+
+// src/observability/capsman-sampler.ts
+var SERVER_TAG = "mikrotik-mcp";
+var CAPSMAN_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+var DEFAULT_CAPSMAN_INTERVAL_MS = 5 * 60000;
+var MIN_CAPSMAN_INTERVAL_MS = 60000;
+var MAX_CAPSMAN_INTERVAL_MS = 6 * 60 * 60000;
+var timer2 = null;
+var inFlight2 = false;
+var noCapsman = new Set;
+function clampInterval(ms) {
+  if (!Number.isFinite(ms))
+    return DEFAULT_CAPSMAN_INTERVAL_MS;
+  return Math.max(MIN_CAPSMAN_INTERVAL_MS, Math.min(MAX_CAPSMAN_INTERVAL_MS, Math.round(ms)));
+}
+async function sampleDevice(store, device, ts) {
+  if (noCapsman.has(device))
+    return;
+  const ctx = createContext(undefined, device);
+  const state = await fetchCapsmanState(ctx);
+  if (state.path === null) {
+    noCapsman.add(device);
+    return;
+  }
+  const overview = capsmanOverview(state);
+  const samples = overview.radios.map((r) => ({
+    radioId: r.radioId,
+    cap: r.cap,
+    band: r.band,
+    channel: r.channel,
+    clients: r.clientCount
+  }));
+  store.recordRadioSamples(device, ts, samples);
+}
+async function sampleCapsmanOnce(store) {
+  if (inFlight2)
+    return;
+  inFlight2 = true;
+  const ts = Date.now();
+  try {
+    const cfg = getConfig();
+    await Promise.all(Object.entries(cfg.devices).map(async ([name, dc]) => {
+      if (dc.mac)
+        return;
+      try {
+        await sampleDevice(store, name, ts);
+      } catch (e) {
+        logger.warn(`[${SERVER_TAG}] capsman sample failed for '${name}': ${String(e)}`);
+      }
+    }));
+    store.pruneSamples(ts - CAPSMAN_RETENTION_MS);
+  } finally {
+    inFlight2 = false;
+  }
+}
+function startCapsmanSampler(store, intervalMs = DEFAULT_CAPSMAN_INTERVAL_MS) {
+  const ms = clampInterval(intervalMs);
+  sampleCapsmanOnce(store);
+  timer2 = setInterval(() => void sampleCapsmanOnce(store), ms);
+}
+function stopCapsmanSampler() {
+  if (timer2) {
+    clearInterval(timer2);
+    timer2 = null;
+  }
+}
+
+// src/observability/usage-store.ts
+import { mkdirSync as mkdirSync5 } from "fs";
+import { dirname as dirname4 } from "path";
 function dayOf(ts) {
   return new Date(ts).toISOString().slice(0, 10);
 }
@@ -1039,7 +1216,7 @@ function dailyUsageFromSamples(samples) {
   }
   return [...byDay.entries()].map(([day, v]) => ({ day, rx: v.rx, tx: v.tx })).sort((a, b) => a.day.localeCompare(b.day));
 }
-var SCHEMA_STATEMENTS2 = [
+var SCHEMA_STATEMENTS3 = [
   `CREATE TABLE IF NOT EXISTS usage_samples (
      device TEXT NOT NULL,
      subject TEXT NOT NULL,
@@ -1071,7 +1248,7 @@ class SqliteUsageStore {
     this.db = db;
     db.run("PRAGMA journal_mode = WAL");
     db.run("PRAGMA synchronous = NORMAL");
-    for (const stmt of SCHEMA_STATEMENTS2)
+    for (const stmt of SCHEMA_STATEMENTS3)
       db.run(stmt);
   }
   recordClientSamples(device, ts, samples) {
@@ -1140,7 +1317,7 @@ class SqliteUsageStore {
 async function openUsageStore(path) {
   if (path !== ":memory:") {
     try {
-      mkdirSync4(dirname3(path), { recursive: true });
+      mkdirSync5(dirname4(path), { recursive: true });
     } catch {}
   }
   const { Database } = await import("bun:sqlite");
@@ -1149,16 +1326,16 @@ async function openUsageStore(path) {
 }
 
 // src/observability/usage-sampler.ts
-var SERVER_TAG = "mikrotik-mcp";
+var SERVER_TAG2 = "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 timer3 = null;
+var inFlight3 = false;
 var currentStore = null;
 var currentIntervalMs = DEFAULT_USAGE_INTERVAL_MS;
-function clampInterval(ms) {
+function clampInterval2(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)));
@@ -1184,10 +1361,17 @@ async function sampleClients(store, device, ts) {
   }
   store.recordClientSamples(device, ts, samples);
 }
+var noUserManager = new Set;
 async function ingestSessions(store, device) {
+  if (noUserManager.has(device))
+    return;
   const ctx = createContext(undefined, device);
   const out = await executeMikrotikCommand("/user-manager session print detail", ctx);
-  if (isEmpty(out) || looksLikeError(out) || commandUnsupported(out))
+  if (commandUnsupported(out)) {
+    noUserManager.add(device);
+    return;
+  }
+  if (isEmpty(out) || looksLikeError(out))
     return;
   const sessions = [];
   for (const row of parseRecords(out).rows) {
@@ -1209,9 +1393,9 @@ async function ingestSessions(store, device) {
   store.upsertSessions(device, sessions);
 }
 async function sampleUsageOnce(store) {
-  if (inFlight2)
+  if (inFlight3)
     return;
-  inFlight2 = true;
+  inFlight3 = true;
   const ts = Date.now();
   try {
     const cfg = getConfig();
@@ -1222,37 +1406,37 @@ async function sampleUsageOnce(store) {
         await sampleClients(store, name, ts);
         await ingestSessions(store, name);
       } catch (e) {
-        logger.warn(`[${SERVER_TAG}] usage sample failed for '${name}': ${String(e)}`);
+        logger.warn(`[${SERVER_TAG2}] usage sample failed for '${name}': ${String(e)}`);
       }
     }));
     store.pruneSamples(ts - USAGE_RETENTION_MS);
   } finally {
-    inFlight2 = false;
+    inFlight3 = false;
   }
 }
 function startUsageSampler(store, intervalMs = DEFAULT_USAGE_INTERVAL_MS) {
   currentStore = store;
-  currentIntervalMs = clampInterval(intervalMs);
+  currentIntervalMs = clampInterval2(intervalMs);
   sampleUsageOnce(store);
-  timer2 = setInterval(() => void sampleUsageOnce(store), currentIntervalMs);
+  timer3 = setInterval(() => void sampleUsageOnce(store), currentIntervalMs);
 }
 function getUsageSamplerInterval() {
   return currentIntervalMs;
 }
 function setUsageSamplerInterval(intervalMs) {
-  currentIntervalMs = clampInterval(intervalMs);
-  if (timer2)
-    clearInterval(timer2);
+  currentIntervalMs = clampInterval2(intervalMs);
+  if (timer3)
+    clearInterval(timer3);
   if (currentStore) {
     const store = currentStore;
-    timer2 = setInterval(() => void sampleUsageOnce(store), currentIntervalMs);
+    timer3 = setInterval(() => void sampleUsageOnce(store), currentIntervalMs);
   }
   return currentIntervalMs;
 }
 function stopUsageSampler() {
-  if (timer2) {
-    clearInterval(timer2);
-    timer2 = null;
+  if (timer3) {
+    clearInterval(timer3);
+    timer3 = null;
   }
   currentStore = null;
 }
@@ -1614,7 +1798,7 @@ async function memoryRoutes(req, url) {
 }
 
 // src/observability/dashboard.ts
-var SERVER_TAG2 = "mikrotik-mcp";
+var SERVER_TAG3 = "mikrotik-mcp";
 var JSON_HEADERS3 = { "content-type": "application/json; charset=utf-8" };
 function json3(body, status = 200) {
   return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS3 });
@@ -1645,7 +1829,7 @@ function runUpgrade(spec) {
       env: process.env,
       stdio: ["ignore", "pipe", "pipe"]
     });
-    const timer3 = setTimeout(() => {
+    const timer4 = setTimeout(() => {
       child.kill();
       resolve({ ok: false, log: `${out}
 (timed out after 180s)` });
@@ -1653,12 +1837,12 @@ function runUpgrade(spec) {
     child.stdout?.on("data", (d) => out += d.toString());
     child.stderr?.on("data", (d) => out += d.toString());
     child.on("error", (e) => {
-      clearTimeout(timer3);
+      clearTimeout(timer4);
       resolve({ ok: false, log: `${out}
 spawn error: ${String(e)}` });
     });
     child.on("exit", (code) => {
-      clearTimeout(timer3);
+      clearTimeout(timer4);
       resolve({ ok: code === 0, log: out.trim() || `(exit ${code})` });
     });
   });
@@ -1775,7 +1959,7 @@ function devicesPayload(store) {
       }
     };
   });
-  return { server: SERVER_TAG2, defaultDevice: cfg.defaultDevice, devices };
+  return { server: SERVER_TAG3, defaultDevice: cfg.defaultDevice, devices };
 }
 function topologyPayload() {
   const cfg = getConfig();
@@ -1788,7 +1972,7 @@ function topologyPayload() {
   for (const { name } of devices)
     neighborsByDevice[name] = getDeviceNeighbors(name);
   return {
-    server: SERVER_TAG2,
+    server: SERVER_TAG3,
     defaultDevice: cfg.defaultDevice,
     generatedAt: Date.now(),
     ...buildTopology({ devices, neighborsByDevice })
@@ -2171,6 +2355,99 @@ async function captureRoutes(req, url) {
   }
   return null;
 }
+var capsmanStore = null;
+async function capsmanRoutes(req, url) {
+  const p = url.pathname;
+  if (!p.startsWith("/api/capsman"))
+    return null;
+  if (req.method === "GET") {
+    const ctx = createContext(undefined, url.searchParams.get("device") ?? undefined);
+    if (p === "/api/capsman/overview") {
+      return json3(capsmanOverview(await fetchCapsmanState(ctx)));
+    }
+    if (p === "/api/capsman/clients") {
+      const state = await fetchCapsmanState(ctx);
+      const weakDbm = Number.parseInt(url.searchParams.get("weak_dbm") ?? "", 10);
+      const weak = reportWeakClients(state, Number.isFinite(weakDbm) ? weakDbm : undefined);
+      return json3({ clients: state.clients, weak });
+    }
+    if (p === "/api/capsman/audit") {
+      return json3(runCapsmanAudit(await fetchCapsmanState(ctx)));
+    }
+    if (p === "/api/capsman/trends") {
+      if (!capsmanStore)
+        return json3({ error: "capsman store not active" }, 503);
+      const device = resolveDeviceName(url.searchParams.get("device") ?? undefined);
+      const days = daysParam(url, 7, 30);
+      const series = capsmanStore.radioSeries(device, Date.now() - days * 86400000);
+      return json3({ series, days });
+    }
+    return null;
+  }
+  if (req.method === "POST") {
+    const body = await readJson(req);
+    const ctx = createContext(undefined, body?.device);
+    const state = await fetchCapsmanState(ctx);
+    if (p === "/api/capsman/apply/steer") {
+      const client = state.clients.find((c) => c.mac.toLowerCase() === (body.mac ?? "").toLowerCase());
+      if (!client)
+        return json3({ ok: false, error: "client not associated" }, 400);
+      if (steerAlreadyPresent(state, body.mac ?? "")) {
+        return json3({ ok: true, message: "already steered (no-op)" });
+      }
+      const mode = body.mode === "soft" ? "soft" : "hard";
+      const commands = buildSteerCommands(state, body.mac ?? "", client.radioId, mode);
+      if (!body.confirm)
+        return json3({ ok: true, preview: commands });
+      return json3(await applyCapsmanWrites(ctx, commands, `pre-steer-${body.mac}`));
+    }
+    if (p === "/api/capsman/apply/load-balance") {
+      const plan = loadBalancePlan(state);
+      const commands = buildLoadBalanceCommands(state, plan);
+      if (!body.confirm)
+        return json3({ ok: true, preview: commands, plan });
+      return json3(await applyCapsmanWrites(ctx, commands, "pre-load-balance"));
+    }
+    if (p === "/api/capsman/apply/channel-plan") {
+      if (state.path === "/caps-man") {
+        return json3({ ok: false, error: "channel-plan apply is v7 /interface wifi only" }, 400);
+      }
+      const commands = buildChannelPlanCommands(state);
+      if (!body.confirm)
+        return json3({ ok: true, preview: commands });
+      return json3(await applyCapsmanWrites(ctx, commands, "pre-channel-plan"));
+    }
+    if (p === "/api/capsman/apply/ft") {
+      const commands = buildFtCommands(state);
+      if (!body.confirm)
+        return json3({ ok: true, preview: commands });
+      return json3(await applyCapsmanWrites(ctx, commands, "pre-ft"));
+    }
+    if (p === "/api/capsman/apply/ha") {
+      const commands = buildHaCommands(state);
+      const guidance = haGuidance(state);
+      if (!body.confirm)
+        return json3({ ok: true, preview: commands, guidance });
+      const res = await applyCapsmanWrites(ctx, commands, "pre-ha");
+      return json3({ ...res, guidance });
+    }
+  }
+  return null;
+}
+async function applyCapsmanWrites(ctx, commands, label) {
+  if (commands.length === 0)
+    return { ok: true, applied: 0 };
+  const snapshotId = await captureSnapshot(ctx, label);
+  const device = resolveDeviceName(ctx.device);
+  const outcome = await applyWritesSafely(ctx, device, commands, { allowDirectFallback: false });
+  return {
+    ok: outcome.committed && !outcome.error,
+    snapshotId,
+    safeMode: outcome.safeMode,
+    applied: outcome.applied,
+    error: outcome.error
+  };
+}
 async function clientsRoutes(req, url) {
   const p = url.pathname;
   if (!p.startsWith("/api/clients"))
@@ -2559,16 +2836,22 @@ async function runDashboard(cfg, transportLabel) {
   });
   startHealthChecks(30000);
   try {
-    usageStore = await openUsageStore(join3(dirname4(cfg.dbPath), "usage.db"));
+    usageStore = await openUsageStore(join3(dirname5(cfg.dbPath), "usage.db"));
     startUsageSampler(usageStore);
   } catch (e) {
-    logger.warn(`[${SERVER_TAG2}] usage history disabled: ${String(e)}`);
+    logger.warn(`[${SERVER_TAG3}] usage history disabled: ${String(e)}`);
+  }
+  try {
+    capsmanStore = await openCapsmanStore(join3(dirname5(cfg.dbPath), "capsman.db"));
+    startCapsmanSampler(capsmanStore);
+  } catch (e) {
+    logger.warn(`[${SERVER_TAG3}] capsman trends disabled: ${String(e)}`);
   }
   try {
     if (isEmpty2())
       recordVersion(getConfig(), "auto", Date.now(), "baseline");
   } catch (e) {
-    logger.warn(`[${SERVER_TAG2}] could not seed config history baseline: ${String(e)}`);
+    logger.warn(`[${SERVER_TAG3}] could not seed config history baseline: ${String(e)}`);
   }
   const configAdmin = createConfigAdmin({
     getConfig,
@@ -2615,6 +2898,9 @@ async function runDashboard(cfg, transportLabel) {
     const captureResp = await captureRoutes(req, url);
     if (captureResp)
       return captureResp;
+    const capsmanResp = await capsmanRoutes(req, url);
+    if (capsmanResp)
+      return capsmanResp;
     const clientsResp = await clientsRoutes(req, url);
     if (clientsResp)
       return clientsResp;
@@ -2868,10 +3154,13 @@ async function runDashboard(cfg, transportLabel) {
     stop() {
       stopHealthChecks();
       stopUsageSampler();
+      stopCapsmanSampler();
       server.stop(true);
       store.close();
       usageStore?.close();
       usageStore = null;
+      capsmanStore?.close();
+      capsmanStore = null;
       closeMemoryStore();
     }
   };

package/dist/index.js

@@ -29,7 +29,7 @@ import {
   selectToolModules,
   setConfig,
   updateSummaryLine
-} from "./shared/library-212xbkwr.js";
+} from "./shared/library-qma8metz.js";
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

package/dist/shared/{cli-9s02dq5d.js → cli-1ftjz1jx.js}

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