@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/clients/proxmox-client.js

@@ -0,0 +1,92 @@
+import { fetch, Agent } from "undici";
+import { formatError } from "@nightsquawktech/mcp-core/catalog";
+import { resolveSurfaceConfig } from "../config.js";
+/**
+ * Thin Proxmox REST client for one surface (PVE or PDM). Handles token auth,
+ * self-signed TLS (per-surface), path-param substitution, and routing of
+ * non-path params to the query string or JSON body per the endpoint spec.
+ *
+ * Lazily reads env on first request so missing credentials surface as a clear
+ * tool error rather than crashing the server at startup.
+ */
+export class ProxmoxClient {
+    constructor(surface) {
+        this.surface = surface;
+        this.initialized = false;
+        this.baseUrl = "";
+        this.authHeader = "";
+        this.dispatcher = null;
+    }
+    ensureInitialized() {
+        if (this.initialized)
+            return;
+        const { config, missing } = resolveSurfaceConfig(this.surface);
+        if (!config) {
+            throw new Error(`${this.surface.toUpperCase()} is not configured. Missing: ${missing.join(", ")}.`);
+        }
+        this.baseUrl = config.baseUrl;
+        this.authHeader = config.authHeader;
+        this.dispatcher = new Agent({ connect: { rejectUnauthorized: config.rejectUnauthorized } });
+        this.initialized = true;
+    }
+    async request(spec, args = {}) {
+        try {
+            this.ensureInitialized();
+            // Substitute {placeholder} path params.
+            let path = spec.path;
+            for (const pp of spec.pathParams) {
+                const v = args.pathParams?.[pp.name];
+                if (v === undefined || v === null || v === "") {
+                    throw new Error(`Missing path parameter "${pp.name}" for ${spec.method} ${spec.path}`);
+                }
+                path = path.replace(`{${pp.name}}`, encodeURIComponent(String(v)));
+            }
+            let url = `${this.baseUrl}${path}`;
+            const headers = { Authorization: this.authHeader };
+            let body;
+            const entries = Object.entries(args.params ?? {}).filter(([, v]) => v !== undefined && v !== null);
+            if (spec.paramLocation === "body" && entries.length) {
+                headers["Content-Type"] = "application/json";
+                body = JSON.stringify(Object.fromEntries(entries));
+            }
+            else if (entries.length) {
+                const qs = entries
+                    .map(([k, v]) => {
+                    const val = Array.isArray(v)
+                        ? v.join(",")
+                        : typeof v === "boolean"
+                            ? v ? "1" : "0"
+                            : String(v);
+                    return `${encodeURIComponent(k)}=${encodeURIComponent(val)}`;
+                })
+                    .join("&");
+                url += `?${qs}`;
+            }
+            const res = await fetch(url, {
+                method: spec.method,
+                headers,
+                body,
+                dispatcher: this.dispatcher,
+            });
+            const text = await res.text();
+            let data = null;
+            if (text) {
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    data = text;
+                }
+            }
+            if (!res.ok) {
+                const detail = typeof data === "string" ? data : JSON.stringify(data);
+                return { result: null, isError: true, error: `HTTP ${res.status} ${res.statusText}: ${detail}` };
+            }
+            // Proxmox wraps payloads as { data: ... }. Return the whole object.
+            return { result: data, isError: false, error: null };
+        }
+        catch (error) {
+            return { result: null, isError: true, error: formatError(error) };
+        }
+    }
+}

package/dist/config.js

@@ -0,0 +1,57 @@
+/**
+ * Per-surface configuration, resolved lazily from environment variables so the
+ * server can boot (and serve the catalog) without credentials. A surface's
+ * `call` tool only errors at call time if its vars are unset.
+ *
+ * Auth note: PVE uses `PVEAPIToken=USER@REALM!TOKENID=SECRET`. Other Proxmox
+ * products may differ in scheme name or the id/secret separator, so both are
+ * overridable via `<SURFACE>_AUTH_SCHEME` / `<SURFACE>_AUTH_SEP`.
+ */
+export const SURFACE_DEFAULTS = {
+    pve: { product: "Proxmox VE", port: 8006, authScheme: "PVEAPIToken" },
+    pdm: { product: "Proxmox Datacenter Manager", port: 8443, authScheme: "PDMAPIToken" },
+};
+/** Resolve a surface's connection config, or report which env vars are missing. */
+export function resolveSurfaceConfig(surface) {
+    const S = surface.toUpperCase();
+    const d = SURFACE_DEFAULTS[surface];
+    const host = process.env[`${S}_HOST`];
+    const baseUrl = process.env[`${S}_BASE_URL`] || (host ? `https://${host}:${d.port}/api2/json` : "");
+    const tokenId = process.env[`${S}_TOKEN_ID`];
+    const tokenSecret = process.env[`${S}_TOKEN_SECRET`];
+    const scheme = process.env[`${S}_AUTH_SCHEME`] || d.authScheme;
+    const sep = process.env[`${S}_AUTH_SEP`] ?? "=";
+    const missing = [];
+    if (!baseUrl)
+        missing.push(`${S}_HOST (or ${S}_BASE_URL)`);
+    if (!tokenId)
+        missing.push(`${S}_TOKEN_ID`);
+    if (!tokenSecret)
+        missing.push(`${S}_TOKEN_SECRET`);
+    if (missing.length)
+        return { config: null, missing };
+    return {
+        config: {
+            baseUrl: baseUrl.replace(/\/+$/, ""),
+            authHeader: `${scheme}=${tokenId}${sep}${tokenSecret}`,
+            // Self-signed certs are the Proxmox default; opt out of verification per surface.
+            rejectUnauthorized: process.env[`${S}_TLS_REJECT_UNAUTHORIZED`] !== "false",
+        },
+        missing: [],
+    };
+}
+/**
+ * Whether write operations (POST/PUT/DELETE) may execute for a surface.
+ * Read-only by default. Enable globally with PROXMOX_ALLOW_WRITES=true, or
+ * per-surface with e.g. PVE_ALLOW_WRITES=true.
+ */
+export function writesAllowed(surface) {
+    const S = surface.toUpperCase();
+    return (process.env[`${S}_ALLOW_WRITES`] === "true" ||
+        process.env.PROXMOX_ALLOW_WRITES === "true");
+}
+/** The env var(s) that gate writes for a surface, for help text. */
+export function writeGateEnvHint(surface) {
+    const S = surface.toUpperCase();
+    return `PROXMOX_ALLOW_WRITES=true (all surfaces) or ${S}_ALLOW_WRITES=true (this surface only)`;
+}

package/dist/helpers/format-error.js

@@ -0,0 +1,14 @@
+/**
+ * Formats an error into a standardized error message.
+ */
+export function formatError(error) {
+    if (error instanceof Error) {
+        return `Error: ${error.message}`;
+    }
+    else if (typeof error === "string") {
+        return `Error: ${error}`;
+    }
+    else {
+        return `Unknown error: ${JSON.stringify(error)}`;
+    }
+}

package/dist/helpers/register-surface-tools.js

@@ -0,0 +1,26 @@
+import { RegisterTool } from "@nightsquawktech/mcp-core/catalog";
+import { loadIndex } from "../catalog/endpoint-spec.js";
+import { ProxmoxClient } from "../clients/proxmox-client.js";
+import { makeListEndpointsTool } from "../tools/list-endpoints.js";
+import { makeDescribeEndpointTool } from "../tools/describe-endpoint.js";
+import { makeCallEndpointTool } from "../tools/call-endpoint.js";
+/**
+ * Registers the three catalog-backed tools for one surface:
+ *   <surface>_list_endpoints      discover endpoints
+ *   <surface>_describe_endpoint   full param + response spec (+ enrichment)
+ *   <surface>_call_endpoint       validate, write-gate, execute
+ *
+ * Boot-time sanity check: the catalog index must load and be non-empty, so a
+ * missing/uncopied catalog fails fast at startup rather than on first call.
+ */
+export function registerSurfaceTools(server, surface) {
+    const index = loadIndex(surface);
+    if (!index.endpoints || index.endpoints.length === 0) {
+        throw new Error(`${surface} catalog is empty or missing — expected src/catalog-${surface}/index.json. ` +
+            `Did the build copy the catalog into dist/? Run scripts/extract.mjs + scripts/assemble-catalog.mjs.`);
+    }
+    const client = new ProxmoxClient(surface);
+    RegisterTool(server, makeListEndpointsTool(surface));
+    RegisterTool(server, makeDescribeEndpointTool(surface));
+    RegisterTool(server, makeCallEndpointTool(surface, client));
+}

package/dist/helpers/register-tool.js

@@ -0,0 +1,3 @@
+export function RegisterTool(server, toolDefinition) {
+    server.tool(toolDefinition.name, toolDefinition.description, { params: toolDefinition.schema }, toolDefinition.handler);
+}

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ProxmoxMCPServer } from "./server/proxmox-mcp-server.js";
+import { registerSurfaceTools } from "./helpers/register-surface-tools.js";
+const server = ProxmoxMCPServer.GetServer();
+// Both surfaces are always registered (the catalogs ship in-repo). A surface's
+// call tool only errors at call time if its credentials are unset — configure
+// one or both via environment variables.
+registerSurfaceTools(server, "pve");
+registerSurfaceTools(server, "pdm");
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/server/proxmox-mcp-server.js

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export class ProxmoxMCPServer {
+    constructor() { }
+    static GetServer() {
+        if (ProxmoxMCPServer.instance === null) {
+            ProxmoxMCPServer.instance = new McpServer({
+                name: "Proxmox MCP Server",
+                version: "0.1.0",
+            }, {
+                capabilities: {
+                    tools: {},
+                },
+            });
+        }
+        return ProxmoxMCPServer.instance;
+    }
+}
+ProxmoxMCPServer.instance = null;

package/dist/tools/call-endpoint.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { SURFACE_DEFAULTS, writesAllowed, writeGateEnvHint } from "../config.js";
+import { loadEndpointSpec, loadEnrichment, loadIndex } from "../catalog/endpoint-spec.js";
+const schema = z.object({
+    operation_id: z
+        .string()
+        .describe("The endpoint operationId to call, e.g. 'get_nodes'. See list_endpoints / describe_endpoint."),
+    path_params: z
+        .record(z.any())
+        .optional()
+        .describe("Values for {placeholder} path params, e.g. { node: 'pve1', vmid: 100 }."),
+    params: z
+        .record(z.any())
+        .optional()
+        .describe("Non-path params: query params for GET/DELETE, JSON body fields for POST/PUT. See describe_endpoint."),
+    confirm: z
+        .boolean()
+        .optional()
+        .describe("Must be true to execute a DESTRUCTIVE operation (delete/stop/reset/migrate/etc.), even when writes are enabled."),
+});
+function errorText(text) {
+    return { content: [{ type: "text", text }] };
+}
+export function makeCallEndpointTool(surface, client) {
+    const product = SURFACE_DEFAULTS[surface].product;
+    return {
+        name: `${surface}_call_endpoint`,
+        description: `Call a ${product} API endpoint and return its JSON response. Validates the operationId and ` +
+            `required path params against the catalog, enforces the read-only write gate, then executes. ` +
+            `Reads (GET) always run; writes (POST/PUT/DELETE) run only when enabled via ${writeGateEnvHint(surface)}. ` +
+            `Use ${surface}_describe_endpoint first to learn the exact params.`,
+        schema,
+        handler: async ({ params }) => {
+            const operationId = params?.operation_id;
+            const spec = loadEndpointSpec(surface, operationId);
+            if (!spec) {
+                const known = loadIndex(surface).endpoints.map((e) => e.operationId);
+                const suggestions = known
+                    .filter((id) => operationId && (id.includes(operationId) || operationId.includes(id)))
+                    .slice(0, 5);
+                return errorText(`Unknown endpoint "${operationId}" on ${surface}. ` +
+                    (suggestions.length ? `Did you mean: ${suggestions.join(", ")}? ` : "") +
+                    `Call ${surface}_list_endpoints to discover endpoints.`);
+            }
+            // Required path params (hard — the URL can't be built without them).
+            const provided = params?.path_params ?? {};
+            const missing = spec.pathParams
+                .filter((p) => p.required)
+                .filter((p) => {
+                const v = provided[p.name];
+                return v === undefined || v === null || (typeof v === "string" && v.trim() === "");
+            });
+            if (missing.length) {
+                return errorText(`Missing required path parameter(s) for "${spec.operationId}" (${spec.method} ${spec.path}): ` +
+                    `${missing.map((p) => p.name).join(", ")}. Call ${surface}_describe_endpoint("${spec.operationId}").`);
+            }
+            // Write gate — read-only unless explicitly enabled.
+            if (spec.writeOperation && !writesAllowed(surface)) {
+                return errorText(`"${spec.operationId}" is a WRITE (${spec.method} ${spec.path}) and writes are disabled (read-only mode). ` +
+                    `Enable with ${writeGateEnvHint(surface)}, then retry.`);
+            }
+            // Destructive ops need an explicit confirm even when writes are enabled.
+            if (spec.destructive && params?.confirm !== true) {
+                const enrichment = loadEnrichment(surface, operationId);
+                const reason = enrichment?.destructiveReason || "This operation can cause data loss or service disruption.";
+                return errorText(`"${spec.operationId}" (${spec.method} ${spec.path}) is flagged DESTRUCTIVE. ${reason} ` +
+                    `Re-call with confirm:true to proceed.`);
+            }
+            const response = await client.request(spec, {
+                pathParams: provided,
+                params: params?.params,
+            });
+            if (response.isError) {
+                return errorText(`Error calling ${spec.operationId} (${spec.method} ${spec.path}): ${response.error}`);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            operation_id: spec.operationId,
+                            surface,
+                            method: spec.method,
+                            path: spec.path,
+                            result: response.result,
+                        }),
+                    },
+                ],
+            };
+        },
+    };
+}

package/dist/tools/describe-endpoint.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { SURFACE_DEFAULTS, writesAllowed, writeGateEnvHint } from "../config.js";
+import { loadEndpointSpec, loadEnrichment, loadIndex } from "../catalog/endpoint-spec.js";
+const schema = z.object({
+    operation_id: z
+        .string()
+        .describe("The endpoint operationId, e.g. 'get_nodes' or 'post_nodes_node_qemu'. See list_endpoints."),
+});
+export function makeDescribeEndpointTool(surface) {
+    const product = SURFACE_DEFAULTS[surface].product;
+    return {
+        name: `${surface}_describe_endpoint`,
+        description: `Get the full spec for one ${product} endpoint: method, path, path params, query/body ` +
+            `params (with types, formats, enums, constraints), the response schema, required permissions, ` +
+            `and a request sample. Call before ${surface}_call_endpoint so you send exactly the right params.`,
+        schema,
+        handler: async ({ params }) => {
+            const operationId = params?.operation_id;
+            const spec = loadEndpointSpec(surface, operationId);
+            if (!spec) {
+                const known = loadIndex(surface).endpoints.map((e) => e.operationId);
+                const suggestions = known
+                    .filter((id) => operationId && (id.includes(operationId) || operationId.includes(id)))
+                    .slice(0, 5);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown endpoint "${operationId}" on ${surface}. ` +
+                                (suggestions.length ? `Did you mean: ${suggestions.join(", ")}? ` : "") +
+                                `Call ${surface}_list_endpoints to discover endpoints.`,
+                        },
+                    ],
+                };
+            }
+            const enrichment = loadEnrichment(surface, operationId);
+            const payload = {
+                operation_id: spec.operationId,
+                surface,
+                name: spec.name,
+                method: spec.method,
+                path: spec.path,
+                description: spec.description,
+                category: spec.category,
+                resource: spec.resource,
+                writeOperation: spec.writeOperation,
+                destructive: spec.destructive,
+                protected: spec.protected,
+                paramLocation: spec.paramLocation,
+                pathParams: spec.pathParams,
+                params: spec.params,
+                returns: spec.returns,
+                permissions: spec.permissions,
+                requestSample: spec.requestSample,
+            };
+            if (spec.writeOperation) {
+                payload.writeStatus = writesAllowed(surface)
+                    ? "Writes ENABLED for this surface."
+                    : `Writes DISABLED (read-only). Enable with ${writeGateEnvHint(surface)}.`;
+            }
+            if (enrichment) {
+                payload.enrichment = {
+                    ...(enrichment.usageNotes ? { usageNotes: enrichment.usageNotes } : {}),
+                    ...(enrichment.examples ? { examples: enrichment.examples } : {}),
+                    ...(enrichment.destructiveReason ? { destructiveReason: enrichment.destructiveReason } : {}),
+                    ...(enrichment.tips ? { tips: enrichment.tips } : {}),
+                    ...(enrichment.relatedOperations ? { relatedOperations: enrichment.relatedOperations } : {}),
+                };
+            }
+            return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+        },
+    };
+}

package/dist/tools/list-endpoints.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { SURFACE_DEFAULTS } from "../config.js";
+import { loadIndex } from "../catalog/endpoint-spec.js";
+const schema = z.object({
+    category: z.string().optional().describe("Filter by category (call with no args to see all categories)."),
+    resource: z.string().optional().describe("Filter by resource = the path's first segment, e.g. 'nodes', 'cluster', 'access'."),
+    method: z.string().optional().describe("Filter by HTTP method: GET, POST, PUT, or DELETE."),
+    reads_only: z.boolean().optional().describe("Only read (GET) endpoints."),
+    writes_only: z.boolean().optional().describe("Only write (POST/PUT/DELETE) endpoints."),
+    search: z.string().optional().describe("Case-insensitive substring match on operationId, path, name, or description."),
+    limit: z.number().optional().describe("Max endpoints to return (default 200). Narrow with filters/search for big surfaces."),
+});
+export function makeListEndpointsTool(surface) {
+    const product = SURFACE_DEFAULTS[surface].product;
+    return {
+        name: `${surface}_list_endpoints`,
+        description: `List ${product} API endpoints (operationId, method, path, category, description, ` +
+            `read/write, destructive). Filter by category, resource, method, reads/writes, or search. ` +
+            `Use this to discover an endpoint, then ${surface}_describe_endpoint for its parameters and ` +
+            `${surface}_call_endpoint to execute it.`,
+        schema,
+        handler: async ({ params }) => {
+            const index = loadIndex(surface);
+            let eps = index.endpoints;
+            const category = params?.category;
+            const resource = params?.resource;
+            const method = params?.method?.toUpperCase();
+            const search = params?.search?.toLowerCase();
+            if (category)
+                eps = eps.filter((e) => e.category.toLowerCase() === category.toLowerCase());
+            if (resource)
+                eps = eps.filter((e) => e.resource.toLowerCase() === resource.toLowerCase());
+            if (method)
+                eps = eps.filter((e) => e.method === method);
+            if (params?.reads_only)
+                eps = eps.filter((e) => !e.writeOperation);
+            if (params?.writes_only)
+                eps = eps.filter((e) => e.writeOperation);
+            if (search) {
+                eps = eps.filter((e) => e.operationId.toLowerCase().includes(search) ||
+                    e.path.toLowerCase().includes(search) ||
+                    e.name.toLowerCase().includes(search) ||
+                    e.description.toLowerCase().includes(search));
+            }
+            const categories = [...new Set(index.endpoints.map((e) => e.category))].sort();
+            const limit = params?.limit ?? 200;
+            const matched = eps.length;
+            const truncated = matched > limit;
+            const shown = eps.slice(0, limit);
+            const payload = {
+                surface,
+                product,
+                matched,
+                shown: shown.length,
+                truncated,
+                totalEndpoints: index.endpointCount,
+                readCount: index.readCount,
+                writeCount: index.writeCount,
+                categories,
+                ...(truncated
+                    ? { note: `Showing ${shown.length} of ${matched}. Narrow with category/resource/method/search or raise limit.` }
+                    : {}),
+                endpoints: shown.map((e) => ({
+                    operation_id: e.operationId,
+                    method: e.method,
+                    path: e.path,
+                    name: e.name,
+                    category: e.category,
+                    resource: e.resource,
+                    description: e.description,
+                    writeOperation: e.writeOperation,
+                    ...(e.destructive ? { destructive: true } : {}),
+                })),
+            };
+            return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+        },
+    };
+}

package/dist/types/tool-definition.js

@@ -0,0 +1 @@
+export {};

package/dist/types/tool-response.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@nightsquawktech/proxmox-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Proxmox VE and Proxmox Datacenter Manager — every API endpoint behind catalog-backed list/describe/call tools, reads live, writes ENV-gated.",
+  "license": "AGPL-3.0-only",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "COMMERCIAL.md"
+  ],
+  "scripts": {
+    "build": "tsc && shx rm -rf dist/catalog-pve dist/catalog-pdm && shx cp -r src/catalog-pve dist/catalog-pve && shx cp -r src/catalog-pdm dist/catalog-pdm && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "extract": "node scripts/extract.mjs pve && node scripts/extract.mjs pdm",
+    "assemble": "node scripts/assemble-catalog.mjs pve && node scripts/assemble-catalog.mjs pdm",
+    "regen": "npm run extract && npm run assemble"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "@nightsquawktech/mcp-core": "^0.1.0",
+    "undici": "^6.21.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2"
+  },
+  "author": "Kevin Reyes (NightSquawk Tech) <hello@nightsquawk.tech>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NightSquawk/proxmox-mcp-server.git"
+  },
+  "homepage": "https://github.com/NightSquawk/proxmox-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/NightSquawk/proxmox-mcp-server/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}