vpsnet-mcp 2.3.15 → 2.6.0

package/build/service-readiness.js

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+const orderNo = z.string().regex(/^[A-Za-z0-9-]{1,64}$/);
+const attemptKey = z.string().regex(/^[A-Za-z0-9._:-]{16,128}$/);
+/** Advisory continuation, never an ETA, grant, background task or payment retry. */
+export const serviceFollowUpSchema = z.object({
+    purchase_state: z.enum(['accepted', 'pending', 'unknown']).nullable(),
+    provisioning_state: z.enum(['pending', 'complete', 'not_running', 'needs_attention', 'failed', 'unknown']),
+    permission_required: z.literal('services:read').nullable(),
+    order_no: orderNo.nullable(),
+    idempotency_key: attemptKey.nullable(),
+    next_check: z.object({
+        tool: z.enum(['get_service', 'get_purchase_result']),
+        arguments: z.object({ orderNo: orderNo.optional(), idempotencyKey: attemptKey.optional() }),
+    }).nullable(),
+    poll_after_seconds: z.literal(10).nullable(),
+    max_checks_before_update: z.literal(6),
+    do_not_reorder: z.literal(true),
+    background_notification: z.literal(false),
+    server_running: z.boolean().nullable(),
+    guest_agent_available: z.boolean().nullable(),
+    application_ready: z.null(),
+    message: z.string(),
+});
+// Directory-only clients must not discover purchase tools through this schema.
+export const serviceResultOutput = z.object({ follow_up: serviceFollowUpSchema.extend({
+        next_check: z.object({ tool: z.literal('get_service'), arguments: z.object({ orderNo }) }).nullable(),
+    }) }).passthrough();
+export const purchaseResultOutput = z.object({ follow_up: serviceFollowUpSchema.optional() }).passthrough();
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : undefined;
+}
+function base() {
+    return {
+        purchase_state: null, provisioning_state: 'unknown', permission_required: null,
+        order_no: null, idempotency_key: null, next_check: null, poll_after_seconds: null,
+        max_checks_before_update: 6, do_not_reorder: true, background_notification: false,
+        server_running: null, guest_agent_available: null, application_ready: null,
+        message: 'Readiness is unknown. Inspect the original order; do not place another order or restart it.',
+    };
+}
+const pendingMessage = 'Keep the same order and check again after about 10 seconds; this is a polling interval, not a completion estimate. Check at most 6 times before a progress update. If still pending, report that state and retain the order number for the next check. Do not reorder or restart. No background notification is scheduled.';
+export function serviceReadiness(data, status, requestedOrderNo, remote = true) {
+    const response = object(data);
+    const follow = { ...base(), order_no: requestedOrderNo };
+    if (status === 403 && (response?.required_scope === 'services:read' || response?.requiredScope === 'services:read')) {
+        follow.permission_required = 'services:read';
+        follow.message = remote
+            ? 'Service readiness could not be read. If services:read is missing, ask the customer to approve it by re-authorizing this existing connection. Do not grant it automatically or submit another order.'
+            : 'Service readiness could not be read. Ask the owner to approve services:read for this management API key in the VPSnet panel, then inspect the same order. Do not change permissions automatically or submit another order.';
+    }
+    else if (status >= 200 && status < 300 && response?.success === true) {
+        const service = object(response.service);
+        const extra = object(service?.extra);
+        const processValue = service && 'stateProcess' in service ? service.stateProcess : service?.stateProccess;
+        const process = object(processValue);
+        const state = service?.state;
+        const sameOrder = service?.orderNo === requestedOrderNo;
+        if (service && sameOrder && typeof state === 'string') {
+            follow.next_check = { tool: 'get_service', arguments: { orderNo: requestedOrderNo } };
+            follow.guest_agent_available = typeof extra?.guestAgentAvailable === 'boolean' ? extra.guestAgentAvailable : null;
+            const waiting = extra?.pendingActivation === true || extra?.awaitingCapacity === true
+                || extra?.awaitingStock === true || service.finalizing === true || process !== undefined;
+            if (state === 'create_failed') {
+                follow.provisioning_state = 'failed';
+                follow.next_check = null;
+                follow.message = 'The service reports create_failed. Preserve its createFailure reason and original order; report the failure and any operator attention. Do not automatically order, pay, retry provisioning or restart it.';
+            }
+            else if (process?.attention === true || extra?.operatorWaiting === true
+                || (extra?.pendingActivation === true && extra.pendingActivationRefresh === false)) {
+                follow.provisioning_state = 'needs_attention';
+                follow.next_check = null;
+                follow.message = 'This service reports operator attention. Report the original order number and observed reason; do not blindly retry, reorder, pay again or restart it.';
+            }
+            else if (waiting || ['creating', 'starting', 'restarting'].includes(state)) {
+                follow.provisioning_state = 'pending';
+                follow.poll_after_seconds = 10;
+                follow.message = pendingMessage;
+            }
+            else if (state === 'running' && extra?.pendingActivation === false
+                && service.finalizing === false && processValue === null) {
+                follow.provisioning_state = 'complete';
+                follow.server_running = true;
+                follow.next_check = null;
+                follow.message = 'The service reports a running VM with provisioning and finalization clear. Guest-agent availability is separate and advisory; verify the required guest capability before using it. Application health, endpoint reachability and Windows license activation are not proved by this result.';
+            }
+            else if (['stopped', 'suspended'].includes(state)) {
+                follow.provisioning_state = 'not_running';
+                follow.server_running = false;
+                follow.next_check = null;
+                follow.message = 'The service is not running. Inspect the observed state and the original order before proposing a change; do not automatically reorder or restart.';
+            }
+        }
+    }
+    return { ...(response ?? { success: false, error: 'invalid_service_response' }), follow_up: follow };
+}
+/** Preserve the financial receipt, then explicitly hand off to its service. */
+export function purchaseReadiness(data, status, key, canReadServices, receiptRecovery = true) {
+    const response = object(data) ?? { success: false, error: 'invalid_purchase_response' };
+    // Domain receipts belong to the registrar workflow, not service provisioning.
+    if (typeof response.domain_id === 'number' || object(response.domain) || typeof response.domain === 'string')
+        return response;
+    const follow = { ...base(), idempotency_key: key, purchase_state: 'unknown' };
+    const parsedOrder = orderNo.safeParse(response.orderno);
+    if (status >= 200 && status < 300 && response.success === true && parsedOrder.success) {
+        follow.purchase_state = 'accepted';
+        follow.order_no = parsedOrder.data;
+        follow.next_check = { tool: 'get_service', arguments: { orderNo: parsedOrder.data } };
+        if (!canReadServices) {
+            follow.permission_required = 'services:read';
+            follow.message = 'The financial request succeeded; provisioning is not verified. Ask the customer to approve services:read by re-authorizing this existing connection, then inspect this same order. Never grant permissions automatically, create another connection/order, pay again or restart the server.';
+        }
+        else {
+            follow.message = 'The financial request succeeded; this receipt is not server readiness. Call get_service with this order number now, then follow its state checks. Retain the original key and order; never pay or order again because provisioning is slow.';
+        }
+    }
+    else {
+        follow.next_check = { tool: 'get_purchase_result', arguments: { idempotencyKey: key } };
+        follow.poll_after_seconds = 10;
+        if (status === 202 && response.state === 'pending' && response.idempotencyKey === key)
+            follow.purchase_state = 'pending';
+        follow.message = 'The financial outcome is pending or unknown. Inspect get_purchase_result with this original key; do not submit another confirmation, order or key. Check at most 6 times at about 10-second intervals, then report the unresolved outcome and retain the key. A timeout is not proof of failure; no background notification is scheduled.';
+        if (!receiptRecovery) {
+            follow.next_check = null;
+            follow.poll_after_seconds = null;
+            follow.message = 'The financial outcome is unresolved. Inspect this original attempt in the VPSnet panel; local API-key ordering has no durable purchase-result tool. Retain the key and never submit another confirmation, order or key to retry an uncertain purchase.';
+        }
+    }
+    return { ...response, follow_up: follow };
+}

package/build/service-reinstall-contract.js

@@ -0,0 +1,8 @@
+/** One safety contract across transports; directory clients never collect a password. */
+export function reinstallDescription(directory) {
+    const safety = "Reinstall OS on a VPS or qualified dedicated server. WARNING: destroys existing data; confirm with the user before reinstalling. Cloud VPS and Firecracker VPS: reinstall also deletes existing snapshots, so they cannot provide rollback after reinstall. Read get_os_options.snapshotDeletion first; when snapshots exist, set confirmSnapshotDelete to true only after the user explicitly confirms their deletion. A pending snapshot action blocks reinstall until it finishes. Container VPS has no snapshots. Dedicated servers erase every disk and have no snapshot rollback; get_os_options reports dedicated=true and confirmRequired=true. Pass confirmReinstall=true only after the user explicitly approves reinstalling that exact dedicated server and losing all disk data.";
+    const credentials = directory
+        ? "Use an account public sshKey ID from list_ssh_keys. If omitted, a dedicated server reuses its installed key when available; otherwise VPSnet generates a password and delivers it through the customer's existing VPSnet access flow, not this tool. Do not ask for or pass passwords through this connector; use the VPSnet panel to set a chosen password."
+        : "Use an account public sshKey ID from list_ssh_keys or an optional rootPassword, never both. If neither is supplied, a dedicated server reuses its installed key when available; otherwise VPSnet generates a password. Password rules: 6-40 chars, alphanumeric, uppercase + lowercase + digit.";
+    return `${safety} ${credentials} Dedicated reinstall returns a reinstall job ID. VPS reinstall returns a noty UUID for acceptance; follow get_service_history for completion. Acceptance is not completion. OAuth requires services:reinstall; API keys require full access.`;
+}

package/build/tool-result.js

@@ -7,7 +7,18 @@ function failurePayload(value) {
     const hasError = error === true
         || (typeof error === "string" && error.trim().length > 0)
         || (error !== null && typeof error === "object" && Object.keys(error).length > 0);
-    return payload.success === false
+    // A validated asynchronous purchase receipt says success=false while its
+    // financial outcome is pending. Keep that resumable read distinct from a
+    // failed payment. Explicit errors and HTTP failures still take precedence.
+    const follow = payload.follow_up;
+    const next = follow?.next_check;
+    const purchasePending = payload.state === 'pending'
+        && typeof payload.idempotencyKey === 'string'
+        && follow?.purchase_state === 'pending'
+        && follow.idempotency_key === payload.idempotencyKey
+        && next?.tool === 'get_purchase_result'
+        && next.arguments?.idempotencyKey === payload.idempotencyKey;
+    return (payload.success === false && !purchasePending)
         || hasError
         || (typeof payload.http_status === "number" && payload.http_status >= 400)
         || payload.state === "error";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vpsnet-mcp",
-  "version": "2.3.15",
+  "version": "2.6.0",
   "type": "module",
   "description": "MCP server for managing VPSnet.com services, applications, DNS, domains, billing, and server lifecycle operations",
   "bin": {
@@ -23,14 +23,18 @@
     "build/auth-failure.js",
     "build/certificate-contract.js",
     "build/custom-project-contract.js",
+    "build/dns-zone-contract.js",
     "build/file-restore-contract.js",
     "build/index.js",
+    "build/service-reinstall-contract.js",
     "build/service-rescue-contract.js",
+    "build/service-readiness.js",
     "build/temp-vm-contract.js",
     "build/api-path.js",
     "build/tool-result.js",
     "build/tool-schema.js",
     "build/networking-tools.js",
+    "build/service-files.js",
     "build/remote.js",
     "build/http-server.js",
     "build/request-context.js",
@@ -38,6 +42,7 @@
     "build/scope-catalog.js",
     "build/remote-auth-error.js",
     "build/remote-tools.js",
+    "build/read-only-context.js",
     "build/update-info.js",
     "scripts/update-clients.json",
     "build/remote-orders.js"