nutanix-aiops 0.1.0__tar.gz

nutanix_aiops-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

nutanix_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to nutanix-aiops are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — preview
+
+Initial preview release: governed AI-ops for **Nutanix Prism Central** (v4 REST
+API) with a bundled governance harness. **Mock-validated only — not yet verified
+against a live Prism Central.**
+
+### Added
+
+- **47 MCP tools** (21 read, 26 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit, policy, token/runaway budget, undo,
+  risk-tiers):
+  - **Clusters** (read) — `cluster_list`, `cluster_health`, `host_list`,
+    `cluster_utilization`.
+  - **VMs** — `vm_list` (AHV + ESXi), `vm_get` (surfaces ETag); `vm_power_on`
+    (low), `vm_guest_shutdown` / `vm_power_off` / `vm_reboot` / `vm_create` /
+    `vm_update` (med, undo prior CPU/mem) / `vm_clone` (med); `vm_delete` and
+    `vm_migrate` (HIGH, dry-run; `vm_migrate` undo → prior host).
+  - **Storage** — `storage_container_list`; `storage_container_create` /
+    `_update` (med, undo prior); `storage_container_delete` (HIGH, dry-run).
+  - **Network** — `subnet_list`, `subnet_get` (ETag); `subnet_create` (med);
+    `subnet_delete` (HIGH, dry-run).
+  - **Catalog** — `image_list`; `image_delete` (HIGH, dry-run); `category_list`;
+    `category_create` (low); `category_assign` (med, bulk-assign to VMs).
+  - **Data protection / DR** — `snapshot_list`, `recovery_point_list`,
+    `protection_domain_list`; `snapshot_create` (low); `vm_protect` (med);
+    `snapshot_delete` / `snapshot_restore` / `pd_failover` (HIGH, dry-run).
+  - **Alerts** — `alert_list`, `event_list`, `audit_list`; `analyze_alert`
+    (RCA — correlates an alert with related events into a probable-cause +
+    suggested-actions summary); `alert_acknowledge` / `alert_resolve` (low).
+  - **LCM** — `lcm_inventory`; `lcm_precheck` (low); `lcm_update` (HIGH
+    firmware/software update, dry-run).
+  - **Capacity** — `task_list`; `capacity_runway` (days-to-full forecast).
+- **Automatic ETag / If-Match** handling on every mutation and **automatic
+  pagination** on every list tool.
+- **Mixed-hypervisor VM listing** — `vm_list` returns both AHV and ESXi guests.
+- **Encrypted secret store** — the Prism Central password is stored encrypted in
+  `~/.nutanix-aiops/secrets.enc` (Fernet + scrypt); never plaintext on disk.
+  Legacy `NUTANIX_<TARGET>_PASSWORD` env var honoured as a fallback.
+- **CLI** (`nutanix-aiops`) — `init` wizard, `secret` management, `doctor`
+  (connectivity + REST-RBAC preflight), `overview`, `mcp`, and the `cluster` /
+  `vm` sub-commands (`vm delete` / `vm migrate` with `--dry-run` + double
+  confirm).
+- **HTTP Basic-auth REST connection layer** over Prism Central `:9440` with
+  centralised teaching error translation.
+
+### Known limitations
+
+- Preview / mock-only: validated against mocked v4 responses; needs live
+  verification against a real Prism Central. Self-testable free on Nutanix
+  Community Edition (CE) + X-Small Prism Central.
+- The **LCM update**, **PD failover**, and **ESXi-VM listing** paths in
+  particular are unverified against live systems.
+- The Prism Central account needs REST API rights, not just Web UI access.
+- Out of scope this release: IAM / users / roles, Files / Objects / Volumes
+  services, reports, X-Play playbooks, and anything outside Prism Central v4.
+</content>

nutanix_aiops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nutanix_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: nutanix-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for Nutanix Prism Central (v4): cluster/VM/storage/network/DR/alert/LCM operations with automatic ETag & pagination handling and 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/nutanix-aiops -->
+
+# Nutanix AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Nutanix.** Product and trademark names belong to their owners. MIT licensed.
+
+Governed AI-ops for **Nutanix Prism Central** (v4 REST API) — clusters, hosts,
+VMs (AHV + ESXi), storage, network, catalog, data protection / DR, alerts, LCM
+upgrades, and capacity — with a **built-in governance harness**: unified audit
+log, policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers. Connects to Prism Central on HTTPS `:9440` with
+HTTP Basic auth (username + encrypted password). Self-contained: no dependencies
+beyond `httpx` and the MCP SDK. **Preview — mock-validated only, not yet verified
+against a live Prism Central.**
+
+## Why this over a read-only Nutanix MCP
+
+- **Automatic ETag / If-Match** on every mutation. The v4 API rejects an update
+  or delete without the entity's current ETag — the classic footgun. This tool
+  fetches and sends `If-Match` for you.
+- **Automatic pagination** — list tools return the full set, not just page one.
+- **Mixed-hypervisor VM listing** — `vm_list` returns both **AHV** and **ESXi**
+  guests under the same Prism Central (built for Broadcom→Nutanix migration
+  estates).
+- **Governance harness** — audit / token+call budget / risk-tier approval /
+  undo-token / prompt-injection sanitize, with **dry-run + double-confirm** on
+  destructive writes.
+
+## Capability matrix (47 MCP tools)
+
+| Group | Tools | Count | R/W |
+|-------|-------|:-----:|:---:|
+| **Clusters** | `cluster_list`, `cluster_health`, `host_list`, `cluster_utilization` | 4 | 4 read |
+| **VMs** | `vm_list`, `vm_get`, `vm_power_on`, `vm_guest_shutdown`, `vm_power_off`, `vm_reboot`, `vm_create`, `vm_update`, `vm_clone`, `vm_delete`, `vm_migrate` | 11 | 2 read · 9 write |
+| **Storage** | `storage_container_list` / `_create` / `_update` / `_delete` | 4 | 1 read · 3 write |
+| **Network** | `subnet_list`, `subnet_get`, `subnet_create`, `subnet_delete` | 4 | 2 read · 2 write |
+| **Catalog** | `image_list`, `image_delete`, `category_list`, `category_create`, `category_assign` | 5 | 2 read · 3 write |
+| **Data protection / DR** | `snapshot_list` / `_create` / `_delete` / `_restore`, `recovery_point_list`, `protection_domain_list`, `vm_protect`, `pd_failover` | 8 | 3 read · 5 write |
+| **Alerts** | `alert_list`, `event_list`, `audit_list`, `analyze_alert` (RCA), `alert_acknowledge`, `alert_resolve` | 6 | 4 read · 2 write |
+| **LCM (upgrades)** | `lcm_inventory`, `lcm_precheck`, `lcm_update` | 3 | 1 read · 2 write |
+| **Capacity** | `task_list`, `capacity_runway` | 2 | 2 read |
+| **Total** | | **47** | 21 read · 26 write |
+
+`analyze_alert` is the flagship read: it correlates an alert with its related
+events into a probable-cause + suggested-actions summary. High-risk writes
+(`vm_delete`, `vm_migrate`, `storage_container_delete`, `subnet_delete`,
+`snapshot_delete`, `snapshot_restore`, `pd_failover`, `image_delete`,
+`lcm_update`) support `dry_run` and, at the CLI, double confirmation.
+
+## Install
+
+```bash
+uv tool install nutanix-aiops          # or: pipx install nutanix-aiops
+```
+
+## Quick start
+
+```bash
+nutanix-aiops init                     # wizard: PC host / port 9440 / username / verify_ssl + encrypted password
+nutanix-aiops doctor                   # config, secrets, connectivity + REST-RBAC preflight
+nutanix-aiops overview                 # one-shot estate summary
+nutanix-aiops vm list                  # AHV + ESXi VMs
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export NUTANIX_AIOPS_MASTER_PASSWORD=...   # unlock the encrypted secret store non-interactively
+nutanix-aiops mcp
+```
+
+## CLI
+
+`nutanix-aiops` (Typer): `init`, `overview`, `doctor`, `mcp`; `cluster
+list/health/hosts/util`; `vm list/get/power/delete/migrate` (`delete` & `migrate`
+take `--dry-run` + double confirm); `secret set/list/rm/migrate/rotate-password`.
+The CLI is a convenience subset — the full 47-tool surface is via the MCP server.
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier, approver,
+  rationale) is logged to `~/.nutanix-aiops/audit.db` (relocatable via
+  `NUTANIX_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops can require a named approver
+  (`NUTANIX_AUDIT_APPROVED_BY` / `NUTANIX_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes record an inverse descriptor
+  (`vm_update` → prior CPU/memory, `vm_migrate` → prior host).
+
+## Credentials
+
+The Prism Central password is stored **encrypted** in
+`~/.nutanix-aiops/secrets.enc` (Fernet + scrypt) — never plaintext on disk.
+Unlock with a master password from `NUTANIX_AIOPS_MASTER_PASSWORD` (MCP/CI) or an
+interactive prompt (CLI). The non-secret connection details (host, port,
+username, verify_ssl) live in `~/.nutanix-aiops/config.yaml`. A legacy plaintext
+env var `NUTANIX_<TARGET>_PASSWORD` is honoured as a fallback.
+
+> **Gotcha:** the Prism Central account needs **REST API** rights, not just Web
+> UI access. `doctor`'s REST-RBAC preflight catches this early.
+
+## Supported scope & limitations
+
+- **Preview / mock-only.** All behaviour is validated against mocked v4 REST
+  responses; it has not been run against a live Prism Central. The fastest live
+  check is `nutanix-aiops doctor`.
+- **Self-testable free** on **Nutanix Community Edition (CE)**: a single-node CE
+  cluster + an X-Small Prism Central VM.
+- **Least-verified paths:** LCM update (`lcm_update`), protection-domain failover
+  (`pd_failover`), and **ESXi-VM listing** in particular need live validation.
+- **Out of scope this release:** IAM / users / roles, Files / Objects / Volumes
+  services, reports, X-Play playbooks, and anything outside Prism Central v4.
+
+## Missing a capability?
+
+Missing a tool, an API dialect, or a workflow? **Open an issue or PR** —
+feedback and contributions are welcome.
+</content>

nutanix_aiops-0.1.0/README.md

@@ -0,0 +1,120 @@
+<!-- mcp-name: io.github.AIops-tools/nutanix-aiops -->
+
+# Nutanix AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Nutanix.** Product and trademark names belong to their owners. MIT licensed.
+
+Governed AI-ops for **Nutanix Prism Central** (v4 REST API) — clusters, hosts,
+VMs (AHV + ESXi), storage, network, catalog, data protection / DR, alerts, LCM
+upgrades, and capacity — with a **built-in governance harness**: unified audit
+log, policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers. Connects to Prism Central on HTTPS `:9440` with
+HTTP Basic auth (username + encrypted password). Self-contained: no dependencies
+beyond `httpx` and the MCP SDK. **Preview — mock-validated only, not yet verified
+against a live Prism Central.**
+
+## Why this over a read-only Nutanix MCP
+
+- **Automatic ETag / If-Match** on every mutation. The v4 API rejects an update
+  or delete without the entity's current ETag — the classic footgun. This tool
+  fetches and sends `If-Match` for you.
+- **Automatic pagination** — list tools return the full set, not just page one.
+- **Mixed-hypervisor VM listing** — `vm_list` returns both **AHV** and **ESXi**
+  guests under the same Prism Central (built for Broadcom→Nutanix migration
+  estates).
+- **Governance harness** — audit / token+call budget / risk-tier approval /
+  undo-token / prompt-injection sanitize, with **dry-run + double-confirm** on
+  destructive writes.
+
+## Capability matrix (47 MCP tools)
+
+| Group | Tools | Count | R/W |
+|-------|-------|:-----:|:---:|
+| **Clusters** | `cluster_list`, `cluster_health`, `host_list`, `cluster_utilization` | 4 | 4 read |
+| **VMs** | `vm_list`, `vm_get`, `vm_power_on`, `vm_guest_shutdown`, `vm_power_off`, `vm_reboot`, `vm_create`, `vm_update`, `vm_clone`, `vm_delete`, `vm_migrate` | 11 | 2 read · 9 write |
+| **Storage** | `storage_container_list` / `_create` / `_update` / `_delete` | 4 | 1 read · 3 write |
+| **Network** | `subnet_list`, `subnet_get`, `subnet_create`, `subnet_delete` | 4 | 2 read · 2 write |
+| **Catalog** | `image_list`, `image_delete`, `category_list`, `category_create`, `category_assign` | 5 | 2 read · 3 write |
+| **Data protection / DR** | `snapshot_list` / `_create` / `_delete` / `_restore`, `recovery_point_list`, `protection_domain_list`, `vm_protect`, `pd_failover` | 8 | 3 read · 5 write |
+| **Alerts** | `alert_list`, `event_list`, `audit_list`, `analyze_alert` (RCA), `alert_acknowledge`, `alert_resolve` | 6 | 4 read · 2 write |
+| **LCM (upgrades)** | `lcm_inventory`, `lcm_precheck`, `lcm_update` | 3 | 1 read · 2 write |
+| **Capacity** | `task_list`, `capacity_runway` | 2 | 2 read |
+| **Total** | | **47** | 21 read · 26 write |
+
+`analyze_alert` is the flagship read: it correlates an alert with its related
+events into a probable-cause + suggested-actions summary. High-risk writes
+(`vm_delete`, `vm_migrate`, `storage_container_delete`, `subnet_delete`,
+`snapshot_delete`, `snapshot_restore`, `pd_failover`, `image_delete`,
+`lcm_update`) support `dry_run` and, at the CLI, double confirmation.
+
+## Install
+
+```bash
+uv tool install nutanix-aiops          # or: pipx install nutanix-aiops
+```
+
+## Quick start
+
+```bash
+nutanix-aiops init                     # wizard: PC host / port 9440 / username / verify_ssl + encrypted password
+nutanix-aiops doctor                   # config, secrets, connectivity + REST-RBAC preflight
+nutanix-aiops overview                 # one-shot estate summary
+nutanix-aiops vm list                  # AHV + ESXi VMs
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export NUTANIX_AIOPS_MASTER_PASSWORD=...   # unlock the encrypted secret store non-interactively
+nutanix-aiops mcp
+```
+
+## CLI
+
+`nutanix-aiops` (Typer): `init`, `overview`, `doctor`, `mcp`; `cluster
+list/health/hosts/util`; `vm list/get/power/delete/migrate` (`delete` & `migrate`
+take `--dry-run` + double confirm); `secret set/list/rm/migrate/rotate-password`.
+The CLI is a convenience subset — the full 47-tool surface is via the MCP server.
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier, approver,
+  rationale) is logged to `~/.nutanix-aiops/audit.db` (relocatable via
+  `NUTANIX_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops can require a named approver
+  (`NUTANIX_AUDIT_APPROVED_BY` / `NUTANIX_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes record an inverse descriptor
+  (`vm_update` → prior CPU/memory, `vm_migrate` → prior host).
+
+## Credentials
+
+The Prism Central password is stored **encrypted** in
+`~/.nutanix-aiops/secrets.enc` (Fernet + scrypt) — never plaintext on disk.
+Unlock with a master password from `NUTANIX_AIOPS_MASTER_PASSWORD` (MCP/CI) or an
+interactive prompt (CLI). The non-secret connection details (host, port,
+username, verify_ssl) live in `~/.nutanix-aiops/config.yaml`. A legacy plaintext
+env var `NUTANIX_<TARGET>_PASSWORD` is honoured as a fallback.
+
+> **Gotcha:** the Prism Central account needs **REST API** rights, not just Web
+> UI access. `doctor`'s REST-RBAC preflight catches this early.
+
+## Supported scope & limitations
+
+- **Preview / mock-only.** All behaviour is validated against mocked v4 REST
+  responses; it has not been run against a live Prism Central. The fastest live
+  check is `nutanix-aiops doctor`.
+- **Self-testable free** on **Nutanix Community Edition (CE)**: a single-node CE
+  cluster + an X-Small Prism Central VM.
+- **Least-verified paths:** LCM update (`lcm_update`), protection-domain failover
+  (`pd_failover`), and **ESXi-VM listing** in particular need live validation.
+- **Out of scope this release:** IAM / users / roles, Files / Objects / Volumes
+  services, reports, X-Play playbooks, and anything outside Prism Central v4.
+
+## Missing a capability?
+
+Missing a tool, an API dialect, or a workflow? **Open an issue or PR** —
+feedback and contributions are welcome.
+</content>

nutanix_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,58 @@
+# Nutanix AIops v0.1.0 — preview
+
+Governed AI-ops for **Nutanix Prism Central** (v4 REST API) for AI agents, with a
+built-in governance harness (audit, policy, token/runaway budget, undo-token
+recording, graduated risk tiers) and an encrypted credential store. Standalone —
+no external skill-family dependency.
+
+> **Preview / mock-only.** All behaviour is validated against mocked v4 REST
+> responses; it has not been run against a live Prism Central. The fastest live
+> check is `nutanix-aiops doctor`.
+
+## Highlights
+
+- **47 MCP tools** (21 read, 26 write), every one wrapped with `@governed_tool`,
+  across nine groups:
+  - **Clusters** (read) — `cluster_list`, `cluster_health`, `host_list`,
+    `cluster_utilization`.
+  - **VMs** — `vm_list` (AHV + ESXi), `vm_get` (surfaces ETag); writes
+    `vm_power_on` / `vm_guest_shutdown` / `vm_power_off` / `vm_reboot` /
+    `vm_create` / `vm_update` (undo prior CPU/mem) / `vm_clone` / `vm_delete`
+    (HIGH, dry-run) / `vm_migrate` (HIGH, dry-run, undo → prior host).
+  - **Storage** — container list / create / update (undo prior) / delete (HIGH).
+  - **Network** — subnet list / get (ETag) / create / delete (HIGH).
+  - **Catalog** — image list / delete (HIGH); category list / create / assign
+    (bulk).
+  - **Data protection / DR** — snapshot list / create / delete (HIGH) / restore
+    (HIGH), `recovery_point_list`, `protection_domain_list`, `vm_protect`,
+    `pd_failover` (HIGH).
+  - **Alerts** — `alert_list`, `event_list`, `audit_list`, **`analyze_alert`**
+    (the flagship RCA read), `alert_acknowledge`, `alert_resolve`.
+  - **LCM** — `lcm_inventory`, `lcm_precheck`, `lcm_update` (HIGH firmware/software).
+  - **Capacity** — `task_list`, `capacity_runway` (days-to-full forecast).
+- **Automatic ETag / If-Match** on every mutation (the v4 footgun) and
+  **automatic pagination** on every list; `vm_list` returns **AHV + ESXi**.
+- **Encrypted password store** (`~/.nutanix-aiops/secrets.enc`, Fernet + scrypt)
+  — never plaintext on disk; legacy `NUTANIX_<TARGET>_PASSWORD` env fallback.
+- **CLI** with an `init` onboarding wizard, `secret` management, `overview`,
+  `cluster` / `vm` sub-commands, and a `doctor` with a REST-RBAC preflight.
+- **Basic-auth REST connection layer** over Prism Central `:9440` with teaching
+  error translation.
+
+## Install
+
+```bash
+uv tool install nutanix-aiops
+nutanix-aiops init
+nutanix-aiops doctor
+```
+
+## Caveats
+
+- The Prism Central account needs **REST API** rights, not just Web UI access.
+- Self-testable free on **Nutanix Community Edition (CE)** + X-Small Prism
+  Central. The **LCM update**, **PD failover**, and **ESXi-VM listing** paths in
+  particular need live verification.
+- Out of scope this release: IAM / users / roles, Files / Objects / Volumes
+  services, reports, X-Play playbooks, and anything outside Prism Central v4.
+</content>

nutanix_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,81 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by Nutanix, Inc.** Product and trademark names (Nutanix, Prism, AHV)
+belong to their owners. Source is publicly auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Nutanix-AIops](https://github.com/AIops-tools/Nutanix-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target Prism Central passwords live **encrypted** in
+  `~/.nutanix-aiops/secrets.enc` (Fernet/AES-128 + scrypt-derived key; chmod
+  600), never in `config.yaml` and never in source. The master password is
+  never stored — only a per-store random salt and the ciphertext are on disk.
+- A legacy plaintext env var `NUTANIX_<TARGET_NAME_UPPER>_PASSWORD` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `nutanix-aiops secret migrate`).
+- The password is used for HTTP Basic auth at request time and held only in
+  memory. It is never logged or echoed; the config file holds only host, port,
+  username, and TLS settings. Note: the Prism Central account needs REST API
+  rights, not just WebUI access.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`nutanix_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.nutanix-aiops/`
+  (relocatable via `NUTANIX_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`NUTANIX_MAX_TOOL_CALLS` /
+  `NUTANIX_MAX_TOOL_SECONDS`) plus an on-by-default guard that trips a tight
+  poll/retry loop, preventing unbounded API consumption (e.g. polling a slow
+  session).
+- **Graduated risk tiers** — `~/.nutanix-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver.
+- **Undo-token recording** — reversible writes capture the entity's BEFORE state
+  and record an inverse descriptor (e.g. `vm_power_on`→re-power to prior state,
+  `vm_update`→restore prior CPU/memory, `vm_migrate`→migrate back to the prior
+  host) so the change can be rolled back.
+- **Automatic ETag / If-Match** — every mutation first fetches the entity's
+  current ETag and sends it back as `If-Match`, preventing lost-update (mid-air
+  collision) races the v4 API would otherwise reject.
+
+### State-Changing Operations
+Destructive writes — `vm_delete`, `vm_migrate`, `storage_container_delete`,
+`subnet_delete`, `image_delete`, `snapshot_delete`, `snapshot_restore`,
+`pd_failover`, `lcm_update` — are `risk_level=high`, accept a `dry_run` preview,
+and (under `risk_tiers`) require a recorded approver (`NUTANIX_AUDIT_APPROVED_BY`
++ `NUTANIX_AUDIT_RATIONALE`). The CLI additionally double-confirms `vm delete`
+and `vm migrate` and supports `--dry-run`. Reversible medium/low writes capture
+before-state and, where a safe inverse exists, record an undo token.
+
+### SSL/TLS Verification
+`verify_ssl` defaults to true; disable only for self-signed lab certificates.
+
+### Prompt-Injection Protection
+All server-returned text (VM/cluster names, alert titles, extIds, event fields)
+is passed through a `sanitize()` truncate + control-character strip before
+reaching the agent.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured Prism Central
+REST API endpoint (HTTPS :9440). No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r nutanix_aiops/ mcp_server/
+uv run ruff check .
+```
+
+## Supported Versions
+
+The latest released version receives security fixes. This is a preview (0.x);
+pin a version in production.

nutanix_aiops-0.1.0/mcp_server/__init__.py

@@ -0,0 +1 @@
+"""MCP server package for nutanix-aiops."""

nutanix_aiops-0.1.0/mcp_server/_shared.py

@@ -0,0 +1,100 @@
+"""Shared MCP server primitives: the FastMCP instance, connection helper,
+error sanitisation, and the ``@tool_errors`` decorator.
+
+Tool modules under ``mcp_server/tools/`` import ``mcp`` from here and register
+their ``@mcp.tool()`` functions onto it. ``mcp_server/server.py`` then imports
+those modules and runs the server.
+
+Keep ``Optional[X]`` (never PEP 604 ``X | None``) in any FastMCP-reflected
+tool signature — on older mcp/pydantic the union eval'd to ``types.UnionType``
+crashes FastMCP's ``issubclass`` check.
+"""
+
+import functools
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from nutanix_aiops.config import load_config
+from nutanix_aiops.connection import ConnectionManager, NutanixApiError
+from nutanix_aiops.governance import sanitize
+
+logger = logging.getLogger(__name__)
+
+_DOCTOR_HINT = "Run 'nutanix-aiops doctor' to verify connectivity and credentials."
+
+
+def _safe_error(exc: Exception, tool: str) -> str:
+    """Return an agent-safe error string; log full detail server-side only."""
+    logger.error("Tool %s failed", tool, exc_info=True)
+    _passthrough = (
+        ValueError,
+        FileNotFoundError,
+        KeyError,
+        PermissionError,
+        TimeoutError,
+        ConnectionError,
+        NutanixApiError,
+    )
+    if isinstance(exc, _passthrough):
+        return sanitize(str(exc), 300)
+    return f"{type(exc).__name__}: operation failed."
+
+
+def tool_errors(shape: str = "dict") -> Callable:
+    """Wrap a tool body in the canonical try/except → ``_safe_error`` pattern.
+
+    Place this *between* ``@governed_tool`` and the function so the audit
+    decorator and FastMCP still see the original signature.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        name = func.__name__
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:  # noqa: BLE001 — sanitised below
+                msg = _safe_error(e, name)
+                if shape == "list":
+                    return [{"error": msg, "hint": _DOCTOR_HINT}]
+                if shape == "str":
+                    return f"Error: {msg} {_DOCTOR_HINT}"
+                return {"error": msg, "hint": _DOCTOR_HINT}
+
+        return wrapper
+
+    return decorator
+
+
+mcp = FastMCP(
+    "nutanix-aiops",
+    instructions=(
+        "Nutanix Prism Central (v4) operations (preview): clusters/hosts and "
+        "utilization; VM inventory (AHV + ESXi) and lifecycle (power / create / "
+        "update / clone / migrate / delete); storage containers; subnets; images "
+        "and categories; snapshots / recovery points and protection domains; "
+        "alerts / events (list, acknowledge, resolve, analyze); and LCM upgrades. "
+        "Mutations auto-handle the v4 ETag/If-Match footgun and auto-paginate. "
+        "Destructive writes (delete / migrate / pool changes) are risk=high with a "
+        "dry_run preview and require an approver. Every tool runs through the "
+        "nutanix-aiops governance harness (audit / budget / risk-tier / undo)."
+    ),
+)
+
+_conn_mgr: Optional[ConnectionManager] = None
+
+
+def _get_connection(target: Optional[str] = None) -> Any:
+    """Return a Nutanix connection, lazily initialising the manager."""
+    global _conn_mgr  # noqa: PLW0603
+    if _conn_mgr is None:
+        config_path_str = os.environ.get("NUTANIX_AIOPS_CONFIG")
+        config_path = Path(config_path_str) if config_path_str else None
+        _conn_mgr = ConnectionManager(load_config(config_path))
+    return _conn_mgr.connect(target)

nutanix_aiops-0.1.0/mcp_server/server.py

@@ -0,0 +1,39 @@
+"""MCP server wrapping nutanix-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``nutanix_aiops`` ops package and is wrapped with the
+nutanix-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed Nutanix Prism Central (v4) operations (preview).
+Cluster / VM / storage / network / snapshot-DR / alert / LCM management with
+automatic ETag & pagination handling.
+
+Source: https://github.com/AIops-tools/Nutanix-AIops
+License: MIT
+"""
+
+import logging
+
+from mcp_server._shared import _safe_error, mcp, tool_errors
+
+# Importing the tool modules registers every @mcp.tool() onto the shared
+# `mcp` instance. Order does not matter; each module is self-contained.
+from mcp_server.tools import (  # noqa: F401 — side effects
+    alerts,
+    capacity,
+    catalog,
+    clusters,
+    dataprotection,
+    lcm,
+    network,
+    storage,
+    vms,
+)
+
+__all__ = ["mcp", "main", "_safe_error", "tool_errors"]
+
+
+def main() -> None:
+    """Run the MCP server over stdio."""
+    logging.basicConfig(level=logging.INFO)
+    mcp.run(transport="stdio")

nutanix_aiops-0.1.0/mcp_server/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool modules. Importing each registers its @mcp.tool() functions."""