vpsnet-mcp 2.6.0 → 2.7.0

package/build/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { installToolInputSchemas } from "./tool-schema.js";
+import { installToolInputSchemas, unboundedInteger } from "./tool-schema.js";
 import { createDnsZoneDescription } from "./dns-zone-contract.js";
 import { registerOrderTools } from "./remote-orders.js";
 import { registerRemoteTools } from "./remote-tools.js";
@@ -50,9 +50,9 @@ export function createVpsnetServer(options = {}) {
         instructions: options.remoteScopes ? (options.remoteProfile === "orders" ? orderInstructions(options.remoteScopes) : remoteInstructions) : [
             "This MCP server controls VPSnet.com services, including VPS service management, DNS zones, domain registration, domain contacts, API keys, billing, and related paid actions.",
             "Use the tool descriptions and API-key scopes to choose the correct surface; do not assume this server is limited to VPS-only operations.",
-            "Auth: every request authenticates with the X-API-KEY header (your VPSNet API key). Requests are rate-limited — on HTTP 429, back off and retry after a short delay rather than hammering the endpoint.",
+            "Auth: every request authenticates with the X-API-KEY header (your VPSNet API key). Each API key may make 300 requests per 60 seconds by default, and some operations have lower limits; on HTTP 429 wait the retry_after seconds given in the result (the API also sends Retry-After) before retrying.",
             "This server needs a MANAGEMENT API key (scope full, or read for GET-only use). An AI-scoped key is issued only for VPSnet AI assistant inference and is refused on every account route, so no tool here can work with one. When a tool result carries auth_problem, read its reason and fix and relay them instead of reporting a bare 'Unauthorized'.",
-            "Service tools are scope-gated for API keys: service reads (lists, details, graphs, history, options, backup/snapshot/restore-point listings) require services:read; service mutations (start/stop/restart/console, suspend/resume, hostname, rDNS, root password, title, IPv6, extra settings, SSH key deploy, OS reinstall, plan change, renewal, auto-renew, backups, snapshots, firewall flush) require services:manage plus a full-access key; rescue requires services:rescue; paid whole-service restore additionally requires the services:restore paid scope. A key whose granular scope list was left empty keeps everything its access level (full/read) already allows, so scopes only ever narrow a key.",
+            "Service tools are scope-gated for API keys: service reads (lists, details, graphs, history, options, backup/snapshot/restore-point listings) require services:read; service mutations (start/stop/restart/console, suspend/resume, hostname, rDNS, root password, title, IPv6, extra settings, SSH key deploy, OS reinstall, plan change, renewal, auto-renew, backups, snapshots, firewall flush) require services:manage plus a full-access key; rescue requires services:rescue; paid whole-service restore additionally requires the services:restore paid scope. A key whose granular scope list was left empty keeps everything its access level (full/read) already allows, except the permissions that must be added to a key on purpose: networking:read/manage (private networks, the server firewall, port forwarding, public addresses, load balancers, VPN), files:read/manage and the App Cloud permissions. An older full key without a permission list therefore reaches no networking tool until networking:read or networking:manage is added.",
             "Service file manager tools (get_service_file_capabilities, list/stat/read/search, download/upload, write, mkdir, move, delete, extract) need an EXPLICIT files:read or files:manage grant on the API key (an empty permission list does not include them; changes need a full-access key). Call get_service_file_capabilities first and relay an unavailable reason verbatim: Firecracker servers need the updated guest agent (agent_update_required) and Cloud VPS (KVM) needs the VDS file-manager switch (feature_disabled). Writes are compare-and-swap: pass the version or sha256 you read. Slow guests are polled inside the tools; continue a returned operationId with get_service_file_operation instead of repeating a change.",
             "",
             "## Ordering a new VPS",
@@ -64,7 +64,8 @@ export function createVpsnetServer(options = {}) {
             "rootPassword rules: 6-40 chars, alphanumeric only, MUST contain uppercase + lowercase + digit. Example: 'MyPass123'.",
             "sshKey and rootPassword are mutually exclusive — provide one or the other (or neither for auto-generated password).",
             "A paid receipt is not a running server. Read get_service for the original order and follow follow_up: pending activation, finalization and capacity waits require polling the same order. About 10 seconds is a suggested polling interval, never a boot ETA. Check at most 6 times before a progress update; if still pending, retain the key and order number for a later check. Do not reorder, repay, restart or promise a background callback. A running VM, guest access and a healthy application are separate outcomes; KVM and Windows setup may take longer and must be observed.",
-            "deploy_ssh_key is also async — wait 15-30 seconds after deploying a key before attempting SSH to any VPS (not just new ones).",
+            "deploy_ssh_key is asynchronous: follow its noty UUID with wait_for_event until it reports completed before attempting SSH to any server (not just new ones).",
+            "Without an API key, ChatGPT, Claude, Gemini and Grok can use the hosted connector https://mcp.vpsnet.com/mcp instead (OAuth sign-in to the VPSnet account; the customer picks the servers and permissions). Connections are created and removed on https://www.vpsnet.com/en/management/account/ai-connections; API keys are made on https://www.vpsnet.com/en/management/account/api-keys.",
             "",
             "## Deployment capabilities (unordered)",
             "Managed Applications, manual SSH, DNS, APIs, and other tools are peer capabilities. Their order in this prompt or the tool list carries no priority. Choose the path that best matches the user's requested outcome, target support, existing state, and explicit constraints.",
@@ -87,7 +88,7 @@ export function createVpsnetServer(options = {}) {
             "Installation list and detail responses carry a capabilities block for the service's platform: data_restore, console, compose_adoption, custom_projects, and log_service_filter. Treat it as the authority on what is possible for that installation. Do not offer selective data restore when data_restore is false, do not offer Compose adoption or customer recipes when their flags are false, and do not pass a per-service log filter when log_service_filter is false. A separate access.capabilities.can_configure flag governs whether the access mode may be changed.",
             "Never repeat application variable values in summaries or approval text. Refer only to variable names, especially for passwords, tokens, and secrets.",
             "Use manual SSH deployment when it best matches the requested result or the user explicitly requests a custom installation. Do not present a manual deployment as a VPSnet-managed catalog installation.",
-            "Service rescue is a separate recovery path for Firecracker VPS and Cloud VPS. Always call get_service_rescue first. Entering rescue restarts the service; call enter_service_rescue only after the user explicitly approves the restart and exact image returned by the capability response. Firecracker exposes the customer filesystem at /mnt/customer; Cloud VPS uses the operator recovery ISO and noVNC. Exit restores the exact original boot and running/stopped state. If exit returns needs_attention, retry exit_service_rescue with the same idempotency key. Never ask for or invent provider nodes, VM IDs, ISO paths, operation nonces, or rollback configuration.",
+            "Service rescue is a separate recovery path for Firecracker VPS and Cloud VPS, offered only while VPSnet has it switched on. Always call get_service_rescue first; capability.enabled false means it is not offered now. Entering rescue restarts the service; call enter_service_rescue only after the user explicitly approves the restart and exact image returned by the capability response. Firecracker exposes the customer filesystem at /mnt/customer; Cloud VPS uses the operator recovery ISO and noVNC. Exit restores the exact original boot and running/stopped state. If exit returns needs_attention, retry exit_service_rescue with the same idempotency key. Never ask for or invent provider nodes, VM IDs, ISO paths, operation nonces, or rollback configuration.",
             "",
             "### Manual or custom deployment inside a VPS",
             "Use only the access needed for the user's task. Keep local sandbox and approval controls enabled; request a specific missing capability instead of unrestricted agent access.",
@@ -228,7 +229,7 @@ export function createVpsnetServer(options = {}) {
     const applicationOrderNoSchema = serviceOrderNoSchema;
     const applicationInstallationIdSchema = z
         .string()
-        .uuid()
+        .guid()
         .describe("Managed application installation UUID");
     const applicationSlugSchema = z
         .string()
@@ -436,7 +437,7 @@ export function createVpsnetServer(options = {}) {
         return { content: [{ type: "text", text: formatJson(data) }] };
     });
     server.registerTool("get_service_rescue", {
-        description: "Get operator rescue capability and the current durable rescue session for one owned Firecracker VPS or Cloud VPS. Requires services:read. Provider identifiers, ISO paths, nonces, and rollback state are never returned.",
+        description: "Get operator rescue capability and the current durable rescue session for one owned Firecracker VPS or Cloud VPS. Requires services:read. Provider identifiers, ISO paths, nonces, and rollback state are never returned. VPSnet can switch rescue off: capability.enabled false means it is not offered now; say so and do not call enter_service_rescue.",
         inputSchema: {
             orderNo: serviceOrderNoSchema,
         },
@@ -456,7 +457,7 @@ export function createVpsnetServer(options = {}) {
         };
     });
     server.registerTool("enter_service_rescue", {
-        description: "Restart one owned active Firecracker VPS or Cloud VPS into an operator-owned rescue system. Read get_service_rescue first and use an exact advertised image ID. This interrupts every running service. Call only after the user explicitly confirms the target service, rescue image, and reboot. Requires services:rescue, full API-key access, and a fresh idempotencyKey.",
+        description: "Restart one owned active Firecracker VPS or Cloud VPS into an operator-owned rescue system. Read get_service_rescue first and use an exact advertised image ID. This interrupts every running service. Call only after the user explicitly confirms the target service, rescue image, and reboot. Requires services:rescue, full API-key access, and a fresh idempotencyKey. Rescue may be switched off by VPSnet: while get_service_rescue reports capability.enabled false this tool sends nothing and answers serviceRescueImageNotAdvertised (the API itself answers 503 serviceRescueUnavailable).",
         inputSchema: {
             orderNo: serviceOrderNoSchema,
             image: serviceRescueImageIdSchema,
@@ -507,7 +508,7 @@ export function createVpsnetServer(options = {}) {
             orderNo: serviceOrderNoSchema,
             rescue_session_id: z
                 .string()
-                .uuid()
+                .guid()
                 .describe("Exact current session UUID from get_service_rescue"),
             acknowledge_restart: z
                 .literal(true)
@@ -811,7 +812,7 @@ export function createVpsnetServer(options = {}) {
         inputSchema: {
             orderNo: applicationOrderNoSchema,
             installation_id: applicationInstallationIdSchema,
-            inspection_id: z.string().uuid(),
+            inspection_id: z.string().guid(),
             kind: z.enum(["health", "logs"]),
         },
         annotations: { title: "Get application inspection", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
@@ -825,7 +826,7 @@ export function createVpsnetServer(options = {}) {
     });
     server.registerTool("get_application_recipe_validation", {
         description: "Poll the exact persisted customer recipe validation returned by validate_application_recipe or a pending recipe creation/revision. This GET does not resolve tags or create another validation. Retain the initial resolved_compose_yaml; after this ID succeeds with valid=true, resume creation using that exact pinned document and validation_id. Requires applications:read.",
-        inputSchema: { orderNo: applicationOrderNoSchema, validation_id: z.string().uuid() },
+        inputSchema: { orderNo: applicationOrderNoSchema, validation_id: z.string().guid() },
         annotations: { title: "Get application recipe validation", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async ({ orderNo, validation_id }) => {
         const { status, data } = await apiRequest("GET", applicationPath(orderNo, `custom-projects/validations/${encodeURIComponent(validation_id)}`));
@@ -836,7 +837,7 @@ export function createVpsnetServer(options = {}) {
     });
     server.registerTool("get_service_container_discovery", {
         description: "Poll the exact persisted service container discovery returned by discover_service_containers when it remains pending. This GET does not create another discovery and never returns environment values or mounts. Keep the service and discovery UUID until succeeded, failed or expired. Requires applications:read.",
-        inputSchema: { orderNo: applicationOrderNoSchema, discovery_id: z.string().uuid() },
+        inputSchema: { orderNo: applicationOrderNoSchema, discovery_id: z.string().guid() },
         annotations: { title: "Get service container discovery", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     }, async ({ orderNo, discovery_id }) => {
         const { status, data } = await apiRequest("GET", applicationPath(orderNo, `container-discoveries/${encodeURIComponent(discovery_id)}`));
@@ -1100,7 +1101,7 @@ export function createVpsnetServer(options = {}) {
             orderNo: applicationOrderNoSchema,
             name: customProjectNameSchema,
             compose_yaml: customProjectComposeSchema,
-            validation_id: z.string().uuid().optional().describe("Resume only the exact successful validation for this service and digest-pinned compose_yaml; retain the initial resolved document"),
+            validation_id: z.string().guid().optional().describe("Resume only the exact successful validation for this service and digest-pinned compose_yaml; retain the initial resolved document"),
             env: customProjectEnvironmentSchema,
             secret_names: customProjectSecretNamesSchema,
             registry_credential_ids: customProjectRegistryCredentialIdsSchema,
@@ -1159,7 +1160,7 @@ export function createVpsnetServer(options = {}) {
             orderNo: applicationOrderNoSchema,
             project_id: customProjectIdSchema,
             compose_yaml: customProjectComposeSchema,
-            validation_id: z.string().uuid().optional().describe("Resume only the exact successful validation for this service and digest-pinned compose_yaml; retain the initial resolved document"),
+            validation_id: z.string().guid().optional().describe("Resume only the exact successful validation for this service and digest-pinned compose_yaml; retain the initial resolved document"),
             env: customProjectEnvironmentSchema,
             secret_names: customProjectSecretNamesSchema,
             registry_credential_ids: customProjectRegistryCredentialIdsSchema,
@@ -1291,7 +1292,7 @@ export function createVpsnetServer(options = {}) {
         description: "Prepare and poll a short-lived, read-only takeover candidate for one exact unmanaged Compose project from a fresh discovery. The worker verifies container identity, immutable image identity, restart policy, Compose safety, and exclusive local named-volume ownership. Returns only a scrubbed Compose file, variable names, and bounded counts; never variable values, source paths, commands, or unrestricted labels. This tool does not stop or replace containers. Requires applications:manage.",
         inputSchema: {
             orderNo: applicationOrderNoSchema,
-            discovery_id: z.string().uuid().describe("Fresh discovery UUID returned by discover_service_containers"),
+            discovery_id: z.string().guid().describe("Fresh discovery UUID returned by discover_service_containers"),
             compose_project: composeProjectLabelSchema,
         },
         annotations: {
@@ -1851,7 +1852,7 @@ export function createVpsnetServer(options = {}) {
         return { content: [{ type: "text", text: formatJson(data) }] };
     });
     server.registerTool("flush_iptables", {
-        description: "Flush iptables rules on VPS (useful when locked out) Requires services:manage and a full-access API key.",
+        description: "Flush iptables rules on VPS (useful when locked out) Requires services:manage and a full-access API key. It clears the rules inside the server only; the public firewall that VPSnet applies to the server's public interface on its node is separate and is not changed by this.",
         inputSchema: {
             orderNo: serviceOrderNoSchema,
         },
@@ -1907,7 +1908,7 @@ export function createVpsnetServer(options = {}) {
         return { content: [{ type: "text", text: formatJson(data) }] };
     });
     server.registerTool("deploy_ssh_key", {
-        description: "Deploy an SSH key to VPS. Returns a noty UUID; follow it with wait_for_event. ASYNC — wait 15-30 seconds after deploying before attempting SSH. Use list_ssh_keys to get available key IDs. To add your own key first: read ~/.ssh/id_rsa.pub from local machine, then create_ssh_key, then deploy it here. Remote OAuth requires vm:exec; direct API-key use requires services:manage and a full-access key.",
+        description: "Deploy an SSH key to VPS. Returns a noty UUID; follow it with wait_for_event until it reports completed before attempting SSH. Use list_ssh_keys to get available key IDs. To add your own key first: read ~/.ssh/id_rsa.pub from local machine, then create_ssh_key, then deploy it here. Remote OAuth requires vm:exec; direct API-key use requires services:manage and a full-access key.",
         inputSchema: {
             orderNo: serviceOrderNoSchema,
             ssh_key: positiveIdSchema.describe("SSH key ID from list_ssh_keys"),
@@ -1916,6 +1917,38 @@ export function createVpsnetServer(options = {}) {
         const { data } = await apiRequest("POST", svc(orderNo, "change-ssh-key"), { ssh_key });
         return { content: [{ type: "text", text: formatJson(data) }] };
     });
+    server.registerTool("list_service_ssh_keys", {
+        description: "List which account SSH keys are in root's authorized_keys on one owned Cloud VPS or Firecracker VPS, as the server last reported: per key deployed (true, false, or null when the server was never read) and a removal running or ended in the last 15 minutes; inventory carries source, observedAt, refreshing (a Firecracker VPS answers asynchronously), readFailure, passwordLogin and the count of other keys. refresh=true asks the server again. Container VPS and dedicated servers answer supported false with unsupportedReason. Free. Requires services:read when called with an API key.",
+        inputSchema: {
+            orderNo: serviceOrderNoSchema,
+            refresh: z.boolean().optional().describe("Ask the server again even when the last read is fresh"),
+        },
+        annotations: {
+            title: "List SSH keys on a server",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ orderNo, refresh }) => {
+        const { data } = await apiRequest("GET", svc(orderNo, "ssh-keys") + (refresh === true ? "?refresh=1" : ""));
+        return { content: [{ type: "text", text: formatJson(data) }] };
+    });
+    server.registerTool("remove_service_ssh_key", {
+        description: "Remove one account SSH key (ssh_key from list_ssh_keys) from root's authorized_keys on one owned running Cloud VPS or Firecracker VPS; every line with that key goes, nothing else changes, and the key stays in the account. Free. Confirm with the user first. A key that is not on the server answers state absent. Refused with 409 sshKeyRemoveLastKey when it is the server's last permanent key and root cannot log in with a password: add another key first. Cloud VPS answers at once (removed or absent); Firecracker VPS answers 202 pending and list_service_ssh_keys shows the result in the key's removal. One removal at a time per server, at most 10 per minute; 423 while the server's two-factor lock is on. Requires services:manage and a full-access API key.",
+        inputSchema: {
+            orderNo: serviceOrderNoSchema,
+            ssh_key: positiveIdSchema.describe("SSH key ID from list_ssh_keys"),
+        },
+        annotations: {
+            title: "Remove an SSH key from a server",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ orderNo, ssh_key }) => {
+        const { data } = await apiRequest("DELETE", svc(orderNo, `ssh-keys/${ssh_key}`));
+        return { content: [{ type: "text", text: formatJson(data) }] };
+    });
     // --- OS Reinstall ---
     server.registerTool("get_os_options", {
         description: "Get available OS templates for reinstall Requires services:read when called with an API key.",
@@ -2360,7 +2393,7 @@ export function createVpsnetServer(options = {}) {
     });
     // --- API Keys ---
     server.registerTool("list_api_keys", {
-        description: "Show the API key this request authenticated with: scope (read/full/ai), granular scopes, paid_scopes, paid_operations_enabled, daily_spend_limit_eur, monthly_spend_limit_eur, allowed IPs, expiry and rate_limit (requests per minute), plus permission_options listing every scope the panel can grant. The backend scopes this endpoint to the calling key itself (apiKeyScopedToSelf), so other keys on the account are never listed here. By design an API key can never create, change or revoke API keys (403 apiKeyForbidden, reason api_keys_cannot_manage_api_keys): that is done in the VPSnet panel while signed in. Read-only.",
+        description: "Show the API key this request authenticated with: scope (read/full/ai), granular scopes, paid_scopes, paid_operations_enabled, daily_spend_limit_eur, monthly_spend_limit_eur, allowed IPs, expiry and rate_limit (a stored value the limiter does not read: every key may make 300 requests per 60 seconds by default, fewer on some operations), plus permission_options listing every scope the panel can grant. The backend scopes this endpoint to the calling key itself (apiKeyScopedToSelf), so other keys on the account are never listed here. By design an API key can never create, change or revoke API keys (403 apiKeyForbidden, reason api_keys_cannot_manage_api_keys): that is done in the VPSnet panel while signed in. Read-only.",
         inputSchema: {},
     }, async () => {
         const { data } = await apiRequest("GET", "/account/api-keys");
@@ -2376,7 +2409,7 @@ export function createVpsnetServer(options = {}) {
         return { content: [{ type: "text", text: formatJson(data) }] };
     });
     server.registerTool("get_api_key_activity", {
-        description: "Get the recorded request activity for this API key: recent matched route patterns and statuses, resolved and separately labelled caller-claimed source addresses, endpoint/source totals, and retained daily history. API-key callers can inspect only the same key that authenticated the MCP connection. Key values, headers, query strings, path values, and request bodies are never returned. To protect the control plane during abusive bursts, audit writes are capped per key per minute and retained detail has a separate per-key row ceiling; totals describe recorded rows and are not a billing ledger.",
+        description: "Get the recorded request activity for this API key: recent matched route patterns and statuses, resolved and separately labelled caller-claimed source addresses, endpoint/source totals, and retained daily history. API-key callers can inspect only the same key that authenticated the MCP connection, and this server needs a management key: a management key has no inference usage of its own and an inference key is refused on every account route, so read inference usage in the VPSnet panel. Key values, headers, query strings, path values, and request bodies are never returned. To protect the control plane during abusive bursts, audit writes are capped per key per minute and retained detail has a separate per-key row ceiling; totals describe recorded rows and are not a billing ledger.",
         inputSchema: {
             id: positiveIdSchema.describe("API key ID from list_api_keys (the calling key's own ID)"),
             limit: z.number().int().min(1).max(200).optional().describe("Recent request rows to return (default 50, maximum 200)"),
@@ -2387,7 +2420,7 @@ export function createVpsnetServer(options = {}) {
         return { content: [{ type: "text", text: formatJson(data) }] };
     });
     server.registerTool("get_api_key_inference_usage", {
-        description: "Get exact paid VPSnet AI usage for this inference API key: committed and currently reserved spend for the UTC day and month, request and token totals by public VPSnet model profile, configured spend limits, remaining spend, and notification preferences. API-key callers can inspect only the same key that authenticated the MCP connection. Internal provider model names are never returned. This is read-only and does not change limits, notifications, or billing.",
+        description: "Get exact paid VPSnet AI usage for this inference API key: committed and currently reserved spend for the UTC day and month, request and token totals by public VPSnet model profile, configured spend limits, remaining spend, and notification preferences. API-key callers can inspect only the same key that authenticated the MCP connection, and this server needs a management key: a management key has no inference usage of its own and an inference key is refused on every account route, so read inference usage in the VPSnet panel. Internal provider model names are never returned. This is read-only and does not change limits, notifications, or billing.",
         inputSchema: {
             id: positiveIdSchema.describe("Inference API key ID from list_api_keys (the calling key's own ID)"),
         },
@@ -2398,7 +2431,7 @@ export function createVpsnetServer(options = {}) {
     // --- TLS certificates ---
     const certificatePaymentSchema = z
         .object({
-        payment: z.number().int().positive().describe("Payment method ID; use 1 for account balance"),
+        payment: unboundedInteger().positive().describe("Payment method ID; use 1 for account balance"),
         successUrl: z.string().max(2048).describe("Approved VPSnet redirect URL, or an empty string"),
         cancelUrl: z.string().max(2048).describe("Approved VPSnet redirect URL, or an empty string"),
     })
@@ -4403,7 +4436,7 @@ export function createVpsnetServer(options = {}) {
             template: dnsTemplateIdSchema
                 .describe("Template ID returned by list_dns_templates, e.g. web_service, null_mx, google_workspace, microsoft_365, mail_security, caa_letsencrypt"),
             parameters: z
-                .record(z.union([z.string(), z.number(), z.boolean()]))
+                .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
                 .optional()
                 .describe("Template parameters, e.g. { ipv4, ipv6, www, mx_target, ttl } depending on the template"),
             preview: z