@mguttmann/hetzner-cloud-mcp 0.1.0

package/dist/tools/wrappers/server_metrics.js

@@ -0,0 +1,55 @@
+import { asToolError } from "../_error.js";
+const VALID_TYPES = ["cpu", "disk", "network"];
+export function makeServerMetricsTool(deps) {
+    const now = deps.nowMs ?? (() => Date.now());
+    return {
+        name: "hcloud_get_server_metrics",
+        description: "Fetch a server's metrics (cpu / disk / network). Accept id OR name. Defaults to the last hour with step=60s. Hand-tuned wrapper.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", minimum: 1 },
+                name: { type: "string", minLength: 1 },
+                type: { type: "string", enum: [...VALID_TYPES] },
+                start: { type: "string", description: "ISO-8601 timestamp; default: now - 1 hour" },
+                end: { type: "string", description: "ISO-8601 timestamp; default: now" },
+                step: { type: "integer", minimum: 1, default: 60 },
+            },
+            required: ["type"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+        handler: async (input) => {
+            const type = input.type;
+            if (!VALID_TYPES.includes(type)) {
+                return { content: [{ type: "text", text: `Invalid type="${type}". Use one of: ${VALID_TYPES.join(", ")}.` }], isError: true };
+            }
+            let id = typeof input.id === "number" ? input.id : undefined;
+            if (id === undefined) {
+                if (typeof input.name !== "string") {
+                    return { content: [{ type: "text", text: "Provide either `id` or `name`." }], isError: true };
+                }
+                const lookup = await deps.client.request("GET", "/servers", { query: { name: input.name } });
+                const lookupErr = asToolError(lookup);
+                if (lookupErr)
+                    return lookupErr;
+                const match = lookup.body?.servers?.[0];
+                if (!match) {
+                    return { content: [{ type: "text", text: `Server with name="${input.name}" not found.` }], isError: true };
+                }
+                id = match.id;
+            }
+            const end = typeof input.end === "string" ? input.end : new Date(now()).toISOString();
+            const start = typeof input.start === "string"
+                ? input.start
+                : new Date(now() - 60 * 60 * 1000).toISOString();
+            const step = typeof input.step === "number" ? input.step : 60;
+            const res = await deps.client.request("GET", `/servers/${id}/metrics`, { query: { type, start, end, step } });
+            const errResult = asToolError(res);
+            if (errResult)
+                return errResult;
+            return { content: [{ type: "text", text: JSON.stringify(res.body ?? {}, null, 2) }] };
+        },
+    };
+}
+//# sourceMappingURL=server_metrics.js.map

package/dist/tools/wrappers/server_metrics.js.map

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

package/dist/tools/wrappers/server_power.js

@@ -0,0 +1,32 @@
+import { runServerAction } from "./_server_action.js";
+const VALID_OPS = ["poweron", "poweroff", "reboot", "shutdown", "reset"];
+export function makeServerPowerTool(deps) {
+    return {
+        name: "hcloud_server_power",
+        description: "Run a power operation on a server (poweron / poweroff / reboot / shutdown / reset). Hand-tuned wrapper that polls the resulting action by default.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", minimum: 1 },
+                op: { type: "string", enum: [...VALID_OPS] },
+                wait: { type: "boolean", default: true },
+            },
+            required: ["id", "op"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const id = input.id;
+            const op = input.op;
+            if (!VALID_OPS.includes(op)) {
+                return {
+                    content: [{ type: "text", text: `Invalid op="${op}". Must be one of: ${VALID_OPS.join(", ")}.` }],
+                    isError: true,
+                };
+            }
+            const wait = input.wait !== false;
+            return runServerAction(deps, id, op, undefined, wait);
+        },
+    };
+}
+//# sourceMappingURL=server_power.js.map

package/dist/tools/wrappers/server_power.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_power.js","sourceRoot":"","sources":["../../../src/tools/wrappers/server_power.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAyB,MAAM,qBAAqB,CAAC;AAE7E,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAU,CAAC;AAGlF,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,oJAAoJ;QACtJ,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE;gBACnC,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE;gBAC5C,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;aACzC;YACD,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;YACtB,oBAAoB,EAAE,KAAK;SAC5B;QACD,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;QAChF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAuB,EAAE;YAC5C,MAAM,EAAE,GAAG,KAAK,CAAC,EAAY,CAAC;YAC9B,MAAM,EAAE,GAAG,KAAK,CAAC,EAAQ,CAAC;YAC1B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC5B,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,sBAAsB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;oBACjG,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC;YAClC,OAAO,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;QACxD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/wrappers/server_rebuild.js

@@ -0,0 +1,34 @@
+import { runServerAction } from "./_server_action.js";
+export function makeServerRebuildTool(deps) {
+    return {
+        name: "hcloud_server_rebuild",
+        description: "Rebuild a server from an image. Accept image_id (integer) OR image_name (string). Hand-tuned wrapper; polls the resulting action by default.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", minimum: 1 },
+                image_id: { type: "integer", minimum: 1 },
+                image_name: { type: "string", minLength: 1 },
+                wait: { type: "boolean", default: true },
+            },
+            required: ["id"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const id = input.id;
+            const hasId = typeof input.image_id === "number";
+            const hasName = typeof input.image_name === "string";
+            if (hasId === hasName) {
+                return {
+                    content: [{ type: "text", text: "Provide exactly one of `image_id` or `image_name`." }],
+                    isError: true,
+                };
+            }
+            const image = hasId ? input.image_id : input.image_name;
+            const wait = input.wait !== false;
+            return runServerAction(deps, id, "rebuild", { image }, wait);
+        },
+    };
+}
+//# sourceMappingURL=server_rebuild.js.map

package/dist/tools/wrappers/server_rebuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_rebuild.js","sourceRoot":"","sources":["../../../src/tools/wrappers/server_rebuild.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAyB,MAAM,qBAAqB,CAAC;AAE7E,MAAM,UAAU,qBAAqB,CAAC,IAAsB;IAC1D,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EACT,8IAA8I;QAChJ,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE;gBACnC,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE;gBACzC,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;gBAC5C,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;aACzC;YACD,QAAQ,EAAE,CAAC,IAAI,CAAC;YAChB,oBAAoB,EAAE,KAAK;SAC5B;QACD,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;QAChF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAuB,EAAE;YAC5C,MAAM,EAAE,GAAG,KAAK,CAAC,EAAY,CAAC;YAC9B,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC;YACjD,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,CAAC;YACrD,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;gBACtB,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oDAAoD,EAAE,CAAC;oBACvF,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,KAAK,CAAC,QAAmB,CAAC,CAAC,CAAE,KAAK,CAAC,UAAqB,CAAC;YAChF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC;YAClC,OAAO,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAC/D,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/wrappers/server_rescue.js

@@ -0,0 +1,34 @@
+import { runServerAction } from "./_server_action.js";
+export function makeServerRescueTool(deps) {
+    return {
+        name: "hcloud_server_rescue",
+        description: "Toggle Hetzner rescue mode on a server. When enabling, defaults type to 'linux64' and accepts ssh_keys (array of SSH-key ids). Hand-tuned wrapper.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", minimum: 1 },
+                enable: { type: "boolean", description: "true to enter rescue, false to leave." },
+                type: { type: "string", enum: ["linux64", "linux32", "freebsd64"], default: "linux64" },
+                ssh_keys: { type: "array", items: { type: "integer" } },
+                wait: { type: "boolean", default: true },
+            },
+            required: ["id", "enable"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        handler: async (input) => {
+            const id = input.id;
+            const wait = input.wait !== false;
+            if (input.enable === true) {
+                const body = {
+                    type: typeof input.type === "string" ? input.type : "linux64",
+                };
+                if (Array.isArray(input.ssh_keys))
+                    body.ssh_keys = input.ssh_keys;
+                return runServerAction(deps, id, "enable_rescue", body, wait);
+            }
+            return runServerAction(deps, id, "disable_rescue", undefined, wait);
+        },
+    };
+}
+//# sourceMappingURL=server_rescue.js.map

package/dist/tools/wrappers/server_rescue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_rescue.js","sourceRoot":"","sources":["../../../src/tools/wrappers/server_rescue.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAyB,MAAM,qBAAqB,CAAC;AAE7E,MAAM,UAAU,oBAAoB,CAAC,IAAsB;IACzD,OAAO;QACL,IAAI,EAAE,sBAAsB;QAC5B,WAAW,EACT,oJAAoJ;QACtJ,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE;gBACnC,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,uCAAuC,EAAE;gBACjF,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE;gBACvF,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;gBACvD,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;aACzC;YACD,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC;YAC1B,oBAAoB,EAAE,KAAK;SAC5B;QACD,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE;QACjF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAuB,EAAE;YAC5C,MAAM,EAAE,GAAG,KAAK,CAAC,EAAY,CAAC;YAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC;YAClC,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC1B,MAAM,IAAI,GAA4B;oBACpC,IAAI,EAAE,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;iBAC9D,CAAC;gBACF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;oBAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;gBAClE,OAAO,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAChE,CAAC;YACD,OAAO,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,gBAAgB,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;QACtE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/wrappers/server_snapshot.js

@@ -0,0 +1,33 @@
+import { runServerAction } from "./_server_action.js";
+export function makeServerSnapshotTool(deps) {
+    return {
+        name: "hcloud_server_snapshot",
+        description: "Create an image (snapshot or backup) of a server. Default type is 'snapshot'. Hand-tuned wrapper that polls the resulting action.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", minimum: 1 },
+                type: { type: "string", enum: ["snapshot", "backup"], default: "snapshot" },
+                description: { type: "string" },
+                labels: { type: "object", additionalProperties: { type: "string" } },
+                wait: { type: "boolean", default: true },
+            },
+            required: ["id"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        handler: async (input) => {
+            const id = input.id;
+            const body = {
+                type: typeof input.type === "string" ? input.type : "snapshot",
+            };
+            if (typeof input.description === "string")
+                body.description = input.description;
+            if (input.labels && typeof input.labels === "object")
+                body.labels = input.labels;
+            const wait = input.wait !== false;
+            return runServerAction(deps, id, "create_image", body, wait);
+        },
+    };
+}
+//# sourceMappingURL=server_snapshot.js.map

package/dist/tools/wrappers/server_snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_snapshot.js","sourceRoot":"","sources":["../../../src/tools/wrappers/server_snapshot.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAyB,MAAM,qBAAqB,CAAC;AAE7E,MAAM,UAAU,sBAAsB,CAAC,IAAsB;IAC3D,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,mIAAmI;QACrI,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE;gBACnC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE;gBAC3E,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC/B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;gBACpE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;aACzC;YACD,QAAQ,EAAE,CAAC,IAAI,CAAC;YAChB,oBAAoB,EAAE,KAAK;SAC5B;QACD,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE;QACjF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAuB,EAAE;YAC5C,MAAM,EAAE,GAAG,KAAK,CAAC,EAAY,CAAC;YAC9B,MAAM,IAAI,GAA4B;gBACpC,IAAI,EAAE,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU;aAC/D,CAAC;YACF,IAAI,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;gBAAE,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;YAChF,IAAI,KAAK,CAAC,MAAM,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;gBAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YACjF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC;YAClC,OAAO,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/D,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@mguttmann/hetzner-cloud-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP server (stdio) covering the entire Hetzner Cloud API as 201 typed tools — read and write.",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "hetzner-cloud-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "specs/cloud.spec.json",
+    "scripts/refresh-spec.ts",
+    "scripts/generate.ts",
+    "scripts/refresh-snapshot.ts",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build && npm test",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:live": "RUN_LIVE_TESTS=1 vitest run tests/live-smoke.test.ts",
+    "generate": "tsx scripts/generate.ts",
+    "refresh-spec": "tsx scripts/refresh-spec.ts",
+    "refresh-snapshot": "tsx scripts/refresh-snapshot.ts",
+    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "hetzner",
+    "hetzner-cloud",
+    "claude",
+    "ai-tools",
+    "stdio",
+    "openapi"
+  ],
+  "author": "Manuel Guttmann",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mguttmann/the-real-hetzner-mcp.git"
+  },
+  "homepage": "https://github.com/mguttmann/the-real-hetzner-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/mguttmann/the-real-hetzner-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.4.0",
+    "pino": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/scripts/generate.ts

@@ -0,0 +1,245 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import type { OperationDef, ParameterDef } from "../src/types.js";
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const;
+type Method = (typeof HTTP_METHODS)[number];
+
+const WRAPPER_COLLISIONS = new Set([
+  "hcloud_list_servers",
+  "hcloud_get_server",
+  "hcloud_get_server_metrics",
+]);
+
+const DANGEROUS_ACTIONS = new Set([
+  "poweroff",
+  "reset",
+  "rebuild",
+  "request_console",
+]);
+
+const SINGLETON_PATHS = new Set(["pricing"]);
+
+type SpecParam = {
+  name: string;
+  in: "path" | "query" | "header";
+  required?: boolean;
+  schema?: Record<string, unknown>;
+  description?: string;
+};
+
+type SpecOperation = {
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  parameters?: SpecParam[];
+  requestBody?: {
+    required?: boolean;
+    content?: { "application/json"?: { schema?: Record<string, unknown> } };
+  };
+  responses?: Record<
+    string,
+    {
+      content?: { "application/json"?: { schema?: Record<string, unknown> } };
+    }
+  >;
+  tags?: string[];
+};
+
+type Spec = {
+  paths: Record<string, Partial<Record<Method, SpecOperation>>>;
+};
+
+export type { OperationDef, ParameterDef };
+
+function singularize(plural: string): string {
+  if (plural.endsWith("ies")) return plural.slice(0, -3) + "y";
+  if (plural.endsWith("s") && !plural.endsWith("ss")) return plural.slice(0, -1);
+  return plural;
+}
+
+function isPathParam(seg: string): boolean {
+  return seg.startsWith("{") && seg.endsWith("}");
+}
+
+function resourceChain(segs: string[], stopBefore?: number): string[] {
+  // Singularized non-{param} segments, up to (but not including) `stopBefore`.
+  const end = stopBefore ?? segs.length;
+  const chain: string[] = [];
+  for (let i = 0; i < end; i++) {
+    const s = segs[i]!;
+    if (!isPathParam(s)) chain.push(singularize(s));
+  }
+  return chain;
+}
+
+function deriveToolName(method: Method, path: string): string {
+  const segs = path.split("/").filter(Boolean);
+
+  if (segs.length === 1) {
+    const r = segs[0]!;
+    if (SINGLETON_PATHS.has(r)) return `hcloud_get_${r}`;
+    if (method === "get") return `hcloud_list_${r}`;
+    if (method === "post") return `hcloud_create_${singularize(r)}`;
+  }
+
+  if (segs.length === 2 && isPathParam(segs[1]!)) {
+    const r = singularize(segs[0]!);
+    if (method === "get") return `hcloud_get_${r}`;
+    if (method === "put" || method === "patch") return `hcloud_update_${r}`;
+    if (method === "delete") return `hcloud_delete_${r}`;
+  }
+
+  if (segs.length === 3 && isPathParam(segs[1]!)) {
+    const r = singularize(segs[0]!);
+    const sub = segs[2]!;
+    if (sub === "actions" && method === "get") return `hcloud_list_${r}_actions`;
+    if (sub === "metrics" && method === "get") return `hcloud_get_${r}_metrics`;
+    return `hcloud_${method}_${r}_${sub}`;
+  }
+
+  if (
+    segs.length === 4 &&
+    isPathParam(segs[1]!) &&
+    segs[2] === "actions"
+  ) {
+    const r = singularize(segs[0]!);
+    const sub = segs[3]!;
+    if (isPathParam(sub)) return `hcloud_get_${r}_action`;
+    return `hcloud_${r}_${sub}_action`;
+  }
+
+  // Deep paths (5+ segments). Hetzner pattern:
+  // <resA>/{idA}/<resB>/{idB}/<resC>[/actions/<name>]
+  // Build a name from the singularized resource chain, with a special case for the
+  // trailing /actions/<name> sub-path.
+  if (segs.length >= 5) {
+    const last = segs[segs.length - 1]!;
+    const beforeLast = segs[segs.length - 2]!;
+    // Trailing /actions/<action_name>: include the full chain up to "actions"
+    // and emit hcloud_<chain>_<action>_action.
+    if (beforeLast === "actions" && !isPathParam(last)) {
+      const chain = resourceChain(segs, segs.length - 2);
+      return `hcloud_${chain.join("_")}_${last}_action`;
+    }
+    // Trailing /actions/{id}: single action GET.
+    if (beforeLast === "actions" && isPathParam(last) && method === "get") {
+      const chain = resourceChain(segs, segs.length - 2);
+      return `hcloud_get_${chain.join("_")}_action`;
+    }
+    // Otherwise, derive from the full resource chain (no action segment).
+    const chain = resourceChain(segs);
+    if (chain.length > 0) {
+      if (method === "get") return `hcloud_get_${chain.join("_")}`;
+      if (method === "delete") return `hcloud_delete_${chain.join("_")}`;
+      if (method === "put" || method === "patch") return `hcloud_update_${chain.join("_")}`;
+      if (method === "post") return `hcloud_create_${chain.join("_")}`;
+    }
+  }
+
+  // Fallback: snake the whole path
+  const slug = segs
+    .map((s) => (isPathParam(s) ? s.slice(1, -1) : s))
+    .join("_");
+  return `hcloud_${method}_${slug}`;
+}
+
+function applyCollisionSuffix(toolName: string): string {
+  return WRAPPER_COLLISIONS.has(toolName) ? `${toolName}_raw` : toolName;
+}
+
+function detectReturnsAction(op: SpecOperation): boolean {
+  if (!op.responses) return false;
+  for (const status of ["200", "201", "202"]) {
+    const schema = op.responses[status]?.content?.["application/json"]?.schema;
+    if (!schema) continue;
+    const props = (schema as { properties?: Record<string, unknown> }).properties;
+    if (props && "action" in props) return true;
+  }
+  return false;
+}
+
+function detectIsDestructive(
+  method: Method,
+  toolName: string,
+): boolean {
+  if (method === "delete") return true;
+  for (const action of DANGEROUS_ACTIONS) {
+    if (toolName.endsWith(`_${action}_action`)) return true;
+  }
+  return false;
+}
+
+export function buildOperations(spec: Spec): OperationDef[] {
+  const ops: OperationDef[] = [];
+  for (const [path, methods] of Object.entries(spec.paths ?? {})) {
+    for (const m of HTTP_METHODS) {
+      const op = methods?.[m];
+      if (!op) continue;
+      const baseName = deriveToolName(m, path);
+      const toolName = applyCollisionSuffix(baseName);
+      const parameters: ParameterDef[] = (op.parameters ?? []).map((p) => ({
+        name: p.name,
+        in: p.in,
+        required: !!p.required,
+        schema: p.schema ?? {},
+        ...(p.description ? { description: p.description } : {}),
+      }));
+      const requestBodySchema =
+        op.requestBody?.content?.["application/json"]?.schema;
+      const requestBodyRequired = !!op.requestBody?.required;
+      const okResponse = ["200", "201", "202", "204"]
+        .map((s) => op.responses?.[s]?.content?.["application/json"]?.schema)
+        .find(Boolean);
+      ops.push({
+        operationId: op.operationId ?? `${m}_${path}`.replace(/\W+/g, "_"),
+        toolName,
+        method: m.toUpperCase() as OperationDef["method"],
+        path,
+        summary: op.summary ?? "",
+        description: op.description ?? "",
+        tags: op.tags ?? [],
+        parameters,
+        ...(requestBodySchema ? { requestBodySchema } : {}),
+        ...(requestBodySchema ? { requestBodyRequired } : {}),
+        ...(okResponse ? { responseSchema: okResponse } : {}),
+        returnsAction: detectReturnsAction(op),
+        isDestructive: detectIsDestructive(m, toolName),
+      });
+    }
+  }
+  ops.sort((a, b) => a.toolName.localeCompare(b.toolName));
+  return ops;
+}
+
+function emitTypeScript(operations: OperationDef[]): string {
+  const header =
+    "// AUTO-GENERATED by scripts/generate.ts. Do not edit by hand.\n" +
+    "// Run `npm run generate` after refreshing specs/cloud.spec.json.\n\n" +
+    'import type { OperationDef } from "../../types.js";\n\n' +
+    "export const OPERATIONS: OperationDef[] = " +
+    JSON.stringify(operations, null, 2) +
+    " as const;\n";
+  return header;
+}
+
+async function main(): Promise<void> {
+  const specPath = resolve(process.cwd(), "specs/cloud.spec.json");
+  const outPath = resolve(process.cwd(), "src/tools/generated/operations.ts");
+  const spec = JSON.parse(await readFile(specPath, "utf8")) as Spec;
+  const operations = buildOperations(spec);
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, emitTypeScript(operations), "utf8");
+  process.stderr.write(
+    `Wrote ${outPath} with ${operations.length} operations.\n`,
+  );
+}
+
+const isDirectInvocation = process.argv[1]?.endsWith("generate.ts") ||
+  process.argv[1]?.endsWith("generate.js");
+if (isDirectInvocation) {
+  main().catch((err) => {
+    process.stderr.write(`generate failed: ${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+  });
+}

package/scripts/refresh-snapshot.ts

@@ -0,0 +1,33 @@
+import { writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { OPERATIONS } from "../src/tools/generated/operations.js";
+
+const SNAPSHOT_PATH = resolve(process.cwd(), "tests/snapshots/tool-registry.json");
+
+function hashSchema(obj: unknown): string {
+  return createHash("sha256").update(JSON.stringify(obj)).digest("hex").slice(0, 16);
+}
+
+async function main(): Promise<void> {
+  const snapshot = OPERATIONS.map((op) => ({
+    name: op.toolName,
+    schemaHash: hashSchema({
+      parameters: op.parameters,
+      requestBodySchema: op.requestBodySchema ?? null,
+      requestBodyRequired: op.requestBodyRequired ?? false,
+      returnsAction: op.returnsAction,
+      method: op.method,
+      path: op.path,
+    }),
+  }));
+  await writeFile(SNAPSHOT_PATH, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+  process.stderr.write(
+    `Wrote ${SNAPSHOT_PATH} with ${snapshot.length} entries.\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`refresh-snapshot failed: ${err instanceof Error ? err.message : err}\n`);
+  process.exit(1);
+});

package/scripts/refresh-spec.ts

@@ -0,0 +1,35 @@
+import { writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+const SPEC_URL = "https://docs.hetzner.cloud/cloud.spec.json";
+const OUTPUT = resolve(process.cwd(), "specs/cloud.spec.json");
+
+async function main(): Promise<void> {
+  process.stderr.write(`Fetching ${SPEC_URL}\n`);
+  const res = await fetch(SPEC_URL);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch spec: HTTP ${res.status}`);
+  }
+  const text = await res.text();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(`Spec is not valid JSON: ${(err as Error).message}`);
+  }
+  const formatted = JSON.stringify(parsed, null, 2) + "\n";
+
+  await mkdir(dirname(OUTPUT), { recursive: true });
+  await writeFile(OUTPUT, formatted, "utf8");
+
+  const sizeKb = (Buffer.byteLength(formatted) / 1024).toFixed(0);
+  const info = parsed as { info?: { version?: string; title?: string } };
+  process.stderr.write(
+    `Wrote ${OUTPUT} (${sizeKb} KB, title="${info.info?.title ?? "?"}", version="${info.info?.version ?? "?"}")\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`refresh-spec failed: ${err instanceof Error ? err.message : err}\n`);
+  process.exit(1);
+});