"""MCP tool schemas and HTTP-backed handlers (NMS adapter + managed NE). Model-facing tool names use generic Nms*; REST paths remain /v1/ume/* for the current zte-ume provider. Params prefer nms_ne_id with ume_ne_id aliases. """ from __future__ import annotations import os from typing import Any, Callable from .http_client import http_json, http_post_json, mcp_from_handler_result, quote_ne_id _EXEC_MAX_COMMANDS_CAP = 50 _EXEC_MAX_COMMANDS_DEFAULT = 5 def exec_max_commands() -> int: """Mirror netx API NETX_NE_EXEC_MAX_COMMANDS (default 5, hard cap 50).""" try: raw = int(os.getenv("NETX_NE_EXEC_MAX_COMMANDS") or _EXEC_MAX_COMMANDS_DEFAULT) except ValueError: raw = _EXEC_MAX_COMMANDS_DEFAULT return max(1, min(_EXEC_MAX_COMMANDS_CAP, raw)) def _async_min_nes() -> int: try: raw = int(os.getenv("NETX_NE_EXEC_ASYNC_MIN_NES") or 4) except ValueError: raw = 4 return max(0, min(50, raw)) def _truthy_async_flag(raw: Any) -> bool | None: if raw is None: return None if isinstance(raw, bool): return raw text = str(raw).strip().lower() if text in {"1", "true", "yes", "on"}: return True if text in {"0", "false", "no", "off"}: return False return None def _count_exec_ne_targets(args: dict[str, Any]) -> int: n = 0 for key in ("ne_ids", "nms_ne_ids", "ume_ne_ids"): val = args.get(key) if isinstance(val, list): n = max(n, len([x for x in val if str(x or "").strip()])) targets = args.get("targets") if isinstance(targets, list): n = max(n, len([t for t in targets if isinstance(t, dict)])) if n == 0 and ( str(args.get("ne_id") or "").strip() or str(args.get("nms_ne_id") or "").strip() or str(args.get("ume_ne_id") or "").strip() ): return 1 return int(n) def _should_run_exec_async(args: dict[str, Any]) -> bool: flag = _truthy_async_flag(args.get("async")) if flag is False: return False if flag is True: return True min_n = _async_min_nes() if min_n <= 0: return False return _count_exec_ne_targets(args) >= min_n UME_RAW_GROUP_FIELDS = [ "alarm_alarm_key", "alarm_host_name", "alarm_ne_id", "alarm_object_name", "alarm_event_type", "alarm_native_probable_cause", "alarm_perceived_severity", "alarm_is_cleared", "alarm_time_created", "alarm_root_cause_alarm_indication", "ne_ne_id", "ne_ne_name", "ne_user_label", "ne_ip_address", "ne_ipv6_address", "ne_ne_type", "ne_device_level", "ne_host_name", "ne_location", "ne_hardware_version", "ne_loopback", "ne_consistent_state", "ne_interface_version", "ne_mac", "ne_admin_status", "ne_address_type", "ne_connection_status", "ne_maintain_status", "ne_net_mask", "ne_create_time", "ne_creator", "ne_vendor", "ne_source_type", "ne_exists", ] _UME_RAW_FIELD_PRESETS: dict[str, list[str]] = { "brief": [ "alarm_alarm_key", "alarm_host_name", "alarm_perceived_severity", "alarm_event_type", "alarm_last_seen_at", "ne_host_name", "ne_user_label", "ne_ne_name", "ne_ip_address", "ne_exists", ], "evidence": [ "alarm_alarm_key", "alarm_host_name", "alarm_object_name", "alarm_event_type", "alarm_native_probable_cause", "alarm_perceived_severity", "alarm_is_cleared", "alarm_time_created", "alarm_last_seen_at", "ne_host_name", "ne_user_label", "ne_ne_name", "ne_ip_address", "ne_connection_status", "ne_exists", ], "ne_debug": [ "alarm_alarm_key", "alarm_ne_id", "alarm_perceived_severity", "alarm_last_seen_at", "ne_user_label", "ne_ne_name", "ne_ip_address", "ne_ipv6_address", "ne_device_level", "ne_host_name", "ne_connection_status", "ne_admin_status", "ne_address_type", "ne_maintain_status", "ne_exists", ], } def _query_ume_alarms(args: dict[str, Any]) -> dict[str, Any]: page = max(1, int(args.get("page") or 1)) if page > 2: page = 2 page_size = min(500, max(1, int(args.get("page_size") or 50))) params: dict[str, Any] = {"page": page, "page_size": page_size} if str(args.get("severity") or "").strip(): params["severity"] = str(args.get("severity")).strip() keyword = str(args.get("keyword") or "").strip() ne_name = str(args.get("ne_name") or "").strip() if keyword: params["keyword"] = keyword elif ne_name: params["keyword"] = ne_name if str(args.get("ne_id") or "").strip(): params["ne_id"] = str(args.get("ne_id")).strip() if str(args.get("host_name") or "").strip(): params["host_name"] = str(args.get("host_name")).strip() for k in ("time_from", "time_to"): if str(args.get(k) or "").strip(): params[k] = str(args.get(k)).strip() return http_json("GET", "/v1/ume/alarms", params=params) def _aggregate_ume_alarms(args: dict[str, Any]) -> dict[str, Any]: # Agents often pass group_by here (docs historically mixed tools). Route to raw aggregate. group_by = str(args.get("group_by") or "").strip() if group_by: return _aggregate_ume_alarms_raw(args) # Default top 50 named NEs — missing host buckets reported separately. top_ne = max(0, min(500, int(args.get("top_ne") if args.get("top_ne") is not None else 50))) params: dict[str, Any] = {"top_ne": top_ne} if "exclude_missing_host" in args: params["exclude_missing_host"] = bool(args.get("exclude_missing_host")) for k in ("severity", "time_from", "time_to"): if str(args.get(k) or "").strip(): params[k] = str(args.get(k)).strip() return http_json("GET", "/v1/ume/alarms/aggregate", params=params) def _run_ume_diagnostics(args: dict[str, Any]) -> dict[str, Any]: _ = args return http_json("GET", "/v1/ume/diagnostics", params=None) def _query_ume_ne_inventory(args: dict[str, Any]) -> dict[str, Any]: page = max(1, int(args.get("page") or 1)) page_size = min(500, max(1, int(args.get("page_size") or 50))) params: dict[str, Any] = {"page": page, "page_size": page_size} if str(args.get("keyword") or "").strip(): params["keyword"] = str(args.get("keyword")).strip() return http_json("GET", "/v1/ume/inventory/ne", params=params) def _get_ume_ne(args: dict[str, Any]) -> dict[str, Any]: ne_id = str(args.get("ne_id") or "").strip() if not ne_id: return {"ok": False, "error": "ne_id_required", "error_code": "ne_id_required"} return http_json("GET", f"/v1/ume/inventory/ne/{quote_ne_id(ne_id)}", params=None) def _query_ume_alarms_raw(args: dict[str, Any]) -> dict[str, Any]: page = max(1, int(args.get("page") or 1)) page_size = min(500, max(1, int(args.get("page_size") or 50))) params: dict[str, Any] = {"page": page, "page_size": page_size} for k in ("severity", "is_cleared", "ne_id", "event_type", "keyword", "time_from", "time_to", "order_by", "order"): v = str(args.get(k) or "").strip() if v: params[k] = v sf = args.get("select_fields") fields: list[str] = [] if isinstance(sf, list): fields = [str(x).strip() for x in sf if str(x).strip()] if not fields: preset = str(args.get("field_preset") or "").strip().lower() fields = list(_UME_RAW_FIELD_PRESETS.get(preset) or []) if fields: params["select_fields"] = ",".join(fields) return http_json("GET", "/v1/ume/alarms/raw", params=params) def _aggregate_ume_alarms_raw(args: dict[str, Any]) -> dict[str, Any]: params: dict[str, Any] = {} for k in ( "group_by", "group_by2", "severity", "is_cleared", "ne_id", "event_type", "keyword", "time_from", "time_to", "limit", ): v = args.get(k) if v is None: continue sv = str(v).strip() if sv: params[k] = sv if "exclude_missing_host" in args: params["exclude_missing_host"] = bool(args.get("exclude_missing_host")) return http_json("GET", "/v1/ume/alarms/aggregate/raw", params=params) def _list_ume_alarm_fields(args: dict[str, Any]) -> dict[str, Any]: _ = args return http_json("GET", "/v1/ume/alarms/fields", params=None) def _sql_query_ume(args: dict[str, Any]) -> dict[str, Any]: sql = str(args.get("sql") or "").strip() limit = max(1, min(2000, int(args.get("limit") or 200))) statement_timeout_ms = max(0, min(30000, int(args.get("statement_timeout_ms") or 0))) if not sql: return {"ok": False, "error": "sql_required"} return http_post_json( "/v1/sql/ume_query", {"sql": sql, "limit": limit, "statement_timeout_ms": statement_timeout_ms}, timeout=60.0, ) def _list_managed_ne(args: dict[str, Any]) -> dict[str, Any]: page = max(1, int(args.get("page") or 1)) page_size = min(100, max(1, int(args.get("page_size") or 20))) keyword = str(args.get("keyword") or "").strip() vendor = str(args.get("vendor") or "").strip() connect_status = str(args.get("connect_status") or "").strip() if not (keyword or vendor or connect_status): return {"ok": False, "error": "managed_ne_filter_required", "error_code": "managed_ne_filter_required"} if keyword and len(keyword) < 2: return {"ok": False, "error": "managed_ne_keyword_too_short", "error_code": "managed_ne_keyword_too_short"} params: dict[str, Any] = {"page": page, "page_size": page_size} if keyword: params["keyword"] = keyword if vendor: params["vendor"] = vendor if connect_status: params["connect_status"] = connect_status return http_json("GET", "/v1/managed-ne", params=params) def _first_str(*vals: Any) -> str: for v in vals: s = str(v or "").strip() if s: return s return "" def _get_managed_ne(args: dict[str, Any]) -> dict[str, Any]: ne_id = str( args.get("ne_id") or args.get("managed_ne_id") or args.get("id") or "" ).strip() if not ne_id: return { "ok": False, "error": "ne_id_required", "error_code": "ne_id_required", "hint": ( "Pass managed NE id from listManagedNe/listCliTargets (source=managed). " "For NMS inventory UUIDs use execManagedNe(nms_ne_id=...) or getNmsNe, not getManagedNe." ), "example": {"ne_id": ""}, } # NMS ne_id is typically a UUID; managed NE may differ. Soft-guide when callers mix them. out = http_json("GET", f"/v1/managed-ne/{ne_id}", params=None) if isinstance(out, dict) and out.get("ok") is False: detail = str(out.get("detail") or out.get("error") or "") low = detail.lower() if "404" in low or "not_found" in low or "not found" in low or out.get("error") == "netx_http_404": out = dict(out) out["hint"] = ( "Managed NE not found for this ne_id. Call listManagedNe(keyword=...) or " "listCliTargets(source=managed) first. If this is an NMS ne_id, use " "execManagedNe(nms_ne_id=...) / getNmsNe instead of getManagedNe." ) return out def _exec_managed_ne(args: dict[str, Any]) -> dict[str, Any]: targets_raw = args.get("targets") ne_ids_raw = args.get("ne_ids") nms_ne_ids_raw = args.get("nms_ne_ids") if not isinstance(nms_ne_ids_raw, list) or not nms_ne_ids_raw: nms_ne_ids_raw = args.get("ume_ne_ids") shared_cmds_raw = args.get("commands") shared_commands = ( [str(c).strip() for c in shared_cmds_raw if str(c).strip()] if isinstance(shared_cmds_raw, list) else [] ) multi = bool( (isinstance(targets_raw, list) and targets_raw) or (isinstance(ne_ids_raw, list) and ne_ids_raw) or (isinstance(nms_ne_ids_raw, list) and nms_ne_ids_raw) ) want_async = _should_run_exec_async(args) if multi: body: dict[str, Any] = {} if isinstance(targets_raw, list) and targets_raw: cleaned_targets: list[dict[str, Any]] = [] for t in targets_raw: if not isinstance(t, dict): continue row: dict[str, Any] = {} if str(t.get("ne_id") or "").strip(): row["ne_id"] = str(t.get("ne_id")).strip() # Wire still uses ume_ne_id on REST; accept nms_ne_id as preferred model param. nms_id = _first_str(t.get("nms_ne_id"), t.get("ume_ne_id")) if nms_id: row["ume_ne_id"] = nms_id cmds = t.get("commands") if isinstance(cmds, list) and cmds: row["commands"] = [str(c).strip() for c in cmds if str(c).strip()] if row: cleaned_targets.append(row) body["targets"] = cleaned_targets if isinstance(ne_ids_raw, list) and ne_ids_raw: body["ne_ids"] = [str(x).strip() for x in ne_ids_raw if str(x).strip()] if isinstance(nms_ne_ids_raw, list) and nms_ne_ids_raw: body["ume_ne_ids"] = [str(x).strip() for x in nms_ne_ids_raw if str(x).strip()] if shared_commands: if len(shared_commands) > exec_max_commands(): return {"ok": False, "error": "too_many_commands", "error_code": "too_many_commands"} body["commands"] = shared_commands rts = args.get("read_timeout_sec") body["read_timeout_sec"] = int(rts) if rts is not None else 60 conc = args.get("concurrency") if conc is not None: body["concurrency"] = int(conc) if want_async: out = http_post_json("/v1/managed-ne/exec-jobs", body, timeout=60.0) if not out.get("ok"): return out data = out.get("data") if isinstance(out.get("data"), dict) else out return data if isinstance(data, dict) else {"ok": True, "data": data} # Wall clock: many NEs × per-cmd timeout; keep below oclaw MCP override. out = http_post_json("/v1/managed-ne/exec-batch", body, timeout=600.0) if not out.get("ok"): return out data = out.get("data") or {} if isinstance(data, dict) and data.get("ok") is False: return {"ok": False, "data": data, "error": str(data.get("error") or "exec_batch_failed")} return {"ok": True, "data": data} ne_id = str(args.get("ne_id") or "").strip() nms_ne_id = _first_str(args.get("nms_ne_id"), args.get("ume_ne_id")) if bool(ne_id) == bool(nms_ne_id): return { "ok": False, "error": "exactly_one_of_ne_id_or_nms_ne_id_required", "error_code": "exactly_one_of_ne_id_or_nms_ne_id_required", "hint": ( "For one NE pass ne_id OR nms_ne_id (alias ume_ne_id). For many NEs pass " "ne_ids / nms_ne_ids with shared commands, or targets[] with per-NE commands — " "one call, concurrent on server." ), } if not shared_commands: return {"ok": False, "error": "commands_required", "error_code": "commands_required"} if len(shared_commands) > exec_max_commands(): return {"ok": False, "error": "too_many_commands", "error_code": "too_many_commands"} body = {"commands": shared_commands} if ne_id: body["ne_id"] = ne_id if nms_ne_id: body["ume_ne_id"] = nms_ne_id # Default 60s matches netx API default; slow show commands often exceed 30s. rts = args.get("read_timeout_sec") body["read_timeout_sec"] = int(rts) if rts is not None else 60 if want_async: out = http_post_json("/v1/managed-ne/exec-jobs", body, timeout=60.0) if not out.get("ok"): return out data = out.get("data") if isinstance(out.get("data"), dict) else out return data if isinstance(data, dict) else {"ok": True, "data": data} out = http_post_json("/v1/managed-ne/exec", body, timeout=300.0) if not out.get("ok"): return out data = out.get("data") or {} if isinstance(data, dict) and data.get("ok") is False: return {"ok": False, "data": data, "error": str(data.get("error") or "exec_failed")} return {"ok": True, "data": data} def _get_ne_exec_job(args: dict[str, Any]) -> dict[str, Any]: job_id = str(args.get("job_id") or "").strip() if not job_id: return { "ok": False, "error": "job_id_required", "error_code": "job_id_required", "hint": "Pass job_id from execManagedNe async ack.", } return http_json("GET", f"/v1/managed-ne/exec-jobs/{quote_ne_id(job_id)}", params=None) def _list_cli_targets(args: dict[str, Any]) -> dict[str, Any]: page = max(1, int(args.get("page") or 1)) page_size = min(500, max(1, int(args.get("page_size") or 50))) params: dict[str, Any] = {"page": page, "page_size": page_size} source = str(args.get("source") or "").strip() if source: # API still uses source=ume; accept model-facing "nms". params["source"] = "ume" if source.lower() == "nms" else source if str(args.get("keyword") or "").strip(): params["keyword"] = str(args.get("keyword")).strip() return http_json("GET", "/v1/cli/targets", params=params) def _find_topology_paths(args: dict[str, Any]) -> dict[str, Any]: from_uid = _first_str(args.get("from_nms_ne_id"), args.get("from_ume_ne_id")) from_mid = str(args.get("from_managed_ne_id") or "").strip() to_uid = _first_str(args.get("to_nms_ne_id"), args.get("to_ume_ne_id")) to_mid = str(args.get("to_managed_ne_id") or "").strip() if bool(from_uid) == bool(from_mid): return {"ok": False, "error": "exactly_one_of_from_nms_ne_id_or_from_managed_ne_id_required"} if bool(to_uid) == bool(to_mid): return {"ok": False, "error": "exactly_one_of_to_nms_ne_id_or_to_managed_ne_id_required"} detail = str(args.get("detail") or "summary").strip().lower() or "summary" if detail not in {"summary", "full"}: detail = "summary" body: dict[str, Any] = { "max_paths": max(1, min(10, int(args.get("max_paths") or 3))), "max_hops": max(1, min(12, int(args.get("max_hops") or 6))), "layer": str(args.get("layer") or "physical").strip() or "physical", "detail": detail, } if from_uid: body["from_ume_ne_id"] = from_uid else: body["from_managed_ne_id"] = from_mid if to_uid: body["to_ume_ne_id"] = to_uid else: body["to_managed_ne_id"] = to_mid return http_post_json("/v1/topology/fabric/paths", body, timeout=30.0) HTTP_MCP_TOOLS: list[dict[str, Any]] = [ { "name": "queryNmsAlarms", "description": ( "Query NMS current alarms (each row includes host_name). " "Supports severity/ne_id/host_name/keyword, last_seen time_from/time_to, pagination. " "Prefer host_name for display; ne_id is for filters only. " "Field keyword examples (native_probable_cause): LOS, Fiber Break, bandwidth, CRC, " "BN EMS, dying gasp, License, BGP Neighbour, Port down, optical power, NTP. " "Area = hostname prefix (MDN-/MKS-/PLG-/ACH-/PAD-/BJM-/…). " "Optical-power threshold ≠ fiber cut; capacity A<>B is CLI optics, not this tally alone." ), "inputSchema": { "type": "object", "properties": { "severity": {"type": "string"}, "ne_id": {"type": "string", "description": "Filter only; do not show UUID to users"}, "host_name": {"type": "string", "description": "Filter by NE host_name"}, "ne_name": {"type": "string", "description": "Legacy alias mapped to keyword"}, "keyword": { "type": "string", "description": ( "Substring on cause/object/event. Examples: LOS, Fiber Break, bandwidth, " "CRC, BN EMS, dying gasp, License, optical power, BGP Neighbour." ), }, "time_from": {"type": "string", "description": "ISO time; filters last_seen_at >="}, "time_to": {"type": "string", "description": "ISO time; filters last_seen_at <="}, "page": {"type": "integer", "minimum": 1, "default": 1}, "page_size": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50}, }, "required": [], "additionalProperties": False, }, }, { "name": "aggregateNmsAlarms", "description": ( "Aggregate NMS current alarms (by_severity + top by_ne). " "Optional severity filter (e.g. critical) for risk Top-N. " "by_ne is capped by top_ne (default 50) and excludes missing host_name by default " "(see by_ne_missing). meta.last_seen_min/max show data freshness. " "If group_by is set (e.g. alarm_host_name), automatically routes to the same " "behavior as aggregateNmsAlarmsRaw — preferred for custom dimensions. " "Snapshot volumes are large (tens of thousands); always filter severity/keyword/time " "before paging — do not dump unfiltered lists." ), "inputSchema": { "type": "object", "properties": { "severity": { "type": "string", "description": "Optional perceived_severity filter (critical/major/minor/warning).", }, "top_ne": { "type": "integer", "minimum": 0, "maximum": 500, "default": 50, "description": "Max NE buckets to return (0 = all, capped at API 5000). Ignored when group_by is set.", }, "exclude_missing_host": { "type": "boolean", "default": True, "description": "Omit (host_name missing) from by_ne / host rankings.", }, "time_from": {"type": "string", "description": "ISO time; filters last_seen_at >="}, "time_to": {"type": "string", "description": "ISO time; filters last_seen_at <="}, "group_by": { "type": "string", "enum": UME_RAW_GROUP_FIELDS, "description": ( "Optional. When set, routes to dynamic raw aggregation " "(same as aggregateNmsAlarmsRaw). Prefer alarm_host_name for NE Top." ), }, "group_by2": { "type": "string", "enum": UME_RAW_GROUP_FIELDS, "description": "Optional second group field when group_by is set.", }, "is_cleared": {"type": "string", "description": "Only used when group_by is set."}, "ne_id": {"type": "string", "description": "Only used when group_by is set."}, "event_type": {"type": "string", "description": "Only used when group_by is set."}, "keyword": {"type": "string", "description": "Only used when group_by is set."}, "limit": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 200, "description": "Bucket limit when group_by is set (default 200).", }, }, "required": [], "additionalProperties": False, }, }, { "name": "runNmsDiagnostics", "description": ( "NMS alarm diagnostics: severity, top_event_types, top_alarm_codes (vendor alarmCode), " "top_ne (excludes missing host), protocol buckets, and meta.last_seen_min/max freshness." ), "inputSchema": {"type": "object", "properties": {}, "required": [], "additionalProperties": False}, }, { "name": "queryNmsNeInventory", "description": "Paged NMS NE inventory synced in netx (keyword matches ne_id/ne_name/user_label/ip/host_name).", "inputSchema": { "type": "object", "properties": { "keyword": {"type": "string"}, "page": {"type": "integer", "minimum": 1, "default": 1}, "page_size": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50}, }, "required": [], "additionalProperties": False, }, }, { "name": "getNmsNe", "description": "Get single NMS NE detail by ne_id (UUID).", "inputSchema": { "type": "object", "properties": {"ne_id": {"type": "string"}}, "required": ["ne_id"], "additionalProperties": False, }, }, { "name": "queryNmsAlarmsRaw", "description": ( "Power query NMS current alarms with full alarm_* + ne_* fields; optional field_preset or select_fields. " "Use field_preset=evidence for WA citations. Same keyword vocabulary as queryNmsAlarms " "(LOS / Fiber Break / bandwidth / CRC / BN EMS / dying gasp / License / optical power). " "For area asks: keyword then keep hosts starting with AREA- (e.g. PAD-, ACH-, BPP-)." ), "inputSchema": { "type": "object", "properties": { "severity": {"type": "string"}, "is_cleared": {"type": "string"}, "ne_id": {"type": "string"}, "event_type": {"type": "string"}, "keyword": { "type": "string", "description": "Substring filter; see queryNmsAlarms keyword examples.", }, "time_from": {"type": "string"}, "time_to": {"type": "string"}, "order_by": { "type": "string", "enum": ["last_seen_at", "time_created", "perceived_severity", "event_type", "ne_id"], }, "order": {"type": "string", "enum": ["asc", "desc"]}, "select_fields": {"type": "array", "items": {"type": "string"}}, "field_preset": {"type": "string", "enum": ["brief", "evidence", "ne_debug"]}, "page": {"type": "integer", "minimum": 1, "default": 1}, "page_size": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50}, }, "required": [], "additionalProperties": False, }, }, { "name": "aggregateNmsAlarmsRaw", "description": ( "Dynamic aggregation on NMS raw fields (group_by/group_by2); prefer alarm_host_name. " "When grouping by host fields, (host_name missing) is omitted by default " "(see by_ne_missing)." ), "inputSchema": { "type": "object", "properties": { "group_by": {"type": "string", "enum": UME_RAW_GROUP_FIELDS}, "group_by2": {"type": "string", "enum": UME_RAW_GROUP_FIELDS}, "severity": {"type": "string"}, "is_cleared": {"type": "string"}, "ne_id": {"type": "string"}, "event_type": {"type": "string"}, "keyword": {"type": "string"}, "time_from": {"type": "string"}, "time_to": {"type": "string"}, "exclude_missing_host": { "type": "boolean", "default": True, "description": "Omit missing host buckets when grouping by host/user_label fields.", }, "limit": {"type": "integer", "minimum": 1, "maximum": 2000, "default": 200}, }, "required": ["group_by"], "additionalProperties": False, }, }, { "name": "listNmsAlarmFields", "description": "List available fields for NMS raw alarm queries.", "inputSchema": {"type": "object", "properties": {}, "required": [], "additionalProperties": False}, }, { "name": "sqlQueryNms", "description": ( "Read-only SELECT on NMS tables (ume_alarms_current/ume_inventory_ne; zte-ume adapter); " "server enforces limits. Requires netx scope sql:query. If insufficient_scope, use " "aggregateNmsAlarms / queryNmsAlarmsRaw instead." ), "inputSchema": { "type": "object", "properties": { "sql": {"type": "string"}, "limit": {"type": "integer", "minimum": 1, "maximum": 2000, "default": 200}, "statement_timeout_ms": {"type": "integer", "minimum": 0, "maximum": 30000, "default": 0}, }, "required": ["sql"], "additionalProperties": False, }, }, { "name": "listManagedNe", "description": "List filtered netx managed NEs (keyword/vendor/connect_status required); use before execManagedNe.", "inputSchema": { "type": "object", "properties": { "keyword": {"type": "string"}, "vendor": {"type": "string"}, "connect_status": {"type": "string", "enum": ["unknown", "testing", "pass", "fail"]}, "page": {"type": "integer", "minimum": 1, "default": 1}, "page_size": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}, }, "required": [], "additionalProperties": False, }, }, { "name": "getManagedNe", "description": ( "Get one **managed** NE by managed ne_id (from listManagedNe / listCliTargets source=managed). " "Response includes capability (device_family, exec_policy_effective, recommended_mode, hints) " "— read it before complex execManagedNe. " "Do NOT pass NMS inventory UUID here — use getNmsNe or execManagedNe(nms_ne_id=...) instead." ), "inputSchema": { "type": "object", "properties": { "ne_id": { "type": "string", "description": "Managed NE id (not NMS host_name / not NMS ne_id unless they coincide).", }, "managed_ne_id": {"type": "string", "description": "Alias for ne_id."}, "id": {"type": "string", "description": "Alias for ne_id."}, }, "required": [], "additionalProperties": False, }, }, { "name": "execManagedNe", "description": ( f"Run CLI via netx (default read-only: show/display/ping/traceroute; " f"max {exec_max_commands()} commands per NE, NETX_NE_EXEC_MAX_COMMANDS). " "Managed NE exec_policy=linux_shell|unrestricted allows shell/script on Linux or " "MikroTik (routeros/switchos) hosts " "(pipes/&&/;/quotes/heredoc / RouterOS multiline OK; check getManagedNe / listManagedNe). " "Single NE: ne_id OR nms_ne_id (+ alias ume_ne_id) + commands. " "Many NEs (batch-first, server concurrency default 4, max 20): " "(1) same CLI on all → ne_ids[]/nms_ne_ids[] + shared commands; " "(2) different CLI per NE (vendor/role) → ONE targets=[" "{nms_ne_id|ne_id, commands:[…]}, …] — do NOT fall back to one-NE loops. " "Do NOT loop one-NE execManagedNe for multi-NE work. " "Default read_timeout_sec=60; on timeout raise to 90–120 — do not blind-retry. " "Long or multi-NE work: async=true (or auto when ≥4 NEs) returns job_id immediately; " "poll getNeExecJob. Pass async=false to force sync. " "Read getManagedNe.capability before choosing show_only vs script_on_device." ), "inputSchema": { "type": "object", "properties": { "ne_id": {"type": "string"}, "nms_ne_id": {"type": "string", "description": "NMS inventory id (preferred)."}, "ume_ne_id": {"type": "string", "description": "Legacy alias of nms_ne_id."}, "ne_ids": { "type": "array", "items": {"type": "string"}, "maxItems": 20, "description": "Managed NE ids for concurrent batch (shared commands).", }, "nms_ne_ids": { "type": "array", "items": {"type": "string"}, "maxItems": 20, "description": "NMS inventory ne_ids for concurrent batch (shared commands).", }, "ume_ne_ids": { "type": "array", "items": {"type": "string"}, "maxItems": 20, "description": "Legacy alias of nms_ne_ids.", }, "targets": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "ne_id": {"type": "string"}, "nms_ne_id": {"type": "string"}, "ume_ne_id": {"type": "string", "description": "Legacy alias of nms_ne_id."}, "commands": { "type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": exec_max_commands(), }, }, "additionalProperties": False, }, "description": ( "Preferred for mixed-vendor / per-NE command sets: " "each item is one NE (ne_id OR nms_ne_id) with its own commands[]. " "Per-target commands override top-level shared commands. " "Still one concurrent batch — not N single-NE calls." ), }, "commands": { "type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": exec_max_commands(), "description": ( "Commands for single NE, or shared commands for ne_ids/nms_ne_ids. " "Optional fallback for targets that omit per-target commands." ), }, "read_timeout_sec": { "type": "integer", "minimum": 10, "maximum": 120, "default": 60, "description": "Per-command read timeout (default 60; use 90–120 for slow show).", }, "concurrency": { "type": "integer", "minimum": 1, "maximum": 8, "default": 4, "description": "Parallel NEs for batch mode (ignored for single-NE).", }, "async": { "type": "boolean", "description": ( "true=background job_id + getNeExecJob; false=force sync; " "omit=auto for large batches (~4+ NEs, NETX_NE_EXEC_ASYNC_MIN_NES)." ), }, }, "required": [], "additionalProperties": False, }, }, { "name": "getNeExecJob", "description": ( "Poll a background execManagedNe job (job_id from async ack). " "When terminal=true, result holds the exec/exec-batch payload. " "Do not busy-wait; end the turn and poll later if still running." ), "inputSchema": { "type": "object", "properties": { "job_id": {"type": "string", "description": "Job id from execManagedNe async response."}, }, "required": ["job_id"], "additionalProperties": False, }, }, { "name": "listCliTargets", "description": ( "List CLI-capable targets (managed NE and/or NMS inventory). " "Call once per session with keyword/source, cache nms_ne_id/ne_id, " "then execManagedNe — do not re-list before every command." ), "inputSchema": { "type": "object", "properties": { "source": { "type": "string", "enum": ["managed", "nms", "ume", "all"], "default": "all", "description": "nms preferred; ume is a legacy alias mapped to the same inventory.", }, "keyword": {"type": "string"}, "page": {"type": "integer", "minimum": 1, "default": 1}, "page_size": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50}, }, "required": [], "additionalProperties": False, }, }, { "name": "findTopologyPaths", "description": ( "Find up to max_paths simple paths between two fabric nodes for troubleshooting. " "For each endpoint provide exactly one of nms_ne_id (from NMS alarm ne_id; alias " "from_ume_ne_id) or managed_ne_id — resolved to fabric node internally. Returns " "shortest paths first with compact label + node/edge summary (detail=summary default). " "Use after critical alarms to correlate neighboring NEs before CLI login." ), "inputSchema": { "type": "object", "properties": { "from_nms_ne_id": { "type": "string", "description": "Source NMS ne_id (from alarm ne_id); mutually exclusive with from_managed_ne_id", }, "from_ume_ne_id": { "type": "string", "description": "Legacy alias of from_nms_ne_id", }, "from_managed_ne_id": { "type": "string", "description": "Source managed NE id; mutually exclusive with from_nms_ne_id", }, "to_nms_ne_id": { "type": "string", "description": "Target NMS ne_id; mutually exclusive with to_managed_ne_id", }, "to_ume_ne_id": { "type": "string", "description": "Legacy alias of to_nms_ne_id", }, "to_managed_ne_id": { "type": "string", "description": "Target managed NE id; mutually exclusive with to_nms_ne_id", }, "max_paths": {"type": "integer", "minimum": 1, "maximum": 10, "default": 3}, "max_hops": {"type": "integer", "minimum": 1, "maximum": 12, "default": 6}, "layer": {"type": "string", "default": "physical"}, "detail": { "type": "string", "enum": ["summary", "full"], "default": "summary", "description": "summary=compact ops fields; full=include attrs/coords.", }, }, "required": [], "additionalProperties": False, }, }, ] _HANDLERS: dict[str, Callable[[dict[str, Any]], dict[str, Any]]] = { "queryNmsAlarms": _query_ume_alarms, "aggregateNmsAlarms": _aggregate_ume_alarms, "runNmsDiagnostics": _run_ume_diagnostics, "queryNmsNeInventory": _query_ume_ne_inventory, "getNmsNe": _get_ume_ne, "queryNmsAlarmsRaw": _query_ume_alarms_raw, "aggregateNmsAlarmsRaw": _aggregate_ume_alarms_raw, "listNmsAlarmFields": _list_ume_alarm_fields, "sqlQueryNms": _sql_query_ume, "listManagedNe": _list_managed_ne, "getManagedNe": _get_managed_ne, "execManagedNe": _exec_managed_ne, "getNeExecJob": _get_ne_exec_job, "listCliTargets": _list_cli_targets, "findTopologyPaths": _find_topology_paths, } # Minimum scope required to advertise / invoke each tool (matches netx API RBAC). TOOL_REQUIRED_SCOPE: dict[str, str] = { "queryNmsAlarms": "alarms:read", "aggregateNmsAlarms": "alarms:read", "runNmsDiagnostics": "alarms:read", "queryNmsNeInventory": "ne:read", "getNmsNe": "ne:read", "queryNmsAlarmsRaw": "alarms:read", "aggregateNmsAlarmsRaw": "alarms:read", "listNmsAlarmFields": "alarms:read", "sqlQueryNms": "sql:query", "listManagedNe": "ne:read", "getManagedNe": "ne:read", "execManagedNe": "ne:exec", "getNeExecJob": "ne:exec", "listCliTargets": "ne:read", "findTopologyPaths": "ne:read", } def tools_for_scopes(scopes: list[str] | set[str] | frozenset[str] | None) -> list[dict[str, Any]]: """Filter MCP tool list by granted scopes. Empty/None => return all (offline / unauthenticated listing).""" if scopes is None: return list(HTTP_MCP_TOOLS) granted = {str(s).strip().lower() for s in scopes if str(s).strip()} if not granted: return [] out: list[dict[str, Any]] = [] for tool in HTTP_MCP_TOOLS: name = str(tool.get("name") or "") need = TOOL_REQUIRED_SCOPE.get(name) if need is None or need in granted: out.append(tool) return out def call_http_tool(name: str, args: dict[str, Any]) -> dict[str, Any]: fn = _HANDLERS.get(str(name or "").strip()) if not fn: raise ValueError(f"unknown tool: {name}") return mcp_from_handler_result(fn(dict(args or {})))