pan-aiops-ngfw-bpa-mcp 0.1.0

MCP server for the Palo Alto Networks AIOps NGFW Best Practice Assessment (BPA) API

🛡️ AIOps NGFW BPA MCP Server

An MCP server that fully implements the Palo Alto Networks AIOps NGFW Best Practice Assessment (BPA) API, so any MCP-capable agent can generate BPA reports for PAN-OS configurations.

---

✨ Features

• 📡 Full API coverage — every endpoint of the BPA Report API: generate request, job status, report URL.
• 🔄 Complete workflow — also handles the signed-URL steps the API itself doesn't expose: uploading the PAN-OS config and downloading the finished report.
• 🤖 One-shot orchestration — run_bpa_assessment runs generate → upload → poll → fetch → download in a single tool call.
• 🔐 Flexible auth — OAuth2 client credentials with automatic token refresh, or a pre-issued bearer token.
• 🎨 Best Practice Report skill — a bundled Claude Skill turns the raw BPA JSON into a polished Markdown + PDF report.
• 🧪 Tested — unit tests for the client, auth and tool layers using mocked HTTP.

---

🧰 Tools

🔧 Tool	📍 Maps to	📝 Purpose
generate_bpa_report	POST /bpa/v1/requests	Start report generation; returns a job id and a signed upload_url.
get_bpa_job_status	GET /bpa/v1/jobs/{id}	Check job status (UPLOAD_INITIATED → COMPLETED_WITH_SUCCESS/ERROR).
get_bpa_report	GET /bpa/v1/reports/{id}	Get the signed download_url for a finished report.
upload_panos_config	signed URL PUT	Upload a PAN-OS XML config to the upload_url.
download_bpa_report	signed URL GET	Download a finished report to a local file.
run_bpa_assessment	🪄 end-to-end	Generate → upload → poll → fetch → (optionally) download, in one call.

See docs/tools.md for full parameter reference.

---

🚀 Installation

Install (end users)

The server is published to PyPI as pan-aiops-ngfw-bpa-mcp:

# zero-install, run on demand (recommended)
uvx pan-aiops-ngfw-bpa-mcp

# or install as a command
pipx install pan-aiops-ngfw-bpa-mcp

# or into the current environment
pip install pan-aiops-ngfw-bpa-mcp

From source (contributors)

# with uv (recommended)
uv sync

# or with pip
pip install -e .

Requires Python 3.10+.

---

🔐 Authentication

The server needs credentials for the Strata Cloud / SASE-protected BPA API. Two modes are supported — see docs/authentication.md for the full setup.

Option A — OAuth2 client credentials (recommended)

The server fetches and auto-refreshes the bearer token for you.

export BPA_CLIENT_ID="<service-account-client-id>"
export BPA_CLIENT_SECRET="<service-account-client-secret>"
export BPA_TSG_ID="<your-tenant-service-group-id>"

Option B — pre-issued bearer token (testing / CI)

export BPA_ACCESS_TOKEN="<bearer-token>"

If BPA_ACCESS_TOKEN is set it takes precedence and the OAuth2 flow is skipped.

💡 Copy .env.example to .env as a starting point.

---

▶️ Running

# as a module
python -m pan_aiops_ngfw_bpa_mcp

# or via the installed console script
pan-aiops-ngfw-bpa-mcp

The server speaks MCP over stdio.

Use with Claude Desktop / Claude Code

Add to your MCP client configuration:

{
  "mcpServers": {
    "aiops-bpa": {
      "command": "uvx",
      "args": ["pan-aiops-ngfw-bpa-mcp"],
      "env": {
        "BPA_CLIENT_ID": "...",
        "BPA_CLIENT_SECRET": "...",
        "BPA_TSG_ID": "..."
      }
    }
  }
}

See docs/using-with-claude.md for the full end-to-end guide — Claude Desktop and Claude Code setup, verification, example prompts, and troubleshooting.

Inspect with the MCP Inspector

npx @modelcontextprotocol/inspector uvx pan-aiops-ngfw-bpa-mcp

---

💬 Example workflow

"Run a BPA assessment for the config at ./pa-440-config.xml. It's a PA-440, family 400f, serial 023101010101, PAN-OS 11.0. I'm Joe User ([e-mail]). Save the report to ./bpa-report.json."

The agent calls run_bpa_assessment, which:

1. 📨 POSTs the report request and receives a job id + signed upload_url.
2. ⬆️ PUTs the PAN-OS XML config to the upload_url.
3. ⏳ Polls GET /bpa/v1/jobs/{id} until COMPLETED_WITH_SUCCESS.
4. 🔗 GETs the signed download_url.
5. ⬇️ Downloads the JSON report to ./bpa-report.json.

See docs/workflow.md for the step-by-step diagram.

---

🎨 Best Practice Report skill

The MCP server downloads a BPA report as raw JSON. The bundled bpa-best-practice-report Claude Skill turns that JSON into a polished, customizable report — a canonical Markdown file and a visually styled PDF (cover page, scorecard, severity badges, per-category tables). It is a formatter + analysis skill: a bundled script structures the data deterministically, while Claude contributes the executive summary, prioritization and remediation guidance.

pip install -e ".[report]"   # or: pip install -r skills/bpa-best-practice-report/requirements.txt
python skills/bpa-best-practice-report/scripts/render_report.py \
  --report bpa-report.json --analysis analysis.md --out-dir ./out

PDF output needs WeasyPrint's system libraries; without them the skill still produces the Markdown. See docs/best-practice-report.md for the full guide.

---

⚙️ Configuration reference

🌱 Env var	Default	Description
BPA_CLIENT_ID	—	OAuth2 service-account client ID.
BPA_CLIENT_SECRET	—	OAuth2 service-account client secret.
BPA_TSG_ID	—	Tenant Service Group ID (used as the OAuth2 scope).
BPA_ACCESS_TOKEN	—	Pre-issued bearer token; overrides the OAuth2 flow.
BPA_API_BASE_URL	https://api.stratacloud.paloaltonetworks.com/aiops	BPA API base URL.
BPA_AUTH_URL	https://auth.apps.paloaltonetworks.com/oauth2/access_token	OAuth2 token endpoint.
BPA_HTTP_TIMEOUT	30	HTTP timeout in seconds.

---

🧪 Development

pip install -e ".[dev]"
pytest

---

📚 Documentation

• docs/using-with-claude.md — 🤖 end-to-end guide for using the server in Claude
• docs/best-practice-report.md — 🎨 the Best Practice Report skill (Markdown + PDF)
• docs/authentication.md — 🔐 credentials & OAuth2 setup
• docs/tools.md — 🧰 full MCP tool reference
• docs/api-reference.md — 📡 tool ↔ BPA API mapping
• docs/workflow.md — 🔄 end-to-end workflow
• docs/releasing.md — 🚀 release process (maintainers)

---

📄 License

MIT — see LICENSE.

This is an unofficial, community-built integration and is not affiliated with or endorsed by Palo Alto Networks.