cp config.example.yaml config.yaml

---
inventory:
  plugin: SimpleInventory
  options:
    host_file: "inventory/hosts.yaml"
    group_file: "inventory/groups.yaml"
    defaults_file: "inventory/defaults.yaml"

runner:
  plugin: threaded
  options:
    num_workers: 10

logging:
  enabled: false

{
  "mcpServers": {
    "nornir": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sydasif/nornir-napalm-mcp",
        "nornir-mcp"
      ],
      "env": {
        "NORNIR_CONFIG": "/absolute/path/to/config.yaml"
      }
    }
  }
}

uv run nornir-mcp --help

NORNIR_CONFIG=/path/to/config.yaml uv run nornir-mcp

NORNIR_CONFIG=/path/to/config.yaml uv run nornir-mcp --transport http --host 0.0.0.0 --port 8000

NORNIR_CONFIG=/path/to/config.yaml uv run python -m nornir_mcp

nornir-mcp/
├── nornir_mcp/
│   ├── __init__.py       # Package version
│   ├── __main__.py       # python -m support
│   ├── main.py           # CLI entry point (argparse, transport selection)
│   ├── models.py         # Pydantic data models (InventoryDevice, GetterInfo)
│   ├── errors.py         # Categorized exceptions (McpError, ErrorType) with retryable policy
│   ├── responses.py      # ToolEnvelope / HostOutcome response models and truncation
│   ├── policy.py         # Command canonicalization + classification (READ/SAFE/CONFIG/DANGEROUS/BLOCKED/UNKNOWN)
│   ├── capability.py     # Platform capability gate (netmiko device-type mapping)
│   ├── storage.py        # Immutable backup storage (0600 files, sha256 sidecars, traversal-safe)
│   ├── audit.py          # Append-only JSONL audit logger (hashes only, never config text)
│   ├── changes.py        # Write-path orchestration: capture, plan, fail-closed backups, dry-run, transcript parse
│   ├── runner.py         # Nornir init, config loading, singleton caching, execution lock, NornirLike protocol
│   ├── tasks.py          # Task helpers: device filtering, execution, outcome normalization
│   ├── introspection.py  # NAPALM getter discovery per platform
│   ├── server.py         # FastMCP server instance and the 12 tool definitions
│   └── py.typed          # PEP 561 marker for downstream type checking
├── tests/
│   ├── conftest.py       # Fake Nornir stubs, fake netmiko tasks, pytest fixtures
│   ├── test_server.py    # Unit tests for the 12 MCP tools, envelope contract, tool-surface pin
│   ├── test_policy.py    # Canonicalization, classification, config-line gating
│   ├── test_capability.py# Capability gate + netmiko fakes
│   ├── test_storage.py   # Immutable backup storage
│   ├── test_audit.py     # Audit logger
│   ├── test_tasks.py     # Device filtering and task execution
│   ├── test_runner.py    # Config loading and path expansion
│   ├── test_locking.py   # Global execution lock
│   ├── test_changes.py   # Planning, pre-change backups, dry-run, transcript parsing
│   ├── test_e2e.py       # Full-stack tests through the MCP protocol layer
│   ├── test_cli.py       # CLI entry points
├── config.example.yaml   # Example Nornir configuration
├── pyproject.toml        # Build config, dependencies, and tool settings
├── uv.lock               # Locked dependencies
└── README.md

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=nornir_mcp --cov-branch

# Lint
uv run ruff check .

# Auto-fix lint issues
uv run ruff check --fix .

# Format
uv run ruff format .

# Type check (strict mode)
uv run mypy .

feat(server): add nornir_ping tool
fix(runner): handle missing NORNIR_CONFIG gracefully
refactor: extract _run_nornir_task helper
test: add runner config expansion tests