@usex/mikrotik-mcp 5.6.0 → 5.7.0

package/schemas/tool-catalog.json

@@ -1,9 +1,492 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "generated": "by scripts/gen-schemas.ts — do not edit by hand",
-  "toolCount": 891,
+  "toolCount": 903,
   "tools": [
+    {
+      "name": "trace_round_trip",
+      "title": "Model a Multi-Router Round Trip",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "Trace an explicit IPv4 forward and reverse transit path across up to eight routers using exact saved snapshot IDs. Shows per-hop firewall/routing evidence, declared asymmetry and snapshot provenance. All devices are authorized before snapshot lookup. Static no-NAT scope: NAT, dynamic routing, incomplete evidence and unmodelled constructs stop with UNKNOWN. Freshness/skew checks are enforced. No network requests or router writes. MODELLED never means live connectivity; the return leg assumes established conntrack and a replying host.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "snapshots": {
+            "minItems": 1,
+            "maxItems": 8,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "device": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                },
+                "id": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                }
+              },
+              "required": ["device", "id"],
+              "additionalProperties": false
+            }
+          },
+          "forward": {
+            "minItems": 1,
+            "maxItems": 8,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "device": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                },
+                "ingress": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                },
+                "egress": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                }
+              },
+              "required": ["device", "ingress", "egress"],
+              "additionalProperties": false
+            }
+          },
+          "reverse": {
+            "minItems": 1,
+            "maxItems": 8,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "device": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                },
+                "ingress": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                },
+                "egress": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                }
+              },
+              "required": ["device", "ingress", "egress"],
+              "additionalProperties": false
+            }
+          },
+          "packet": {
+            "type": "object",
+            "properties": {
+              "srcAddress": {
+                "type": "string",
+                "format": "ipv4",
+                "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"
+              },
+              "dstAddress": {
+                "type": "string",
+                "format": "ipv4",
+                "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"
+              },
+              "protocol": {
+                "default": "tcp",
+                "type": "string",
+                "enum": ["tcp", "udp", "icmp"]
+              },
+              "srcPort": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              },
+              "dstPort": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              }
+            },
+            "required": ["srcAddress", "dstAddress", "protocol"],
+            "additionalProperties": false
+          },
+          "maxAgeSeconds": {
+            "default": 900,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 86400
+          },
+          "maxSkewSeconds": {
+            "default": 120,
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 3600
+          }
+        },
+        "required": [
+          "snapshots",
+          "forward",
+          "reverse",
+          "packet",
+          "maxAgeSeconds",
+          "maxSkewSeconds"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "audit_service_contracts",
+      "title": "Audit Enrolled Service Contracts",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "Run the administrator-enrolled service contracts for this device (serviceProbes.scheduled) and return stable failures/unknowns for scheduled-audit regression notifications. New contracts are not enrolled automatically. At most five contracts and ten network checks; no router configuration writes.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "list_service_probe_targets",
+      "title": "List Approved Service Probe Targets",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "List the service probe aliases approved by the server administrator. Probes originate from the MCP host, not the router or client. No network request is made. Empty by default; edit serviceProbes.targets in the server config to enable explicitly bounded endpoints.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "create_service_contract",
+      "title": "Create a Service Health Contract",
+      "risk": "write",
+      "annotations": {
+        "destructiveHint": false,
+        "openWorldHint": false
+      },
+      "description": "Save an immutable device-owned contract of DNS/TCP/TLS/HTTPS checks against administrator-approved aliases, latency thresholds and expected HTTPS status codes. Optionally attach a saved packet suite evaluated against a fresh device export. Definition only: no probes or router writes. To revise a contract, create a new one and select its new ID explicitly.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120
+          },
+          "checks": {
+            "minItems": 1,
+            "maxItems": 10,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "target": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 64
+                },
+                "maxLatencyMs": {
+                  "default": 2000,
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 10000
+                },
+                "expectedStatus": {
+                  "default": [200],
+                  "minItems": 1,
+                  "maxItems": 10,
+                  "type": "array",
+                  "items": {
+                    "type": "integer",
+                    "minimum": 200,
+                    "maximum": 599
+                  }
+                }
+              },
+              "required": ["target", "maxLatencyMs", "expectedStatus"],
+              "additionalProperties": false
+            }
+          },
+          "packetSuiteId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120
+          }
+        },
+        "required": ["name", "checks"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "list_service_contracts",
+      "title": "List Service Health Contracts",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "Read up to 100 local service contract definitions owned by the selected device. No probes are run.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "run_service_contract",
+      "title": "Check a Service Health Contract",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "Run and record bounded DNS/TCP/TLS/HTTPS checks from the MCP host against server-approved, IP-pinned targets. No redirects, request credentials or response bodies. Report PASS/FAIL/UNKNOWN per check, not blanket client health. An optional packet suite reads a fresh /export terse from its device for this run; never tests an old baseline after a change. No router configuration writes. Unknown never passes a rollout gate. For scheduled checks, explicitly enroll contracts and schedule audit_service_contracts.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "service_contract_history",
+      "title": "Read Service Contract History",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "Read the latest 100 recorded service checks for a contract owned by the selected device. A historical passing run is not a current gate result.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "inspect_flow_path",
+      "title": "Inspect Exported Client Flow Path",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "Read the last five minutes of exact IPv4 TCP/UDP five-tuple NetFlow/IPFIX evidence for the selected router. Reports exporter input/output ifIndex and resolves up to eight explicitly named interfaces with read-only OID queries. Requires a unique configured IPv4 host matching the exporter sender. Never enables capture, changes configuration or generates traffic. Unauthenticated UDP exports, current name mappings and no-match results are not proof of VPN encryption, packet loss or application delivery. NAT aliases are not inferred.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "client": {
+            "type": "string",
+            "format": "ipv4",
+            "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"
+          },
+          "destination": {
+            "type": "string",
+            "format": "ipv4",
+            "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"
+          },
+          "source_port": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535
+          },
+          "destination_port": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535
+          },
+          "protocol": {
+            "type": "string",
+            "enum": ["tcp", "udp"]
+          },
+          "interface_names": {
+            "default": [],
+            "maxItems": 8,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128
+            }
+          }
+        },
+        "required": [
+          "client",
+          "destination",
+          "source_port",
+          "destination_port",
+          "protocol",
+          "interface_names"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "list_client_flow_candidates",
+      "title": "List Recent Client Flow Tuples",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "List up to 50 recent exported TCP/UDP tuples originating from an exact client IPv4 on the selected router, including ephemeral source ports, for inspect_flow_path. Reads local NetFlow/IPFIX storage only; does not query the client or router. Requires unambiguous exporter host binding. Missing records do not mean no traffic.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "client": {
+            "type": "string",
+            "format": "ipv4",
+            "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"
+          }
+        },
+        "required": ["client"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "create_investigation",
+      "title": "Investigate a Client and Service",
+      "risk": "write",
+      "annotations": {
+        "destructiveHint": false,
+        "openWorldHint": false
+      },
+      "description": "Read client DHCP/ARP/bridge evidence and VLAN/interface/DNS/route/firewall/NAT context from the selected router and up to two explicit additional routers. Run three router-originated ICMP probes and save a local case. Never changes router configuration or starts captures. WRITE reflects local persistence. Application health remains UNVERIFIED; no endpoint probe is installed. IPv4 or colon-separated MAC clients only. Returns JSON evidence with timestamps, unknowns and next tests.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "client": {
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "ipv4",
+                "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"
+              },
+              {
+                "type": "string",
+                "pattern": "^(?:[\\da-f]{2}:){5}[\\da-f]{2}$"
+              }
+            ]
+          },
+          "target": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 253,
+            "pattern": "^[a-z\\d](?:[a-z\\d.-]*[a-z\\d])?$"
+          },
+          "service": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120
+          },
+          "vantage_devices": {
+            "default": [],
+            "maxItems": 2,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "required": ["client", "target", "service", "vantage_devices"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "list_investigations",
+      "title": "List Client Investigations",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "List up to 100 saved cases for the selected primary device. Cases requiring denied device access are omitted. No router I/O.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "get_investigation",
+      "title": "Read a Client Investigation",
+      "risk": "read",
+      "annotations": {
+        "readOnlyHint": true,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "description": "Read a case by UUID under its primary device. Rechecks access to all evidence devices. Historical evidence is not a current health check.",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      }
+    },
     {
       "name": "find_tools",
       "title": "Find Tools (catalog search)",
@@ -30751,6 +31234,27 @@
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",
         "properties": {
+          "service_contracts": {
+            "description": "Optional service contracts: must pass before any change and after every wave. Probes originate from the MCP host, not the router. Unknown blocks the gate.",
+            "maxItems": 10,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "format": "uuid",
+                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                },
+                "device": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": ["id", "device"],
+              "additionalProperties": false
+            }
+          },
           "commands": {
             "anyOf": [
               {
@@ -30923,7 +31427,7 @@
         "destructiveHint": false,
         "openWorldHint": false
       },
-      "description": "Schedules an audit to run on its own and report only what changed since the previous run. Only READ auditors can be scheduled — this is enforced, not advisory: an unattended loop that can write to a router is a footgun, so schedule the audit and wire the alert to a human instead. Cron is the restricted 5-field form (minute hour day-of-month month day-of-week) with *, ranges, lists and step syntax.\n\nSchedulable auditors:\n  run_security_hardening_audit — Device security posture — services, firewall defaults, credentials, helpers.\n  run_compliance_audit — Scored pass/fail compliance checks across 10 categories.\n  firewall_audit — Shadowed, unreachable, overly-broad and dead firewall rules.\n  run_policy_check — Loaded policy-as-code rules against the device's live configuration.",
+      "description": "Schedules an audit to run on its own and report only what changed since the previous run. Only READ auditors can be scheduled — this is enforced, not advisory: an unattended loop that can write to a router is a footgun, so schedule the audit and wire the alert to a human instead. Cron is the restricted 5-field form (minute hour day-of-month month day-of-week) with *, ranges, lists and step syntax.\n\nSchedulable auditors:\n  audit_service_contracts — Enrolled service contracts: live MCP-host probes, optional fresh-export simulation, explicit unknowns.\n  run_security_hardening_audit — Device security posture — services, firewall defaults, credentials, helpers.\n  run_compliance_audit — Scored pass/fail compliance checks across 10 categories.\n  firewall_audit — Shadowed, unreachable, overly-broad and dead firewall rules.\n  run_policy_check — Loaded policy-as-code rules against the device's live configuration.",
       "inputSchema": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",

package/schemas/tools/audit_service_contracts.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "audit_service_contracts",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}

package/schemas/tools/create_investigation.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "create_investigation",
+  "type": "object",
+  "properties": {
+    "client": {
+      "anyOf": [
+        {
+          "type": "string",
+          "format": "ipv4",
+          "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"
+        },
+        {
+          "type": "string",
+          "pattern": "^(?:[\\da-f]{2}:){5}[\\da-f]{2}$"
+        }
+      ]
+    },
+    "target": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 253,
+      "pattern": "^[a-z\\d](?:[a-z\\d.-]*[a-z\\d])?$"
+    },
+    "service": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120
+    },
+    "vantage_devices": {
+      "default": [],
+      "maxItems": 2,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "required": ["client", "target", "service", "vantage_devices"],
+  "additionalProperties": false
+}

package/schemas/tools/create_service_contract.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "create_service_contract",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120
+    },
+    "checks": {
+      "minItems": 1,
+      "maxItems": 10,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "target": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "maxLatencyMs": {
+            "default": 2000,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10000
+          },
+          "expectedStatus": {
+            "default": [200],
+            "minItems": 1,
+            "maxItems": 10,
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "minimum": 200,
+              "maximum": 599
+            }
+          }
+        },
+        "required": ["target", "maxLatencyMs", "expectedStatus"],
+        "additionalProperties": false
+      }
+    },
+    "packetSuiteId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120
+    }
+  },
+  "required": ["name", "checks"],
+  "additionalProperties": false
+}

package/schemas/tools/get_investigation.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "get_investigation",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    }
+  },
+  "required": ["id"],
+  "additionalProperties": false
+}