@soyrageagency/proxmox-mcp 1.0.0

package/dist/plugins.js

@@ -0,0 +1,149 @@
+/**
+ * Plugin registry & loader.
+ *
+ * The server is built as a set of independent *plugins*, each owning one
+ * capability group. Which plugins load is fully driven by configuration.
+ *
+ * The `about` plugin is NON-DISABLEABLE: it carries the SoyRage Agency identity
+ * and attribution, which the license requires to stay present.
+ *
+ * Part of Proxmox MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * MIT licensed (see LICENSE).
+ */
+import { registerAboutTool } from "./tools/about.js";
+import { registerNodeTools } from "./tools/nodes.js";
+import { registerGuestTools } from "./tools/guests.js";
+import { registerClusterTools } from "./tools/cluster.js";
+import { registerStorageTools } from "./tools/storage.js";
+import { registerTaskTools } from "./tools/tasks.js";
+import { registerSnapshotTools } from "./tools/snapshots.js";
+import { registerLifecycleTools } from "./tools/lifecycle.js";
+import { registerManagementTools } from "./tools/management.js";
+import { registerBackupTools } from "./tools/backups.js";
+import { registerProvisioningTools } from "./tools/provisioning.js";
+import { registerResilienceTools } from "./tools/resilience.js";
+/** The built-in plugin catalogue. */
+export const BUILTIN_PLUGINS = Object.freeze([
+    {
+        name: "about",
+        title: "Identity & credits",
+        description: "SoyRage Agency welcome banner, credits and license.",
+        category: "identity",
+        mutating: false,
+        locked: true,
+        register: registerAboutTool,
+    },
+    {
+        name: "nodes",
+        title: "Cluster nodes",
+        description: "List nodes and read detailed node status.",
+        category: "nodes",
+        mutating: false,
+        register: registerNodeTools,
+    },
+    {
+        name: "guests",
+        title: "VMs & containers",
+        description: "List guests and read their status and configuration.",
+        category: "guests",
+        mutating: false,
+        register: registerGuestTools,
+    },
+    {
+        name: "storage",
+        title: "Storage",
+        description: "List storages and their usage on a node.",
+        category: "storage",
+        mutating: false,
+        register: registerStorageTools,
+    },
+    {
+        name: "tasks",
+        title: "Tasks",
+        description: "Recent task log on a node.",
+        category: "tasks",
+        mutating: false,
+        register: registerTaskTools,
+    },
+    {
+        name: "cluster",
+        title: "Cluster",
+        description: "Cluster status/quorum and a consolidated resource view.",
+        category: "cluster",
+        mutating: false,
+        register: registerClusterTools,
+    },
+    {
+        name: "snapshots",
+        title: "Snapshots",
+        description: "List snapshots and (unless read-only) create/rollback/delete.",
+        category: "snapshots",
+        mutating: true,
+        register: registerSnapshotTools,
+    },
+    {
+        name: "lifecycle",
+        title: "Guest lifecycle",
+        description: "Start, shutdown, stop, reboot, suspend and resume guests.",
+        category: "lifecycle",
+        mutating: true,
+        register: registerLifecycleTools,
+    },
+    {
+        name: "management",
+        title: "Advanced management",
+        description: "Migrate, clone, resize, backup and delete guests.",
+        category: "management",
+        mutating: true,
+        register: registerManagementTools,
+    },
+    {
+        name: "backups",
+        title: "Backups (vzdump)",
+        description: "List backup archives and (unless read-only) restore them.",
+        category: "backups",
+        mutating: true,
+        register: registerBackupTools,
+    },
+    {
+        name: "provisioning",
+        title: "Provisioning",
+        description: "List templates/ISOs and (unless read-only) create VMs and containers.",
+        category: "provisioning",
+        mutating: true,
+        register: registerProvisioningTools,
+    },
+    {
+        name: "resilience",
+        title: "Resilience & Compliance",
+        description: "Automated backup verification (restore-testing), patch orchestration with " +
+            "automatic rollback, and scheduled DR drills — each producing signed, dated " +
+            "ISO 27001 / NIS2 / DORA evidence reports.",
+        category: "resilience",
+        mutating: true,
+        register: registerResilienceTools,
+    },
+]);
+/** Resolve which plugins should load, applying the enable/disable selection. */
+export function selectPlugins(config, logger, catalogue = BUILTIN_PLUGINS) {
+    const enabledSet = new Set(config.plugins.enabled);
+    const disabledSet = new Set(config.plugins.disabled);
+    const selected = catalogue.filter((plugin) => {
+        if (plugin.locked)
+            return true;
+        if (enabledSet.size > 0 && !enabledSet.has(plugin.name))
+            return false;
+        if (disabledSet.has(plugin.name))
+            return false;
+        return true;
+    });
+    for (const name of disabledSet) {
+        if (catalogue.find((p) => p.name === name)?.locked) {
+            logger.warn(`Plugin "${name}" cannot be disabled (identity/attribution) and will still load.`);
+        }
+    }
+    logger.info(`Plugins enabled: ${selected.map((p) => p.name).join(", ") || "(none)"}`);
+    return selected;
+}
+//# sourceMappingURL=plugins.js.map

package/dist/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"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"}

package/dist/proxmox/client.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Proxmox VE API client.
+ *
+ * A small, typed wrapper around the Proxmox VE REST API (`/api2/json`). It
+ * supports both API-token auth (recommended) and username/password ticket
+ * auth, controls TLS verification (Proxmox ships self-signed certs), applies
+ * the optional guest allowlist and exposes the helpers the tools build on.
+ *
+ * Part of Proxmox MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * MIT licensed (see LICENSE).
+ */
+import type { AppConfig } from "../config.js";
+import type { Logger } from "../logger.js";
+/** A guest (QEMU VM or LXC container) as seen in cluster resources. */
+export interface Guest {
+    type: "qemu" | "lxc";
+    vmid: number;
+    name: string;
+    node: string;
+    status: string;
+    cpu: number;
+    maxcpu: number;
+    mem: number;
+    maxmem: number;
+    disk: number;
+    maxdisk: number;
+    uptime: number;
+    template: boolean;
+}
+/** A cluster node summary. */
+export interface NodeSummary {
+    node: string;
+    status: string;
+    cpu: number;
+    maxcpu: number;
+    mem: number;
+    maxmem: number;
+    uptime: number;
+}
+/** Raised when a guest is excluded by the allowlist. */
+export declare class GuestNotAllowedError extends Error {
+    constructor(ref: string);
+}
+/** Raised when a referenced guest does not exist. */
+export declare class GuestNotFoundError extends Error {
+    constructor(ref: string);
+}
+interface RawResource {
+    type: string;
+    vmid?: number;
+    name?: string;
+    node?: string;
+    status?: string;
+    cpu?: number;
+    maxcpu?: number;
+    mem?: number;
+    maxmem?: number;
+    disk?: number;
+    maxdisk?: number;
+    uptime?: number;
+    template?: number;
+}
+/** Application-facing Proxmox client. One instance is shared across tools. */
+export declare class ProxmoxClient {
+    private readonly config;
+    private readonly log;
+    private readonly agent;
+    private readonly allowlist;
+    private readonly demo;
+    private ticket;
+    constructor(config: AppConfig, logger: Logger);
+    /** Whether the client is serving fabricated demo data. */
+    get isDemo(): boolean;
+    /** True when using username/password ticket auth (vs. an API token). */
+    private get usingTicket();
+    /** Verify connectivity/credentials by hitting /version. */
+    ping(): Promise<void>;
+    private authHeaders;
+    /** Acquire a login ticket (username/password auth). */
+    private login;
+    private fetch;
+    /** Perform an authenticated request and return the `data` payload. */
+    private request;
+    /** GET helper. */
+    get<T>(path: string): Promise<T>;
+    /** POST helper (form-encoded params). */
+    post<T = unknown>(path: string, params?: Record<string, string | number>): Promise<T>;
+    /** DELETE helper. */
+    del<T = unknown>(path: string): Promise<T>;
+    /** Proxmox version info. */
+    version(): Promise<Record<string, unknown>>;
+    /** Detailed status of a single node. */
+    nodeStatus(node: string): Promise<Record<string, unknown>>;
+    /** All cluster nodes with load summary. */
+    nodes(): Promise<NodeSummary[]>;
+    /** Raw cluster resources (optionally filtered by type). */
+    clusterResources(type?: string): Promise<RawResource[]>;
+    /** Cluster status (quorum, members). */
+    clusterStatus(): Promise<Array<Record<string, unknown>>>;
+    /** All guests (QEMU + LXC), honouring the allowlist. */
+    guests(): Promise<Guest[]>;
+    /** Whether a guest is permitted by the allowlist (by VMID or name). */
+    isAllowed(guest: Guest): boolean;
+    /**
+     * Resolve a reference (VMID or name) to a guest, enforcing the allowlist.
+     * Returns the guest including its node — required for every guest API call.
+     */
+    resolveGuest(reference: string): Promise<Guest>;
+    /** Internal: guests without allowlist filtering (for resolution/errors). */
+    private guestsUnfiltered;
+    /** Base API path for a guest, e.g. /nodes/pve/qemu/100. */
+    guestBase(guest: Guest): string;
+    /** Current runtime status of a guest. */
+    guestStatus(guest: Guest): Promise<Record<string, unknown>>;
+    /** Full configuration of a guest. */
+    guestConfig(guest: Guest): Promise<Record<string, unknown>>;
+    /** Storage available on a node. */
+    storage(node: string): Promise<Array<Record<string, unknown>>>;
+    /** Recent tasks on a node. */
+    tasks(node: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /** Snapshots of a guest. */
+    snapshots(guest: Guest): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Operating-system info for a guest: the configured `ostype` plus, for
+     * running QEMU VMs with the guest agent, the detected OS and IP addresses.
+     */
+    osInfo(guest: Guest): Promise<Record<string, unknown>>;
+    /** List the content of a storage (backups, ISOs, templates, disks…). */
+    storageContent(node: string, storage: string, content?: string): Promise<Array<Record<string, unknown>>>;
+    /** Storages on a node that can hold backups. */
+    backupStorages(node: string): Promise<string[]>;
+    /** Resolve a node name, defaulting to the first cluster node. */
+    resolveNode(node?: string): Promise<string>;
+    /** Whether the AI copilot is available (demo always simulates it). */
+    get aiEnabled(): boolean;
+    /**
+     * AI copilot: interpret a natural-language order against the current guests
+     * and return a structured intent — either an action to run on a guest, or a
+     * plain-language answer. Uses an OpenAI-compatible endpoint when configured;
+     * demo mode simulates it with a small rule engine.
+     */
+    aiAssist(prompt: string): Promise<AiIntent>;
+}
+/** A structured AI intent returned by aiAssist. */
+export interface AiIntent {
+    action: "start" | "shutdown" | "stop" | "reboot" | "snapshot" | "none";
+    guest: string;
+    answer: string;
+    explanation: string;
+    source: string;
+}
+export {};