Metadata-Version: 2.4
Name: pan-aiops-ngfw-bpa-mcp
Version: 0.1.0
Summary: MCP server for the Palo Alto Networks AIOps NGFW Best Practice Assessment (BPA) API
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: report
Requires-Dist: jinja2>=3.1; extra == 'report'
Requires-Dist: weasyprint>=62; extra == 'report'
Description-Content-Type: text/markdown

# 🛡️ AIOps NGFW BPA MCP Server

> An [MCP](https://modelcontextprotocol.io) 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.

[![PyPI](https://img.shields.io/pypi/v/pan-aiops-ngfw-bpa-mcp)](https://pypi.org/project/pan-aiops-ngfw-bpa-mcp/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## ✨ Features

- 📡 **Full API coverage** — every endpoint of the [BPA Report API](https://pan.dev/aiops-ngfw-bpa/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](skills/bpa-best-practice-report/)
  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`](docs/tools.md) for full parameter reference.

---

## 🚀 Installation

### Install (end users)

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

```bash
# 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)

```bash
# 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`](docs/authentication.md)
for the full setup.

### Option A — OAuth2 client credentials *(recommended)*

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

```bash
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)*

```bash
export BPA_ACCESS_TOKEN="<bearer-token>"
```

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

> 💡 Copy [`.env.example`](.env.example) to `.env` as a starting point.

---

## ▶️ Running

```bash
# 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:

```json
{
  "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`](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

```bash
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
> (`joe@example.com`). Save the report to `./bpa-report.json`."

The agent calls `run_bpa_assessment`, which:

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

See [`docs/workflow.md`](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`](skills/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.

```bash
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`](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

```bash
pip install -e ".[dev]"
pytest
```

---

## 📚 Documentation

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

---

## 📄 License

MIT — see [LICENSE](LICENSE).

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