Metadata-Version: 2.4
Name: xcpng-aiops
Version: 0.1.0
Summary: XCP-ng AI-powered operations via Xen Orchestra with a built-in governance harness (audit, budget, undo, risk tiers)
Author-email: wei <zhouwei008@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: mcp[cli]<2.0,>=1.10
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<16.0,>=13.0
Requires-Dist: typer<1.0,>=0.12
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.AIops-tools/xcpng-aiops -->

# XCP-ng AIops (preview)

> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Vates, the XCP-ng project, or the Xen Orchestra project.** "XCP-ng", "Xen Orchestra", and "Xen" are trademarks of their owners. MIT licensed.

AI-powered **XCP-ng** operations **via Xen Orchestra's REST API** with a
**built-in governance harness** — unified audit log, policy engine,
token/runaway budget guard, undo-token recording, and graduated-autonomy risk
tiers. Built for homelabs and small/self-hosted XCP-ng fleets that want an AI
agent to triage VM health, storage pressure, backup failures, and patch
posture — with every write audited, previewable, and (where honest)
reversible. Self-contained: no dependencies beyond `httpx` and the MCP SDK.
**Preview — mock-validated only, not yet verified against a live Xen
Orchestra instance.**

> **Requires a Xen Orchestra instance** (XO from sources or the Xen Orchestra
> Appliance, 5.x with `/rest/v0`). XO is the management plane this tool talks
> to — **direct per-host XAPI access is out of scope for v0.1**. Do NOT use
> for Proxmox VE — use proxmox-aiops.

## What works

- **CLI** (`xcpng-aiops ...`): `init`, `overview`, `vm list/get/stats/health-rca/start/stop/reboot/migrate`, `host list/get/missing-patches`, `pool list/get/posture`, `sr list/get/vdis/usage-rca/rescan`, `snapshot list/create/delete/revert`, `backup jobs/logs/failure-rca`, `task list`, `secret set/list/rm/migrate/rotate-password`, `doctor`, `mcp`.
- **MCP server** (`xcpng-aiops mcp` or `xcpng-aiops-mcp`): **27 tools** (19 read, 8 write), every one wrapped with the bundled `@governed_tool` harness.
- **Four flagship RCA analyses** (cause + action structured output): VM health, SR usage, backup-job failures, pool patch & HA posture.
- **Encrypted credentials**: the XO authentication token lives in an encrypted store `~/.xcpng-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `XCPNG_AIOPS_MASTER_PASSWORD` (MCP/CI) or an interactive prompt (CLI).
- **Reversibility**: `vm_start` ↔ `vm_stop` record each other as inverses; `vm_migrate` captures the REAL source host before moving and records "migrate back"; `snapshot_create` captures the created snapshot's REAL id from the XO response and records "delete THAT snapshot". Irreversible ops (`snapshot_delete`, `snapshot_revert`, `vm_reboot`) capture prior state for the audit record and honestly declare **no undo**.
- **Safety**: destructive CLI ops require double confirmation and support `--dry-run`; every write MCP tool takes a `dry_run` preview (no API call, no undo recorded).

## Capability matrix (27 MCP tools)

| Domain | Tools | Count | R/W |
|--------|-------|:-----:|:---:|
| **Overview** | `overview` | 1 | read |
| **VMs** | `vm_list`, `vm_get`, `vm_stats`, `vm_health_rca` | 4 | read |
| | `vm_start`, `vm_stop`, `vm_reboot`, `vm_migrate` | 4 | write (medium) |
| **Hosts** | `host_list`, `host_get` | 2 | read |
| **Pools** | `pool_list`, `pool_get`, `pool_patch_ha_posture` | 3 | read |
| **SRs / VDIs** | `sr_list`, `sr_get`, `vdi_list`, `sr_usage_rca` | 4 | read |
| | `sr_rescan` | 1 | write (low) |
| **Snapshots** | `snapshot_list` | 1 | read |
| | `snapshot_create` (medium), `snapshot_delete` (high), `snapshot_revert` (high) | 3 | write |
| **Backups** | `backup_job_list`, `backup_log_list`, `backup_failure_rca` | 3 | read |
| **Tasks** | `task_list` | 1 | read |

### Flagship RCAs

1. **`vm_health_rca`** — VMs halted unexpectedly (auto-poweron / HA restart priority set), paused/suspended VMs, running VMs without guest tools, CPU/memory pressure from RRD stats → cause + action per finding.
2. **`sr_usage_rca`** — SRs ranked by physical fullness (near-full ≥ 85%, critical ≥ 95%), thin-provision overcommit (virtual allocation > capacity), orphaned VDIs (attached to no VM) with reclaimable bytes per SR.
3. **`backup_failure_rca`** — failed/skipped/interrupted XO backup runs classified: **vdi-chain** (coalesce not finished), **quiesce** (guest VSS), **transport** (remote unreachable), **storage-full**, unknown — with per-job counts and sample messages.
4. **`pool_patch_ha_posture`** — hosts missing patches, hosts pending reboot, **version skew** across a pool's hosts (breaks live migration / rolling updates), multi-host pools without HA.

## Quick start

```bash
uv tool install xcpng-aiops
xcpng-aiops init        # interactive wizard: XO URL + encrypted token
xcpng-aiops doctor      # verify config, encrypted store, XO reachability + pool count
xcpng-aiops overview    # one-shot fleet health summary
```

`init` writes `~/.xcpng-aiops/config.yaml` (non-secret connection details) and
stores the XO token **encrypted** in `~/.xcpng-aiops/secrets.enc`. Example
config it produces:

```yaml
targets:
  - name: xo1
    url: https://xo.example.com   # the XO web origin (management plane)
    verify_ssl: true              # set false only for self-signed lab certs
    api_path: /rest/v0
```

Create the token in the XO UI (**user menu → Personal tokens**) or with
`xo-cli --createToken`. For non-interactive use (MCP server, CI, cron) export
the master password so the store can be unlocked without a prompt:

```bash
export XCPNG_AIOPS_MASTER_PASSWORD='your-master-password'
```

### MCP client config

```json
{
  "mcpServers": {
    "xcpng-aiops": {
      "command": "uvx",
      "args": ["--from", "xcpng-aiops", "xcpng-aiops-mcp"],
      "env": { "XCPNG_AIOPS_MASTER_PASSWORD": "your-master-password" }
    }
  }
}
```

> **Env-block caveat**: MCP clients launch the server with a minimal
> environment — your shell profile's exports are **not** inherited. Put
> `XCPNG_AIOPS_MASTER_PASSWORD` (and, if you use them, `XCPNG_AIOPS_HOME` /
> `XCPNG_AIOPS_CONFIG` / `XCPNG_AUDIT_APPROVED_BY`) in the `env` block above,
> or the encrypted store cannot be unlocked and every tool returns a teaching
> error.

### Managing secrets

```bash
xcpng-aiops secret set xo1              # prompts hidden for the XO token
xcpng-aiops secret list                 # names only, values never shown
xcpng-aiops secret rm xo1
xcpng-aiops secret rotate-password      # re-encrypt under a new master password
xcpng-aiops secret migrate              # import a legacy plaintext .env, then retires it
```

A legacy plaintext env var `XCPNG_<TARGET_NAME_UPPER>_TOKEN` is still honoured
as a fallback with a deprecation warning (migrate with `xcpng-aiops secret migrate`).

## Governance

Every MCP tool passes through the bundled `@governed_tool` harness:

- **Audit** — every call (params, result, status, duration, risk tier, approver, rationale) lands in `~/.xcpng-aiops/audit.db` (relocate with `XCPNG_AIOPS_HOME`).
- **Budget / runaway guard** — cumulative call and wall-time caps, plus a tight-loop circuit breaker (`XCPNG_MAX_TOOL_CALLS`, `XCPNG_MAX_TOOL_SECONDS`, `XCPNG_RUNAWAY_MAX`).
- **Undo recording** — reversible writes record a replayable inverse descriptor to `~/.xcpng-aiops/undo.db` and return an `_undo_id`; irreversible writes record prior state only.
- **Graduated approval** — **secure by default**: with no `~/.xcpng-aiops/rules.yaml`, high-risk operations (`snapshot_delete`, `snapshot_revert`) are **denied** unless `XCPNG_AUDIT_APPROVED_BY` names a human approver (set `XCPNG_AUDIT_RATIONALE` too). `xcpng-aiops init` seeds a starter rules.yaml with that dual-control tier; an operator-authored rules file is honoured as-is.
- **Output hygiene** — all XO-returned text is sanitized and bounded before it reaches the agent.

## 支持范围 / Supported scope

| Area | Read | Write (governed) |
|------|------|------------------|
| VMs | list / get / RRD stats / health RCA | start, stop (clean/hard), reboot (clean/hard), migrate |
| Hosts | list / get / missing patches | — |
| Pools | list / get / patch & HA posture RCA | — |
| SRs / VDIs | list / get / VDI list (orphan filter) / usage RCA | rescan |
| Snapshots | list | create, delete, revert |
| Backups | jobs / logs / failure RCA | — |
| Tasks | list | — |

**缺功能？(Missing something?)** This is a focused preview. Open an issue or PR at
[github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops/issues)
— feature requests, contributions, and comments are all welcome.

## Preview caveats

- **Mock-only**: all behaviour is validated against mocked REST responses; not
  yet run against a live Xen Orchestra instance. `xcpng-aiops doctor` is the
  fastest live check.
- Endpoint paths (e.g. `/vms/<id>/actions/snapshot`, `/vm-snapshots/<id>`,
  `/srs/<id>/actions/rescan`, `/hosts/<id>/missing_patches`, `/backup/logs`)
  are modelled against the documented XO REST `/rest/v0` API and need live
  verification — action names may differ across XO releases.
- **Management plane only**: everything goes through XO. Per-host XAPI,
  XO server management (adding servers, users), and backup job *execution*
  (run/restore) are out of scope for v0.1.
- Out of scope by design: anything that destroys bulk data (VM/VDI deletion) —
  only `snapshot_delete` / `snapshot_revert` discard state, and both are
  `high` risk + double-confirmed.

## Not for

Other hypervisors or VM platforms (use their own ops tools — e.g. Proxmox VE →
proxmox-aiops), NAS/storage appliances, backup software suites, container
clusters, or network devices — those are out of scope for this tool.

## License

MIT — [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops)
