@sakupa/mcp 0.4.0 → 0.6.0

package/dist/bin.js

@@ -126,6 +126,9 @@ var FORBIDDEN_PATH_SEGMENTS = [
 ];
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
+// ../core/dist/domain/version.js
+var SAKUPA_MCP_VERSION = "0.6.0";
+
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
   invalid_request: 400,
@@ -449,8 +452,17 @@ async function sha256Hex(bytes) {
   return hex;
 }
 
-// ../core/dist/domain/subscription.js
-var SUBSCRIPTION_WARNING_TEXT = "You are subscribing this site ({siteUrl}) to Sakupa Hosting: the {plan} monthly plan (\xA5{priceJpy}/month).\n\nPaying makes THIS site permanent on its {siteUrl} address \u2014 it stops expiring. Binding a custom domain afterwards is an optional included extra: it requires proving DNS control of that domain, and whether or not you ever bind one does not change the subscription or qualify for a refund.\n\nIf this site outgrows its plan, Sakupa automatically upgrades the subscription to the next plan (water -> personal -> share -> business) and renewals bill the new plan. There is no metered overage: above the Business plan, growth is limited instead of billed further.\n\nYou can cancel anytime; when the subscription ends, the site immediately becomes a free temporary site again (24h validity) and all paid data \u2014 custom domain bindings included \u2014 is removed.";
+// ../core/dist/domain/billing-operation.js
+var BILLING_MUTATION_LIMITS = {
+  globalPerTenMinutes: 20,
+  sitePerTenMinutes: 1,
+  perBillingPeriod: 3,
+  maxConcurrency: 2,
+  leaseSeconds: 30,
+  maxConsecutiveFailures: 5,
+  circuitBreakSeconds: 15 * 60,
+  providerTimeoutMs: 1e4
+};
 
 // ../core/dist/dto.js
 var CREDENTIAL_HEADER = "x-sakupa-credential";
@@ -461,6 +473,12 @@ var MCP_VERSION_HEADER = "x-sakupa-mcp-version";
 var utf8Decoder = new TextDecoder("utf-8", { fatal: false });
 var utf8Encoder = new TextEncoder();
 
+// ../core/dist/services/authorization.js
+var AUTHORIZATION_TTL_MS = 15 * 60 * 1e3;
+
+// ../core/dist/services/subscriptions.js
+var WEBHOOK_PROCESSING_LEASE_MS = 5 * 60 * 1e3;
+
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -572,6 +590,12 @@ var HttpApiClient = class {
   async recoverDomain(req) {
     return this.call("POST", "/v1/domains/recover", { body: req });
   }
+  async getRecoveryStatus(verificationId) {
+    return this.call(
+      "GET",
+      `/v1/domains/recover/${encodeURIComponent(verificationId)}`
+    );
+  }
   async completeRecovery(verificationId, req) {
     return this.call(
       "POST",
@@ -602,13 +626,19 @@ var HttpApiClient = class {
       { credential }
     );
   }
-  async setBillingPlan(siteId, credential, req) {
+  async getBillingPlanCatalog() {
+    return this.call("GET", "/v1/billing/plans");
+  }
+  async manageSubscription(siteId, credential, req) {
     return this.call(
       "POST",
-      `/v1/sites/${encodeURIComponent(siteId)}/billing/plan`,
+      `/v1/sites/${encodeURIComponent(siteId)}/billing/manage`,
       { credential, body: req }
     );
   }
+  async getPublicBillingPortal() {
+    return this.call("GET", "/v1/billing/portal");
+  }
   async createTicket(credential, req) {
     return this.call("POST", "/v1/support/tickets", {
       credential,
@@ -627,7 +657,7 @@ var HttpApiClient = class {
 import { randomUUID } from "node:crypto";
 import { promises as fs2 } from "node:fs";
 import { join as join3, resolve as resolve2 } from "node:path";
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/analyze/analyzer.ts
 import { promises as fs } from "node:fs";
@@ -1115,9 +1145,50 @@ function credentialGitReminder(projectDir) {
 }
 
 // src/version.ts
-var MCP_VERSION = "0.4.0";
+var MCP_VERSION = SAKUPA_MCP_VERSION;
 var CLIENT_TYPE = "sakupa-mcp";
 
+// src/tools/result.ts
+import { z } from "zod";
+var STRUCTURED_TOOL_OUTPUT_SCHEMA = {
+  schemaVersion: z.literal(1),
+  outcome: z.enum([
+    "completed",
+    "preview",
+    "waiting_user",
+    "pending_provider",
+    "blocked",
+    "expired",
+    "failed"
+  ]),
+  resultCode: z.string(),
+  operationId: z.string().optional(),
+  summary: z.string(),
+  data: z.record(z.string(), z.unknown()),
+  userAction: z.object({
+    type: z.enum(["open_url", "confirm_in_mcp", "configure_dns"]),
+    provider: z.enum(["stripe", "sakupa"]).optional(),
+    url: z.string().optional(),
+    expiresAt: z.string().optional(),
+    expectedOutcome: z.string(),
+    resumeWith: z.object({ tool: z.string(), arguments: z.record(z.string(), z.unknown()) }).optional()
+  }).optional(),
+  nextActions: z.array(
+    z.object({
+      tool: z.string(),
+      arguments: z.record(z.string(), z.unknown()).optional(),
+      allowed: z.boolean(),
+      reasonCode: z.string().optional()
+    })
+  )
+};
+function structuredToolResult(envelope) {
+  return {
+    content: [{ type: "text", text: envelope.summary }],
+    structuredContent: envelope
+  };
+}
+
 // src/tools/context.ts
 function requireSiteFile(ctx) {
   const file = readSiteFile(ctx.projectDir);
@@ -1130,35 +1201,49 @@ function requireSiteFile(ctx) {
   return file;
 }
 function toolError(e) {
-  if (isSakupaError(e)) {
-    let text2 = `Error [${e.code}]: ${e.message}`;
-    if (e.details !== void 0) {
-      text2 += `
-Details: ${JSON.stringify(e.details, null, 2)}`;
-    }
-    return { content: [{ type: "text", text: text2 }], isError: true };
-  }
-  const message = e instanceof Error ? e.message : String(e);
-  return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+  const errorCode = isSakupaError(e) ? e.code : "internal";
+  const retryable = false;
+  const safeSummary = errorCode === "not_found" ? "\u6240\u9700\u7684\u672C\u5730\u9879\u76EE\u7ED1\u5B9A\u6216\u8D44\u6E90\u4E0D\u53EF\u7528\uFF1B\u5982\u679C\u672C\u5730\u6CA1\u6709 .sakupa/site.json\uFF0C\u8BF7\u5148\u8FD0\u884C deploy_site first\u3002" : errorCode === "unauthorized" ? "\u5F53\u524D\u64CD\u4F5C\u672A\u901A\u8FC7\u7AD9\u70B9\u6743\u9650\u6821\u9A8C\u3002" : errorCode === "invalid_request" || errorCode === "validation_failed" ? "\u8BF7\u6C42\u53C2\u6570\u6216\u672C\u5730\u9879\u76EE\u68C0\u67E5\u672A\u901A\u8FC7\u3002" : errorCode === "state_conflict" ? "\u8D44\u6E90\u72B6\u6001\u5DF2\u7ECF\u53D8\u5316\uFF0C\u8BF7\u91CD\u65B0\u67E5\u8BE2\u72B6\u6001\u540E\u518D\u51B3\u5B9A\u4E0B\u4E00\u6B65\u3002" : retryable ? "\u5916\u90E8\u670D\u52A1\u6682\u65F6\u4E0D\u53EF\u7528\u6216\u8BF7\u6C42\u8FC7\u4E8E\u9891\u7E41\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002" : "\u64CD\u4F5C\u5931\u8D25\uFF1B\u672A\u8FD4\u56DE\u670D\u52A1\u7AEF\u5185\u90E8\u8BE6\u60C5\u3002";
+  const result = structuredToolResult({
+    schemaVersion: 1,
+    outcome: "failed",
+    resultCode: `error_${errorCode}`,
+    summary: safeSummary,
+    data: { errorCode, retryable },
+    nextActions: []
+  });
+  return { ...result, isError: true };
 }
 
 // src/tools/definitions.ts
-function text(t) {
-  return { content: [{ type: "text", text: t }] };
+function text(resultCode, t, data = {}, outcome = "completed") {
+  return structuredToolResult({
+    schemaVersion: 1,
+    outcome,
+    resultCode,
+    summary: t,
+    data,
+    nextActions: []
+  });
 }
-function textJson(header, obj) {
-  return text(`${header}
-${JSON.stringify(obj, null, 2)}`);
+function textJson(resultCode, header, obj, outcome = "completed") {
+  const summary = `${header}
+${JSON.stringify(obj, null, 2)}`;
+  return structuredToolResult({
+    schemaVersion: 1,
+    outcome,
+    resultCode,
+    summary,
+    data: typeof obj === "object" && obj !== null ? { result: obj } : { result: obj },
+    nextActions: []
+  });
 }
-var planEnum = z.enum(["water", "personal", "share", "business"]);
-var severityEnum = z.enum(["low", "medium", "high", "critical"]);
+var planEnum = z2.enum(["water", "personal", "share", "business"]);
+var severityEnum = z2.enum(["low", "medium", "high", "critical"]);
 function planCatalog() {
   return TIER_ORDER.map((p) => `${p} \xA5${tierPriceJpy(p)}/month`).join(", ");
 }
-function subscriptionWarning(siteUrl, plan) {
-  return SUBSCRIPTION_WARNING_TEXT.replaceAll("{siteUrl}", siteUrl).replaceAll("{plan}", plan).replaceAll("{priceJpy}", String(tierPriceJpy(plan)));
-}
-var ticketCategoryEnum = z.enum([
+var ticketCategoryEnum = z2.enum([
   "billing",
   "payment",
   "refund_review",
@@ -1176,14 +1261,17 @@ function analysisSummary(analysis) {
 }
 function notDeployableResult(analysis) {
   return textJson(
+    "site_analysis_not_deployable",
     `This project is NOT deployable as-is. No files were uploaded and no API call was made.
 Next action: ${analysis.suggestedNextAction}
 Analysis:`,
-    analysisSummary(analysis)
+    analysisSummary(analysis),
+    "blocked"
   );
 }
 function spaConfirmationResult(analysis) {
   return text(
+    "spa_fallback_confirmation_required",
     `SPA fallback confirmation required \u2014 nothing was deployed yet.
 
 This site looks like a single-page application (one index.html plus JavaScript). SPA fallback rewrites every unknown path to index.html so client-side routes work, but it CHANGES normal 404 behavior: visitors never see a not-found page.
@@ -1192,7 +1280,9 @@ Please ask the user to choose, then re-run deploy_site with:
 - spaFallback: true, spaFallbackConfirmed: true  -> enable SPA fallback
 - spaFallbackConfirmed: true (spaFallback omitted or false) -> deploy WITHOUT fallback (unknown paths return 404)
 
-Output directory: "${analysis.recommendedOutputDir ?? "."}", ${analysis.fileCount} files.`
+Output directory: "${analysis.recommendedOutputDir ?? "."}", ${analysis.fileCount} files.`,
+    { analysis: analysisSummary(analysis), requestedConfirmation: "spa_fallback" },
+    "waiting_user"
   );
 }
 var MB2 = 1024 * 1024;
@@ -1252,10 +1342,12 @@ function registerTools(server, ctx) {
     "analyze_site",
     {
       description: "Analyze the local project and decide whether it can be deployed as a static site. Detects the framework, the built static output directory (dist/build/out/...), missing index.html, SSR/API-route/database-runtime risks, SPA fallback needs, forbidden files (secrets, .env, archives, media) and size limits. Sakupa deploys ONLY prebuilt static output \u2014 never source, secrets or server code. Run this before deploy_site.",
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       inputSchema: {
-        outputDir: z.string().optional().describe("Output directory relative to the project root (overrides detection)."),
-        spaFallbackRequested: z.boolean().optional().describe("User asked for SPA fallback (unknown paths rewritten to index.html)."),
-        spaFallbackConfirmed: z.boolean().optional().describe("User explicitly confirmed the SPA fallback 404-behavior change.")
+        outputDir: z2.string().optional().describe("Output directory relative to the project root (overrides detection)."),
+        spaFallbackRequested: z2.boolean().optional().describe("User asked for SPA fallback (unknown paths rewritten to index.html)."),
+        spaFallbackConfirmed: z2.boolean().optional().describe("User explicitly confirmed the SPA fallback 404-behavior change.")
       }
     },
     async (args) => {
@@ -1266,6 +1358,7 @@ function registerTools(server, ctx) {
           ...args.spaFallbackConfirmed !== void 0 ? { spaFallbackConfirmed: args.spaFallbackConfirmed } : {}
         });
         return textJson(
+          "site_analysis_completed",
           `Analysis of ${ctx.projectDir}
 Next action: ${analysis.suggestedNextAction}`,
           analysisSummary(analysis)
@@ -1279,11 +1372,16 @@ Next action: ${analysis.suggestedNextAction}`,
     "deploy_site",
     {
       description: `Deploy the local static output to Sakupa. First deploy creates a free temporary site (valid ${FREE_SITE_TTL_HOURS}h, public URL like https://{shortId}.sakupa.com) and stores the management credential in .sakupa/site.json. Later runs update the existing site (free sites also refresh their validity; subscribed sites are permanent). Runs analyze_site first and refuses to upload source projects, secrets, .env files, archives, media or server code. Never uploads anything when the analysis says the project is not deployable.`,
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
-        outputDir: z.string().optional().describe("Output directory relative to the project root (overrides detection)."),
-        spaFallback: z.boolean().optional().describe("Enable SPA fallback (requires spaFallbackConfirmed: true)."),
-        spaFallbackConfirmed: z.boolean().optional().describe("User explicitly confirmed the SPA fallback 404-behavior change."),
-        lang: z.string().optional().describe("Site language override (en | ja | zh-CN); defaults to the html lang.")
+        outputDir: z2.string().optional().describe("Output directory relative to the project root (overrides detection)."),
+        spaFallback: z2.boolean().optional().describe("Enable SPA fallback (requires spaFallbackConfirmed: true)."),
+        spaFallbackConfirmed: z2.boolean().optional().describe("User explicitly confirmed the SPA fallback 404-behavior change."),
+        publicConfirmed: z2.boolean().optional().describe(
+          "Required only for the first deployment: user explicitly confirmed creation of a public 24-hour URL."
+        ),
+        lang: z2.string().optional().describe("Site language override (en | ja | zh-CN); defaults to the html lang.")
       }
     },
     async (args) => {
@@ -1303,6 +1401,14 @@ Next action: ${analysis.suggestedNextAction}`,
         const outputAbs = resolve2(ctx.projectDir, analysis.recommendedOutputDir ?? ".");
         const manifest = await buildHashedManifest(files, outputAbs);
         const existing = readSiteFile(ctx.projectDir);
+        if (!existing && args.publicConfirmed !== true) {
+          return text(
+            "public_deployment_confirmation_required",
+            `First deployment creates a public URL that anyone with the link can open. The free preview stays live for ${FREE_SITE_TTL_HOURS} hours. Explain this to the user and obtain explicit confirmation before retrying deploy_site with publicConfirmed: true.`,
+            { publicUrlLifetimeHours: FREE_SITE_TTL_HOURS, confirmationField: "publicConfirmed" },
+            "waiting_user"
+          );
+        }
         ensureUploadSizeWithinLimits(manifest, !existing);
         if (!existing) {
           const created = await ctx.client.createSite({
@@ -1326,6 +1432,7 @@ Next action: ${analysis.suggestedNextAction}`,
             apiBaseUrl: ctx.apiBaseUrl
           });
           return text(
+            "site_published",
             `Site published: ${finalized2.url}
 Files uploaded: ${uploaded2} (${finalized2.totalBytes} bytes)
 ` + (finalized2.expiresAt ? `Expires at: ${finalized2.expiresAt}
@@ -1333,7 +1440,19 @@ Files uploaded: ${uploaded2} (${finalized2.totalBytes} bytes)
 This is a FREE temporary preview: it stays live for ${FREE_SITE_TTL_HOURS} hours. Deploying again or calling refresh_site extends the validity; subscribing the site (subscribe_site) makes this URL permanent. The management credential was saved to .sakupa/site.json \u2014 keep that file: it is the only way to manage this site.
 ` + credentialGitReminder(ctx.projectDir) + (finalized2.warnings.length > 0 ? `
 Warnings:
-${JSON.stringify(finalized2.warnings, null, 2)}` : "")
+${JSON.stringify(finalized2.warnings, null, 2)}` : ""),
+            {
+              siteId: created.siteId,
+              shortId: created.shortId,
+              url: finalized2.url,
+              deploymentId: created.deploymentId,
+              mode: finalized2.mode,
+              expiresAt: finalized2.expiresAt,
+              filesUploaded: uploaded2,
+              totalBytes: finalized2.totalBytes,
+              warnings: finalized2.warnings,
+              credentialStoredLocally: true
+            }
           );
         }
         const updateOnce = async (forceFullUpload) => {
@@ -1367,6 +1486,7 @@ ${JSON.stringify(finalized2.warnings, null, 2)}` : "")
         const { uploaded, finalized } = update;
         writeSiteFile(ctx.projectDir, { ...existing, url: finalized.url });
         return text(
+          "site_updated",
           `Site updated: ${finalized.url}
 Files uploaded: ${uploaded} (${finalized.totalBytes} bytes)
 ` + (finalized.expiresAt ? `Validity refreshed \u2014 expires at: ${finalized.expiresAt}
@@ -1374,7 +1494,16 @@ Files uploaded: ${uploaded} (${finalized.totalBytes} bytes)
 Reminder: free sites stay live for ${FREE_SITE_TTL_HOURS} hours after the last deploy or refresh_site call. Subscribing (subscribe_site) makes the site permanent.
 ` : "\nThis site is subscribed and permanent \u2014 no expiry.\n") + (finalized.warnings.length > 0 ? `
 Warnings:
-${JSON.stringify(finalized.warnings, null, 2)}` : "")
+${JSON.stringify(finalized.warnings, null, 2)}` : ""),
+          {
+            siteId: existing.siteId,
+            url: finalized.url,
+            mode: finalized.mode,
+            expiresAt: finalized.expiresAt,
+            filesUploaded: uploaded,
+            totalBytes: finalized.totalBytes,
+            warnings: finalized.warnings
+          }
         );
       } catch (e) {
         return toolError(e);
@@ -1385,6 +1514,8 @@ ${JSON.stringify(finalized.warnings, null, 2)}` : "")
     "refresh_site",
     {
       description: "Refresh the validity of the free temporary site WITHOUT uploading content. Uses the local credential in .sakupa/site.json. Subscribed sites are permanent and need no refresh.",
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       inputSchema: {}
     },
     async () => {
@@ -1392,8 +1523,10 @@ ${JSON.stringify(finalized.warnings, null, 2)}` : "")
         const site = requireSiteFile(ctx);
         const res = await ctx.client.refreshSite(site.siteId, site.credential);
         return text(
+          "site_refreshed",
           `Site validity refreshed. New expiry: ${res.expiresAt}
-Free sites stay live for ${FREE_SITE_TTL_HOURS} hours after each deploy or refresh.`
+Free sites stay live for ${FREE_SITE_TTL_HOURS} hours after each deploy or refresh.`,
+          { siteId: site.siteId, expiresAt: res.expiresAt }
         );
       } catch (e) {
         return toolError(e);
@@ -1404,13 +1537,15 @@ Free sites stay live for ${FREE_SITE_TTL_HOURS} hours after each deploy or refre
     "site_status",
     {
       description: "Show the current status of this project's Sakupa site: URL, mode (free/paid), expiry, subscription state, custom domains, size, last deployment and warnings.",
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
       inputSchema: {}
     },
     async () => {
       try {
         const site = requireSiteFile(ctx);
         const res = await ctx.client.getSiteStatus(site.siteId, site.credential);
-        return textJson("Site status:", res);
+        return textJson("site_status_returned", "Site status:", res);
       } catch (e) {
         return toolError(e);
       }
@@ -1419,40 +1554,42 @@ Free sites stay live for ${FREE_SITE_TTL_HOURS} hours after each deploy or refre
   server.registerTool(
     "subscribe_site",
     {
-      description: `Create a Stripe Checkout link that subscribes THIS site to a Sakupa Hosting monthly plan (${planCatalog()}). Paying makes the site PERMANENT on its {shortId}.sakupa.com URL \u2014 no more 24h expiry; that is the core value of paying. Binding a custom domain afterwards (bind_domain) is an optional included extra and requires DNS control of that domain. Owner-only: requires this project's site credential (.sakupa/site.json) \u2014 deploy_site first. If the site outgrows its plan, Sakupa auto-upgrades to the next plan (capped at Business, where growth is limited instead of billed further). Card details are entered only on the Stripe-hosted page \u2014 never through the AI tool. Without confirm: true this tool only shows the mandatory disclosure and makes no API call.`,
+      description: `Create a Stripe Checkout link that subscribes THIS site to a Sakupa Hosting monthly plan (${planCatalog()}). Paying makes the site PERMANENT on its {shortId}.sakupa.com URL \u2014 no more 24h expiry; that is the core value of paying. Binding a custom domain afterwards (bind_domain) is an optional included extra and requires DNS control of that domain. Owner-only: requires this project's site credential (.sakupa/site.json) \u2014 deploy_site first. If the site outgrows its plan, Sakupa shows an over-limit notice and never changes billing automatically. The owner can explicitly choose another plan through Stripe Customer Portal. Card details are entered only on the Stripe-hosted page \u2014 never through the AI tool. Opening and completing Stripe Checkout is the final subscription confirmation.`,
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       inputSchema: {
         plan: planEnum.describe(
           "Monthly plan: water (very light personal pages), personal (personal brand / small shop), share (small-business site), business (steadier traffic, more headroom)."
-        ),
-        confirm: z.boolean().optional().describe("User read the subscription disclosure and confirmed. Required to proceed.")
+        )
       }
     },
     async (args) => {
       try {
         const site = requireSiteFile(ctx);
-        const siteUrl = site.url ?? (site.shortId ? `https://${site.shortId}.sakupa.com` : site.siteId);
-        if (args.confirm !== true) {
-          return text(
-            `${subscriptionWarning(siteUrl, args.plan)}
-
-No checkout link was created yet. Please show this disclosure to the user and, after their explicit confirmation, re-run subscribe_site with confirm: true.`
-          );
-        }
         const res = await ctx.client.createPlanCheckout(
           {
             siteId: site.siteId,
             plan: args.plan,
-            idempotencyKey: randomUUID(),
-            confirmPlan: true
+            idempotencyKey: randomUUID()
           },
           site.credential
         );
         return text(
+          "subscription_checkout_ready",
           `Stripe Checkout link \u2014 Sakupa Hosting for this site: ${res.plan} plan, \xA5${res.monthlyPriceJpy}/month
 ${res.checkoutUrl}
 
 Open this link in a browser to subscribe. Card data is entered only on the Stripe-hosted page \u2014 never give card numbers, passwords or security codes to the AI tool.
-Once payment confirms, the site becomes permanent on its current URL. Binding a custom domain (bind_domain) is optional and still requires DNS verification.`
+Once payment confirms, the site becomes permanent on its current URL. Binding a custom domain (bind_domain) is optional and still requires DNS verification.`,
+          {
+            siteId: res.siteId,
+            plan: res.plan,
+            monthlyPriceJpy: res.monthlyPriceJpy,
+            checkoutUrl: res.checkoutUrl,
+            sessionId: res.sessionId,
+            finalConfirmationProvider: "stripe"
+          },
+          "waiting_user"
         );
       } catch (e) {
         return toolError(e);
@@ -1463,36 +1600,54 @@ Once payment confirms, the site becomes permanent on its current URL. Binding a
     "bind_domain",
     {
       description: "Bind a custom domain to this subscribed site \u2014 an OPTIONAL extra serving surface; the permanent {shortId}.sakupa.com URL keeps working alongside it. The binding unit is the APEX domain: binding example.com automatically includes www.example.com (both serve the same content, one apex TXT verification covers both), and one site binds at most ONE apex domain \u2014 a second domain needs a second subscribed site. Requires an ACTIVE subscription (subscribe_site). Ownership is proven ONLY by DNS control of the apex \u2014 payment never grants ownership. A binding request never reserves the domain: whoever proves DNS control first gets it, and unverified requests expire after 72 hours. Call again with verificationId to check progress.",
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
-        hostname: z.string().describe(
-          'Domain to bind: the apex ("example.com") or its www form ("www.example.com") \u2014 both mean the same unit. Other subdomains cannot be bound.'
-        ),
-        verificationId: z.string().optional().describe("Check an existing DNS verification instead of starting a new one.")
+        action: z2.enum(["start", "status"]),
+        hostname: z2.string().optional().describe("Required for start."),
+        verificationId: z2.string().optional().describe("Required for status.")
       }
     },
     async (args) => {
       try {
         const site = requireSiteFile(ctx);
-        if (args.verificationId !== void 0) {
+        if (args.action === "status") {
+          if (!args.verificationId) {
+            throw new SakupaError("invalid_request", "verificationId is required for status");
+          }
           const res2 = await ctx.client.checkVerification(args.verificationId, site.credential);
           if (res2.status === "verified") {
             writeSiteFile(ctx.projectDir, { ...site, boundDomain: res2.apexDomain });
           }
           return text(
+            res2.status === "verified" ? "domain_verification_succeeded" : "domain_verification_pending",
             `DNS verification ${res2.verificationId}: ${res2.status}
 ${res2.message}
 ` + (res2.provisioningJobId ? `Provisioning started (job ${res2.provisioningJobId}). HTTPS certificates and serving setup are in progress; check again with bind_domain + verificationId later.
 ` : "") + (res2.pendingDnsRecords.length > 0 ? `
 DNS records still required:
-${JSON.stringify(res2.pendingDnsRecords, null, 2)}` : "")
+${JSON.stringify(res2.pendingDnsRecords, null, 2)}` : ""),
+            {
+              verificationId: res2.verificationId,
+              status: res2.status,
+              apexDomain: res2.apexDomain,
+              provisioningJobId: res2.provisioningJobId,
+              pendingDnsRecords: res2.pendingDnsRecords,
+              message: res2.message
+            },
+            res2.status === "verified" ? "completed" : "pending_provider"
           );
         }
+        if (!args.hostname) {
+          throw new SakupaError("invalid_request", "hostname is required for start");
+        }
         const req = {
           siteId: site.siteId,
           hostname: args.hostname
         };
         const res = await ctx.client.bindDomain(site.credential, req);
         return text(
+          "domain_verification_started",
           `Domain binding started for ${res.apexDomain} (includes: ${res.includedHostnames.join(", ")} \u2014 both will serve this site).
 
 1. Prove control of ${res.apexDomain} by creating this DNS record:
@@ -1503,7 +1658,15 @@ ${JSON.stringify(res2.pendingDnsRecords, null, 2)}` : "")
 
 2. Serving DNS (after verification): ${res.servingInstructions}
 
-Then run bind_domain again with verificationId: "${res.verificationId}" to check verification and start provisioning.`
+Then run bind_domain again with verificationId: "${res.verificationId}" to check verification and start provisioning.`,
+          {
+            verificationId: res.verificationId,
+            apexDomain: res.apexDomain,
+            includedHostnames: res.includedHostnames,
+            verificationRecord: res.verificationRecord,
+            servingInstructions: res.servingInstructions
+          },
+          "waiting_user"
         );
       } catch (e) {
         return toolError(e);
@@ -1514,6 +1677,8 @@ Then run bind_domain again with verificationId: "${res.verificationId}" to check
     "billing_status",
     {
       description: "Show this site's hosting subscription: plan, payment state, current paid period, reconciled usage, estimated usage tier, bound custom domains and risks. Owner-only (uses the credential in .sakupa/site.json).",
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
       inputSchema: {}
     },
     async () => {
@@ -1532,7 +1697,7 @@ Then run bind_domain again with verificationId: "${res.verificationId}" to check
           res.boundHostnames.length > 0 ? `Bound custom domains: ${res.boundHostnames.join(", ")}` : void 0,
           res.risks.pastDue ? "ATTENTION: renewal payment failing \u2014 update the payment method (manage_billing). Serving continues while Stripe retries; if Stripe gives up, the site reverts to free." : void 0
         ].filter((l) => l !== void 0);
-        return textJson(`${lines.join("\n")}
+        return textJson("billing_status_returned", `${lines.join("\n")}
 
 Full status:`, res);
       } catch (e) {
@@ -1543,19 +1708,53 @@ Full status:`, res);
   server.registerTool(
     "manage_billing",
     {
-      description: "Open the Stripe-hosted billing portal for this site: update the payment method, view invoices, or cancel the subscription. All billing operations happen on the Stripe-hosted page \u2014 never inside the AI tool. Requires the local site credential (.sakupa/site.json).",
-      inputSchema: {}
+      description: "Open the Stripe-hosted billing portal for this site: update the payment method, view invoices, or cancel the subscription. All billing operations happen on the Stripe-hosted page \u2014 never inside the AI tool. With .sakupa/site.json, this opens the site-specific portal. Without the local credential, this returns Stripe's public no-code Customer Portal login page. The customer enters the checkout email and confirms a one-time passcode sent by Stripe. This never restores Sakupa site authority.",
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      inputSchema: {
+        scope: z2.enum(["site", "public_recovery"])
+      }
     },
-    async () => {
+    async (args) => {
       try {
-        const site = requireSiteFile(ctx);
-        const res = await ctx.client.createBillingPortal(site.siteId, site.credential);
-        return text(
-          `Stripe billing portal for this site:
-${res.portalUrl}
-
-Open this link in a browser to update the payment method, view invoices, or manage the subscription. The link is temporary \u2014 create a fresh one when needed.`
-        );
+        if (args.scope === "site") {
+          const site = requireSiteFile(ctx);
+          const res2 = await ctx.client.createBillingPortal(site.siteId, site.credential);
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "waiting_user",
+            resultCode: "site_billing_portal_ready",
+            summary: `\u5DF2\u521B\u5EFA\u6B64\u7AD9\u70B9\u7684 Stripe \u5BA2\u6237\u95E8\u6237\u77ED\u65F6\u94FE\u63A5\uFF1A${res2.portalUrl}\u3002\u4EFB\u4F55\u53D8\u66F4\u4ECD\u987B\u5728 Stripe \u9875\u9762\u5B8C\u6210\u3002`,
+            data: { scope: args.scope, portalUrl: res2.portalUrl },
+            userAction: {
+              type: "open_url",
+              provider: "stripe",
+              url: res2.portalUrl,
+              expectedOutcome: "\u7528\u6237\u5728 Stripe \u6258\u7BA1\u9875\u9762\u7BA1\u7406\u4ED8\u6B3E\u65B9\u5F0F\u3001\u53D1\u7968\u6216\u53D6\u6D88\u7EED\u8BA2"
+            },
+            nextActions: [{ tool: "billing_status", allowed: true }]
+          });
+        }
+        const res = await ctx.client.getPublicBillingPortal();
+        return structuredToolResult({
+          schemaVersion: 1,
+          outcome: "waiting_user",
+          resultCode: "public_billing_recovery_portal_ready",
+          summary: `Stripe \u516C\u5171\u90AE\u7BB1 OTP \u767B\u5F55\u9875\uFF1A${res.portalUrl}\u3002\u5B83\u4F7F\u7528 one-time passcode\uFF0Cdoes not recover the Sakupa key\uFF0C\u4E5F\u4E0D\u6388\u4E88\u7AD9\u70B9\u6743\u9650\uFF1B\u540C\u90AE\u7BB1\u5B58\u5728\u591A\u4E2A Customer \u65F6\uFF0CStripe \u53EF\u80FD\u53EA\u6253\u5F00 most recently created \u7684\u53EF\u7528\u8BB0\u5F55\u3002`,
+          data: {
+            scope: args.scope,
+            portalUrl: res.portalUrl,
+            grantsSiteAuthority: false,
+            acceptsSiteIdentifier: false
+          },
+          userAction: {
+            type: "open_url",
+            provider: "stripe",
+            url: res.portalUrl,
+            expectedOutcome: "\u7528\u6237\u7531 Stripe \u9A8C\u8BC1\u8D26\u5355\u90AE\u7BB1\u540E\u67E5\u770B\u5E76\u53D6\u6D88\u95E8\u6237\u4E2D\u663E\u793A\u7684\u8BA2\u9605"
+          },
+          nextActions: []
+        });
       } catch (e) {
         return toolError(e);
       }
@@ -1565,17 +1764,24 @@ Open this link in a browser to update the payment method, view invoices, or mana
     "recover_domain_site",
     {
       description: "Recover management control of a subscribed site WITH A BOUND CUSTOM DOMAIN after losing the local project, by proving DNS control of the apex domain. Sites without a bound domain are identified solely by their local credential and cannot be recovered. By default, completing recovery REVOKES all previous local credentials. Call first with the hostname to get the DNS record, then again with verificationId to complete recovery (writes a new .sakupa/site.json and returns a download link for the current site content).",
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
-        hostname: z.string().describe('Hostname of the site to recover, e.g. "www.example.com".'),
-        verificationId: z.string().optional().describe("Complete a recovery previously started for this hostname."),
-        preserveExistingCredentials: z.boolean().optional().describe("Explicitly keep old local credentials working (default: revoke them all).")
+        action: z2.enum(["start", "status", "complete"]),
+        hostname: z2.string().optional().describe("Required for start."),
+        verificationId: z2.string().optional().describe("Required for status or complete."),
+        preserveExistingCredentials: z2.boolean().optional().describe("Explicitly keep old local credentials working (default: revoke them all).")
       }
     },
     async (args) => {
       try {
-        if (args.verificationId === void 0) {
+        if (args.action === "start") {
+          if (!args.hostname) {
+            throw new SakupaError("invalid_request", "hostname is required for start");
+          }
           const res2 = await ctx.client.recoverDomain({ hostname: args.hostname });
           return text(
+            "domain_recovery_started",
             `Recovery started for ${args.hostname} (apex domain: ${res2.apexDomain}).
 
 Create this DNS record to prove apex-domain control:
@@ -1587,9 +1793,40 @@ ${res2.message}
 
 IMPORTANT: completing recovery revokes ALL previous local authorizations for this site by default (this protects you if the old project or its credential leaked). If you want to keep the old credentials working, pass preserveExistingCredentials: true when completing.
 
-After the DNS record resolves, re-run recover_domain_site with verificationId: "${res2.verificationId}".`
+After the DNS record resolves, re-run recover_domain_site with verificationId: "${res2.verificationId}".`,
+            {
+              verificationId: res2.verificationId,
+              apexDomain: res2.apexDomain,
+              verificationRecord: res2.verificationRecord,
+              revokesPreviousCredentialsByDefault: true
+            },
+            "waiting_user"
+          );
+        }
+        if (!args.verificationId) {
+          throw new SakupaError(
+            "invalid_request",
+            "verificationId is required for status or complete"
           );
         }
+        if (args.action === "status") {
+          const res2 = await ctx.client.getRecoveryStatus(args.verificationId);
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: res2.status === "expired" ? "expired" : res2.readyToComplete ? "completed" : "pending_provider",
+            resultCode: res2.status === "expired" ? "domain_recovery_expired" : res2.readyToComplete ? "domain_recovery_ready" : "domain_recovery_pending_dns",
+            summary: `DNS \u6062\u590D\u9A8C\u8BC1\u72B6\u6001\uFF1A${res2.status}`,
+            data: { recovery: res2 },
+            nextActions: [
+              {
+                tool: "recover_domain_site",
+                arguments: { action: "complete", verificationId: args.verificationId },
+                allowed: res2.readyToComplete,
+                ...res2.readyToComplete ? {} : { reasonCode: res2.status }
+              }
+            ]
+          });
+        }
         const res = await ctx.client.completeRecovery(args.verificationId, {
           ...args.preserveExistingCredentials !== void 0 ? { preserveExistingCredentials: args.preserveExistingCredentials } : {}
         });
@@ -1601,6 +1838,7 @@ After the DNS record resolves, re-run recover_domain_site with verificationId: "
           apiBaseUrl: ctx.apiBaseUrl
         });
         return text(
+          "domain_recovery_completed",
           `Recovery complete.
 Site: ${res.siteId} (hostnames: ${res.boundHostnames.join(", ") || "(none)"})
 Previous credentials revoked: ${res.revokedPreviousCredentials ? "YES" : "no (preserved on request)"}
@@ -1608,56 +1846,16 @@ Previous credentials revoked: ${res.revokedPreviousCredentials ? "YES" : "no (pr
 A NEW management credential was written to .sakupa/site.json in this project \u2014 this project now manages the site.
 ` + credentialGitReminder(ctx.projectDir) + `
 Download the current site content (signed URL):
-${res.archiveUrl}`
-        );
-      } catch (e) {
-        return toolError(e);
-      }
-    }
-  );
-  server.registerTool(
-    "set_billing_plan",
-    {
-      description: `Change this site's hosting plan, cancel/re-enable renewal, or cancel immediately. Plans: ${planCatalog()}. Plan changes go through the Stripe subscription; renewals bill the new plan. Auto-upgrade (one plan up when usage exceeds the current plan, capped at Business) is built in and not configurable. cancelRenewal: true ends the subscription at the period end; cancelNow: true ends it IMMEDIATELY \u2014 the site reverts to a free 24h site at once and all paid data (custom domain bindings included) is removed, with no refund of the current period. The API returns the consequences first; explicit owner confirmation (confirm: true) is required before anything is applied.`,
-      inputSchema: {
-        plan: planEnum.optional().describe("Target monthly plan."),
-        cancelRenewal: z.boolean().optional().describe(
-          "true: cancel renewal (the site stays permanent to the end of the paid month, then reverts to free). false: re-enable renewal."
-        ),
-        cancelNow: z.boolean().optional().describe("End the subscription immediately; the site reverts to free right away."),
-        confirm: z.boolean().optional().describe("User saw the consequences and explicitly confirmed.")
-      }
-    },
-    async (args) => {
-      try {
-        const site = requireSiteFile(ctx);
-        const req = {
-          ...args.plan !== void 0 ? { plan: args.plan } : {},
-          ...args.cancelRenewal !== void 0 ? { cancelRenewal: args.cancelRenewal } : {},
-          ...args.cancelNow !== void 0 ? { cancelNow: args.cancelNow } : {},
-          confirm: args.confirm === true
-        };
-        try {
-          const res = await ctx.client.setBillingPlan(site.siteId, site.credential, req);
-          return textJson(
-            `Billing updated for site ${res.siteId} (mode: ${res.mode}).
-Consequences:
-${res.consequences.map((c) => `- ${c}`).join("\n")}
-Result:`,
-            res
-          );
-        } catch (e) {
-          if (isSakupaError(e) && e.code === "confirmation_required") {
-            return text(
-              `Confirmation required before changing the billing plan \u2014 nothing was applied.
-
-${e.message}
-` + (e.details !== void 0 ? `${JSON.stringify(e.details, null, 2)}
-` : "") + "\nPlease show these consequences to the user and, after their explicit confirmation, re-run set_billing_plan with the same arguments plus confirm: true."
-            );
+${res.archiveUrl}`,
+          {
+            siteId: res.siteId,
+            boundHostnames: res.boundHostnames,
+            revokedPreviousCredentials: res.revokedPreviousCredentials,
+            archiveUrl: res.archiveUrl,
+            archiveExpiresAt: res.archiveExpiresAt,
+            credentialStoredLocally: true
           }
-          throw e;
-        }
+        );
       } catch (e) {
         return toolError(e);
       }
@@ -1667,11 +1865,13 @@ ${e.message}
     "create_support_ticket",
     {
       description: "Create a Sakupa support ticket for billing, payment, refund review, domain verification, deployment, serving or other issues the MCP cannot solve automatically. Do not include secrets, credentials or card data in the description.",
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       inputSchema: {
         category: ticketCategoryEnum,
-        subject: z.string().describe("Short subject line."),
-        description: z.string().describe("Problem description (no secrets, no card data)."),
-        contactEmail: z.string().optional().describe("Optional contact email for follow-up.")
+        subject: z2.string().describe("Short subject line."),
+        description: z2.string().describe("Problem description (no secrets, no card data)."),
+        contactEmail: z2.string().optional().describe("Optional contact email for follow-up.")
       }
     },
     async (args) => {
@@ -1684,7 +1884,11 @@ ${e.message}
           description: args.description,
           ...args.contactEmail !== void 0 ? { contactEmail: args.contactEmail } : {}
         });
-        return text(`Support ticket created: ${res.ticketId} (status: ${res.status}).`);
+        return text(
+          "support_ticket_created",
+          `Support ticket created: ${res.ticketId} (status: ${res.status}).`,
+          { ticketId: res.ticketId, status: res.status }
+        );
       } catch (e) {
         return toolError(e);
       }
@@ -1694,15 +1898,17 @@ ${e.message}
     "report_bug",
     {
       description: "Prepare and submit a sanitized bug report when a Sakupa tool failed and the issue looks like a product bug. Only whitelisted structured diagnostics are sent (tool name, error code/message, site id, bound domain, deployment id, timestamps, client/MCP version, request id) \u2014 NEVER file contents, source code, secrets, .env values or credentials. Without confirmSubmit: true the exact payload is shown for user review and nothing is submitted.",
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       inputSchema: {
-        toolName: z.string().describe('The Sakupa tool that failed, e.g. "deploy_site".'),
-        errorCode: z.string().optional(),
-        errorMessage: z.string().optional().describe("Sanitized error message (no secrets)."),
-        requestId: z.string().optional(),
-        deploymentId: z.string().optional(),
+        toolName: z2.string().describe('The Sakupa tool that failed, e.g. "deploy_site".'),
+        errorCode: z2.string().optional(),
+        errorMessage: z2.string().optional().describe("Sanitized error message (no secrets)."),
+        requestId: z2.string().optional(),
+        deploymentId: z2.string().optional(),
         severity: severityEnum.optional(),
-        description: z.string().optional().describe("What happened, in the user's words (no secrets)."),
-        confirmSubmit: z.boolean().optional().describe("User reviewed the report payload and approved submission.")
+        description: z2.string().optional().describe("What happened, in the user's words (no secrets)."),
+        confirmSubmit: z2.boolean().optional().describe("User reviewed the report payload and approved submission.")
       }
     },
     async (args) => {
@@ -1728,14 +1934,18 @@ ${e.message}
         };
         if (args.confirmSubmit !== true) {
           return textJson(
+            "bug_report_preview_ready",
             "Bug report prepared but NOT submitted. This is the exact payload that would be sent (structured diagnostics only \u2014 no file contents, source code or secrets). Please show it to the user; re-run report_bug with confirmSubmit: true to submit.",
-            payload
+            payload,
+            "preview"
           );
         }
         const res = await ctx.client.reportBug(payload, site?.credential);
         return text(
+          "bug_report_submitted",
           `Bug report submitted. Ticket: ${res.ticketId}
-Summary: ${res.sanitizedSummary}`
+Summary: ${res.sanitizedSummary}`,
+          { ticketId: res.ticketId, sanitizedSummary: res.sanitizedSummary }
         );
       } catch (e) {
         return toolError(e);
@@ -1744,6 +1954,132 @@ Summary: ${res.sanitizedSummary}`
   );
 }
 
+// src/tools/billing.ts
+import { z as z3 } from "zod";
+var plan = z3.enum(["water", "personal", "share", "business"]);
+var trigger = z3.enum(["actual_overage", "credential_automation"]);
+function registerBillingTools(server, ctx) {
+  server.registerTool(
+    "list_billing_plans",
+    {
+      description: "Return the authoritative Sakupa monthly plan catalog, exact limits, prices, catalog version and plan-change billing rules. This is read-only and does not require a site.",
+      inputSchema: {},
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
+    },
+    async () => {
+      try {
+        const catalog = await ctx.client.getBillingPlanCatalog();
+        return structuredToolResult({
+          schemaVersion: 1,
+          outcome: "completed",
+          resultCode: "billing_catalog_returned",
+          summary: `\u5DF2\u8FD4\u56DE ${catalog.plans.length} \u4E2A\u6708\u4ED8\u65B9\u6848\uFF1BStripe \u6258\u7BA1\u9875\u9762\u662F\u4ED8\u8D39\u4E0E\u6539\u6863\u7684\u6700\u7EC8\u786E\u8BA4\u5165\u53E3\u3002`,
+          data: { catalog },
+          nextActions: [{ tool: "subscribe_site", allowed: true }]
+        });
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+  server.registerTool(
+    "manage_subscription",
+    {
+      description: "Manage this site subscription through explicit actions. open_plan_change returns a Stripe-hosted confirmation URL. create_automation_authorization returns a short-lived Sakupa authorization URL binding the exact cap and triggers. disable_automation is immediate and owner-authorized. request_authorized_upgrade executes only under an existing exact grant, fresh usage snapshot, catalog version and server-side safety gates.",
+      inputSchema: {
+        action: z3.enum([
+          "open_plan_change",
+          "create_automation_authorization",
+          "disable_automation",
+          "request_authorized_upgrade"
+        ]),
+        operationId: z3.string().min(1).describe("Stable idempotency key chosen by the caller."),
+        targetPlan: plan.optional(),
+        maxPlan: plan.optional(),
+        allowedTriggers: z3.array(trigger).min(1).optional(),
+        observedSnapshotId: z3.string().optional(),
+        observedCatalogVersion: z3.string().optional()
+      },
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const site = requireSiteFile(ctx);
+        let request;
+        if (args.action === "open_plan_change") {
+          if (!args.targetPlan) {
+            throw new SakupaError("invalid_request", "targetPlan is required for open_plan_change");
+          }
+          request = {
+            action: args.action,
+            targetPlan: args.targetPlan,
+            operationId: args.operationId
+          };
+        } else if (args.action === "create_automation_authorization") {
+          if (!args.maxPlan || !args.allowedTriggers) {
+            throw new SakupaError(
+              "invalid_request",
+              "maxPlan and allowedTriggers are required for authorization"
+            );
+          }
+          request = {
+            action: args.action,
+            maxPlan: args.maxPlan,
+            allowedTriggers: args.allowedTriggers,
+            operationId: args.operationId
+          };
+        } else if (args.action === "disable_automation") {
+          request = { action: args.action, operationId: args.operationId };
+        } else {
+          if (!args.targetPlan) {
+            throw new SakupaError(
+              "invalid_request",
+              "targetPlan is required for request_authorized_upgrade"
+            );
+          }
+          request = {
+            action: args.action,
+            operationId: args.operationId,
+            targetPlan: args.targetPlan,
+            trigger: "credential_automation",
+            ...args.observedSnapshotId ? { observedSnapshotId: args.observedSnapshotId } : {},
+            ...args.observedCatalogVersion ? { observedCatalogVersion: args.observedCatalogVersion } : {}
+          };
+        }
+        const result = await ctx.client.manageSubscription(site.siteId, site.credential, request);
+        const portalUrl = "portalUrl" in result ? result.portalUrl : void 0;
+        const authorizationUrl = "authorizationUrl" in result ? result.authorizationUrl : void 0;
+        const executionOutcome = "outcome" in result ? result.outcome : void 0;
+        const outcome = portalUrl || authorizationUrl ? "waiting_user" : executionOutcome === "pending_provider" ? "pending_provider" : executionOutcome === "blocked" ? "blocked" : "completed";
+        const resultCode = "resultCode" in result ? result.resultCode : portalUrl ? "stripe_plan_change_confirmation_required" : authorizationUrl ? "automation_authorization_required" : args.action === "disable_automation" ? "automation_disabled" : "subscription_action_completed";
+        const url = portalUrl ?? authorizationUrl;
+        return structuredToolResult({
+          schemaVersion: 1,
+          outcome,
+          resultCode,
+          operationId: args.operationId,
+          summary: url ? "\u5DF2\u521B\u5EFA\u77ED\u65F6\u6548\u6258\u7BA1\u786E\u8BA4\u94FE\u63A5\uFF1B\u5F53\u524D\u8BA2\u9605\u5C1A\u672A\u56E0\u521B\u5EFA\u94FE\u63A5\u800C\u6539\u53D8\u3002" : `\u8BA2\u9605\u52A8\u4F5C\u7ED3\u679C\uFF1A${resultCode}`,
+          data: { action: args.action, result },
+          ...url ? {
+            userAction: {
+              type: "open_url",
+              provider: portalUrl ? "stripe" : "sakupa",
+              url,
+              ..."expiresAt" in result && typeof result.expiresAt === "string" ? { expiresAt: result.expiresAt } : {},
+              expectedOutcome: portalUrl ? "\u7528\u6237\u5728 Stripe \u6258\u7BA1\u9875\u9762\u786E\u8BA4\u540E\uFF0C\u7531 webhook \u66F4\u65B0 Sakupa \u72B6\u6001" : "\u7528\u6237\u5728 Sakupa \u77ED\u65F6\u6548\u9875\u9762\u786E\u8BA4\u7CBE\u786E\u81EA\u52A8\u5347\u7EA7\u6388\u6743"
+            }
+          } : {},
+          nextActions: [{ tool: "billing_status", allowed: true }]
+        });
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+}
+
 // src/transport.ts
 var FetchTransport = class {
   baseUrl;
@@ -1809,14 +2145,17 @@ Workflow:
    management credential in .sakupa/site.json. Deploying again updates the site and refreshes
    its validity; refresh_site extends validity without uploading.
 3. To make the site PERMANENT, subscribe it to a monthly hosting plan (subscribe_site ->
-   Stripe-hosted checkout; water/personal/share/business, auto-upgrade when the site outgrows
-   its plan). Paying makes the {shortId}.sakupa.com URL permanent \u2014 that is what payment buys.
+   Stripe-hosted checkout; water/personal/share/business). Paying makes the
+   {shortId}.sakupa.com URL permanent \u2014 that is what payment buys. Usage over the chosen plan
+   shows an over-limit notice by default. Automatic upgrades require a separate, bounded,
+   one-time Sakupa authorization and can never exceed the user-approved plan cap.
 4. Optionally bind a custom domain to the subscribed site (bind_domain): an included extra
    serving surface alongside the permanent URL. Ownership is proven only by DNS control; the
    first verified request wins; unverified requests expire after 72 hours. billing_status,
-   set_billing_plan, manage_billing and recover_domain_site manage the paid lifecycle.
-   Canceling the subscription immediately reverts the site to a free 24h site and removes all
-   paid data.
+   manage_subscription, manage_billing and recover_domain_site manage the paid lifecycle. Manual plan
+   changes are confirmed only on Stripe Customer Portal and synchronized by Stripe webhook.
+   A cancellation keeps the site paid through the current period. Sakupa reverts it to a free
+   24h site and removes paid data after Stripe sends the signed final-cancellation webhook.
 
 Safety boundaries:
 - Static output only: no SSR, API routes, middleware, server actions, databases or online builds.
@@ -1824,7 +2163,9 @@ Safety boundaries:
 - Payment card data is entered only on Stripe-hosted pages \u2014 never through the AI tool.
 - A subscription never grants domain ownership; only DNS verification does.
 - The management credential lives only in .sakupa/site.json; never share or upload it. Without
-  a bound custom domain, a lost credential is unrecoverable by design.`;
+  a bound custom domain, a lost credential is unrecoverable by design. manage_billing then opens
+  Stripe's public no-code portal login, where the customer verifies the checkout email with a
+  Stripe one-time passcode; it never restores site authority.`;
 function createSakupaMcpServer(opts) {
   const client = opts.client ?? new HttpApiClient(new FetchTransport(opts.apiBaseUrl));
   const server = new McpServer(
@@ -1836,6 +2177,11 @@ function createSakupaMcpServer(opts) {
     projectDir: opts.projectDir,
     apiBaseUrl: opts.apiBaseUrl
   });
+  registerBillingTools(server, {
+    client,
+    projectDir: opts.projectDir,
+    apiBaseUrl: opts.apiBaseUrl
+  });
   return server;
 }