network-aiops 0.1.0__py3-none-any.whl

mcp_server/_shared.py

@@ -0,0 +1,113 @@
+"""Shared MCP server primitives: the FastMCP instance, manager helper,
+error sanitisation, and the ``@tool_errors`` decorator.
+
+Tool modules under ``mcp_server/tools/`` import ``mcp`` from here and register
+their ``@mcp.tool()`` functions onto it. ``mcp_server/server.py`` then imports
+those modules and runs the server.
+
+Keep ``Optional[X]`` (never PEP 604 ``X | None``) in any FastMCP-reflected
+tool signature — on older mcp/pydantic the union eval'd to ``types.UnionType``
+crashes FastMCP's ``issubclass`` check.
+"""
+
+import functools
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from network_aiops.config import load_config
+from network_aiops.connection import ConnectionManager, NetworkApiError
+from network_aiops.governance import sanitize
+
+logger = logging.getLogger(__name__)
+
+_DOCTOR_HINT = "Run 'network-aiops doctor' to verify device config and reachability."
+
+_SUPPORTED = "ios, nxos, nxos_ssh, iosxr, eos, junos"
+
+
+def _safe_error(exc: Exception, tool: str) -> str:
+    """Return an agent-safe error string; log full detail server-side only."""
+    logger.error("Tool %s failed", tool, exc_info=True)
+    _passthrough = (
+        ValueError,
+        FileNotFoundError,
+        KeyError,
+        PermissionError,
+        TimeoutError,
+        ConnectionError,
+        NetworkApiError,
+    )
+    if isinstance(exc, _passthrough):
+        return sanitize(str(exc), 300)
+    return f"{type(exc).__name__}: operation failed."
+
+
+def tool_errors(shape: str = "dict") -> Callable:
+    """Wrap a tool body in the canonical try/except → ``_safe_error`` pattern.
+
+    Place this *between* ``@governed_tool`` and the function so the audit
+    decorator and FastMCP still see the original signature.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        name = func.__name__
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:  # noqa: BLE001 — sanitised below
+                msg = _safe_error(e, name)
+                if shape == "list":
+                    return [{"error": msg, "hint": _DOCTOR_HINT}]
+                if shape == "str":
+                    return f"Error: {msg} {_DOCTOR_HINT}"
+                return {"error": msg, "hint": _DOCTOR_HINT}
+
+        return wrapper
+
+    return decorator
+
+
+mcp = FastMCP(
+    "network-aiops",
+    instructions=(
+        "Governed multi-vendor network device operations (preview) over NAPALM. "
+        f"Officially supported drivers: {_SUPPORTED} (Cisco IOS/IOS-XE, Nexus "
+        "NX-OS, IOS-XR, Arista EOS, Juniper Junos). Read tools: device facts, "
+        "interfaces, IP addresses, BGP/LLDP neighbors, ARP table, config backup, "
+        "and config diff (dry-run). Write tools: config merge, config replace, "
+        "config rollback. An optional NetBox block adds source-of-truth device "
+        "lookups. A 'target' selects a device from config. Every tool runs "
+        "through the network-aiops governance harness (audit / budget / risk-tier "
+        "/ undo). Need another platform (Nokia SR OS, Huawei VRP) or action? "
+        "Request it via a GitHub issue or PR."
+    ),
+)
+
+_conn_mgr: Optional[ConnectionManager] = None
+
+
+def _manager() -> ConnectionManager:
+    """Return the connection manager, lazily initialising it from config."""
+    global _conn_mgr  # noqa: PLW0603
+    if _conn_mgr is None:
+        config_path_str = os.environ.get("NETWORK_AIOPS_CONFIG")
+        config_path = Path(config_path_str) if config_path_str else None
+        _conn_mgr = ConnectionManager(load_config(config_path))
+    return _conn_mgr
+
+
+def _target(name: Optional[str] = None) -> Any:
+    """Resolve a device target by name (or the default device)."""
+    return _manager().target(name)
+
+
+def _netbox() -> Any:
+    """Return a NetBox client (raises a teaching NetworkApiError if unconfigured)."""
+    return _manager().netbox()

mcp_server/server.py

@@ -0,0 +1,33 @@
+"""MCP server wrapping network-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``network_aiops`` ops package and is wrapped with the
+network-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed network device operations (preview) over NAPALM —
+Cisco IOS/IOS-XE, Nexus NX-OS, IOS-XR, Arista EOS, Juniper Junos, plus optional
+NetBox source-of-truth.
+
+Source: https://github.com/AIops-tools/Network-AIops
+License: MIT
+"""
+
+import logging
+
+from mcp_server._shared import _safe_error, mcp, tool_errors
+
+# Importing the tool modules registers every @mcp.tool() onto the shared
+# `mcp` instance. Order does not matter; each module is self-contained.
+from mcp_server.tools import (  # noqa: F401 — side effects
+    config_ops,
+    facts,
+    netbox,
+)
+
+__all__ = ["mcp", "main", "_safe_error", "tool_errors"]
+
+
+def main() -> None:
+    """Run the MCP server over stdio."""
+    logging.basicConfig(level=logging.INFO)
+    mcp.run(transport="stdio")

mcp_server/tools/config_ops.py

@@ -0,0 +1,107 @@
+"""Config MCP tools: backup + diff (read/dry-run), merge + replace + rollback (write).
+
+Every tool is wrapped with ``@governed_tool`` (the network-aiops harness):
+policy pre-check, budget/runaway guard, risk-tier gate, audit logging to
+~/.network-aiops/audit.db, and undo-token recording. ``config_merge`` and
+``config_replace`` capture the pre-change running config and pass an ``undo=``
+lambda so the harness records a ``config_replace``-to-backup reversal (the
+device must support config replace for the undo to apply). ``config_rollback``
+records no undo.
+"""
+
+from typing import Optional
+
+from mcp_server._shared import _target, mcp, tool_errors
+from network_aiops.governance import governed_tool
+from network_aiops.ops import config_ops as ops
+
+
+def _restore_undo(params: dict, result) -> Optional[dict]:
+    """Build the inverse of a committed change: replace config back to the backup."""
+    if not isinstance(result, dict) or "backup" not in result:
+        return None
+    return {
+        "tool": "config_replace",
+        "params": {"target": params.get("target"), "config_text": result["backup"]},
+        "skill": "network-aiops",
+        "note": (
+            "Inverse: restore the captured pre-change running config via "
+            "config_replace. The device must support config replace."
+        ),
+    }
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def config_backup(target: Optional[str] = None) -> dict:
+    """[READ] Return the device running config (a note explains how to save it).
+
+    Args:
+        target: Device name from config; omit to use the default device.
+    """
+    return ops.config_backup(_target(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def config_diff(
+    config_text: str, replace: bool = False, target: Optional[str] = None
+) -> dict:
+    """[READ] DRY-RUN: stage a candidate, return the diff, then discard it.
+
+    Nothing is committed. This is the dry-run primitive for previewing a change.
+
+    Args:
+        config_text: The configuration snippet (merge) or full config (replace).
+        replace: True to diff as a full-config replacement; False (default) to merge.
+        target: Device name from config.
+    """
+    return ops.config_diff(_target(target), config_text, replace=replace)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_restore_undo)
+@tool_errors("dict")
+def config_merge(config_text: str, target: Optional[str] = None) -> dict:
+    """[WRITE] Merge a config snippet and commit. Captures running config for undo.
+
+    Returns ``diff`` (what changed) and ``backup`` (pre-change running config).
+    The recorded undo restores ``backup`` via config_replace.
+
+    Args:
+        config_text: The configuration snippet to merge.
+        target: Device name from config.
+    """
+    return ops.config_merge(_target(target), config_text)
+
+
+@mcp.tool()
+@governed_tool(risk_level="high", undo=_restore_undo)
+@tool_errors("dict")
+def config_replace(config_text: str, target: Optional[str] = None) -> dict:
+    """[WRITE] Replace the full config and commit. HIGH RISK. Captures running for undo.
+
+    Returns ``diff`` and ``backup``. The recorded undo replaces the config back
+    to ``backup`` (the device must support config replace).
+
+    Args:
+        config_text: The full replacement configuration.
+        target: Device name from config.
+    """
+    return ops.config_replace(_target(target), config_text)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def config_rollback(target: Optional[str] = None) -> dict:
+    """[WRITE] Revert the last committed change via NAPALM rollback(). No undo.
+
+    Device support varies (rollback depth is platform-dependent).
+
+    Args:
+        target: Device name from config.
+    """
+    return ops.config_rollback(_target(target))

mcp_server/tools/facts.py

@@ -0,0 +1,87 @@
+"""Read-only device facts MCP tools (NAPALM getters).
+
+Every tool is wrapped with ``@governed_tool`` (the network-aiops harness):
+policy pre-check, budget/runaway guard, graduated-autonomy risk-tier gate, and
+audit logging to ~/.network-aiops/audit.db. These are all READ tools (no undo).
+"""
+
+from typing import Optional
+
+from mcp_server._shared import _target, mcp, tool_errors
+from network_aiops.governance import governed_tool
+from network_aiops.ops import facts as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def device_facts(target: Optional[str] = None) -> dict:
+    """[READ] Core device facts: hostname, vendor, model, OS version, serial, uptime.
+
+    Also returns the interface name list. Use get_interfaces for per-interface
+    state/speed.
+
+    Args:
+        target: Device name from config; omit to use the default device.
+    """
+    return ops.device_facts(_target(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def get_interfaces(target: Optional[str] = None) -> list:
+    """[READ] Interfaces with up/down state, enabled flag, speed, and description.
+
+    Args:
+        target: Device name from config.
+    """
+    return ops.get_interfaces(_target(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def get_interfaces_ip(target: Optional[str] = None) -> list:
+    """[READ] Per-interface IPv4/IPv6 addresses and prefix lengths.
+
+    Args:
+        target: Device name from config.
+    """
+    return ops.get_interfaces_ip(_target(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def get_bgp_neighbors(target: Optional[str] = None) -> list:
+    """[READ] BGP neighbors per VRF: peer, remote AS, up state, prefix counts.
+
+    Args:
+        target: Device name from config.
+    """
+    return ops.get_bgp_neighbors(_target(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def get_lldp_neighbors(target: Optional[str] = None) -> list:
+    """[READ] LLDP neighbors: local port, remote hostname, remote port.
+
+    Args:
+        target: Device name from config.
+    """
+    return ops.get_lldp_neighbors(_target(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def get_arp_table(target: Optional[str] = None) -> list:
+    """[READ] ARP table entries: interface, IP, MAC, age.
+
+    Args:
+        target: Device name from config.
+    """
+    return ops.get_arp_table(_target(target))

mcp_server/tools/netbox.py

@@ -0,0 +1,39 @@
+"""NetBox source-of-truth MCP tools (read-only, optional).
+
+Degrade gracefully: a clear ``NetworkApiError`` (surfaced via ``tool_errors``)
+when NetBox is not configured, instead of an opaque traceback.
+"""
+
+from typing import Optional
+
+from mcp_server._shared import _netbox, mcp, tool_errors
+from network_aiops.governance import governed_tool
+from network_aiops.ops import netbox_ops as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def netbox_list_devices(name: Optional[str] = None, limit: int = 50) -> list:
+    """[READ] List NetBox devices (name, role, site, status, primary IP).
+
+    Requires a configured NetBox block. Use this to confirm intended state
+    before pushing config to a device.
+
+    Args:
+        name: Optional name filter (contains match).
+        limit: Maximum devices to return (default 50).
+    """
+    return ops.netbox_list_devices(_netbox(), limit=limit, name=name)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def netbox_get_device(name: str) -> dict:
+    """[READ] Return a single NetBox device by exact name.
+
+    Args:
+        name: Exact NetBox device name (see netbox_list_devices).
+    """
+    return ops.netbox_get_device(_netbox(), name)

network_aiops/__init__.py

@@ -0,0 +1,11 @@
+"""network-aiops — governed multi-vendor network device operations for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, prompt-injection sanitize) is
+bundled under ``network_aiops.governance`` — this package has no external
+skill-family dependency. Devices are reached over NAPALM (Cisco IOS/IOS-XE,
+Nexus NX-OS, IOS-XR, Arista EOS, Juniper Junos); an optional NetBox block adds
+source-of-truth lookups. Preview: not yet full-coverage.
+"""
+
+__version__ = "0.1.0"

network_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for network-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``network-aiops = "network_aiops.cli:app"`` works unchanged.
+"""
+
+from network_aiops.cli._root import app
+
+__all__ = ["app"]

network_aiops/cli/_common.py

@@ -0,0 +1,84 @@
+"""Shared helpers for network-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[
+    str | None, typer.Option("--target", "-t", help="Device name from config")
+]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Preview the diff without committing")
+]
+OutputOption = Annotated[
+    Path | None, typer.Option("--output", "-o", help="Write output to a file")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    from network_aiops.connection import NetworkApiError
+
+    return (NetworkApiError, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key: {message}"
+            console.print(f"[red]Error: {message}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+def get_manager(config_path: Path | None = None):
+    """Return a ConnectionManager built from config."""
+    from network_aiops.config import load_config
+    from network_aiops.connection import ConnectionManager
+
+    return ConnectionManager(load_config(config_path))
+
+
+def read_config_text(path: Path) -> str:
+    """Read a config-snippet file for merge/replace/diff."""
+    return path.read_text()
+
+
+def dry_run_print(*, operation: str, detail: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview header (the diff is printed by the caller)."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be committed.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  Detail:    {detail}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to commit.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be disruptive.",
+        abort=True,
+    )

network_aiops/cli/_root.py

@@ -0,0 +1,50 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from network_aiops.cli.config import config_app
+from network_aiops.cli.device import device_app
+from network_aiops.cli.doctor import doctor_cmd
+from network_aiops.cli.netbox import netbox_app
+
+app = typer.Typer(
+    name="network-aiops",
+    help="Governed multi-vendor network device operations for AI agents (NAPALM).",
+    no_args_is_help=True,
+)
+
+app.add_typer(device_app, name="device")
+app.add_typer(config_app, name="config")
+app.add_typer(netbox_app, name="netbox")
+app.command("doctor")(doctor_cmd)
+
+
+@app.command("mcp")
+def mcp_cmd() -> None:
+    """Start the MCP server (stdio transport).
+
+    Single-command entry point for MCP clients (does not go through uvx/PyPI
+    resolution at launch):
+        network-aiops mcp
+    """
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: network-aiops requires Python >= 3.11 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}).\n"
+            f"Fix: uv python install 3.12 && "
+            f"uv tool install --python 3.12 --force network-aiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()

network_aiops/cli/config.py

@@ -0,0 +1,111 @@
+"""``network-aiops config ...`` sub-commands (backup / diff / merge / replace / rollback)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from network_aiops.cli._common import (
+    DryRunOption,
+    OutputOption,
+    TargetOption,
+    cli_errors,
+    double_confirm,
+    dry_run_print,
+    get_manager,
+    read_config_text,
+)
+from network_aiops.ops import config_ops
+
+config_app = typer.Typer(help="Device configuration operations.", no_args_is_help=True)
+console = Console()
+
+
+def _resolve(target: str | None):
+    return get_manager().target(target)
+
+
+@config_app.command("backup")
+@cli_errors
+def config_backup_cmd(target: TargetOption = None, output: OutputOption = None) -> None:
+    """Fetch the running config (optionally save it to a file with -o)."""
+    result = config_ops.config_backup(_resolve(target))
+    if output is not None:
+        Path(output).write_text(result["config"])
+        console.print(f"[green]Saved running config of {result['name']} -> {output}[/]")
+    else:
+        console.print(result["config"])
+
+
+@config_app.command("diff")
+@cli_errors
+def config_diff_cmd(
+    config_file: Path,
+    target: TargetOption = None,
+    replace: bool = typer.Option(False, "--replace", help="Diff as a full replace"),
+) -> None:
+    """Dry-run: show the diff a config file would produce (nothing is committed)."""
+    text = read_config_text(config_file)
+    result = config_ops.config_diff(_resolve(target), text, replace=replace)
+    console.print(f"[bold]Diff ({result['mode']}, not committed):[/]")
+    console.print(result["diff"] or "[dim](no changes)[/]")
+
+
+@config_app.command("merge")
+@cli_errors
+def config_merge_cmd(
+    config_file: Path,
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """Merge a config snippet and commit (double confirm; --dry-run shows the diff)."""
+    text = read_config_text(config_file)
+    tgt = _resolve(target)
+    if dry_run:
+        dry_run_print(operation="config_merge", detail=f"merge into {tgt.name}")
+        result = config_ops.config_diff(tgt, text, replace=False)
+        console.print(result["diff"] or "[dim](no changes)[/]")
+        return
+    double_confirm("merge config into", tgt.name)
+    result = config_ops.config_merge(tgt, text)
+    console.print(f"[green]Committed merge to {result['name']}[/]")
+    console.print(result["diff"] or "[dim](no changes)[/]")
+
+
+@config_app.command("replace")
+@cli_errors
+def config_replace_cmd(
+    config_file: Path,
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """Replace the full config and commit (HIGH RISK — double confirm; --dry-run shows diff)."""
+    text = read_config_text(config_file)
+    tgt = _resolve(target)
+    if dry_run:
+        dry_run_print(operation="config_replace", detail=f"replace config of {tgt.name}")
+        result = config_ops.config_diff(tgt, text, replace=True)
+        console.print(result["diff"] or "[dim](no changes)[/]")
+        return
+    double_confirm("REPLACE config of", tgt.name)
+    result = config_ops.config_replace(tgt, text)
+    console.print(f"[green]Committed replace to {result['name']}[/]")
+    console.print(result["diff"] or "[dim](no changes)[/]")
+
+
+@config_app.command("rollback")
+@cli_errors
+def config_rollback_cmd(
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """Revert the last committed change (double confirm; device support varies)."""
+    tgt = _resolve(target)
+    if dry_run:
+        dry_run_print(operation="config_rollback", detail=f"rollback {tgt.name}")
+        return
+    double_confirm("rollback last commit on", tgt.name)
+    config_ops.config_rollback(tgt)
+    console.print(f"[green]Rolled back the last commit on {tgt.name}[/]")