{
  "markdown": "<!-- mcp-name: io.github.AIops-tools/xcpng-aiops -->\n\n# XCP-ng AIops\n\n> **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.\n\nAI-powered **XCP-ng** operations **via Xen Orchestra's REST API** with a\n**built-in governance harness** — unified audit log, policy engine,\ntoken/runaway budget guard, undo-token recording, and descriptive risk\ntiers. Built for homelabs and small/self-hosted XCP-ng fleets that want an AI\nagent to triage VM health, storage pressure, backup failures, and patch\nposture — with every write audited, previewable, and (where honest)\nreversible. Self-contained: no dependencies beyond `httpx` and the MCP SDK.\n\n> **Requires a Xen Orchestra instance** (XO from sources or the Xen Orchestra\n> Appliance, 5.x with `/rest/v0`). XO is the management plane this tool talks\n> to — **direct per-host XAPI access is out of scope for v0.1**. Do NOT use\n> for Proxmox VE — use proxmox-aiops.\n\n## What works\n\n- **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`.\n- **MCP server** (`xcpng-aiops mcp` or `xcpng-aiops-mcp`): **29 tools** (19 read, 8 write, 2 undo), every one wrapped with the bundled `@governed_tool` harness.\n- **Four flagship RCA analyses** (cause + action structured output): VM health, SR usage, backup-job failures, pool patch & HA posture.\n- **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).\n- **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**.\n- **Safety**: destructive CLI ops require double confirmation and support `--dry-run`; every write MCP tool takes a `dry_run` preview (no write call, no undo recorded).\n- **Self-lockout guard (partial — read this)**: Xen Orchestra is commonly a VM on a pool it manages, and stopping that VM kills the API this tool talks to — `vm_start` can then no longer be sent, so recovery needs hypervisor console access (`xe vm-start`). Set `xo_self_vm_uuid` on the target (`xcpng-aiops init` asks) and `vm_stop` refuses exactly that uuid — on `--dry-run` as well, since a preview that green-lights a call the tool will then refuse is reporting the wrong outcome. **If you do not set it there is no protection at all**: XO's REST API exposes no self endpoint and its token carries no claims, so the tool cannot discover which VM it runs on, and it fails open rather than guess. The `dry_run` preview adds a weaker `selfVmHint` when a VM's reported IP matches the configured XO host — that is a coincidence worth checking, not a finding, and it never blocks (it sees nothing without the guest agent and fires on every VM behind a shared proxy).\n\n## Capability matrix (29 MCP tools)\n\n| Domain | Tools | Count | R/W |\n|--------|-------|:-----:|:---:|\n| **Overview** | `overview` | 1 | read |\n| **VMs** | `vm_list`, `vm_get`, `vm_stats`, `vm_health_rca` | 4 | read |\n| | `vm_start`, `vm_stop`, `vm_reboot`, `vm_migrate` | 4 | write (medium) |\n| **Hosts** | `host_list`, `host_get` | 2 | read |\n| **Pools** | `pool_list`, `pool_get`, `pool_patch_ha_posture` | 3 | read |\n| **SRs / VDIs** | `sr_list`, `sr_get`, `vdi_list`, `sr_usage_rca` | 4 | read |\n| | `sr_rescan` | 1 | write (medium) |\n| **Snapshots** | `snapshot_list` | 1 | read |\n| | `snapshot_create` (medium), `snapshot_delete` (high), `snapshot_revert` (high) | 3 | write |\n| **Backups** | `backup_job_list`, `backup_log_list`, `backup_failure_rca` | 3 | read |\n| **Tasks** | `task_list` | 1 | read |\n| **Undo** | `undo_list`, `undo_apply` | 2 | read + replay |\n\n### Flagship RCAs\n\n1. **`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.\n2. **`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.\n3. **`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.\n4. **`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.\n\n## What this tool does, and does not, decide\n\nIt delivers XCP-ng operations — reads and writes — accurately and efficiently,\nand records every one of them. It does **not** decide whether a write is allowed\nto happen. That is the agent's judgement, or the permission of the Xen Orchestra\naccount whose token you connect it with: give that XO user a read-only ACL, or\nscope its token down, and the writes fail at Xen Orchestra — the place that\nactually owns the permission.\n\nSo there is no read-only switch, no policy file, no approval gate to configure.\nThe one thing the tool guarantees is that nothing is silent: **every call, over\nMCP and over the CLI alike, lands an audit row** in `~/.xcpng-aiops/audit.db`,\nand reversible writes still capture their before-state and record an inverse.\n\n> Each tool declares a `risk_level`, kept in agreement with its `[READ]`/`[WRITE]`\n> documentation tag by a test, and carried into the audit row as a descriptive\n> tier — so a reviewer can see at a glance that a row was a high-risk snapshot\n> delete. It is a label, not a gate.\n\nRunning a smaller / local model? See\n[agent-guardrails.md](skills/xcpng-aiops/references/agent-guardrails.md) — it lists\nthe guardrails this tool now enforces for you (so you don't spend prompt budget\nrestating them) and gives a ready-made system prompt for what's left.\n\n## Quick start\n\n### As a Claude Code plugin\n\nOne install gives an agent both the skill and the MCP server:\n\n```\n/plugin marketplace add AIops-tools/marketplace\n/plugin install xcpng-aiops@aiops-tools\n```\n\nThe MCP server is fetched with [uv](https://docs.astral.sh/uv/) and pinned to the\npackage version this plugin declares, so an audit row can be traced back to the\ncode that wrote it. Credentials are still configured with `xcpng-aiops init` — see below.\n\n### As a CLI or standalone MCP server\n\n```bash\nuv tool install xcpng-aiops\nxcpng-aiops init        # interactive wizard: XO URL + encrypted token\nxcpng-aiops doctor      # verify config, encrypted store, XO reachability + pool count\nxcpng-aiops overview    # one-shot fleet health summary\n```\n\n`init` writes `~/.xcpng-aiops/config.yaml` (non-secret connection details) and\nstores the XO token **encrypted** in `~/.xcpng-aiops/secrets.enc`. Example\nconfig it produces:\n\n```yaml\ntargets:\n  - name: xo1\n    url: https://xo.example.com   # the XO web origin (management plane)\n    verify_ssl: true              # set false only for self-signed lab certs\n    api_path: /rest/v0\n```\n\nCreate the token in the XO UI (**user menu → Personal tokens**) or with\n`xo-cli --createToken`. For non-interactive use (MCP server, CI, cron) export\nthe master password so the store can be unlocked without a prompt:\n\n```bash\nexport XCPNG_AIOPS_MASTER_PASSWORD='your-master-password'\n```\n\n### MCP client config\n\n```json\n{\n  \"mcpServers\": {\n    \"xcpng-aiops\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"xcpng-aiops\", \"xcpng-aiops-mcp\"],\n      \"env\": { \"XCPNG_AIOPS_MASTER_PASSWORD\": \"your-master-password\" }\n    }\n  }\n}\n```\n\n> **Env-block caveat**: MCP clients launch the server with a minimal\n> environment — your shell profile's exports are **not** inherited. Put\n> `XCPNG_AIOPS_MASTER_PASSWORD` (and, if you use them, `XCPNG_AIOPS_HOME` /\n> `XCPNG_AIOPS_CONFIG` / `XCPNG_AUDIT_APPROVED_BY`) in the `env` block above,\n> or the encrypted store cannot be unlocked and every tool returns a teaching\n> error.\n\n### Managing secrets\n\n```bash\nxcpng-aiops secret set xo1              # prompts hidden for the XO token\nxcpng-aiops secret list                 # names only, values never shown\nxcpng-aiops secret rm xo1\nxcpng-aiops secret rotate-password      # re-encrypt under a new master password\nxcpng-aiops secret migrate              # import a legacy plaintext .env, then retires it\n```\n\nA legacy plaintext env var `XCPNG_<TARGET_NAME_UPPER>_TOKEN` is still honoured\nas a fallback with a deprecation warning (migrate with `xcpng-aiops secret migrate`).\n\n## Governance\n\nEvery MCP tool — and every CLI write, which routes through the same governed\nfunctions — passes through `@governed_tool`. It records; it does not authorize\n(see above).\n\n- **Audit** — every call (tool, params with secrets redacted, result, status, duration, risk tier, and any operator-supplied approver/rationale) lands in `~/.xcpng-aiops/audit.db` (relocate with `XCPNG_AIOPS_HOME`). The CLI writes the same row the MCP path does — there is no unaudited entry point.\n- **Budget / runaway guard** — a safety backstop, not an authorization gate: cumulative call and wall-time caps plus a tight-loop circuit breaker (`XCPNG_MAX_TOOL_CALLS`, `XCPNG_MAX_TOOL_SECONDS`, `XCPNG_RUNAWAY_MAX`) stop a stuck agent from burning unbounded calls/time.\n- **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.\n- **Risk tier** — a descriptive label on the audit row derived from `risk_level`; it gates nothing.\n- **Output hygiene** — all XO-returned text is sanitized and bounded before it reaches the agent.\n\n## 支持范围 / Supported scope\n\n| Area | Read | Write (governed) |\n|------|------|------------------|\n| VMs | list / get / RRD stats / health RCA | start, stop (clean/hard), reboot (clean/hard), migrate |\n| Hosts | list / get / missing patches | — |\n| Pools | list / get / patch & HA posture RCA | — |\n| SRs / VDIs | list / get / VDI list (orphan filter) / usage RCA | rescan |\n| Snapshots | list | create, delete, revert |\n| Backups | jobs / logs / failure RCA | — |\n| Tasks | list | — |\n\n**缺功能？(Missing something?)** Coverage is intentionally focused. Open an issue or PR at\n[github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops/issues)\n— feature requests, contributions, and comments are all welcome.\n\n## Scope & caveats\n\n- **Verification status**: all behaviour is validated against mocked REST\n  responses; there is no recorded end-to-end run against a live Xen Orchestra\n  instance yet. `xcpng-aiops doctor` is the fastest live check — see\n  [`docs/VERIFICATION.md`](docs/VERIFICATION.md) for the full checklist.\n- Endpoint paths (e.g. `/vms/<id>/actions/snapshot`, `/vm-snapshots/<id>`,\n  `/srs/<id>/actions/rescan`, `/hosts/<id>/missing_patches`, `/backup/logs`)\n  are modelled against the documented XO REST `/rest/v0` API and need live\n  verification — action names may differ across XO releases.\n- **Management plane only**: everything goes through XO. Per-host XAPI,\n  XO server management (adding servers, users), and backup job *execution*\n  (run/restore) are out of scope for v0.1.\n- Out of scope by design: anything that destroys bulk data (VM/VDI deletion) —\n  only `snapshot_delete` / `snapshot_revert` discard state, and both are\n  `high` risk + double-confirmed.\n\n## Not for\n\nOther hypervisors or VM platforms (use their own ops tools — e.g. Proxmox VE →\nproxmox-aiops), NAS/storage appliances, backup software suites, container\nclusters, or network devices — those are out of scope for this tool.\n\n## License\n\nMIT — [github.com/AIops-tools/XCPng-AIops](https://github.com/AIops-tools/XCPng-AIops)\n",
  "bytes": 12460,
  "sha": "630c8dc8838aba1d48441212c3fc23e6afcc27f1e4e8199a1e6e858903750631",
  "repo_slug": "aiops-tools/xcpng-aiops",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aiops_tools_xcpng_aiops_dc16c252/readme"
}