prisma-sdwan-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Registry-first MCP (Model Context Protocol) server exposing Palo Alto Networks Prisma SD-WAN as 27 semantic AI tools, backed by a 316-action capability registry (308 generated + 8 curated) and the prisma_sase SDK, plus one ION CLI passthrough tool (run_commands) over SSH via netmiko. Python 3.11+, FastMCP.

Commands

# Setup
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .
cp .env.example .env           # five settings; everything else has a code default

# Test (dependency-free core suite; no live tenant needed)
PYTHONPATH=. pytest -q
PYTHONPATH=. pytest -q tests/test_resolver.py            # single file
PYTHONPATH=. pytest -q tests/test_resolver.py::test_name # single test

# Run
prisma-sdwan-mcp --transport stdio
prisma-sdwan-mcp --transport streamable-http --host 0.0.0.0 --port 8000

# Docker
docker build -t prisma-sdwan-mcp .
docker run --rm --env-file .env prisma-sdwan-mcp

Device-dependent behaviour is regression-tested without hardware: tests/fixtures/ion/direct_*.txt holds bytes captured verbatim from a live ION 1200 (6.3.6-b9), and tests/test_ion_replay.py replays them through the real code path with no device attached. It is an ordinary part of the run above — no marker, no hardware.

Two pytest markers exist (live, sdk) for tests requiring a real tenant / the prisma_sase package — see docs/LIVE_VALIDATION.md before running anything against a live controller.

Architecture

Design rule: the registry owns API facts, semantic tools own operator meaning. A tool must never hard-code SDK endpoint details the registry already knows.

AI  --intent-->  Semantic tool (prisma_sdwan_mcp/tools/*.py)
                     |
                     +--> Resolver (resolver.py): name -> ID
                     |      site name -> site_id, element name -> element_id (+ site_id), policy name -> policy_id
                     |      exact match always wins over substring match; multiple matches -> candidates returned, never a silent guess
                     |
                     +--> Workflow logic: one operator intent may fan out into several capability calls
                     v
                 CapabilityExecutor (executor.py)
                     |
                     +--> Catalog lookup (catalog.py)
                     +--> required path-parameter validation, unknown-param rejection
                     +--> POST body checked against normalized registry schema hints
                     +--> SDK method binding (client.py: lazy auth, 401/403 re-auth, bounded backoff on 429/5xx)
                     +--> recursive secret redaction (safety.py) on every response
                     +--> response.py: v2 response envelope, cursor pagination, byte-budget enforcement
                     v
                 Prisma SASE SDK