@sakupa/mcp 1.1.0 → 1.2.0

package/dist/bin.js

@@ -402,7 +402,7 @@ function isFreeSiteAllowanceNetworkReference(value) {
 }
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "1.1.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";
@@ -2957,7 +2959,7 @@ import {
 
 // 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() {
@@ -2974,10 +2976,11 @@ 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;
@@ -3016,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, 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."
         )
       };
@@ -3046,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."
         )
       };
@@ -3072,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."
           )
         };
@@ -3097,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."
       )
     };
   }
@@ -3157,11 +3166,7 @@ function fileRootUriToPath(uri, windows = process.platform === "win32") {
 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(call)
-    );
+    return await withOperationTimeout("MCP Roots request", timeoutMs, () => provider(call));
   } catch (error) {
     if (error instanceof McpRootsPending) throw error;
     return {
@@ -3191,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)) };
@@ -3198,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}.`,
@@ -3432,7 +3464,12 @@ 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;
@@ -5698,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: [
@@ -6406,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
@@ -6496,7 +6535,13 @@ function createSakupaMcpServer(opts) {
     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);
@@ -6561,7 +6606,7 @@ async function main() {
     onerror: (error) => console.error("[sakupa-mcp] transport error:", error.message)
   });
   console.error(
-    `[sakupa-mcp] v${MCP_VERSION} serving stdio (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) => {

package/dist/index.js

@@ -147,7 +147,7 @@ function isFreeSiteAllowanceNetworkReference(value) {
 }
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "1.1.0";
+var SAKUPA_MCP_VERSION = "1.2.0";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -487,13 +487,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(
@@ -505,7 +507,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";
@@ -1543,7 +1545,7 @@ import {
 
 // src/project-binding.ts
 import { fileURLToPath } from "node:url";
-import { resolve as resolve3 } from "node:path";
+import { isAbsolute as isAbsolute2, resolve as resolve3 } from "node:path";
 
 // src/project-root.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
@@ -1783,10 +1785,11 @@ 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;
@@ -1825,28 +1828,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, 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."
         )
       };
@@ -1855,19 +1871,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."
         )
       };
@@ -1881,22 +1890,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."
           )
         };
@@ -1906,54 +1910,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."
       )
     };
   }
@@ -1966,11 +1975,7 @@ function fileRootUriToPath(uri, windows = process.platform === "win32") {
 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(call)
-    );
+    return await withOperationTimeout("MCP Roots request", timeoutMs, () => provider(call));
   } catch (error) {
     if (error instanceof McpRootsPending) throw error;
     return {
@@ -2000,6 +2005,31 @@ function inspectRoot(root) {
     };
   }
 }
+function inspectConfiguredRoot(configured) {
+  if (!isAbsolute2(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(resolve3(path)) };
@@ -2007,22 +2037,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}.`,
@@ -2241,7 +2273,12 @@ 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;
@@ -2418,7 +2455,7 @@ import { z as z2 } from "zod";
 // src/recovery-archive.ts
 import { existsSync as existsSync3, realpathSync as realpathSync2 } from "node:fs";
 import { mkdtemp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname as dirname2, isAbsolute as isAbsolute2, join as join4, relative as relative2, resolve as resolve4, sep as sep3 } from "node:path";
+import { dirname as dirname2, isAbsolute as isAbsolute3, join as join4, relative as relative2, resolve as resolve4, sep as sep3 } from "node:path";
 
 // ../../node_modules/fflate/esm/index.mjs
 import { createRequire } from "module";
@@ -2905,13 +2942,13 @@ function unzipSync(data, opts) {
 
 // src/recovery-archive.ts
 function safeOutputPath(projectDir, outputDir) {
-  if (outputDir.length === 0 || isAbsolute2(outputDir)) {
+  if (outputDir.length === 0 || isAbsolute3(outputDir)) {
     throw new SakupaError("invalid_request", "Recovery outputDir must be a relative directory");
   }
   const root = realpathSync2(resolve4(projectDir));
   const target = resolve4(root, outputDir);
   const rel = relative2(root, target);
-  if (rel === "" || rel === ".." || rel.startsWith(`..${sep3}`) || isAbsolute2(rel)) {
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep3}`) || isAbsolute3(rel)) {
     throw new SakupaError("invalid_request", "Recovery outputDir must stay inside projectDir");
   }
   if (rel === ".sakupa" || rel.startsWith(`.sakupa${sep3}`)) {
@@ -2926,7 +2963,7 @@ function safeOutputPath(projectDir, outputDir) {
   const physicalAncestor = realpathSync2(existingAncestor);
   const physicalTarget = resolve4(physicalAncestor, relative2(existingAncestor, target));
   const physicalRel = relative2(root, physicalTarget);
-  if (physicalRel === ".." || physicalRel.startsWith(`..${sep3}`) || isAbsolute2(physicalRel)) {
+  if (physicalRel === ".." || physicalRel.startsWith(`..${sep3}`) || isAbsolute3(physicalRel)) {
     throw new SakupaError(
       "invalid_request",
       "Recovery outputDir resolves through a symlink outside projectDir"
@@ -3292,7 +3329,7 @@ import {
   writeFileSync as writeFileSync5
 } from "node:fs";
 import { createHash } from "node:crypto";
-import { dirname as dirname5, isAbsolute as isAbsolute3, join as join7 } from "node:path";
+import { dirname as dirname5, isAbsolute as isAbsolute4, join as join7 } from "node:path";
 var HANDOFF_LOCK_TTL_MS = 15 * 60 * 1e3;
 function normalizeSiteUrl(raw) {
   const url = new URL(raw);
@@ -3319,7 +3356,7 @@ function resolveReusableSite(rawUrl, currentProjectDir, nowMs, apiBaseUrl) {
     throw new Error(`More than one local free-site record matches ${siteUrl}.`);
   const record = matches2[0];
   if (!record) throw new Error("The selected existing free site disappeared during resolution.");
-  if (!isAbsolute3(record.projectDir)) {
+  if (!isAbsolute4(record.projectDir)) {
     throw new Error("The selected free-site project path is not absolute; refusing cwd lookup.");
   }
   const sourceProjectDir = canonicalProjectDirectory(record.projectDir);
@@ -5817,7 +5854,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: [
@@ -6374,11 +6411,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
@@ -6464,7 +6503,13 @@ function createSakupaMcpServer(opts) {
     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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sakupa/mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "mcpName": "io.github.myerwang/sakupa",
   "description": "Sakupa MCP server: publish AI-made static sites from your AI tool. AI-made pages, live in seconds.",
   "homepage": "https://sakupa.com/manual/",