proxmox-aiops 0.1.0__tar.gz

proxmox_aiops-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual envs / build
+.venv/
+dist/
+build/
+
+# uv
+uv.lock
+
+# Local config / secrets (never commit)
+*.env
+.env
+config.yaml
+
+# OS
+.DS_Store

proxmox_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.

proxmox_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: proxmox-aiops
+Version: 0.1.0
+Summary: Proxmox VE AI-powered VM/container lifecycle operations 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: mcp[cli]<2.0,>=1.10
+Requires-Dist: proxmoxer<3.0,>=2.0
+Requires-Dist: python-dotenv<2.0,>=1.0
+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/proxmox-aiops -->
+
+# Proxmox AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.** "Proxmox" is a trademark of its owner. MIT licensed.
+
+AI-powered Proxmox VE VM and container lifecycle operations with a **built-in
+governance harness** — unified audit log, policy engine, token/runaway budget
+guard, undo-token recording, and graduated-autonomy risk tiers. Self-contained:
+no external dependencies beyond `proxmoxer` and the MCP SDK. Preview — not yet
+full coverage of every Proxmox operation.
+
+## What works
+
+- **CLI** (`proxmox-aiops ...`): `vm list/get/config/start/stop/shutdown/reboot/reconfigure/clone/delete/migrate`, `vm snapshot-create/snapshot-delete/snapshot-list/snapshot-rollback`, `ct list/start/stop`, `cluster nodes/status/task-status`, `storage list/content`, `doctor`, `mcp`.
+- **MCP server** (`proxmox-aiops mcp` or `proxmox-aiops-mcp`): **23 tools**, every one wrapped with the bundled `@governed_tool` harness.
+- **Reversibility**: write ops with a clean inverse (start/stop/shutdown/reconfigure/clone/migrate/snapshot-create, container start/stop) record an inverse undo descriptor; irreversible ops (delete, snapshot-rollback) declare none and are tagged `high` risk.
+- **Async tasks**: Proxmox writes return a task UPID — poll completion with `cluster task-status` (the runaway budget guard prevents poll loops from running away).
+
+## Quick start
+
+```bash
+uv tool install proxmox-aiops
+mkdir -p ~/.proxmox-aiops
+# create ~/.proxmox-aiops/config.yaml with a targets: list
+# put secrets in ~/.proxmox-aiops/.env  (chmod 600)
+proxmox-aiops doctor
+```
+
+Example `~/.proxmox-aiops/config.yaml`:
+
+```yaml
+targets:
+  - name: pve-lab
+    host: 10.0.0.10
+    user: "root@pam!claude"   # API token: user@realm!tokenid
+    node: pve1
+    auth_kind: token
+    verify_ssl: false          # self-signed lab certs only
+```
+
+`~/.proxmox-aiops/.env` (chmod 600): `PROXMOX_PVE_LAB_SECRET=<token-uuid>`
+
+## Audit & safety
+
+All operations are logged to a local SQLite audit DB under `~/.proxmox-aiops/`
+(relocatable via `PROXMOX_AIOPS_HOME`). Every write tool passes through the
+governance harness: policy pre-check, token/runaway budget guard, graduated
+risk-tier gate, and audit logging. Destructive CLI commands (`vm stop`,
+`vm delete`, `vm snapshot-delete`, `vm snapshot-rollback`, `ct stop`) require
+double confirmation and support `--dry-run`. API-returned text is run through a
+prompt-injection sanitizer.
+
+License: MIT.

proxmox_aiops-0.1.0/README.md

@@ -0,0 +1,54 @@
+<!-- mcp-name: io.github.AIops-tools/proxmox-aiops -->
+
+# Proxmox AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.** "Proxmox" is a trademark of its owner. MIT licensed.
+
+AI-powered Proxmox VE VM and container lifecycle operations with a **built-in
+governance harness** — unified audit log, policy engine, token/runaway budget
+guard, undo-token recording, and graduated-autonomy risk tiers. Self-contained:
+no external dependencies beyond `proxmoxer` and the MCP SDK. Preview — not yet
+full coverage of every Proxmox operation.
+
+## What works
+
+- **CLI** (`proxmox-aiops ...`): `vm list/get/config/start/stop/shutdown/reboot/reconfigure/clone/delete/migrate`, `vm snapshot-create/snapshot-delete/snapshot-list/snapshot-rollback`, `ct list/start/stop`, `cluster nodes/status/task-status`, `storage list/content`, `doctor`, `mcp`.
+- **MCP server** (`proxmox-aiops mcp` or `proxmox-aiops-mcp`): **23 tools**, every one wrapped with the bundled `@governed_tool` harness.
+- **Reversibility**: write ops with a clean inverse (start/stop/shutdown/reconfigure/clone/migrate/snapshot-create, container start/stop) record an inverse undo descriptor; irreversible ops (delete, snapshot-rollback) declare none and are tagged `high` risk.
+- **Async tasks**: Proxmox writes return a task UPID — poll completion with `cluster task-status` (the runaway budget guard prevents poll loops from running away).
+
+## Quick start
+
+```bash
+uv tool install proxmox-aiops
+mkdir -p ~/.proxmox-aiops
+# create ~/.proxmox-aiops/config.yaml with a targets: list
+# put secrets in ~/.proxmox-aiops/.env  (chmod 600)
+proxmox-aiops doctor
+```
+
+Example `~/.proxmox-aiops/config.yaml`:
+
+```yaml
+targets:
+  - name: pve-lab
+    host: 10.0.0.10
+    user: "root@pam!claude"   # API token: user@realm!tokenid
+    node: pve1
+    auth_kind: token
+    verify_ssl: false          # self-signed lab certs only
+```
+
+`~/.proxmox-aiops/.env` (chmod 600): `PROXMOX_PVE_LAB_SECRET=<token-uuid>`
+
+## Audit & safety
+
+All operations are logged to a local SQLite audit DB under `~/.proxmox-aiops/`
+(relocatable via `PROXMOX_AIOPS_HOME`). Every write tool passes through the
+governance harness: policy pre-check, token/runaway budget guard, graduated
+risk-tier gate, and audit logging. Destructive CLI commands (`vm stop`,
+`vm delete`, `vm snapshot-delete`, `vm snapshot-rollback`, `ct stop`) require
+double confirmation and support `--dry-run`. API-returned text is run through a
+prompt-injection sanitizer.
+
+License: MIT.

proxmox_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,33 @@
+# Release notes
+
+## v0.1.0 (2026-06-22) — first release (preview)
+
+First public release of **proxmox-aiops** — governed Proxmox VE VM and container
+lifecycle operations for AI agents. Standalone and self-contained.
+
+### Highlights
+- **23 MCP tools** (8 read / 15 write):
+  - VM lifecycle: list/get/config, start/stop/shutdown/reboot, reconfigure,
+    clone, delete, migrate
+  - Snapshots: create/delete/list/rollback
+  - LXC containers: list/start/stop
+  - Cluster/tasks: node list, cluster status, async task (UPID) polling
+  - Storage: pool list, content list
+- **CLI + MCP server** (`proxmox-aiops` and `proxmox-aiops mcp`).
+- **Built-in governance harness** (`proxmox_aiops.governance`, no external
+  dependency): unified audit log under `~/.proxmox-aiops/`, policy engine,
+  token/runaway budget guard, undo-token recording, and graduated-autonomy
+  risk tiers. State dir relocatable via `PROXMOX_AIOPS_HOME`.
+- **Reversibility**: write ops with a clean inverse (start/stop/shutdown/
+  reconfigure/clone/migrate/snapshot-create, container start/stop) record an
+  undo descriptor; irreversible ops (delete, snapshot-rollback) declare none
+  and are tagged `high` risk.
+- **Safety**: destructive CLI commands require double confirmation + `--dry-run`;
+  all API text is sanitized; TLS verification on by default.
+
+### Notes
+- Preview (0.x): broad coverage of common operations, not yet exhaustive — see
+  `references/capabilities.md` for the "not yet covered" list.
+- Proxmox writes are asynchronous; poll completion with `cluster task-status`.
+- Verified with a mocked Proxmox API (9 smoke tests); not yet exercised against
+  a live PVE cluster.

proxmox_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,63 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by Proxmox Server Solutions GmbH.** "Proxmox" is a trademark of its
+owner. Source is publicly auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Proxmox-AIops](https://github.com/AIops-tools/Proxmox-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target secrets live in `~/.proxmox-aiops/.env` (chmod 600), never in
+  `config.yaml` and never in source. Variable pattern:
+  `PROXMOX_<TARGET_NAME_UPPER>_SECRET` (API token UUID, or login password).
+- Secrets are never logged or echoed; the config file holds only host, user,
+  node, and TLS settings.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`proxmox_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.proxmox-aiops/`
+  (relocatable via `PROXMOX_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`PROXMOX_MAX_TOOL_CALLS` /
+  `PROXMOX_MAX_TOOL_SECONDS`) plus an on-by-default guard that trips a tight
+  poll/retry loop, preventing unbounded API consumption.
+- **Graduated risk tiers** — `~/.proxmox-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver.
+- **Undo-token recording** — reversible writes record an inverse descriptor so
+  a change can be rolled back.
+
+### Destructive Operations
+`vm stop`, `vm delete`, `vm snapshot-delete`, `vm snapshot-rollback`, and
+`ct stop` require double confirmation at the CLI layer and support `--dry-run`.
+
+### SSL/TLS Verification
+`verify_ssl` defaults to true; disable only for self-signed lab certificates.
+
+### Prompt-Injection Protection
+All Proxmox-API-returned text (names, UPIDs, descriptions) 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 Proxmox API
+endpoint. No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r proxmox_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.

proxmox_aiops-0.1.0/mcp_server/__init__.py

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

proxmox_aiops-0.1.0/mcp_server/_shared.py

@@ -0,0 +1,102 @@
+"""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 (踩坑 #33).
+"""
+
+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 proxmox_aiops.config import load_config
+from proxmox_aiops.connection import ConnectionManager
+from proxmox_aiops.governance import sanitize
+from proxmox_aiops.ops.lxc import ContainerNotFoundError
+from proxmox_aiops.ops.storage import NodeRequiredError
+from proxmox_aiops.ops.vm_lifecycle import VMNotFoundError
+
+logger = logging.getLogger(__name__)
+
+_DOCTOR_HINT = "Run 'proxmox-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,
+        VMNotFoundError,
+        NodeRequiredError,
+        ContainerNotFoundError,
+    )
+    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(
+    "proxmox-aiops",
+    instructions=(
+        "Proxmox VE operations (preview): QEMU VM lifecycle (list/get/config, "
+        "start/stop/shutdown/reboot, reconfigure, clone, delete, migrate), "
+        "snapshots (create/delete/list/rollback), LXC containers (list/start/stop), "
+        "cluster/nodes + async task polling, and storage listing. Every tool runs "
+        "through the proxmox-aiops governance harness (audit / budget / risk-tier / "
+        "undo)."
+    ),
+)
+
+_conn_mgr: Optional[ConnectionManager] = None
+
+
+def _get_connection(target: Optional[str] = None) -> Any:
+    """Return a proxmoxer connection, lazily initialising the manager."""
+    global _conn_mgr  # noqa: PLW0603
+    if _conn_mgr is None:
+        config_path_str = os.environ.get("PROXMOX_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)

proxmox_aiops-0.1.0/mcp_server/server.py

@@ -0,0 +1,28 @@
+"""MCP server wrapping Proxmox AIops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``proxmox_aiops`` ops package and is wrapped with the
+proxmox-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed Proxmox VE operations (preview).
+For Proxmox VE only.
+
+Source: https://github.com/AIops-tools/Proxmox-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 cluster, lxc, storage, vm  # noqa: F401 — side effects
+
+__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")

proxmox_aiops-0.1.0/mcp_server/tools/__init__.py

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

proxmox_aiops-0.1.0/mcp_server/tools/cluster.py

@@ -0,0 +1,51 @@
+"""Cluster / node / async-task MCP tools (all read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxmox_aiops.governance import governed_tool
+from proxmox_aiops.ops import cluster as cl
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def node_list(target: Optional[str] = None) -> list:
+    """[READ] List Proxmox cluster nodes with status, cpu load, and memory.
+
+    Args:
+        target: Proxmox target name from config; omit to use the default.
+    """
+    return cl.list_nodes(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def cluster_status(target: Optional[str] = None) -> list:
+    """[READ] Return cluster membership + quorum status.
+
+    The ``type=cluster`` row's ``quorate`` field indicates whether the cluster
+    currently has quorum.
+
+    Args:
+        target: Proxmox target name from config.
+    """
+    return cl.cluster_status(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def task_status(upid: str, target: Optional[str] = None, node: Optional[str] = None) -> dict:
+    """[READ] Poll a Proxmox async task (clone / migrate / backup) by its UPID.
+
+    Use after a write that returned a task UPID to check completion instead of
+    re-issuing the operation. The node is parsed from the UPID when omitted.
+
+    Args:
+        upid: The task UPID returned by an async write tool.
+        target: Proxmox target name from config.
+        node: Node the task runs on; omit to parse it from the UPID.
+    """
+    return cl.get_task_status(_get_connection(target), upid, node=node)

proxmox_aiops-0.1.0/mcp_server/tools/lxc.py

@@ -0,0 +1,64 @@
+"""LXC container MCP tools: list / start / stop (start/stop carry undo tokens)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxmox_aiops.governance import governed_tool
+from proxmox_aiops.ops import lxc
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def ct_list(target: Optional[str] = None, node: Optional[str] = None) -> list:
+    """[READ] List LXC containers with name, vmid, status, cpu, mem.
+
+    Args:
+        target: Proxmox target name from config; omit to use the default.
+        node: Node name; omit to use the configured default / all nodes.
+    """
+    return lxc.list_cts(_get_connection(target), node=node)
+
+
+@mcp.tool()
+@governed_tool(
+    risk_level="medium",
+    undo=lambda params, result: {
+        "tool": "ct_stop",
+        "params": {"vmid": params.get("vmid"), "node": params.get("node")},
+        "skill": "proxmox-aiops",
+        "note": "Inverse of ct_start: stop the container again.",
+    },
+)
+@tool_errors("dict")
+def ct_start(vmid: int, target: Optional[str] = None, node: Optional[str] = None) -> dict:
+    """[WRITE] Start an LXC container. Returns the task UPID. Inverse: ct_stop.
+
+    Args:
+        vmid: Numeric container id (see ct_list).
+        target: Proxmox target name from config.
+        node: Node name; omit to auto-locate the container.
+    """
+    return lxc.start_ct(_get_connection(target), vmid, node=node)
+
+
+@mcp.tool()
+@governed_tool(
+    risk_level="medium",
+    undo=lambda params, result: {
+        "tool": "ct_start",
+        "params": {"vmid": params.get("vmid"), "node": params.get("node")},
+        "skill": "proxmox-aiops",
+        "note": "Inverse of ct_stop: start the container again.",
+    },
+)
+@tool_errors("dict")
+def ct_stop(vmid: int, target: Optional[str] = None, node: Optional[str] = None) -> dict:
+    """[WRITE] Stop an LXC container. Returns the task UPID. Inverse: ct_start.
+
+    Args:
+        vmid: Numeric container id (see ct_list).
+        target: Proxmox target name from config.
+        node: Node name; omit to auto-locate the container.
+    """
+    return lxc.stop_ct(_get_connection(target), vmid, node=node)

proxmox_aiops-0.1.0/mcp_server/tools/storage.py

@@ -0,0 +1,43 @@
+"""Storage read MCP tools for Proxmox VE."""
+
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxmox_aiops.governance import governed_tool
+from proxmox_aiops.ops import storage as st
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def storage_list(target: Optional[str] = None, node: Optional[str] = None) -> list:
+    """[READ] List storage pools on a node (id, type, total/used/avail bytes).
+
+    Args:
+        target: Proxmox target name from config; omit to use the default.
+        node: Node name; omit to use the target's configured default node.
+    """
+    return st.list_storage(_get_connection(target), node=node)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("list")
+def storage_content(
+    storage: str,
+    content: Optional[str] = None,
+    target: Optional[str] = None,
+    node: Optional[str] = None,
+) -> list:
+    """[READ] List volumes on a storage pool (ISOs, disk images, backups, templates).
+
+    Args:
+        storage: Storage pool id (see storage_list).
+        content: Optional filter — 'iso', 'images', 'backup', 'vztmpl'.
+        target: Proxmox target name from config.
+        node: Node name; omit to use the configured default node.
+    """
+    return st.list_storage_content(
+        _get_connection(target), storage, node=node, content=content
+    )