# PasarGuard MCP

PasarGuard MCP is a local Model Context Protocol server for managing one or
more PasarGuard panels through their REST APIs. It is intentionally limited to
panel operations. It does not install servers, manage Vultr, SSH into nodes,
manage Cloudflare/Fastly, or change provider infrastructure.

The server supports both reading and writing. Writes use a two-step plan/apply
workflow: the MCP reads the current object, creates a short-lived confirmation
token, and only applies the saved change after the user confirms it. Update
plans preserve fields that were not changed, which is important because
PasarGuard core and host updates expect complete valid objects.

## Install

```bash
cd projects/pasarguard-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
```

Python 3.11 or newer is required.

## Configure panels

Static configuration is optional. The MCP can also load a credential file
from a chat-driven tool call; see the next section.

Copy `config/panels.example.json` to a file outside Git, for example
`~/.config/pasarguard-mcp/panels.json`, and set the password in an environment
variable:

```bash
export PASARGUARD_MCP_CONFIG="$HOME/.config/pasarguard-mcp/panels.json"
export PASARGUARD_EXAMPLE_PASSWORD='your-panel-password'
```

The configuration accepts multiple named panels:

```json
{
  "panels": {
    "main": {
      "base_url": "https://panel.example.com",
      "username": "admin",
      "password_env": "PASARGUARD_MAIN_PASSWORD",
      "verify_tls": true,
      "timeout": 30
    },
    "staging": {
      "base_url": "https://staging-panel.example.com",
      "username_env": "PASARGUARD_STAGING_USERNAME",
      "password_env": "PASARGUARD_STAGING_PASSWORD"
    }
  }
}
```

An existing bearer token can be configured with `token_env` instead of
`username`/`password`. Do not commit panel URLs, credentials, tokens, node API
keys, certificates, or exported panel objects to this repository.

The local state directory stores confirmation plans and before-snapshots with
mode `0700`/`0600`. Override it with `PASARGUARD_MCP_STATE_DIR` when needed.

## MCP client configuration

For a stdio MCP client, use the installed executable:

```json
{
  "mcpServers": {
    "pasarguard": {
      "command": "/absolute/path/to/projects/pasarguard-mcp/.venv/bin/pasarguard-mcp",
      "env": {
        "PASARGUARD_MCP_CONFIG": "/absolute/path/to/panels.json",
        "PASARGUARD_MAIN_PASSWORD": "set-this-in-your-local-client-config"
      }
    }
  }
}
```

Prefer the client's secret/environment mechanism where it provides one. The
MCP server never prints passwords or bearer tokens to stdout.

## Chat-based credential files

You can tell Codex where an existing local credential file is instead of
putting it in the MCP setup. Ask it to use the `load_panel_credentials` tool,
for example:

```text
Use the PasarGuard credentials in
/Users/me/workspace/memory/30-clients/example/credentials.local.md for the
panel named example. Keep them session-only and test the connection.
```

The tool reads the file locally and extracts only recognized fields. Supported
formats are `.env`, `.md`, and `.markdown`; common keys include `PANEL_URL`,
`PASARGUARD_BASE_URL`, `username`, `password`, and `token`. The password is
never returned by the tool and is kept only in the MCP process by default.

If a Markdown file contains multiple named accounts, select the intended
credential block explicitly. For example, a file with a
`flowship_super_admin` block should be loaded with
`credential_name=flowship_super_admin`. The parser strips one matching pair of
Markdown backticks or quote characters around values. This matters for entries
such as `Password: \`...\``; sending the backticks as part of the password
causes PasarGuard to return HTTP 401. When multiple complete credential blocks
exist, omitting `credential_name` now fails safely instead of merging the
username from one account with the password or URL from another.

The tool accepts `persist=true` only when you explicitly want the profile
written to the protected local JSON config. The default is `persist=false`.
Use absolute local paths and keep credential files outside Git repositories.

### URL, credential, filtering, and output normalization

- Dashboard URLs are normalized to the PasarGuard site root. For example,
  `https://flowshipnet.com/dashboard/` becomes `https://flowshipnet.com`
  before API paths are appended.
- Markdown `##` through `######` headings are selectable credential blocks in
  addition to named list blocks. This supports files where a section such as
  `## PasarGuard Panel (production)` directly contains URL, username, and
  password fields.
- List query keys that correspond to returned item fields are also enforced
  locally with exact matching. This protects callers when a panel silently
  ignores a filter such as `inbound_tag`. Pagination/control keys that are not
  item fields remain upstream-only.
- PasarGuard's `/api/hosts` endpoint returns a bare top-level JSON list, unlike
  the wrapped node/core/group/user endpoints. The MCP normalizes bare lists to
  an object keyed by the resource, such as `{"hosts": [...], "total": N}`.
  FastMCP otherwise emits one text content block per list item, which makes a
  large host inventory easy for downstream tool renderers to split or
  truncate. The normalized object produces one coherent structured block.
- Apply responses are compact receipts. Full updated core objects are not
  returned, and recursive redaction covers Reality `privateKey`/`shortIds` in
  read results. Verification should use the read tools after apply.

## Tool groups

Read operations:

- `list_panels`, `load_panel_credentials`, `test_panel`
- `get_panel_inventory`
- `list_panel_resource`, `get_panel_resource`
- `get_node_realtime_stats`, `get_panel_system_status`

Write planning operations:

- Nodes: create, update, delete, reconnect, sync, reset usage, update core
- Cores: create and update, with explicit optional node restart on updates
- Hosts: create and update
- Groups: create and update
- Users: create and update by numeric ID
- All supported resources can be planned for deletion

Write execution and recovery:

- `apply_change` applies one still-valid confirmation token.
- `inspect_change` shows a safe summary without the stored payload.
- `plan_rollback` creates a new confirmation plan from an applied update's
  before-snapshot.

The normal sequence is:

1. Inspect the panel or resource.
2. Call the relevant `plan_*` tool.
3. Show the returned summary and ask the user for confirmation.
4. Call `apply_change` with the returned token.
5. Verify the resulting resource and node status.

## API compatibility

The implementation follows the current public PasarGuard panel API layout,
including `POST /api/admin/token`, `/api/nodes`, `/api/cores`, `/api/hosts`,
`/api/groups`, `/api/users`, node action endpoints, and ID-based user routes
under `/api/user/by-id/{user_id}`. The panel API can evolve, so endpoint
changes should be updated in `src/pasarguard_mcp/server.py` and covered by
tests before release.

## Development

```bash
.venv/bin/python -m pytest
.venv/bin/python -m compileall -q src tests
.venv/bin/ruff check src tests
```

Tests use an in-memory HTTP transport and never contact a real panel.

### Scoped direct-API fallback

When the hosted MCP approval gateway is unavailable, the repository includes
`scripts/apply_reality_expansion.py`. It uses the same `PasarGuardClient`,
loads session credentials from the Lexo, Flowship, and VSL247 credential files,
checks every requested port/tag for collisions, saves each core once with
`restart_nodes=false` so its inbound tags exist, updates the groups, then
saves each core once with `restart_nodes=true`. Without `--apply` it only
reads and validates the live state; `--verify-only` reads back the current
core/group/node state; `--restart-cores panel:id,...` performs targeted
restart-enabled saves when a previous request timed out. It never creates
hosts.

The hosted connector and local elevated execution were both blocked by an
external HTTP 403 approval-gateway response on 2026-08-18; until that gate is
available, do not report the planned ports as live.

For a targeted Microsoft REALITY target/SNI repair across the same four panel
cores, use `scripts/repair_reality_sni.py`. It validates the exact inbound tag,
port, transport, and old/new SNI before changing only `target` and
`serverNames`, then sends one complete-core `PUT` with `restart_nodes=true` per
target and verifies the read-back. Run without `--apply` for a dry-run,
`--verify-only` for current state, or `--apply` for the authorized repair.

## Security boundary

This is an operations tool with write access. Run it locally over stdio, use a
least-privileged PasarGuard administrator when possible, keep TLS verification
enabled, and review every plan before applying it. Credential-file loading
extracts only known fields and does not return passwords. The MCP deliberately
does not provide a generic arbitrary-URL request tool.