vpsnet-mcp 2.3.15 → 2.3.16

package/README.md

@@ -671,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 |
@@ -1005,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

@@ -28,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);
 }
@@ -160,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;
@@ -213,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.
@@ -266,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

@@ -92,6 +92,7 @@ export function registerRemoteTools(server) {
         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 }; });

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vpsnet-mcp",
-  "version": "2.3.15",
+  "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,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"