@sakupa/mcp 1.0.0 → 1.2.0

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/bin.ts
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { stdout } from "node:process";
 
 // src/project-root.ts
@@ -402,7 +402,7 @@ function isFreeSiteAllowanceNetworkReference(value) {
 }
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "1.0.0";
+var SAKUPA_MCP_VERSION = "1.2.0";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -738,13 +738,15 @@ function previewHostPatternFor(apiBaseUrl) {
 function loadMcpRuntimeConfig(env = process.env) {
   const apiBaseUrl = (env["SAKUPA_API_URL"] ?? env["SAKUPA_API_BASE_URL"] ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
   const testAccessToken = env["SAKUPA_TEST_ACCESS_TOKEN"]?.trim() ?? "";
+  const projectRoot = env["SAKUPA_PROJECT_ROOT"]?.trim() ?? "";
+  const projectRootConfig = projectRoot.length > 0 ? { projectRoot } : {};
   if (apiBaseUrl === TEST_API_BASE_URL) {
     if (testAccessToken.length === 0) {
       throw new Error(
         "The Sakupa Test API requires SAKUPA_TEST_ACCESS_TOKEN. Anonymous Test access is disabled."
       );
     }
-    return { apiBaseUrl, testAccessToken };
+    return { apiBaseUrl, testAccessToken, ...projectRootConfig };
   }
   if (apiBaseUrl !== PRODUCTION_API_BASE_URL) {
     throw new Error(
@@ -756,7 +758,7 @@ function loadMcpRuntimeConfig(env = process.env) {
       `SAKUPA_TEST_ACCESS_TOKEN may only be used with ${TEST_API_BASE_URL}. Remove it before connecting to any other API.`
     );
   }
-  return { apiBaseUrl };
+  return { apiBaseUrl, ...projectRootConfig };
 }
 function environmentFor(apiBaseUrl) {
   if (apiBaseUrl === TEST_API_BASE_URL) return "test";
@@ -765,7 +767,11 @@ function environmentFor(apiBaseUrl) {
 }
 
 // src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  CLIENT_CAPABILITIES_META_KEY,
+  McpServer,
+  inputResponse
+} from "@modelcontextprotocol/server";
 
 // src/api-client.ts
 var KNOWN_ERROR_CODES = /* @__PURE__ */ new Set([
@@ -2946,10 +2952,21 @@ async function resumeCredentialRotation(client, projectDir, site, apiBaseUrl) {
   };
 }
 
+// src/tools/context.ts
+import {
+  inputRequired
+} from "@modelcontextprotocol/server";
+
 // src/project-binding.ts
 import { fileURLToPath } from "node:url";
-import { resolve as resolve4 } from "node:path";
+import { isAbsolute as isAbsolute4, resolve as resolve4 } from "node:path";
 var MCP_ROOTS_TIMEOUT_MS = 5e3;
+var McpRootsPending = class extends Error {
+  constructor() {
+    super("MCP Roots must be requested from the client before the project can be bound.");
+    this.name = "McpRootsPending";
+  }
+};
 var ProjectBindingError = class extends Error {
   diagnostics;
   constructor(diagnostics) {
@@ -2959,18 +2976,19 @@ var ProjectBindingError = class extends Error {
   }
 };
 var ProjectBindingResolver = class {
-  constructor(processCwd, rootsProvider, rootsTimeoutMs = MCP_ROOTS_TIMEOUT_MS) {
+  constructor(processCwd, rootsProvider, rootsTimeoutMs = MCP_ROOTS_TIMEOUT_MS, configuredRoot) {
     this.processCwd = processCwd;
     this.rootsProvider = rootsProvider;
     this.rootsTimeoutMs = rootsTimeoutMs;
+    this.configuredRoot = configuredRoot;
   }
   bound;
   boundState;
   resolving;
-  async resolve() {
+  async resolve(call) {
     if (this.bound) return this.bound;
     if (this.resolving) return this.resolving;
-    this.resolving = this.inspect().then((inspection) => {
+    this.resolving = this.inspect(false, call).then((inspection) => {
       if (!inspection.selected) throw new ProjectBindingError(inspection.diagnostics);
       this.bound = inspection.selected;
       this.boundState = inspection.diagnostics;
@@ -2980,18 +2998,18 @@ var ProjectBindingResolver = class {
     });
     return this.resolving;
   }
-  async diagnose() {
+  async diagnose(call) {
     if (this.bound) return this.boundState ?? boundDiagnostics(this.processCwd, this.bound);
-    const inspection = await this.inspect();
+    const inspection = await this.inspect(false, call);
     if (inspection.selected) {
       this.bound = inspection.selected;
       this.boundState = inspection.diagnostics;
     }
     return inspection.diagnostics;
   }
-  async initialize() {
+  async initialize(call) {
     if (this.bound) return this.bound;
-    const inspection = await this.inspect(true);
+    const inspection = await this.inspect(true, call);
     if (inspection.selected) {
       this.bound = inspection.selected;
       this.boundState = inspection.diagnostics;
@@ -3001,28 +3019,41 @@ var ProjectBindingResolver = class {
       throw new ProjectBindingError(inspection.diagnostics);
     }
     const initialized = initializeProject(inspection.initializableRoot);
-    this.bound = { ...initialized, bindingSource: "mcp_root" };
+    this.bound = {
+      ...initialized,
+      bindingSource: inspection.initializableSource ?? "mcp_root"
+    };
     this.boundState = boundDiagnostics(
       this.processCwd,
       this.bound,
-      { supported: true, roots: [] },
-      inspection.diagnostics.rootCandidates
+      { supported: inspection.diagnostics.mcpRootsSupported, roots: [] },
+      inspection.diagnostics.rootCandidates,
+      inspection.diagnostics.configuredProjectRoot
     );
     return this.bound;
   }
-  async inspect(forInitialization = false) {
-    const snapshot = await safeRootsSnapshot(this.rootsProvider, this.rootsTimeoutMs);
+  async inspect(forInitialization = false, call) {
+    const snapshot = await safeRootsSnapshot(this.rootsProvider, this.rootsTimeoutMs, call);
     const rootCandidates = snapshot.roots.map(inspectRoot);
+    const configured = this.configuredRoot === void 0 ? void 0 : inspectConfiguredRoot(this.configuredRoot);
+    const diagnose = (code, guidance) => diagnostic(code, snapshot, this.processCwd, rootCandidates, guidance, configured);
+    const bound = (selected) => ({
+      selected,
+      diagnostics: boundDiagnostics(
+        this.processCwd,
+        selected,
+        snapshot,
+        rootCandidates,
+        configured
+      )
+    });
     const initializedRoots = rootCandidates.filter(
       (candidate) => candidate.initialized && candidate.path !== void 0
     );
     if (snapshot.supported && snapshot.error) {
       return {
-        diagnostics: diagnostic(
+        diagnostics: diagnose(
           "roots_request_failed",
-          snapshot,
-          this.processCwd,
-          rootCandidates,
           "The IDE advertised MCP Roots, but the Roots request failed. Retry help after the IDE finishes loading the workspace. If it persists, restart the MCP connection; do not initialize or deploy from the IDE installation directory."
         )
       };
@@ -3031,19 +3062,12 @@ var ProjectBindingResolver = class {
       const initializedRoot = initializedRoots[0];
       if (!initializedRoot) throw new Error("initialized Root disappeared during resolution");
       const project = resolveLockedProjectRoot(initializedRoot.path);
-      const selected = { ...project, bindingSource: "mcp_root" };
-      return {
-        selected,
-        diagnostics: boundDiagnostics(this.processCwd, selected, snapshot, rootCandidates)
-      };
+      return bound({ ...project, bindingSource: "mcp_root" });
     }
     if (initializedRoots.length > 1) {
       return {
-        diagnostics: diagnostic(
+        diagnostics: diagnose(
           "multiple_initialized_roots",
-          snapshot,
-          this.processCwd,
-          rootCandidates,
           "More than one IDE workspace Root is already initialized for Sakupa. Close the unrelated workspaces and retry help; Sakupa will not guess which site to manage."
         )
       };
@@ -3057,22 +3081,17 @@ var ProjectBindingResolver = class {
         if (!validRoot) throw new Error("workspace Root disappeared during initialization");
         return {
           initializableRoot: validRoot.path,
-          diagnostics: diagnostic(
+          initializableSource: "mcp_root",
+          diagnostics: diagnose(
             "workspace_not_initialized",
-            snapshot,
-            this.processCwd,
-            rootCandidates,
             `The active MCP workspace ${validRoot.path} is ready to initialize.`
           )
         };
       }
       if (validRoots.length > 1) {
         return {
-          diagnostics: diagnostic(
+          diagnostics: diagnose(
             "multiple_uninitialized_roots",
-            snapshot,
-            this.processCwd,
-            rootCandidates,
             "The IDE exposes multiple uninitialized workspace Roots. Open only the intended project before calling init; Sakupa will not choose a directory for the user."
           )
         };
@@ -3082,54 +3101,59 @@ var ProjectBindingResolver = class {
       const validRoot = validRoots[0];
       if (!validRoot) throw new Error("workspace Root disappeared during diagnosis");
       return {
-        diagnostics: diagnostic(
+        diagnostics: diagnose(
           "workspace_not_initialized",
-          snapshot,
-          this.processCwd,
-          rootCandidates,
           `The IDE workspace ${validRoot.path} is not initialized. Call init with no path arguments; it will create .sakupa directly in that workspace Root.`
         )
       };
     }
     if (snapshot.supported && validRoots.length > 1) {
       return {
-        diagnostics: diagnostic(
+        diagnostics: diagnose(
           "multiple_uninitialized_roots",
-          snapshot,
-          this.processCwd,
-          rootCandidates,
           "The IDE exposes multiple uninitialized workspace Roots. Open only the intended project, then call init. Sakupa will not guess a project directory."
         )
       };
     }
+    if (configured) {
+      if (configured.problem !== void 0 || configured.path === void 0) {
+        return {
+          diagnostics: diagnose(
+            "invalid_configured_root",
+            `SAKUPA_PROJECT_ROOT is set to ${configured.configured} but it is not usable: ${configured.problem ?? "unknown problem"}. Fix the MCP server configuration (an absolute path to an existing project directory) and retry help; Sakupa will not fall back to another directory.`
+          )
+        };
+      }
+      if (configured.initialized) {
+        const project = resolveLockedProjectRoot(configured.path);
+        return bound({ ...project, bindingSource: "configured_root" });
+      }
+      return {
+        ...forInitialization ? { initializableRoot: configured.path, initializableSource: "configured_root" } : {},
+        diagnostics: diagnose(
+          "workspace_not_initialized",
+          `The configured project root ${configured.path} (SAKUPA_PROJECT_ROOT) is not initialized. Call init with no path arguments; it will create .sakupa directly there.`
+        )
+      };
+    }
     if (snapshot.supported) {
       return {
-        diagnostics: diagnostic(
+        diagnostics: diagnose(
           "workspace_not_initialized",
-          snapshot,
-          this.processCwd,
-          rootCandidates,
           "The IDE did not expose one usable file workspace Root. Open exactly one local project workspace, then retry help before calling init or deploy."
         )
       };
     }
     try {
       const cwdProject = resolveLockedProjectRoot(this.processCwd);
-      const selected = { ...cwdProject, bindingSource: "process_cwd" };
-      return {
-        selected,
-        diagnostics: boundDiagnostics(this.processCwd, selected, snapshot, rootCandidates)
-      };
+      return bound({ ...cwdProject, bindingSource: "process_cwd" });
     } catch {
     }
     const cwdProblem = inspectDirectory(this.processCwd);
     return {
-      diagnostics: diagnostic(
+      diagnostics: diagnose(
         cwdProblem.problem ? "invalid_process_cwd" : "process_cwd_is_not_workspace",
-        snapshot,
-        this.processCwd,
-        rootCandidates,
-        "This IDE did not provide MCP Roots and the MCP process cwd is not an initialized project. Do not write into the IDE installation directory. Run help from the intended project context. If help confirms the missing-Roots diagnosis, the AI may run `npx -y @sakupa/mcp@latest init` with no path arguments from that directory. Never ask the user to run it."
+        "This IDE did not provide MCP Roots, SAKUPA_PROJECT_ROOT is not configured, and the MCP process cwd is not an initialized project. Do not write into the IDE installation directory. Run help from the intended project context. If help confirms the missing-Roots diagnosis, the AI may run `npx -y @sakupa/mcp@latest init` with no path arguments from that directory, or the MCP server configuration may set SAKUPA_PROJECT_ROOT to the absolute project path. Never ask the user to run it."
       )
     };
   }
@@ -3139,11 +3163,12 @@ function fileRootUriToPath(uri, windows = process.platform === "win32") {
   if (parsed.protocol !== "file:") throw new Error("Root URI is not a file URI");
   return fileURLToPath(parsed, { windows });
 }
-async function safeRootsSnapshot(provider, timeoutMs = MCP_ROOTS_TIMEOUT_MS) {
+async function safeRootsSnapshot(provider, timeoutMs = MCP_ROOTS_TIMEOUT_MS, call) {
   if (!provider) return { supported: false, roots: [] };
   try {
-    return await withOperationTimeout("MCP Roots request", timeoutMs, () => provider());
+    return await withOperationTimeout("MCP Roots request", timeoutMs, () => provider(call));
   } catch (error) {
+    if (error instanceof McpRootsPending) throw error;
     return {
       supported: true,
       roots: [],
@@ -3171,6 +3196,31 @@ function inspectRoot(root) {
     };
   }
 }
+function inspectConfiguredRoot(configured) {
+  if (!isAbsolute4(configured)) {
+    return {
+      configured,
+      initialized: false,
+      problem: "the value must be an absolute path"
+    };
+  }
+  try {
+    const path = canonicalProjectDirectory(configured);
+    const marker = loadProjectMarker(path);
+    return {
+      configured,
+      path,
+      initialized: marker.kind === "ok",
+      ...marker.kind === "corrupted" ? { problem: marker.problem } : {}
+    };
+  } catch (error) {
+    return {
+      configured,
+      initialized: false,
+      problem: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
 function inspectDirectory(path) {
   try {
     return { path: canonicalProjectDirectory(resolve4(path)) };
@@ -3178,22 +3228,24 @@ function inspectDirectory(path) {
     return { problem: error instanceof Error ? error.message : String(error) };
   }
 }
-function diagnostic(diagnosisCode, snapshot, processCwd, rootCandidates, guidance) {
+function diagnostic(diagnosisCode, snapshot, processCwd, rootCandidates, guidance, configured) {
   return {
     diagnosisCode,
     mcpRootsSupported: snapshot.supported,
     processCwd,
     rootCandidates,
+    ...configured ? { configuredProjectRoot: configured } : {},
     guidance,
     reportRecommended: false
   };
 }
-function boundDiagnostics(processCwd, selected, snapshot = { supported: false, roots: [] }, rootCandidates = []) {
+function boundDiagnostics(processCwd, selected, snapshot = { supported: false, roots: [] }, rootCandidates = [], configured) {
   return {
     diagnosisCode: "project_bound",
     mcpRootsSupported: snapshot.supported,
     processCwd,
     rootCandidates,
+    ...configured ? { configuredProjectRoot: configured } : {},
     selectedProjectDir: selected.projectDir,
     bindingSource: selected.bindingSource,
     guidance: `Sakupa is locked to ${selected.projectDir} from ${selected.bindingSource}.`,
@@ -3221,7 +3273,7 @@ var TARGET_MCP_TOOL_NAMES = [
   "support",
   "report"
 ];
-var STRUCTURED_TOOL_OUTPUT_SCHEMA = {
+var STRUCTURED_TOOL_OUTPUT_SCHEMA = z.object({
   schemaVersion: z.literal(1),
   outcome: z.enum([
     "completed",
@@ -3303,7 +3355,7 @@ var STRUCTURED_TOOL_OUTPUT_SCHEMA = {
       reasonCode: z.string().optional()
     })
   )
-};
+});
 function structuredToolResult(envelope) {
   const clientTimeZone = clientRuntimeTimeZone();
   const presentation = {
@@ -3412,14 +3464,19 @@ function resolverFor(ctx) {
   if (ctx.projectBinding) return ctx.projectBinding;
   let resolver = fallbackResolvers.get(ctx);
   if (!resolver) {
-    resolver = new ProjectBindingResolver(ctx.projectDir, ctx.rootsProvider);
+    resolver = new ProjectBindingResolver(
+      ctx.projectDir,
+      ctx.rootsProvider,
+      MCP_ROOTS_TIMEOUT_MS,
+      ctx.configuredProjectRoot
+    );
     fallbackResolvers.set(ctx, resolver);
   }
   return resolver;
 }
-async function withProjectDir(ctx) {
+async function withProjectDir(ctx, call) {
   try {
-    const binding = await resolverFor(ctx).resolve();
+    const binding = await resolverFor(ctx).resolve(call);
     const resolved = resolveLockedProjectRoot(binding.projectDir);
     return {
       ...ctx,
@@ -3442,12 +3499,12 @@ async function withProjectDir(ctx) {
     throw error;
   }
 }
-async function diagnoseProjectBinding(ctx) {
-  return resolverFor(ctx).diagnose();
+async function diagnoseProjectBinding(ctx, call) {
+  return resolverFor(ctx).diagnose(call);
 }
-async function initializeWorkspaceProject(ctx) {
+async function initializeWorkspaceProject(ctx, call) {
   try {
-    const resolved = await resolverFor(ctx).initialize();
+    const resolved = await resolverFor(ctx).initialize(call);
     return {
       ...ctx,
       projectDir: resolved.projectDir,
@@ -3463,10 +3520,11 @@ async function initializeWorkspaceProject(ctx) {
     throw error;
   }
 }
-async function optionalProjectContext(ctx) {
+async function optionalProjectContext(ctx, call) {
   try {
-    return await withProjectDir(ctx);
-  } catch {
+    return await withProjectDir(ctx, call);
+  } catch (error) {
+    if (error instanceof McpRootsPending) throw error;
     return null;
   }
 }
@@ -3514,6 +3572,9 @@ function requireSiteFile(ctx) {
 }
 var UNAUTHORIZED_SUMMARY = "The server rejected the site credential: the one in .sakupa/site.json no longer matches the server-side verifier. The site itself is intact on the server \u2014 only the local binding file is the problem. Repair the file (restore a backup or undo the local edit). Do NOT delete the .sakupa directory to work around this: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site.";
 function toolError(e) {
+  if (e instanceof McpRootsPending) {
+    return inputRequired({ inputRequests: { roots: inputRequired.listRoots() } });
+  }
   const isSakupa = isSakupaError(e);
   const errorCode = isSakupa ? e.code : "internal";
   const rawDetails = isSakupaError(e) && e.details && typeof e.details === "object" ? e.details : void 0;
@@ -4030,13 +4091,13 @@ function registerTools(server, baseCtx) {
       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.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
-      inputSchema: {
+      inputSchema: z2.object({
         outputDir: z2.string().optional().describe("Output directory relative to the project root (overrides detection).")
-      }
+      })
     },
-    async (args) => {
+    async (args, call) => {
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         const analysis = await analyzeProject(ctx.projectDir, {
           ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {}
         });
@@ -4057,7 +4118,7 @@ Next action: ${analysis.suggestedNextAction}`,
       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://${previewHostPattern}) and stores the management credential in .sakupa/site.json. Later runs update the existing site (free sites also refresh their validity; subscription-backed sites have no free-site expiry while the subscription remains active). Runs analyze first and refuses to upload source projects, secrets, .env files, archives, media or server code. The MCP process is locked to the current directory initialized by the no-argument init MCP tool; no tool argument can change that root. outputDir is a separate REQUIRED relative path supplied from the current project inspection. Never uploads anything when analysis says the project is not deployable.`,
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
-      inputSchema: {
+      inputSchema: z2.object({
         outputDir: z2.string().min(1).describe(
           'REQUIRED: exact publish directory relative to the initialized project root, supplied by the AI after inspecting this project (for example ".", "dist", "html", or any custom build directory). Sakupa applies it only inside the cwd-locked project.'
         ),
@@ -4083,12 +4144,12 @@ Next action: ${analysis.suggestedNextAction}`,
           "Deprecated compatibility field. Project independence is established only by `sakupa-mcp init`, never inferred from package.json or folder names."
         ),
         lang: z2.string().optional().describe("Site language override (en | ja | zh-CN); defaults to the html lang.")
-      }
+      })
     },
-    async (args) => {
+    async (args, call) => {
       let releaseHandoffLock;
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         const analysis = await analyzeProject(ctx.projectDir, { outputDir: args.outputDir });
         if (!analysis.deployable || !analysis.files) {
           return notDeployableResult(analysis);
@@ -4713,11 +4774,11 @@ Optional security recommendation: this management credential was created at ${ti
       description: "Refresh the validity of the free temporary site WITHOUT uploading content. Uses the local credential in .sakupa/site.json. Subscription-backed sites have no free-site expiry while the subscription remains active and need no refresh.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-      inputSchema: {}
+      inputSchema: z2.object({})
     },
-    async () => {
+    async (_args, call) => {
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.refreshSite(site.siteId, site.credential);
         if (site.url) {
@@ -4746,11 +4807,11 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
       description: "Show the current status of this project's Sakupa site: URL, mode (free/paid), expiry, custom domains, size, last deployment and warnings. For a paid site this tool also automatically returns the complete authoritative billing snapshot; users never need to know or name a separate billing tool to get accurate subscription information.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
-      inputSchema: {}
+      inputSchema: z2.object({})
     },
-    async () => {
+    async (_args, call) => {
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.getSiteStatus(site.siteId, site.credential);
         noteSiteMode(res.siteId, res.mode);
@@ -4777,15 +4838,15 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
       description: `Create a Stripe Checkout link that subscribes THIS site to a Sakupa Hosting monthly plan (${planCatalog()}). While the subscription remains active, its ${previewHostPattern} URL stays live without the free 24-hour expiry. Binding a custom domain afterwards (bind) 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 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: {
+      inputSchema: z2.object({
         plan: planEnum.describe(
           "Monthly plan: water (very light personal pages), personal (personal brand / small shop), share (small-business site), business (steadier traffic, more headroom)."
         )
-      }
+      })
     },
-    async (args) => {
+    async (args, call) => {
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.createPlanCheckout(
           {
@@ -4823,17 +4884,17 @@ Once Stripe confirms payment and Sakupa synchronizes the subscription, the curre
       description: `Bind a custom domain to this subscribed site \u2014 an OPTIONAL extra serving surface; the subscription-backed ${previewHostPattern} URL keeps working alongside it while the subscription is active. The binding unit is the APEX domain: binding example.com reserves routes for example.com and www.example.com, but ONLY www is required and judged for activation; the naked apex is optional because many DNS providers cannot point it. One apex TXT verification covers both. A site has one FINAL apex domain; starting a different apex begins a zero-downtime switch and the previous domain remains until the new www is live. The www CNAME must remain while bound. Requires an ACTIVE subscription (subscribe). Ownership is proven ONLY by DNS control of the apex \u2014 payment never grants ownership, and bindings are ALWAYS challengeable: whoever proves CURRENT DNS control takes the domain, even from an existing binding (the displaced site keeps its subscription, content and subscription-backed Sakupa URL). Unverified requests expire after 72 hours. Call again with action "status" to check progress.`,
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
-      inputSchema: {
+      inputSchema: z2.object({
         action: z2.enum(["start", "status"]),
         hostname: z2.string().optional().describe("Required for start."),
         verificationId: z2.string().optional().describe(
           "Optional for status: when omitted, the server finds this site's latest binding verification \u2014 a NEW session can resume without it."
         )
-      }
+      })
     },
-    async (args) => {
+    async (args, call) => {
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         const site = requireSiteFile(ctx);
         if (args.action === "status") {
           const res2 = args.verificationId ? await ctx.client.checkVerification(args.verificationId, site.credential) : await ctx.client.checkVerification("latest", site.credential, site.siteId);
@@ -4962,11 +5023,11 @@ When the user says the TXT is set, run bind "status". It verifies ownership and
       description: "Return the sole authoritative source for this site's hosting subscription: current plan, next renewal plan or cancellation, effective time, payment state, current paid entitlement, reconciled paid usage or current free-site fair-use telemetry, 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: {}
+      inputSchema: z2.object({})
     },
-    async () => {
+    async (_args, call) => {
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.getBillingStatus(site.siteId, site.credential);
         noteSiteMode(res.siteId, res.mode);
@@ -5006,14 +5067,14 @@ Full status:`, res);
       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: {
+      inputSchema: z2.object({
         scope: z2.enum(["site", "public_recovery"])
-      }
+      })
     },
-    async (args) => {
+    async (args, call) => {
       try {
         if (args.scope === "site") {
-          const ctx = await withProjectDir(baseCtx);
+          const ctx = await withProjectDir(baseCtx, call);
           const site = requireSiteFile(ctx);
           const res2 = await ctx.client.createBillingPortal(site.siteId, site.credential);
           return structuredToolResult({
@@ -5062,7 +5123,7 @@ Full status:`, res);
       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. Recovery is resumable: start stores local pending state; complete installs and writes the new .sakupa/site.json credential BEFORE requesting content; download uses that credential to reissue an archive and safely extract it into the explicitly selected outputDir without repeating DNS.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
-      inputSchema: {
+      inputSchema: z2.object({
         action: z2.enum(["start", "status", "complete", "download"]),
         hostname: z2.string().optional().describe("Required for start."),
         verificationId: z2.string().optional().describe("For status or complete; inferred from local recovery state when omitted."),
@@ -5070,11 +5131,11 @@ Full status:`, res);
           "REQUIRED for complete/download: exact extraction directory relative to the initialized project root. Inspect the current project; Sakupa never guesses a name."
         ),
         preserveExistingCredentials: z2.boolean().optional().describe("Explicitly keep old local credentials working (default: revoke them all).")
-      }
+      })
     },
-    async (args) => {
+    async (args, call) => {
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         if ((args.action === "complete" || args.action === "download") && args.outputDir === void 0) {
           throw new LocalGuidanceError(
             "invalid_request",
@@ -5423,16 +5484,16 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
       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: {
+      inputSchema: z2.object({
         category: ticketCategoryEnum,
         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) => {
+    async (args, call) => {
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.createTicket(site.credential, {
           siteId: site.siteId,
@@ -5457,7 +5518,7 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
       description: "LAST RESORT after help explicitly returns reportRecommended:true. Prepare and submit a sanitized product bug report using helpAuthorization from that diagnosis. 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: {
+      inputSchema: z2.object({
         toolName: z2.string().describe('The Sakupa tool that failed, e.g. "deploy".'),
         helpAuthorization: z2.string().describe("Short-lived authorization returned only by help when report is recommended."),
         errorCode: z2.string().optional(),
@@ -5473,12 +5534,12 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
           "OPTIONAL. Before submitting, ask the user ONCE whether they want to leave a contact for follow-up. Omit entirely if they decline \u2014 never require it."
         ),
         confirmSubmit: z2.boolean().optional().describe("User reviewed the report payload and approved submission.")
-      }
+      })
     },
-    async (args) => {
+    async (args, call) => {
       try {
         requireReportAuthorization(baseCtx, args.helpAuthorization, args.toolName);
-        const ctx = await optionalProjectContext(baseCtx);
+        const ctx = await optionalProjectContext(baseCtx, call);
         const siteState = ctx ? loadSiteFile(ctx.projectDir) : { kind: "absent" };
         const site = siteState.kind === "ok" ? siteState.file : null;
         const diagnostics = {
@@ -5558,11 +5619,11 @@ function registerBillingTools(server, baseCtx) {
     "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: {},
+      inputSchema: z3.object({}),
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
     },
-    async () => {
+    async (_args, call) => {
       try {
         const catalog = await baseCtx.client.getBillingPlanCatalog();
         return structuredToolResult({
@@ -5582,15 +5643,15 @@ function registerBillingTools(server, baseCtx) {
     "change",
     {
       description: "Create one Stripe-hosted subscription-management link. The user chooses the plan or period-end cancellation on Stripe; Sakupa never infers intent from the conversation. Creating the link does not change billing.",
-      inputSchema: {
+      inputSchema: z3.object({
         operationId: z3.string().min(1)
-      },
+      }),
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true }
     },
-    async (args) => {
+    async (args, call) => {
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         const site = requireSiteFile(ctx);
         const result = await ctx.client.changeSubscriptionPlan(site.credential, {
           siteId: site.siteId,
@@ -5674,7 +5735,7 @@ var TOOL_MANUALS = {
   init: {
     purpose: "Initialize the active IDE workspace as one Sakupa project.",
     sideEffects: "Creates only .sakupa/project.json locally; no API call, site or charge.",
-    preconditions: "Exactly one usable MCP workspace Root. If Roots are unavailable, help may authorize the AI to use CLI init.",
+    preconditions: "Exactly one usable MCP workspace Root, or the SAKUPA_PROJECT_ROOT directory configured for this server when the client provides no Roots. If neither exists, help may authorize the AI to use CLI init.",
     parameterNames: [],
     parameters: "No parameters and no path argument.",
     warnings: [
@@ -5873,13 +5934,13 @@ function registerHelpTools(server, baseCtx) {
     "init",
     {
       description: "Initialize the active MCP workspace Root as a Sakupa project. Takes no path argument, creates only .sakupa/project.json at that exact Root, preserves site/recovery state, makes no API call and is idempotent. If MCP Roots are unavailable, call help; the AI may then use the no-argument CLI init itself.",
-      inputSchema: {},
+      inputSchema: z4.object({}),
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async () => {
+    async (_args, call) => {
       try {
-        const ctx = await initializeWorkspaceProject(baseCtx);
+        const ctx = await initializeWorkspaceProject(baseCtx, call);
         const marker = loadProjectMarker(ctx.projectDir);
         if (marker.kind !== "ok")
           throw new Error("init postcondition failed: project marker missing");
@@ -5913,17 +5974,17 @@ function registerHelpTools(server, baseCtx) {
     "help",
     {
       description: "FIRST troubleshooting tool for every Sakupa difficulty. With topic diagnose (default), inspect MCP Roots, cwd, binding and local state without requiring a project or calling the API. Use overview, terminology, or a tool name for complete usage, side effects, parameters and warnings. Only recommend report when help explicitly returns reportRecommended:true.",
-      inputSchema: {
+      inputSchema: z4.object({
         topic: z4.enum(HELP_TOPICS).optional().default("diagnose"),
         failedTool: z4.string().optional(),
         errorCode: z4.string().optional(),
         resultCode: z4.string().optional(),
         requestId: z4.string().optional()
-      },
+      }),
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
     },
-    async (args) => {
+    async (args, call) => {
       try {
         if (args.topic === "overview") {
           const catalog = Object.fromEntries(
@@ -5985,7 +6046,7 @@ Terminology: ${terminologyText}` : ""),
             nextActions: []
           });
         }
-        const diagnosis = await diagnoseProjectBinding(baseCtx);
+        const diagnosis = await diagnoseProjectBinding(baseCtx, call);
         const selected = diagnosis.selectedProjectDir;
         const marker = selected ? loadProjectMarker(selected) : { kind: "absent" };
         const site = selected ? loadSiteFile(selected) : { kind: "absent" };
@@ -6064,18 +6125,18 @@ function registerCredentialTools(server, baseCtx) {
     "rotate",
     {
       description: "Optionally rotate this site management credential. The first call is a read-only preview. Only confirmed:true after explicit user approval installs a locally generated new credential and revokes every previous credential. Rotation is never required to deploy.",
-      inputSchema: {
+      inputSchema: z5.object({
         confirmed: z5.boolean().optional().describe(
           "True only after showing the rotate preview and the user explicitly approves revoking every old credential."
         )
-      },
+      }),
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
     },
-    async (args) => {
+    async (args, call) => {
       let releaseLock;
       try {
-        const ctx = await withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx, call);
         let site = requireSiteFile(ctx);
         const pending = loadCredentialRotation(ctx.projectDir);
         if (pending.kind !== "absent" || args.confirmed === true) {
@@ -6382,11 +6443,13 @@ language. Keep option IDs, tool names, exact arguments, URLs, field names and co
 unchanged.
 
 Project directory contract: before the first deploy or a new recovery, CALL the init MCP tool with
-NO path argument. init uses the IDE's exact MCP Root and creates the non-secret
+NO path argument. init uses the IDE's exact MCP Root \u2014 or, when the client provides no Roots, the
+SAKUPA_PROJECT_ROOT directory configured for this MCP server \u2014 and creates the non-secret
 .sakupa/project.json directly there. Do not merely print installation or CLI instructions when the
-init tool is available. Only after help confirms that the client does not provide MCP Roots may the
-AI itself use the CLI command "npx -y @sakupa/mcp@latest init" as a fallback; never ask the user to
-run it. The CLI also accepts NO path argument. ONE MCP process = ONE Roots-first locked project = ONE site.
+init tool is available. Only after help confirms that the client provides neither MCP Roots nor
+SAKUPA_PROJECT_ROOT may the AI itself use the CLI command "npx -y @sakupa/mcp@latest init" as a
+fallback; never ask the user to run it. The CLI also accepts NO path argument. ONE MCP process = ONE
+locked project = ONE site.
 Site tools do not accept projectDir and cannot select another root; help, plans and report preview
 and public_recovery portal remain project-independent.
 Sakupa stores .sakupa/site.json and recovery state only in the locked directory; it never uses
@@ -6466,29 +6529,19 @@ function createSakupaMcpServer(opts) {
     { instructions: instructionsFor(previewHostPatternFor(opts.apiBaseUrl)) }
   );
   const processCwd = resolve6(opts.projectDir ?? process.cwd());
-  const rootsProvider = opts.rootsProvider ?? (async () => {
-    const capabilities = server.server.getClientCapabilities();
-    if (!capabilities?.roots) return { supported: false, roots: [] };
-    try {
-      const response = await server.server.listRoots(void 0, {
-        timeout: MCP_ROOTS_TIMEOUT_MS,
-        maxTotalTimeout: MCP_ROOTS_TIMEOUT_MS
-      });
-      return { supported: true, roots: response.roots };
-    } catch (error) {
-      return {
-        supported: true,
-        roots: [],
-        error: error instanceof Error ? error.message : String(error)
-      };
-    }
-  });
+  const rootsProvider = opts.rootsProvider ?? ((call) => readClientRoots(server, call));
   const ctx = {
     client,
     apiBaseUrl: opts.apiBaseUrl,
     projectDir: processCwd,
     rootsProvider,
-    projectBinding: new ProjectBindingResolver(processCwd, rootsProvider)
+    ...opts.projectRoot !== void 0 ? { configuredProjectRoot: opts.projectRoot } : {},
+    projectBinding: new ProjectBindingResolver(
+      processCwd,
+      rootsProvider,
+      MCP_ROOTS_TIMEOUT_MS,
+      opts.projectRoot
+    )
   };
   registerTools(server, ctx);
   registerBillingTools(server, ctx);
@@ -6496,6 +6549,38 @@ function createSakupaMcpServer(opts) {
   registerHelpTools(server, ctx);
   return server;
 }
+async function readClientRoots(server, call) {
+  if (call?.mcpReq.envelope !== void 0) {
+    const envelope = call.mcpReq.envelope;
+    const declared = envelope[CLIENT_CAPABILITIES_META_KEY];
+    if (!declared?.roots) return { supported: false, roots: [] };
+    const answered = inputResponse(call.mcpReq.inputResponses, "roots");
+    if (answered.kind === "roots") return { supported: true, roots: answered.roots };
+    if (call.mcpReq.inputResponses !== void 0) {
+      return {
+        supported: true,
+        roots: [],
+        error: "The client retried without answering the embedded roots/list request."
+      };
+    }
+    throw new McpRootsPending();
+  }
+  const capabilities = server.server.getClientCapabilities();
+  if (!capabilities?.roots) return { supported: false, roots: [] };
+  try {
+    const response = await server.server.listRoots(void 0, {
+      timeout: MCP_ROOTS_TIMEOUT_MS,
+      maxTotalTimeout: MCP_ROOTS_TIMEOUT_MS
+    });
+    return { supported: true, roots: response.roots };
+  } catch (error) {
+    return {
+      supported: true,
+      roots: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
 
 // src/bin.ts
 async function main() {
@@ -6508,15 +6593,20 @@ async function main() {
     process.exitCode = result.exitCode;
     return;
   }
+  if (argv[0] === "--version" || argv[0] === "-v") {
+    stdout.write(`${MCP_VERSION}
+`);
+    return;
+  }
   if (argv.length > 0) {
-    throw new Error("Usage: sakupa-mcp [init]");
+    throw new Error("Usage: sakupa-mcp [init | --version]");
   }
   const config = loadMcpRuntimeConfig();
-  const server = createSakupaMcpServer(config);
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  serveStdio(() => createSakupaMcpServer(config), {
+    onerror: (error) => console.error("[sakupa-mcp] transport error:", error.message)
+  });
   console.error(
-    `[sakupa-mcp] v${MCP_VERSION} connected (api: ${config.apiBaseUrl}; process cwd fallback: ${process.cwd()}; MCP Roots preferred)`
+    `[sakupa-mcp] v${MCP_VERSION} serving stdio (api: ${config.apiBaseUrl}; configured root: ${config.projectRoot ?? "none"}; process cwd fallback: ${process.cwd()}; MCP Roots preferred)`
   );
 }
 main().catch((err2) => {