@samik081/mcp-pve 0.1.0

package/dist/tools/backup.js

@@ -0,0 +1,176 @@
+/**
+ * Backup tools: backup jobs, manual backup execution, and job management.
+ */
+import { z } from "zod";
+import { registerTool } from "../core/tools.js";
+export function registerBackupTools(server, client, config) {
+    // --- Read-only tools ---
+    registerTool(server, config, {
+        name: "pve_list_backup_jobs",
+        description: "List all scheduled backup jobs in the cluster",
+        category: "backup",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/backup");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_get_backup_job",
+        description: "Get the configuration of a specific backup job",
+        category: "backup",
+        accessTier: "read-only",
+        inputSchema: {
+            id: z.string().describe("The backup job ID"),
+        },
+        handler: async (args) => {
+            const data = await client.get(`/cluster/backup/${args.id}`);
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    // --- Read-execute tools ---
+    registerTool(server, config, {
+        name: "pve_run_backup",
+        description: "Run an immediate backup (vzdump) of one or more VMs/containers on a node",
+        category: "backup",
+        accessTier: "read-execute",
+        inputSchema: {
+            node: z.string().describe("The node name"),
+            vmid: z
+                .string()
+                .optional()
+                .describe("Comma-separated list of VMIDs to back up (omit for all)"),
+            storage: z
+                .string()
+                .optional()
+                .describe("Target storage for the backup"),
+            mode: z
+                .enum(["snapshot", "suspend", "stop"])
+                .optional()
+                .describe("Backup mode (default: snapshot)"),
+            compress: z
+                .enum(["0", "gzip", "lzo", "zstd"])
+                .optional()
+                .describe("Compression algorithm"),
+            mailnotification: z
+                .enum(["always", "failure"])
+                .optional()
+                .describe("When to send email notification"),
+            mailto: z
+                .string()
+                .optional()
+                .describe("Email address for backup notifications"),
+        },
+        handler: async (args) => {
+            const body = {};
+            if (args.vmid !== undefined)
+                body.vmid = args.vmid;
+            if (args.storage !== undefined)
+                body.storage = args.storage;
+            if (args.mode !== undefined)
+                body.mode = args.mode;
+            if (args.compress !== undefined)
+                body.compress = args.compress;
+            if (args.mailnotification !== undefined)
+                body.mailnotification = args.mailnotification;
+            if (args.mailto !== undefined)
+                body.mailto = args.mailto;
+            const data = await client.post(`/nodes/${args.node}/vzdump`, body);
+            return `Backup initiated on node ${args.node}. Task: ${data}`;
+        },
+    });
+    // --- Full access tools ---
+    registerTool(server, config, {
+        name: "pve_create_backup_job",
+        description: "Create a new scheduled backup job",
+        category: "backup",
+        accessTier: "full",
+        inputSchema: {
+            vmid: z
+                .string()
+                .optional()
+                .describe("Comma-separated list of VMIDs to include (omit for all)"),
+            storage: z
+                .string()
+                .optional()
+                .describe("Target storage for backups"),
+            schedule: z
+                .string()
+                .optional()
+                .describe("Backup schedule in cron-like format or PVE calendar event"),
+            mode: z
+                .enum(["snapshot", "suspend", "stop"])
+                .optional()
+                .describe("Backup mode (default: snapshot)"),
+            compress: z
+                .enum(["0", "gzip", "lzo", "zstd"])
+                .optional()
+                .describe("Compression algorithm"),
+            mailnotification: z
+                .enum(["always", "failure"])
+                .optional()
+                .describe("When to send email notification"),
+            mailto: z
+                .string()
+                .optional()
+                .describe("Email address for backup notifications"),
+            enabled: z
+                .boolean()
+                .optional()
+                .describe("Enable the backup job (default: true)"),
+            node: z
+                .string()
+                .optional()
+                .describe("Restrict to specific node"),
+            pool: z
+                .string()
+                .optional()
+                .describe("Backup all VMs in this pool"),
+            maxfiles: z
+                .number()
+                .optional()
+                .describe("Maximum number of backup files per VM (0 = unlimited)"),
+        },
+        handler: async (args) => {
+            const body = {};
+            if (args.vmid !== undefined)
+                body.vmid = args.vmid;
+            if (args.storage !== undefined)
+                body.storage = args.storage;
+            if (args.schedule !== undefined)
+                body.schedule = args.schedule;
+            if (args.mode !== undefined)
+                body.mode = args.mode;
+            if (args.compress !== undefined)
+                body.compress = args.compress;
+            if (args.mailnotification !== undefined)
+                body.mailnotification = args.mailnotification;
+            if (args.mailto !== undefined)
+                body.mailto = args.mailto;
+            if (args.enabled !== undefined)
+                body.enabled = args.enabled ? 1 : 0;
+            if (args.node !== undefined)
+                body.node = args.node;
+            if (args.pool !== undefined)
+                body.pool = args.pool;
+            if (args.maxfiles !== undefined)
+                body.maxfiles = args.maxfiles;
+            await client.post("/cluster/backup", body);
+            return "Backup job created successfully.";
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_delete_backup_job",
+        description: "Delete a scheduled backup job",
+        category: "backup",
+        accessTier: "full",
+        annotations: { destructiveHint: true },
+        inputSchema: {
+            id: z.string().describe("The backup job ID to delete"),
+        },
+        handler: async (args) => {
+            await client.delete(`/cluster/backup/${args.id}`);
+            return `Backup job '${args.id}' deleted successfully.`;
+        },
+    });
+}

package/dist/tools/cluster.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Cluster tools: status, resources, options, and cluster-wide information.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PveClient } from "../core/client.js";
+import type { AppConfig } from "../types/index.js";
+export declare function registerClusterTools(server: McpServer, client: PveClient, config: AppConfig): void;

package/dist/tools/cluster.js

@@ -0,0 +1,150 @@
+/**
+ * Cluster tools: status, resources, options, and cluster-wide information.
+ */
+import { z } from "zod";
+import { registerTool } from "../core/tools.js";
+export function registerClusterTools(server, client, config) {
+    // --- Read-only tools ---
+    registerTool(server, config, {
+        name: "pve_get_cluster_status",
+        description: "Get the current cluster status including node membership and quorum",
+        category: "cluster",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/status");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_list_cluster_resources",
+        description: "List all cluster resources (VMs, containers, storage, nodes) with optional type filter",
+        category: "cluster",
+        accessTier: "read-only",
+        inputSchema: {
+            type: z
+                .enum(["vm", "storage", "node", "sdn"])
+                .optional()
+                .describe("Filter by resource type"),
+        },
+        handler: async (args) => {
+            let path = "/cluster/resources";
+            if (args.type)
+                path += `?type=${args.type}`;
+            const data = await client.get(path);
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_get_next_vmid",
+        description: "Get the next available VMID in the cluster",
+        category: "cluster",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/nextid");
+            return `Next available VMID: ${data}`;
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_get_cluster_log",
+        description: "Get recent cluster log entries",
+        category: "cluster",
+        accessTier: "read-only",
+        inputSchema: {
+            max: z
+                .number()
+                .optional()
+                .describe("Maximum number of log entries to return"),
+        },
+        handler: async (args) => {
+            let path = "/cluster/log";
+            if (args.max !== undefined)
+                path += `?max=${args.max}`;
+            const data = await client.get(path);
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_get_cluster_options",
+        description: "Get cluster-wide datacenter options",
+        category: "cluster",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/options");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_list_cluster_backup_info",
+        description: "List guests that are not covered by any backup job",
+        category: "cluster",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/backup-info/not-backed-up");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_get_cluster_ha_status",
+        description: "Get the current HA manager status",
+        category: "cluster",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/ha/status/current");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_list_cluster_replication",
+        description: "List all replication jobs in the cluster",
+        category: "cluster",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/replication");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    // --- Full access tools ---
+    registerTool(server, config, {
+        name: "pve_update_cluster_options",
+        description: "Update cluster-wide datacenter options",
+        category: "cluster",
+        accessTier: "full",
+        inputSchema: {
+            keyboard: z
+                .string()
+                .optional()
+                .describe("Default keyboard layout for VNC"),
+            language: z
+                .string()
+                .optional()
+                .describe("Default GUI language"),
+            console: z
+                .enum(["applet", "vv", "html5", "xtermjs"])
+                .optional()
+                .describe("Default console viewer"),
+            http_proxy: z
+                .string()
+                .optional()
+                .describe("HTTP proxy configuration"),
+            migration_unsecure: z
+                .boolean()
+                .optional()
+                .describe("Allow insecure migration"),
+        },
+        handler: async (args) => {
+            const body = {};
+            if (args.keyboard !== undefined)
+                body.keyboard = args.keyboard;
+            if (args.language !== undefined)
+                body.language = args.language;
+            if (args.console !== undefined)
+                body.console = args.console;
+            if (args.http_proxy !== undefined)
+                body.http_proxy = args.http_proxy;
+            if (args.migration_unsecure !== undefined)
+                body["migration_unsecure"] = args.migration_unsecure ? 1 : 0;
+            await client.put("/cluster/options", body);
+            return "Cluster options updated successfully.";
+        },
+    });
+}

package/dist/tools/firewall.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Firewall tools: cluster-level firewall options, rules, aliases, and IP sets.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PveClient } from "../core/client.js";
+import type { AppConfig } from "../types/index.js";
+export declare function registerFirewallTools(server: McpServer, client: PveClient, config: AppConfig): void;

package/dist/tools/firewall.js

@@ -0,0 +1,215 @@
+/**
+ * Firewall tools: cluster-level firewall options, rules, aliases, and IP sets.
+ */
+import { z } from "zod";
+import { registerTool } from "../core/tools.js";
+export function registerFirewallTools(server, client, config) {
+    // --- Read-only tools ---
+    registerTool(server, config, {
+        name: "pve_get_firewall_options",
+        description: "Get the cluster-level firewall options",
+        category: "firewall",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/firewall/options");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_list_firewall_rules",
+        description: "List all cluster-level firewall rules",
+        category: "firewall",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/firewall/rules");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_list_firewall_aliases",
+        description: "List all cluster-level firewall aliases (named IP/CIDR entries)",
+        category: "firewall",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/firewall/aliases");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_list_firewall_ipsets",
+        description: "List all cluster-level firewall IP sets",
+        category: "firewall",
+        accessTier: "read-only",
+        handler: async () => {
+            const data = await client.get("/cluster/firewall/ipset");
+            return JSON.stringify(data, null, 2);
+        },
+    });
+    // --- Full access tools ---
+    registerTool(server, config, {
+        name: "pve_update_firewall_options",
+        description: "Update the cluster-level firewall options (e.g. enable/disable firewall)",
+        category: "firewall",
+        accessTier: "full",
+        inputSchema: {
+            enable: z
+                .boolean()
+                .optional()
+                .describe("Enable or disable the cluster firewall"),
+            policy_in: z
+                .enum(["ACCEPT", "REJECT", "DROP"])
+                .optional()
+                .describe("Default input policy"),
+            policy_out: z
+                .enum(["ACCEPT", "REJECT", "DROP"])
+                .optional()
+                .describe("Default output policy"),
+            log_ratelimit: z
+                .string()
+                .optional()
+                .describe("Log rate limit (e.g. 'enable=1,rate=1/second,burst=5')"),
+        },
+        handler: async (args) => {
+            const body = {};
+            if (args.enable !== undefined)
+                body.enable = args.enable ? 1 : 0;
+            if (args.policy_in !== undefined)
+                body.policy_in = args.policy_in;
+            if (args.policy_out !== undefined)
+                body.policy_out = args.policy_out;
+            if (args.log_ratelimit !== undefined)
+                body.log_ratelimit = args.log_ratelimit;
+            await client.put("/cluster/firewall/options", body);
+            return "Cluster firewall options updated successfully.";
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_create_firewall_rule",
+        description: "Create a new cluster-level firewall rule",
+        category: "firewall",
+        accessTier: "full",
+        inputSchema: {
+            action: z
+                .enum(["ACCEPT", "DROP", "REJECT"])
+                .describe("Rule action"),
+            type: z.enum(["in", "out", "group"]).describe("Rule type (direction)"),
+            enable: z
+                .boolean()
+                .optional()
+                .describe("Enable the rule (default: true)"),
+            source: z
+                .string()
+                .optional()
+                .describe("Source address/CIDR or alias"),
+            dest: z
+                .string()
+                .optional()
+                .describe("Destination address/CIDR or alias"),
+            proto: z
+                .string()
+                .optional()
+                .describe("Protocol (e.g. tcp, udp, icmp)"),
+            dport: z
+                .string()
+                .optional()
+                .describe("Destination port or port range"),
+            sport: z
+                .string()
+                .optional()
+                .describe("Source port or port range"),
+            comment: z.string().optional().describe("Rule comment"),
+            pos: z
+                .number()
+                .optional()
+                .describe("Position in the rule list (0-based)"),
+        },
+        handler: async (args) => {
+            const body = {
+                action: args.action,
+                type: args.type,
+            };
+            if (args.enable !== undefined)
+                body.enable = args.enable ? 1 : 0;
+            if (args.source !== undefined)
+                body.source = args.source;
+            if (args.dest !== undefined)
+                body.dest = args.dest;
+            if (args.proto !== undefined)
+                body.proto = args.proto;
+            if (args.dport !== undefined)
+                body.dport = args.dport;
+            if (args.sport !== undefined)
+                body.sport = args.sport;
+            if (args.comment !== undefined)
+                body.comment = args.comment;
+            if (args.pos !== undefined)
+                body.pos = args.pos;
+            await client.post("/cluster/firewall/rules", body);
+            return "Cluster firewall rule created successfully.";
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_update_firewall_rule",
+        description: "Update an existing cluster-level firewall rule by position",
+        category: "firewall",
+        accessTier: "full",
+        inputSchema: {
+            pos: z.number().describe("Rule position (0-based index)"),
+            action: z
+                .enum(["ACCEPT", "DROP", "REJECT"])
+                .optional()
+                .describe("Rule action"),
+            enable: z
+                .boolean()
+                .optional()
+                .describe("Enable or disable the rule"),
+            source: z.string().optional().describe("Source address/CIDR or alias"),
+            dest: z
+                .string()
+                .optional()
+                .describe("Destination address/CIDR or alias"),
+            proto: z.string().optional().describe("Protocol"),
+            dport: z
+                .string()
+                .optional()
+                .describe("Destination port or port range"),
+            sport: z.string().optional().describe("Source port or port range"),
+            comment: z.string().optional().describe("Rule comment"),
+        },
+        handler: async (args) => {
+            const body = {};
+            if (args.action !== undefined)
+                body.action = args.action;
+            if (args.enable !== undefined)
+                body.enable = args.enable ? 1 : 0;
+            if (args.source !== undefined)
+                body.source = args.source;
+            if (args.dest !== undefined)
+                body.dest = args.dest;
+            if (args.proto !== undefined)
+                body.proto = args.proto;
+            if (args.dport !== undefined)
+                body.dport = args.dport;
+            if (args.sport !== undefined)
+                body.sport = args.sport;
+            if (args.comment !== undefined)
+                body.comment = args.comment;
+            await client.put(`/cluster/firewall/rules/${args.pos}`, body);
+            return `Cluster firewall rule at position ${args.pos} updated successfully.`;
+        },
+    });
+    registerTool(server, config, {
+        name: "pve_delete_firewall_rule",
+        description: "Delete a cluster-level firewall rule by position",
+        category: "firewall",
+        accessTier: "full",
+        annotations: { destructiveHint: true },
+        inputSchema: {
+            pos: z.number().describe("Rule position (0-based index) to delete"),
+        },
+        handler: async (args) => {
+            await client.delete(`/cluster/firewall/rules/${args.pos}`);
+            return `Cluster firewall rule at position ${args.pos} deleted successfully.`;
+        },
+    });
+}

package/dist/tools/ha.d.ts

@@ -0,0 +1,9 @@
+/**
+ * HA (High Availability) tools: CRUD for HA-managed resources.
+ *
+ * SID format: type:vmid (e.g. vm:100, ct:200)
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PveClient } from "../core/client.js";
+import type { AppConfig } from "../types/index.js";
+export declare function registerHaTools(server: McpServer, client: PveClient, config: AppConfig): void;