vpsnet-mcp 2.3.14 → 2.3.16

package/README.md

@@ -40,6 +40,8 @@ endpoint and task skills. The npm package supplies the local MCP server;
 installable plugin bundles also carry the AI application's manifest and skills.
 
 Build all client bundles with `python3 scripts/package-distribution.py`.
+The same build creates four [self-contained skill imports](docs/STANDALONE_SKILLS.md)
+for clients that import one skill folder or ZIP at a time.
 The output includes checksums and identifies each format. Public directory
 submission materials are in [the catalog kit](distribution/catalogs/README.md).
 
@@ -337,7 +339,10 @@ Choose your environment:
 - [VS Code with GitHub Copilot](#vs-code-with-github-copilot) — Copilot agent mode
 - [Cline](#cline) / [Cursor](#cursor) / [Windsurf](#windsurf) / [Roo Code](#roo-code) / [Codex](#codex) — Other clients
 
-The standard config works across most MCP clients:
+The following local stdio example uses the `mcpServers` configuration format
+supported by several MCP clients. Use your client's native schema; VS Code's
+`.vscode/mcp.json` uses `servers` instead. For customer OAuth and the hosted
+connector, use [AI client setup](docs/CLIENTS.md).
 
 ```json
 {
@@ -495,7 +500,8 @@ Go to **Cursor Settings** > **MCP** > **Add new MCP Server**. Use command type w
 <details>
 <summary>Roo Code</summary>
 
-Open Roo Code MCP settings and add to `roo_mcp_settings.json`:
+Open Roo Code MCP settings and choose **Edit Global MCP** (currently
+`mcp_settings.json`), or **Edit Project MCP** for `.roo/mcp.json`:
 
 ```json
 {
@@ -516,24 +522,74 @@ Open Roo Code MCP settings and add to `roo_mcp_settings.json`:
 </details>
 
 <details>
-<summary>VS Code with GitHub Copilot</summary>
+<summary id="vs-code-with-github-copilot">VS Code with GitHub Copilot</summary>
 
-Install using the VS Code CLI:
+For the hosted customer OAuth connection, run **MCP: Add Server** and enter
+`https://mcp.vpsnet.com/mcp`, or merge this native VS Code entry into
+`.vscode/mcp.json`, preserving other servers:
+
+```json
+{
+  "servers": {
+    "vpsnet": {
+      "type": "http",
+      "url": "https://mcp.vpsnet.com/mcp"
+    }
+  }
+}
+```
+
+Complete the browser sign-in and consent flow when requested. Copilot's portable
+workspace `.mcp.json` and user `~/.copilot/mcp-config.json` use a top-level
+`mcpServers` object instead. These formats are distinct from the Claude Code
+extension's configuration.
+
+For the separate local stdio package with your own VPSnet API key, install using
+the VS Code CLI:
 
 ```bash
 code --add-mcp '{"name":"vpsnet","command":"npx","args":["-y","vpsnet-mcp"],"env":{"VPSNET_API_KEY":"your_api_key_here"}}'
 ```
 
-Or add to your VS Code MCP config manually using the standard config above.
+For manual native VS Code configuration, place that local server's `command`,
+`args` and private `env` under `servers.vpsnet`, rather than copying the generic
+`mcpServers` wrapper. VS Code's **MCP: Reset Cached Tools** refreshes a stale
+tool catalog. See [official MCP configuration](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
 
 > This is for **GitHub Copilot** agent mode in VS Code. For the **Claude Code** extension, see the [Claude Code for VS Code Extension](#claude-code-for-vs-code-extension) section.
 
 </details>
 
 <details>
-<summary>Windsurf</summary>
+<summary id="windsurf">Windsurf / Devin Desktop</summary>
+
+Current official Windsurf documentation redirects to Devin Desktop. Choose the
+agent you are using: legacy Cascade and the current Devin Local agent have
+different MCP setup paths.
+
+For Devin Local, add and authenticate the hosted connector with the Devin CLI:
+
+```sh
+devin mcp add vpsnet https://mcp.vpsnet.com/mcp
+devin mcp login vpsnet --scopes services:read
+```
+
+This requests a read baseline. Request the documented scopes required for other
+tasks through a new authorization flow before approving them. If authorization
+is lost, use the Desktop **Authenticate** action, or `devin mcp logout vpsnet`
+followed by the login command. Current CLI versions use dedicated
+`.devin/mcp_config.json`, `.devin/mcp_config.local.json` or user
+`~/.config/devin/mcp_config.json` files.
+
+For legacy Cascade, open the panel's **Actions → Open MCP config file** and merge
+a server under `mcpServers` with `serverUrl: "https://mcp.vpsnet.com/mcp"`.
+Complete its OAuth flow. Cascade has a 100-tool total limit, so inspect the
+enabled tools. The local stdio example above is a separate API-key connection.
 
-Follow the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/mcp). Use the standard config above.
+Follow the official [Devin Local MCP guide](https://docs.devin.ai/cli/extensibility/mcp/configuration)
+or [legacy Cascade guide](https://docs.devin.ai/desktop/cascade/mcp) for your
+surface. Client authentication and VPSnet compatibility still need verification
+on the actual client version.
 
 </details>
 
@@ -615,7 +671,7 @@ everything else.
 | Tool | Description | Scope | Paid |
 |------|-------------|-------|------|
 | `list_services` | List all active VPS services | `services:read` | free |
-| `get_service` | Get detailed info for a service | `services:read` | free |
+| `get_service` | Read service details and the next readiness check; keep provisioning, guest access and application health separate | `services:read` | free |
 | `get_service_graphs` | Get one graph series: metric (cpu, ram, ssd, net, io, …) and period (5m … 1y) | `services:read` | free |
 | `get_event` | Read an async action's state by its `event` id or `noty` UUID | `services:read` or `account:read` | free |
 | `wait_for_event` | Poll an async action until completed or error (or a timeout) | `services:read` or `account:read` | free |
@@ -949,7 +1005,7 @@ enabled.
 ### Guest Agent
 | Tool | Description | Scope | Paid |
 |------|-------------|-------|------|
-| `get_guest_agent_status` | Check QEMU guest-agent availability on a Cloud VPS | `services:read` | free |
+| `get_guest_agent_status` | Read guest-agent availability on Cloud VPS or Firecracker; this does not establish application readiness | `services:read` | free |
 
 ### History
 | Tool | Description | Scope | Paid |

package/build/index.js

@@ -2,6 +2,8 @@
 import { installToolInputSchemas } from "./tool-schema.js";
 import { registerOrderTools } from "./remote-orders.js";
 import { registerRemoteTools } from "./remote-tools.js";
+import { registerReadOnlyContext } from "./read-only-context.js";
+import { purchaseReadiness, serviceReadiness, serviceResultOutput } from "./service-readiness.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { pathToFileURL } from "node:url";
@@ -57,7 +59,7 @@ export function createVpsnetServer(options = {}) {
             "Resources is an array of numeric resource value IDs from get_order_options, e.g. [901, 907].",
             "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).",
-            "After placing an order, wait 10-30 seconds before attempting SSH — the VPS needs time to boot and start SSH daemon.",
+            "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).",
             "",
             "## Deployment capabilities (unordered)",
@@ -347,13 +349,15 @@ export function createVpsnetServer(options = {}) {
         return { content: [{ type: "text", text: formatJson(data) }] };
     });
     server.registerTool("get_service", {
-        description: "Get detailed info for a service by order number. stateProcess.waitingReason=public_ip_inventory means the paid CREATE awaits public IP inventory and resumes automatically; poll this same service without a new order, payment or manual retry. stateProcess.attention=true requires operator attention. The legacy stateProccess alias carries the same process data. Resource-usage rows include available; false means the numeric zero is a compatibility placeholder, not a measurement. Requires services:read when called with an API key.",
+        description: "Get detailed info and follow_up readiness guidance for the original service order. Payment, VM provisioning, guest-agent availability and application health are separate. Pending activation, finalizing or active stateProcess means keep polling this same order; about 10 seconds is an interval, not an ETA. Check at most 6 times before a progress update, then retain the order for the next check. stateProcess.waitingReason=public_ip_inventory resumes automatically; never reorder, pay again or manually restart. stateProcess.attention=true requires operator attention. The legacy stateProccess alias carries the same process data. Unknown guest-agent status alone does not prove the VM is down. Resource-usage rows with available=false contain compatibility placeholders, not measurements. Requires services:read when called with an API key.",
         inputSchema: {
             orderNo: serviceOrderNoSchema,
         },
+        outputSchema: serviceResultOutput,
     }, async ({ orderNo }) => {
-        const { data } = await apiRequest("GET", `/account/services/${encodeURIComponent(orderNo)}`);
-        return { content: [{ type: "text", text: formatJson(data) }] };
+        const { status, data } = await apiRequest("GET", `/account/services/${encodeURIComponent(orderNo)}`);
+        const output = serviceReadiness(data, status, orderNo, options.remoteScopes !== undefined);
+        return { content: [{ type: "text", text: formatJson(output) }], structuredContent: output };
     });
     server.registerTool("get_service_graphs", {
         description: "Get one performance graph series for a service: pick a metric and a period. fc_block, fc_net_native and fc_pressure exist only for Firecracker VPS. fields narrows io/net/fc_* metrics to some series. A wrong metric, period or field answers 422 with invalidParameter and allowedValues. Requires services:read when called with an API key.",
@@ -2020,6 +2024,7 @@ export function createVpsnetServer(options = {}) {
             "Payment object for balance: { payment: 1, successUrl: '', cancelUrl: '' }.",
             "First call returns confirmationRequired and an exact gross EUR quote without charging. Show the amount and billing period, obtain explicit approval, then call again with the unchanged order configuration and idempotencyKey, returned quoteToken, expected_total_eur and acknowledge_charge=true. The API key must have paid scope/caps enabled. Never replace the key after an uncertain payment; inspect that original attempt in the VPSnet panel. Quotes are retained in this MCP process; after a restart inspect the original attempt in the panel rather than submitting another order.",
             "Payment acceptance is not server readiness. Poll get_service for the returned order number. stateProcess.waitingReason=public_ip_inventory resumes the same paid CREATE automatically when inventory returns; do not place or pay for another order. stateProcess.attention=true needs operator attention.",
+            "Follow follow_up for the same service. Poll about every 10 seconds, never treating that interval as a boot ETA; after at most 6 checks report pending progress and retain the original key/order. Do not automatically restart or promise a completion callback. Running VM, usable guest access and application health are separate checks.",
             "Resources: array of numeric resource value IDs from get_order_options, e.g. [901, 907].",
             "rootPassword: 6-40 chars, alphanumeric, must contain uppercase + lowercase + digit. Example: 'MyPass123'.",
             "sshKey and rootPassword are mutually exclusive — provide one or the other.",
@@ -2103,7 +2108,8 @@ export function createVpsnetServer(options = {}) {
                                         confirmationRequired: true, idempotencyKey,
                                         message: "The original quote is no longer valid. The API refused confirmation before charging. Inspect this original attempt in the VPSnet panel and obtain approval of any changed price or configuration; do not retry an uncertain purchase with a new key." }) }] };
                     }
-                    return { ...(status >= 400 ? { isError: true } : {}), content: [{ type: "text", text: formatJson(data) }] };
+                    const output = purchaseReadiness(data, status, idempotencyKey, true, false);
+                    return { ...(status >= 400 ? { isError: true } : {}), content: [{ type: "text", text: formatJson(output) }], structuredContent: output };
                 }
                 catch {
                     return refusal("purchaseOutcomeUnknown", "The confirmation outcome is unknown. Inspect this original attempt in the VPSnet panel. Do not submit another order or use a new key.");
@@ -3840,7 +3846,7 @@ export function createVpsnetServer(options = {}) {
         };
     });
     server.registerTool("get_guest_agent_status", {
-        description: "Check whether the QEMU guest agent is running inside a Cloud VPS (KVM/VDS). Useful before OS-level operations that depend on the agent. Requires services:read when called with an API key.",
+        description: "Read guest-agent availability for Cloud VPS (KVM/VDS) or Firecracker. KVM probes its QEMU agent; Firecracker reads worker-reported health. This is separate from VM provisioning and application health. Unknown is advisory, not proof the server failed; unavailable gates only operations that need the agent. Delegated Linux tools do not provide Windows PowerShell or RDP verification. Requires services:read when called with an API key.",
         inputSchema: {
             orderNo: serviceOrderNoSchema,
         },
@@ -4639,7 +4645,8 @@ export function createVpsnetServer(options = {}) {
     if (options.remoteScopes)
         registerRemoteTools(server);
     if (options.remoteProfile === "orders")
-        registerOrderTools(server);
+        registerOrderTools(server, options.remoteScopes);
+    registerReadOnlyContext(server);
     return server;
 }
 // --- Start server ---

package/build/read-only-context.js

@@ -0,0 +1,111 @@
+import { McpError, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { scopeCatalog } from "./scope-catalog.js";
+// Packaged, static guidance only: no filesystem paths, customer data or API calls.
+const guides = [
+    {
+        name: "connection-access",
+        title: "VPSnet connection and permissions",
+        description: "Understand discovery, permissions and safe read-only use.",
+        mimeType: "text/markdown",
+        text: [
+            "# Connection and permissions",
+            "Discover tools with tools/list; their descriptions, input schemas and annotations describe the current connection. Discovery is not permission to execute every listed tool.",
+            "Hosted access uses OAuth. Local stdio access uses a management API key. Never paste credentials into prompts or resources. Use the client's supported authorization flow.",
+            "Use get_connected_account when available to inspect the current grant. Resource visibility and allowed services are enforced by the backend. Missing permission requires the user's explicit authorization; never auto-grant or silently broaden access.",
+            "These resources contain static guidance, not current account data. Prompts prepare read-only workflows and never execute tools themselves. A client may choose whether to expose resources or prompts in its interface.",
+            "Honor the user's existing explicit authorization. Explain the target and effect and obtain approval when an action extends that authorization, destroys unrelated data or adds unapproved charges or exposure. A granted OAuth scope alone does not authorize expanding the task. Functions invocation can incur charges; inspecting an existing invocation does not require starting another one.",
+        ].join("\n\n"),
+    },
+    {
+        name: "async-operations",
+        title: "VPSnet asynchronous operation progress",
+        description: "Follow an existing operation without repeating a change.",
+        mimeType: "text/markdown",
+        text: [
+            "# Following existing operations",
+            "Keep the original service identifier, operation identifier and idempotency key. An accepted receipt is not proof that provisioning, guest boot or application startup has finished. Do not repeat a change or create another order because a response is slow.",
+            "For networking, follow the read tools named in the receipt. Poll get_networking_operation for network/port operations and get_network_appliance_operation for appliance operations; other operation stores have their own documented read tools. in_progress=true and reason_kind=waiting indicate progress, including waiting_dependency or a control-plane-not-yet-answered reason. They are not an MCP tool failure.",
+            "Respect next_check_seconds when provided. If absent, suggest a 10-second interval as polling guidance, not an ETA. Bound a monitoring pass to six reads, then return a pending update containing the identifier and next read needed so the user can resume. Never promise a callback or push notification from the stateless HTTP relay.",
+            "When in_progress=false, inspect the terminal state and reason_kind. Report failure or cancellation honestly and do not retry automatically. HTTP or authorization errors remain errors even while an operation is pending.",
+            "Read get_service for service state, get_event for an existing service event, and get_guest_agent_status when available for guest-agent evidence. VM provisioned/running, OS or guest agent ready, and application healthy are separate observations; absence of an agent does not prove the OS failed. Use application health reads for application readiness. Firecracker, KVM and Windows can take different amounts of time; no fixed completion time is guaranteed.",
+        ].join("\n\n"),
+    },
+    {
+        name: "read-only-workflows",
+        title: "VPSnet read-only diagnostic workflows",
+        description: "Choose existing read tools and report evidence with its limits.",
+        mimeType: "text/markdown",
+        text: [
+            "# Read-only diagnostics",
+            "Start with tools/list and check the current input schema. Use only tools whose annotations declare readOnlyHint=true for a read-only diagnostic pass. Some tools named inspect, discover or browse can enqueue durable work and must not be assumed read-only.",
+            "Service: list_services, then get_service, get_service_history and get_guest_agent_status where available and permitted. Identify the exact service before interpreting its state.",
+            "Networking: read get_networking_capabilities and the relevant network, topology, port or existing operation. A successful control-plane operation alone does not prove guest connectivity.",
+            "Applications: list_service_applications, then read get_application_installation, get_application_health and bounded events or logs for the selected installation. Redact credentials and personal data from quoted logs. Do not run install, restart, repair or reconcile as part of diagnosis.",
+            "Functions: use permitted existing invocation/history reads. list_functions and get_function may reconcile saved trace state; their GET method and functions:read scope do not prove they are side-effect free. Do not use those tools for a strictly side-effect-free review unless the user already authorized that reconciliation. Check current annotations and report limitations. Do not invoke a function to check it; execution is a separate user-authorized action with possible usage charges.",
+            "Report observed facts, unresolved questions and the smallest proposed next step. A permission denial, missing telemetry or pending operation is not proof that a service is broken.",
+        ].join("\n\n"),
+    },
+    {
+        name: "oauth-scopes",
+        title: "VPSnet OAuth scope catalog",
+        description: "Canonical nonlegacy scope names, descriptions, implications and billing categories; not the connection's grants.",
+        mimeType: "application/json",
+        text: JSON.stringify({
+            kind: "scope_catalog",
+            grants: false,
+            note: "Static supported-scope documentation, not granted permissions. Discovery profile and consent determine availability. Inspect get_connected_account when available for this connection's actual grant. Legacy scopes are omitted.",
+            scopes: Object.entries(scopeCatalog).filter(([, entry]) => !entry.legacy)
+                .map(([name, entry]) => ({ name, ...entry })),
+        }, null, 2),
+    },
+];
+const workflows = [
+    ["review-service", "Review service readiness", "Review one existing service using read-only evidence.", "Read list_services if an identifier is needed, then get_service and permitted history/guest-agent reads. Separate provisioning, OS/guest-agent readiness and application readiness. Do not restart, reinstall or create another service."],
+    ["review-network", "Review network progress", "Inspect existing networking state and operation progress.", "Read get_networking_capabilities and the selected network/port or existing operation using the receipt's follow-up read. Treat in_progress=true with reason_kind=waiting as progress; respect next_check_seconds and return a resumable pending update after bounded polling. Do not attach, retry, reconfigure or create resources."],
+    ["review-application", "Review application health", "Inspect an existing application's health without changing it.", "Read list_service_applications if needed, then the selected installation, health and bounded events/logs. Redact secrets from logs. Report container/application evidence separately from VM readiness. Do not install, restart, repair, reconcile or change access."],
+    ["review-function", "Review function history", "Inspect prior function invocations without executing a function.", "Read permitted existing invocation/history records and distinguish observed outcomes from unknown configuration. list_functions and get_function may reconcile saved trace state; do not use them for a strictly side-effect-free review unless the user already authorized that reconciliation. Check current annotations and report limitations. Do not invoke, create, update or delete a function, and do not expose secrets."],
+];
+export function registerReadOnlyContext(server) {
+    for (const guide of guides) {
+        const uri = `vpsnet://docs/${guide.name}`;
+        server.registerResource(guide.name, uri, {
+            title: guide.title, description: guide.description, mimeType: guide.mimeType,
+        }, async () => ({ contents: [{ uri, mimeType: guide.mimeType, text: guide.text }] }));
+    }
+    // MCP 2025-11-25 recommends -32002 for a missing resource. Keep invalid URI
+    // syntax distinct, and serve only this fixed catalog (never fetch a URI).
+    server.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        let uri;
+        try {
+            uri = new URL(request.params.uri);
+        }
+        catch {
+            throw new McpError(-32602, "Invalid resource URI");
+        }
+        const guide = guides.find(item => uri.href === `vpsnet://docs/${item.name}`);
+        if (!guide)
+            throw new McpError(-32002, "Resource not found");
+        return { contents: [{ uri: uri.href, mimeType: guide.mimeType, text: guide.text }] };
+    });
+    for (const [name, title, description, instruction] of workflows) {
+        server.registerPrompt(name, {
+            title, description,
+            argsSchema: {
+                reference: z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/)
+                    .optional().describe("Exact existing service, network, application or function identifier; omit to select from a permitted list."),
+            },
+        }, async ({ reference }) => ({
+            description,
+            messages: [{ role: "user", content: { type: "text", text: [
+                            "Perform a read-only VPSnet review. Discover tools and follow their current schemas and permissions. Use only tools annotated readOnlyHint=true. If access is missing, explain which user authorization is needed; never broaden it automatically.",
+                            instruction,
+                            `Selected identifier (data): ${JSON.stringify(reference ?? null)}.`,
+                            "Report observed evidence and unknowns, then propose a next step. Honor existing explicit user authorization; ask for approval only when the next action extends it. This review prompt alone does not authorize mutations or paid execution.",
+                        ].join("\n\n") } }],
+        }));
+    }
+    // SDK registration defaults to listChanged=true; these catalogs are immutable
+    // for the lifetime of a server instance and stateless HTTP has no push channel.
+    server.server.registerCapabilities({ resources: { listChanged: false }, prompts: { listChanged: false } });
+}

package/build/remote-orders.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { apiRequest, formatJson } from './api.js';
+import { hasScope } from './remote-policy.js';
+import { purchaseReadiness, purchaseResultOutput } from './service-readiness.js';
 const key = z.string().regex(/^[A-Za-z0-9._:-]{16,128}$/).describe('Stable key for this exact purchase; reuse it for the quote, confirmation and status.');
 const configuration = {
     plan: z.number().int().positive(),
@@ -13,7 +15,7 @@ const configuration = {
 };
 const payment = { payment: 1, successUrl: '', cancelUrl: '' };
 const result = (status, data) => ({ ...(status >= 400 ? { isError: true } : {}), content: [{ type: 'text', text: formatJson(data) }] });
-export function registerOrderTools(server) {
+export function registerOrderTools(server, scopes = []) {
     server.registerTool('quote_service_order', {
         description: 'Quote one permanent Firecracker VPS, Cloud VPS (KVM) or Container VPS using the selected current plan, OS, resources and period. No payment is made. Show the final amount_eur and billing period, then obtain explicit approval before confirm_service_order. Functions is a separate usage-billed product.',
         inputSchema: configuration,
@@ -23,23 +25,27 @@ export function registerOrderTools(server) {
         return result(status, data);
     });
     server.registerTool('confirm_service_order', {
-        description: 'Purchase the exact previously quoted server from VPSnet balance after explicit customer approval of its final EUR total and billing period. Supply the unchanged quote configuration, token and key. Never automatically create a new key after an uncertain result: inspect get_purchase_result. A receipt is not a ready server. Poll get_purchase_result for the purchase outcome; get_service for the returned orderno additionally requires services:read. This connection receives access to its newly ordered server only within the permissions the customer granted.',
+        description: 'Purchase the exact previously quoted server from VPSnet balance after explicit customer approval of its final EUR total and billing period. Supply the unchanged quote configuration, token and key. Never automatically create a new key after an uncertain result: inspect get_purchase_result. A receipt is not a ready server. Poll get_purchase_result for the financial outcome; get_service for the returned orderno additionally requires services:read. Follow follow_up for provisioning checks, permission requirements and bounded progress updates. The suggested 10-second polling interval is not an ETA. This connection receives access to its newly ordered server only within the permissions the customer granted.',
         inputSchema: { ...configuration,
             quoteToken: z.string().min(32).max(256),
             expected_total_eur: z.number().finite().nonnegative().describe('Exact final amount_eur from the quote, shown to and approved by the customer.'),
             acknowledge_charge: z.literal(true).describe('The customer explicitly approved this exact balance charge.'),
         },
+        outputSchema: purchaseResultOutput,
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async (input) => {
         const { status, data } = await apiRequest('POST', '/account/mcp/orders/services/confirm', { ...input, payment }, { 'Idempotency-Key': input.idempotencyKey, 'X-Quote-Token': input.quoteToken });
-        return result(status, data);
+        const output = purchaseReadiness(data, status, input.idempotencyKey, hasScope(scopes, 'services:read'));
+        return { ...result(status, output), structuredContent: output };
     });
     server.registerTool('get_purchase_result', {
-        description: 'Inspect this connection’s existing purchase attempt by its original idempotency key. Pending or unknown is not a successful purchase. Do not submit a second order. A returned server orderno can be checked with get_service; a domain remains pending until its registrar status confirms registration.',
+        description: 'Inspect this connection’s existing financial purchase attempt by its original idempotency key. This replays a financial receipt, not live provisioning progress. Pending or unknown must not trigger a second order. Follow follow_up: a returned server orderno is checked with get_service; if services:read is missing, re-authorize this existing connection without ordering again. A domain remains pending until its registrar status confirms registration. Do not promise an idle client a completion callback.',
         inputSchema: { idempotencyKey: key },
+        outputSchema: purchaseResultOutput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async ({ idempotencyKey }) => {
         const { status, data } = await apiRequest('GET', `/account/mcp/orders/requests/${encodeURIComponent(idempotencyKey)}`);
-        return result(status, data);
+        const output = purchaseReadiness(data, status, idempotencyKey, hasScope(scopes, 'services:read'));
+        return { ...result(status, output), structuredContent: output };
     });
 }

package/build/remote-policy.js

@@ -8,6 +8,7 @@ export const remoteInstructions = [
     "Firecracker VPS supports general-purpose and resource-intensive Linux workloads with substantial server resources and low virtualization overhead. MicroVM describes the lightweight design, not a small server limit. Consider it when KVM-specific features are unnecessary; match current plans to resource and availability requirements.",
     "Cloud VPS (KVM) offers Linux and BSD support, automatic Windows Server provisioning, three-copy Ceph NVMe storage on enterprise drives with power-loss protection (PLP), HA restart on another host after host failure, and live migration to another node for planned host upgrades, with migration back when appropriate.",
     "Use the connected VPSnet account and only the services and permissions it granted. Never request a model API key.",
+    "On first VPSnet use in a conversation, call get_update_info once when available. Read an installed skill's bundled plugin-version reference if accessible; otherwise omit pluginVersion rather than infer it from clientInfo.version or repository HEAD. Keep checked/dismissed state only in conversation context. If an actually observed plugin/local version is older, give one concise native update advisory and continue the task. For unknown/current versions or unavailable release facts, stay quiet unless the user asks about updates. Never force an update, change grants or treat a published runtime as proof of deployment.",
     "Tool discovery describes supported capabilities, not granted authority. Compare the scopes and selected services from get_connected_account with each tool's required scope metadata. Explain missing permissions only when relevant to the user's task. Ask the customer to approve the required permission by re-authorizing this existing VPSnet connection through the AI app's OAuth flow; never work around a denial.",
     "Inspect current capabilities and state before a change. Honor the user's existing authorization; obtain consent when a change expands the task, destroys unrelated data or adds unapproved exposure.",
     "Keep operation IDs, reason codes and idempotency keys. Accepted means pending; read the final state before claiming success.",
@@ -27,7 +28,7 @@ export function orderInstructions(scopes) {
     const products = [scopes.includes('orders:servers') ? 'purchase permanent VPS servers' : '',
         scopes.includes('orders:domains') ? 'register domains' : ''].filter(Boolean);
     const instructions = products.length
-        ? `This VPSnet connection can ${products.join(' and ')} from the customer’s VPSnet balance within its granted permissions. Quote first, show the final gross EUR amount and period, and confirm only after explicit approval. ${scopes.includes('orders:domains') ? 'Domain registration may be non-refundable. ' : ''}Daily and monthly limits cover this connection across token refresh. Never use a new key to retry an uncertain payment; inspect get_purchase_result. Payment settings and saved-card charges are not exposed.`
+        ? `This VPSnet connection can ${products.join(' and ')} from the customer’s VPSnet balance within its granted permissions. Quote first, show the final gross EUR amount and period, and confirm only after explicit approval. ${scopes.includes('orders:domains') ? 'Domain registration may be non-refundable. ' : ''}Daily and monthly limits cover this connection across token refresh. Never use a new key to retry an uncertain payment; inspect get_purchase_result. A financial receipt is separate from provisioning: follow follow_up and get_service for the same returned order, requiring services:read. If missing, re-authorize this existing connection without granting it automatically or ordering again. Poll about every 10 seconds as a suggested interval, never an ETA; after at most 6 checks report pending progress and retain the original IDs. Do not restart, reorder or promise an idle AI a callback. A running VM, guest access and application health are separate checks. Payment settings and saved-card charges are not exposed.`
         : 'This VPSnet connection can inspect order plans and existing purchase results within its granted permissions. It cannot submit purchases or change payment settings.';
     return remoteInstructions.replace('This connector does not purchase capacity, change payment settings or run model inference.', instructions);
 }
@@ -118,7 +119,7 @@ const permissions = new Map([
     ["get_system_status", "authenticated"],
     ["get_faq", "authenticated"],
     ["get_pricing", "authenticated"],
-    ["get_connected_account", "authenticated"],
+    ["get_connected_account", "authenticated"], ["get_update_info", "authenticated"],
     ["open_vm_session", "vm:session"], ["run_vm_command", "vm:exec"], ["read_vm_file", "vm:files:read"],
     ["write_vm_file", "vm:files:write"], ["create_vm_file", "vm:files:write"], ["inspect_vm", "vm:diagnostics"], ["get_vm_operation", "vm:session"], ["cancel_vm_operation", "vm:session"],
 ]);
@@ -159,15 +160,138 @@ const titleAcronyms = {
 function defaultToolTitle(name) {
     return name.split(/[_-]+/).filter(Boolean).map((word, index) => titleAcronyms[word.toLowerCase()] ?? (index === 0 ? word[0].toUpperCase() + word.slice(1) : word)).join(' ');
 }
+// Explicit legacy stdio classifications, reviewed against handlers and backend effects.
+// This only fills missing metadata; remote policy supplies every hint and remains unchanged.
+// POST calculate_plan_change only computes a price; POST quotes persist an intent.
+const legacyReadOnlyTools = new Set([
+    'get_account',
+    'get_profile',
+    'list_services',
+    'get_service',
+    'get_service_graphs',
+    'get_event',
+    'wait_for_event',
+    'get_service_history',
+    'get_rdns',
+    'get_title',
+    'get_os_options',
+    'get_plan_options',
+    'get_plan_resources',
+    'calculate_plan_change',
+    'get_period_options',
+    'get_order_plans',
+    'get_order_options',
+    'get_backup_status',
+    'get_backup_history',
+    'list_ssh_keys',
+    'get_ssh_key',
+    'list_api_keys',
+    'get_api_key',
+    'get_api_key_activity',
+    'get_api_key_inference_usage',
+    'list_domains',
+    'get_domain',
+    'list_domain_tlds',
+    'list_domain_glue_records',
+    'get_domain_parent_ds',
+    'check_domain_availability',
+    'get_domain_ordering_status',
+    'list_domain_contacts',
+    'get_registrar_lock',
+    'list_service_dns_options',
+    'list_firecracker_snapshots',
+    'get_restore_status',
+    'list_restore_points',
+    'get_guest_agent_status',
+    'list_function_invocations',
+    'get_function_invocation',
+    'list_dns_zones',
+    'get_dns_zone',
+    'get_dns_zone_diagnostics',
+    'export_dns_zone',
+    'list_dns_templates',
+    'get_dnssec',
+    'get_dns_service_status',
+    'get_dns_zone_history',
+    'list_ddns_tokens',
+    'list_invoices',
+    'get_invoice',
+    'list_payments',
+    'get_login_history',
+    'get_management_history',
+    'get_usage_statements',
+    'get_pricing',
+    'get_system_status',
+    'get_faq',
+]);
+const legacyWriteDestructive = new Map([
+    // GET also advances a pending rollback, including disk/application reconciliation.
+    ['list_snapshots', true],
+    // GET may create/repair the billing anchor and replace a Function's association.
+    ['list_functions', false],
+    ['get_function', false],
+    // GET reserves/reconciles a platform hostname and queues DNS/PTR/guest work.
+    ['get_hostname', true],
+    ['start_service', false],
+    ['stop_service', true],
+    ['restart_service', true],
+    ['console_service', false],
+    ['suspend_service', true],
+    ['resume_service', false],
+    ['change_hostname', true],
+    ['reset_hostname', true],
+    ['change_root_password', true],
+    ['flush_iptables', true],
+    ['change_title', true],
+    ['toggle_ipv6', true],
+    ['toggle_extra_settings', true],
+    ['deploy_ssh_key', true],
+    ['change_plan', true],
+    ['set_auto_renew', true],
+    ['renew_service', true],
+    ['order_service', true],
+    ['create_backup', true],
+    ['create_ssh_key', false],
+    ['delete_ssh_key', true],
+    ['create_domain_contact', true],
+    ['update_domain_contact', true],
+    ['delete_domain_contact', true],
+    ['quote_domain_register', false],
+    ['quote_domain_transfer', false],
+    ['quote_domain_renew', false],
+    ['quote_domain_restore', false],
+    ['set_domain_auto_renew', true],
+    ['create_snapshot', true],
+    ['rollback_snapshot', true],
+    ['delete_snapshot', true],
+    ['create_firecracker_snapshot', false],
+    ['rollback_firecracker_snapshot', true],
+    ['delete_firecracker_snapshot', true],
+    ['reissue_dns_zone_verification', true],
+    ['create_ddns_token', false],
+    ['revoke_ddns_token', true],
+]);
 /** Give every transport a discoverable title while retaining authored annotations. */
 export function installToolTitles(server) {
     const original = server.registerTool.bind(server);
     const register = (name, config, handler) => {
         const annotations = (config.annotations ?? {});
         const authored = [annotations.title, config.title].find(title => typeof title === 'string' && title.trim().length > 0);
+        const title = authored ?? defaultToolTitle(name);
+        const legacyHints = legacyReadOnlyTools.has(name)
+            ? { readOnlyHint: true, destructiveHint: false }
+            : legacyWriteDestructive.has(name)
+                ? { readOnlyHint: false, destructiveHint: legacyWriteDestructive.get(name) }
+                : {};
+        const completed = { ...annotations };
+        for (const [key, value] of Object.entries({ ...legacyHints, openWorldHint: externalTools.has(name) })) {
+            if (completed[key] === undefined)
+                completed[key] = value;
+        }
         return original(name, {
             ...config,
-            annotations: { ...annotations, title: authored ?? defaultToolTitle(name) },
+            title: config.title || title,
+            annotations: { ...completed, title },
         }, handler);
     };
     server.registerTool = register;
@@ -212,6 +336,16 @@ const deduplicatedTools = new Set([
 // These read guest or backup state but queue durable operations, so their read scopes do
 // not imply a read-only MCP call.
 const queuedReadTools = new Set(['browse_restore_files', 'inspect_vm', 'read_vm_file', 'get_application_health', 'get_application_logs', 'discover_service_containers']);
+// Intentional hosted metadata correction: these endpoints can change existing state
+// even though their permission is read-scoped (or default-contact creation is additive
+// only when is_default is false). No permission or handler changes accompany these hints.
+const hostedReconciliationEffects = new Map([
+    ['list_snapshots', true],
+    ['get_hostname', true],
+    ['list_functions', false],
+    ['get_function', false],
+    ['create_domain_contact', true],
+]);
 // Keep cached aggregate calls valid, but advertise the individually scoped
 // actions to new directory clients. The SDK uses one handler for tools/list;
 // filtering its result leaves the normal tools/call dispatcher intact.
@@ -227,7 +361,14 @@ export function installRemotePolicy(server, scopes, profile = 'directory') {
             return setRequestHandler(schema, handler);
         return setRequestHandler(schema, async (...args) => {
             const response = await handler(...args);
-            return { ...response, tools: response.tools.filter((tool) => !legacyAggregateTools.has(tool.name)) };
+            return { ...response, tools: response.tools
+                    .filter((tool) => !legacyAggregateTools.has(tool.name))
+                    // SDK registerTool preserves _meta but drops unknown top-level config
+                    // fields. Add the canonical declaration to the emitted descriptor,
+                    // using exactly the same scopes as its compatibility mirror.
+                    .map((tool) => ({
+                    ...tool, securitySchemes: tool._meta?.securitySchemes,
+                })) };
         });
     });
     const original = server.registerTool.bind(server);
@@ -258,6 +399,10 @@ export function installRemotePolicy(server, scopes, profile = 'directory') {
             annotations.readOnlyHint = true;
             annotations.destructiveHint = false;
         }
+        if (hostedReconciliationEffects.has(name)) {
+            annotations.readOnlyHint = false;
+            annotations.destructiveHint = hostedReconciliationEffects.get(name);
+        }
         if (deduplicatedTools.has(name))
             annotations.idempotentHint = true;
         const objectSchema = config.inputSchema instanceof z.ZodObject ? config.inputSchema : undefined;

package/build/remote-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { randomBytes } from 'node:crypto';
 import { apiRequest, resolveApiBase } from './api.js';
+import { getUpdateInfo, updateInfoOutput } from './update-info.js';
 const resource = { orderNo: z.string().regex(/^[A-Za-z0-9-]{1,64}$/), sessionBinding: z.string().regex(/^[a-f0-9]{32}$/, 'sessionBinding must contain exactly 32 lowercase hexadecimal characters (0-9, a-f), without hyphens. For a new open_vm_session call, omit it so VPSnet creates it; otherwise reuse the returned sessionBinding.').describe('Exactly 32 lowercase hexadecimal characters (0-9, a-f), without hyphens. Copy sessionBinding from open_vm_session and reuse it for every operation and reconnect. Not a credential.') };
 const session = { ...resource, sessionId: z.string().uuid() };
 const idempotencyKey = z.string().regex(/^[A-Za-z0-9_-]{16,128}$/).describe('Stable key for this exact operation. Reuse after a lost response; never automatically replace.');
@@ -76,9 +77,24 @@ async function operationResult(orderNo, sessionBinding, operationId, cancel = fa
     return runtime(await lease(orderNo, sessionBinding, true), cancel ? 'POST' : 'GET', `/mcp/operations/${operationId}${cancel ? '/cancel' : ''}`, cancel ? {} : undefined);
 }
 export function registerRemoteTools(server) {
+    server.registerTool('get_update_info', {
+        description: 'Read public VPSnet releases and reviewed client update guidance without changing software, credentials or permissions. On first VPSnet use in a conversation, check once when available. Pass installed versions only if actually observed or user-reported; never infer them from host clientInfo.version or the gateway runtime. Unknown installed versions stay unknown. If an observed version is older, give one concise advisory and continue; otherwise stay quiet unless the user asks about updates. Remember checks and dismissals in conversation context, not customer tracking. VPSnet maintains the hosted gateway.',
+        inputSchema: {
+            client: z.string().max(64).optional().describe('Known client identifier such as codex, claude-code or gemini-cli; omit when unknown.'),
+            pluginVersion: z.string().max(63).optional().describe('Observed or user-reported installed VPSnet plugin version, not the host application version. Omit if unknown.'),
+            localMcpVersion: z.string().max(63).optional().describe('Observed or user-reported local vpsnet-mcp npm version. Omit for remote-only connections or when unknown.'),
+        }, outputSchema: updateInfoOutput,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => { const data = await getUpdateInfo(args); return { ...result(data), structuredContent: data }; });
+    const spendingLimit = z.union([z.number().finite().nonnegative(), z.string().regex(/^\d+(?:\.\d+)?$/)]).nullable().optional();
     server.registerTool('get_connected_account', {
-        description: 'Identify the connected VPSnet account and its granted permissions and services.', inputSchema: {},
-        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, _meta: { 'openai/profile': true },
+        description: 'Identify the connected VPSnet account and its granted permissions, selected services and spending limits.', inputSchema: {},
+        outputSchema: z.object({
+            id: z.string().min(1), name: z.string(), scopes: z.array(z.string()), services: z.array(z.string()),
+            function_daily_limit_eur: spendingLimit, order_daily_limit_eur: spendingLimit, order_monthly_limit_eur: spendingLimit,
+            function_monthly_limit_eur: spendingLimit.describe('Stored monthly Functions limit in EUR when supplied by the backend. Null or omitted means no explicit monthly cap is reported by this grant, not unlimited usage; account limits still apply. Read only: never infer a default or expand permissions.'),
+        }).passthrough(),
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
     }, async () => { const { data } = await apiRequest('GET', '/account/mcp/profile'); return { ...result(data), structuredContent: data }; });
     server.registerTool('open_vm_session', {
         description: 'Open an authorized Linux session on a selected KVM or Firecracker service. The VPSnet guest channel works without a VM IP, SSH password or guest internet connection; choose connectionMethod="guest" for network/SSH troubleshooting or "ssh" for the independent SSH path. Auto prefers the guest channel. Requires explicit VM permission. Omit sessionBinding for a new session; VPSnet generates it and returns it with sessionId. Reuse both returned values for commands, files and reconnects. The OS user is root. Read /etc/os-release through the first operation to verify guest connectivity before choosing OS-specific commands or making changes. An empty managed-app list does not mean the server has no software.',

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/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/build/update-info.js

@@ -0,0 +1,135 @@
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+export const RELEASE_FEED_URL = 'https://raw.githubusercontent.com/bacarrdy/vpsnet-mcp/main/distribution/releases/published.json';
+export const MAX_FEED_BYTES = 65536;
+const stable = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
+const entry = z.object({
+    version: z.string().max(63).regex(stable), source_commit: z.string().regex(/^[0-9a-f]{40}$/),
+    verified_at: z.string().max(40).datetime({ offset: true }), url: z.string().max(256),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/), ci_run: z.number().int().positive().safe(),
+    ci_conclusion: z.literal('success'),
+}).strict();
+const feedSchema = z.object({ schema_version: z.literal(1), plugin: entry, mcp: entry }).strict();
+const instructions = JSON.parse(readFileSync(new URL('../scripts/update-clients.json', import.meta.url), 'utf8'));
+const runtimeVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+export function validatePublishedFeed(value) {
+    const feed = feedSchema.parse(value);
+    if (feed.plugin.url !== `https://github.com/bacarrdy/vpsnet-mcp/releases/download/plugin-${feed.plugin.version}/vpsnet-plugin-${feed.plugin.version}.zip`
+        || feed.mcp.url !== `https://registry.npmjs.org/vpsnet-mcp/-/vpsnet-mcp-${feed.mcp.version}.tgz`) {
+        throw new Error('Unexpected release artifact URL');
+    }
+    return feed;
+}
+/** Reject duplicate keys (including escaped aliases) before normal JSON parsing. */
+export function parsePublishedFeed(text) {
+    const token = /\s*("(?:[^"\\\u0000-\u001f]|\\(?:["\\/bfnrt]|u[0-9a-fA-F]{4}))*"|true|false|null|-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?|[{}\[\],:])/gy;
+    const stack = [];
+    let position = 0;
+    while (position < text.length && text.slice(position).trim()) {
+        token.lastIndex = position;
+        const match = token.exec(text);
+        if (!match)
+            throw new Error('Invalid release JSON');
+        const value = match[1], frame = stack.at(-1);
+        if (value === '{' || value === '[')
+            stack.push({ object: value === '{', key: value === '{', keys: new Set() });
+        else if (value === '}' || value === ']')
+            stack.pop();
+        else if (value === ',' && frame?.object)
+            frame.key = true;
+        else if (value.startsWith('"') && frame?.object && frame.key) {
+            const name = JSON.parse(value);
+            if (frame.keys.has(name))
+                throw new Error('Duplicate release key');
+            frame.keys.add(name);
+            frame.key = false;
+        }
+        position = token.lastIndex;
+    }
+    return validatePublishedFeed(JSON.parse(text));
+}
+export async function fetchPublishedFeed(fetcher = fetch) {
+    const response = await fetcher(RELEASE_FEED_URL, {
+        redirect: 'error', signal: AbortSignal.timeout(5000), headers: { Accept: 'application/json' },
+    });
+    if (response.status !== 200 || !response.body)
+        throw new Error('Release feed unavailable');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_FEED_BYTES)
+                throw new Error('Release feed too large');
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return parsePublishedFeed(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+}
+let cache;
+async function cachedFeed() {
+    if (!cache || cache.expires <= Date.now()) {
+        // Public facts only: never cache account data, tokens or installed versions.
+        cache = { expires: Date.now() + 300_000, value: fetchPublishedFeed() };
+    }
+    return cache.value;
+}
+const observedSchema = z.object({ version: z.string().nullable(), source: z.enum(['caller_reported', 'runtime', 'unknown']) });
+export const updateInfoOutput = {
+    schema_version: z.literal(1), checked_at: z.string(), client: z.string(),
+    published: z.object({ plugin: entry, mcp: entry }).nullable(),
+    observed: z.object({ plugin: observedSchema, local_mcp: observedSchema, server: observedSchema }),
+    update_available: z.object({ plugin: z.boolean().nullable(), local_mcp: z.boolean().nullable(), server: z.boolean().nullable() }),
+    compatibility: z.object({ status: z.literal('unknown'), reason: z.string() }),
+    distribution_status: z.object({ source_release_published: z.boolean().nullable(), npm_package_published: z.boolean().nullable(),
+        remote_deployment_status: z.literal('unknown'), official_registry: z.object({ status: z.literal('unknown'), version: z.null(), checked_at: z.null() }),
+        downstream_catalogs: z.record(z.unknown()),
+    }),
+    instructions: z.object({ reviewed_at: z.string(), source_urls: z.array(z.string()), steps: z.array(z.string()) }).nullable(),
+    server_update: z.string(), advisory: z.literal(true), reason: z.string().nullable(),
+};
+function observed(value, runtime = false) {
+    return value && value.length < 64 && stable.test(value)
+        ? { version: value, source: runtime ? 'runtime' : 'caller_reported' }
+        : { version: null, source: 'unknown' };
+}
+function older(current, latest) {
+    if (current === null)
+        return null;
+    const a = current.split('.').map(BigInt), b = latest.split('.').map(BigInt);
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    return false;
+}
+export async function getUpdateInfo(args, lookup = cachedFeed) {
+    let published = null;
+    try {
+        published = validatePublishedFeed(await lookup());
+    }
+    catch { /* Do not echo untrusted errors. */ }
+    const client = args.client ?? 'generic';
+    const observations = { plugin: observed(args.pluginVersion), local_mcp: observed(args.localMcpVersion), server: observed(runtimeVersion, true) };
+    return z.object(updateInfoOutput).parse({
+        schema_version: 1, checked_at: new Date().toISOString(), client,
+        published: published ? { plugin: published.plugin, mcp: published.mcp } : null,
+        observed: observations,
+        update_available: { plugin: published ? older(observations.plugin.version, published.plugin.version) : null,
+            local_mcp: published ? older(observations.local_mcp.version, published.mcp.version) : null,
+            server: published ? older(observations.server.version, published.mcp.version) : null },
+        compatibility: { status: 'unknown', reason: 'No version-specific client acceptance evidence is supplied by this check.' },
+        distribution_status: { source_release_published: published ? true : null, npm_package_published: published ? true : null,
+            remote_deployment_status: 'unknown', official_registry: { status: 'unknown', version: null, checked_at: null }, downstream_catalogs: {} },
+        instructions: Object.hasOwn(instructions, client) ? instructions[client] : null,
+        server_update: 'The hosted gateway is maintained by VPSnet. Updating a local npm package does not update it.',
+        advisory: true,
+        reason: published ? null : 'Published release information is unavailable or invalid; installed software is unchanged.',
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vpsnet-mcp",
-  "version": "2.3.14",
+  "version": "2.3.16",
   "type": "module",
   "description": "MCP server for managing VPSnet.com services, applications, DNS, domains, billing, and server lifecycle operations",
   "bin": {
@@ -26,6 +26,7 @@
     "build/file-restore-contract.js",
     "build/index.js",
     "build/service-rescue-contract.js",
+    "build/service-readiness.js",
     "build/temp-vm-contract.js",
     "build/api-path.js",
     "build/tool-result.js",
@@ -38,6 +39,9 @@
     "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"
   ],
   "repository": "github:bacarrdy/vpsnet-mcp",

package/scripts/update-clients.json

@@ -0,0 +1,204 @@
+{
+  "claude-code": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://code.claude.com/docs/en/plugins/cli-reference",
+      "https://code.claude.com/docs/en/discover-plugins"
+    ],
+    "steps": [
+      "Use claude plugin list --json to check the installed VPSnet plugin and its source.",
+      "For the VPSnet marketplace installation, run claude plugin update vpsnet@vpsnet in your own terminal.",
+      "Use /reload-plugins in the running session or start a new session. For another install source, use its native update control."
+    ]
+  },
+  "claude": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://claude.com/docs/plugins/overview"
+    ],
+    "steps": [
+      "Open Customize > Plugins. For an added marketplace, use Check for updates where available.",
+      "Uploaded or organization-managed plugins follow their owner's upload, sync and review process. A GitHub release alone does not prove the account's plugin updated."
+    ]
+  },
+  "cowork": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://claude.com/docs/plugins/overview",
+      "https://support.claude.com/en/articles/13837433-manage-plugins-for-your-organization"
+    ],
+    "steps": [
+      "Manage the account plugin in Customize > Plugins using the source's native update controls.",
+      "For an organization marketplace, ask its owner to upload or re-sync and complete any required review. The served version can remain pinned or await approval."
+    ]
+  },
+  "grok": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://docs.x.ai/grok/connectors"
+    ],
+    "steps": [
+      "Manage the custom remote connection at grok.com/connectors.",
+      "The official connector guide does not establish plugin ZIP updates or a tool-cache refresh command. A remote gateway deployment does not establish whether this conversation refreshed its tools."
+    ]
+  },
+  "codex": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://learn.chatgpt.com/docs/cli/reference",
+      "https://learn.chatgpt.com/docs/plugins"
+    ],
+    "steps": [
+      "Use codex plugin list --json to inspect installed and available plugin versions and the configured marketplace name.",
+      "For that configured marketplace, use codex plugin marketplace upgrade <marketplace-name> --json, then start a new session. Do not assume the active thread reloads plugins."
+    ]
+  },
+  "chatgpt": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://developers.openai.com/plugins/deploy/connect-chatgpt",
+      "https://developers.openai.com/plugins/deploy/submission"
+    ],
+    "steps": [
+      "For a custom MCP connection, open its plugin settings, use Refresh and start a new conversation.",
+      "Published package updates and server rescans are publisher actions, with their own review and publication state. A local ZIP or GitHub release does not prove a directory update."
+    ]
+  },
+  "gemini-cli": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://geminicli.com/docs/extensions/reference/",
+      "https://geminicli.com/docs/reference/commands/"
+    ],
+    "steps": [
+      "For a named installed extension, run gemini extensions update vpsnet in your terminal and restart the CLI.",
+      "/mcp reload re-discovers tools and /skills reload refreshes skills on host versions that support them; these do not install a new extension."
+    ]
+  },
+  "gemini-browser": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://support.google.com/gemini/answer/17209137"
+    ],
+    "steps": [
+      "Manage the custom Connected App in Gemini settings. This remote connection is not a Gemini CLI extension.",
+      "The reviewed guide does not establish a package-upgrade or tool-cache refresh command."
+    ]
+  },
+  "cursor": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://cursor.com/docs/reference/plugins",
+      "https://cursor.com/docs/plugins"
+    ],
+    "steps": [
+      "For a local plugin copy, replace it with the complete reviewed new package and reload the window or restart.",
+      "Public marketplace updates require provider review; team marketplace sync and local updates are separate. No universal public-store update command is established here."
+    ]
+  },
+  "kimi-code": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://www.kimi.com/code/docs/en/kimi-code-cli/customization/plugins.html"
+    ],
+    "steps": [
+      "For a copied local installation, reinstall the reviewed complete source with /plugins install ./vpsnet, then /reload or start a new session.",
+      "Use the plugin manager update action where available. Do not assume custom VPSnet plugins auto-update."
+    ]
+  },
+  "kimi-work": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://www.kimi.com/en/help/plugins-and-skills/create",
+      "https://www.kimi.com/en/help/plugins-and-skills/publish"
+    ],
+    "steps": [
+      "Use Plugin Builder in Kimi Work to convert the reviewed source update and inspect the resulting package.",
+      "Personal installation and public marketplace review are separate; no automatic source-update contract was established."
+    ]
+  },
+  "kiro": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://kiro.dev/docs/powers/installation/",
+      "https://kiro.dev/docs/mcp/configuration/"
+    ],
+    "steps": [
+      "For a repository-backed Power, use its Check for updates and Install updates controls.",
+      "Standalone MCP configuration is separate. Power OAuth scope compatibility needs client verification; installing a package does not grant additional scopes."
+    ]
+  },
+  "vscode": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://code.visualstudio.com/docs/agent-customization/agent-plugins",
+      "https://code.visualstudio.com/docs/agents/reference/mcp-configuration"
+    ],
+    "steps": [
+      "MCP: Reset Cached Tools refreshes discovery, not installed plugin files.",
+      "Use Extensions: Check for Extension Updates for the extension inventory. AgentHost /plugin update applies to its own plugin inventory; inspect which host and install source you use first."
+    ]
+  },
+  "devin": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://docs.devin.ai/cli/extensibility/plugins/overview",
+      "https://docs.devin.ai/cli/extensibility/mcp/configuration"
+    ],
+    "steps": [
+      "For a Devin CLI plugin installation, use devin plugins update vpsnet. A linked local source reloads on a new session.",
+      "Legacy Cascade and Devin Local are different hosts; do not assume a Devin CLI action updates a legacy Cascade configuration."
+    ]
+  },
+  "qwen": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://qwenlm.github.io/qwen-code-docs/en/users/extension/introduction/"
+    ],
+    "steps": [
+      "Use qwen extensions update <installed-name> for a native installed extension, then restart after terminal changes.",
+      "Pinned exact npm versions remain pinned. Marketplace source refresh is separate from updating installed extensions."
+    ]
+  },
+  "cline": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://docs.cline.bot/customization/plugins",
+      "https://docs.cline.bot/mcp/mcp-overview"
+    ],
+    "steps": [
+      "Inspect the actual Cline host and installed source; plugin support differs between CLI/SDK and IDE extensions.",
+      "No custom-plugin automatic upgrade or remote tool-refresh guarantee was established. Use the host-native manager and current official instructions."
+    ]
+  },
+  "mistral-work": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://docs.mistral.ai/vibe/work/connectors/mcp-connectors"
+    ],
+    "steps": [
+      "After tools change, open the existing Vibe Work connector and use Functions > Refresh tools. This host does not support dynamic tool discovery.",
+      "Do not substitute Vibe Code CLI: direct OAuth MCP is not supported there by the reviewed documentation."
+    ]
+  },
+  "mistral-code": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://docs.mistral.ai/vibe/code/cli/mcp-servers"
+    ],
+    "steps": [
+      "The reviewed Vibe Code CLI documentation explicitly excludes OAuth MCP servers. A plugin update does not fix that limitation.",
+      "Use a supported OAuth client; never substitute customer passwords or manually supplied tokens."
+    ]
+  },
+  "perplexity": {
+    "reviewed_at": "2026-10-14",
+    "source_urls": [
+      "https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors"
+    ],
+    "steps": [
+      "Manage the existing custom remote connector in account settings. Native skill ZIP replacement is a separate operation.",
+      "The reviewed connector guide does not establish automatic tool-list refresh, custom plugin upgrades or release notifications."
+    ]
+  }
+}