constructor-research-mcp 0.3.2 → 0.4.0-beta.2

package/dist/files.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { lstat, open, readdir, readFile } from "node:fs/promises";
 import { basename, join } from "node:path";
+import { localPath } from "./desk.js";
 import { ToolError } from "./api.js";
 import { listFilesInput, createFolderInput, syncFilesInput, movePathInput, deletePathInput, } from "./schemas.js";
 /** Single PUTs above ~9 MB are rejected with 413, so larger files go in ranged chunks. */
@@ -201,8 +202,20 @@ export class FileManager {
             ? `Cannot create ${parts.join("/")}: a parent path is missing or is a file.`
             : `Folder creation returned HTTP ${r.status}.`, r.status);
     }
+    /** The desk this MCP runs inside, when `desk` is it. */
+    here(desk) {
+        const d = this.api.config.localDesk;
+        return d && d.deskId === desk ? d : undefined;
+    }
+    /** File tools never touch the desk the MCP runs in: its files are local. */
+    notHere(desk) {
+        const d = this.here(desk);
+        if (d)
+            throw new ToolError("local_desk", `This MCP runs inside desk ${desk}: its disk is the local folder ${d.root}. Read and change files there directly with your own file and shell tools; nothing needs uploading. When the Dockerfile is ready, call deploy_app or build_image with the Dockerfile path inside ${d.root} (for example /Dockerfile).`);
+    }
     async list(raw) {
         const i = listFilesInput.parse(raw);
+        this.notHere(i.desk_id);
         await this.engine.filesDesk(i.project_id, i.desk_id);
         const start = segs(i.path);
         const entries = [];
@@ -238,6 +251,7 @@ export class FileManager {
     }
     async createFolder(raw) {
         const i = createFolderInput.parse(raw);
+        this.notHere(i.desk_id);
         await this.engine.filesDesk(i.project_id, i.desk_id);
         const parts = segs(i.path);
         const created = [];
@@ -255,6 +269,7 @@ export class FileManager {
     }
     async move(raw) {
         const i = movePathInput.parse(raw);
+        this.notHere(i.desk_id);
         await this.engine.filesDesk(i.project_id, i.desk_id);
         const desk = i.desk_id;
         const plan = [];
@@ -318,6 +333,7 @@ export class FileManager {
     }
     async remove(raw) {
         const i = deletePathInput.parse(raw);
+        this.notHere(i.desk_id);
         await this.engine.filesDesk(i.project_id, i.desk_id);
         const desk = i.desk_id;
         const targets = [];
@@ -374,6 +390,7 @@ export class FileManager {
     }
     async sync(raw) {
         const i = syncFilesInput.parse(raw);
+        this.notHere(i.desk_id);
         const begun = Date.now();
         await this.engine.filesDesk(i.project_id, i.desk_id);
         const desk = i.desk_id;
@@ -597,7 +614,7 @@ export class FileManager {
             }
             catch (err) {
                 if (err instanceof ToolError &&
-                    ["needs_auth", "connection_error"].includes(err.code)) {
+                    ["needs_key", "connection_error"].includes(err.code)) {
                     stop ??= err;
                     remaining++;
                     return;
@@ -632,6 +649,11 @@ export class FileManager {
         const missing = [];
         const warnings = [];
         for (const b of sources) {
+            const local = this.here(b.desk_id);
+            if (local) {
+                await this.checkLocal(local, b, missing, warnings);
+                continue;
+            }
             await this.engine.filesDesk(project, b.desk_id);
             const parts = segs(b.dockerfile);
             const r = await this.api.storage("GET", b.desk_id, href(parts));
@@ -661,6 +683,29 @@ export class FileManager {
         }
         return { missing, warnings: [...new Set(warnings)] };
     }
+    /** The same checks as on a disk, for the desk this MCP runs in: its files are local. */
+    async checkLocal(desk, b, missing, warnings) {
+        const parts = segs(b.dockerfile);
+        let text;
+        try {
+            text = (await readFile(localPath(desk, b.dockerfile), "utf8")).slice(0, 256 * 1024);
+        }
+        catch {
+            missing.push(`${b.service}: ${parts.join("/")} (in ${desk.root})`);
+            return;
+        }
+        warnings.push(...lintDockerfile(parts.join("/"), text, b.ports).map((w) => `${b.service}: ${w}`));
+        const dir = parts.slice(0, -1);
+        for (const conf of configsCopied(text)) {
+            const body = await readFile(localPath(desk, [...dir, ...segs(conf)].join("/")), "utf8").then((t) => t.slice(0, 64 * 1024), () => "");
+            if (/^\s*listen\s+\[::\]/m.test(body))
+                warnings.push(`${b.service}: ${conf} has "listen [::]". nginx exits on start when the cluster has no IPv6; keep only the IPv4 listen line (listen <port>;).`);
+        }
+        const names = await readdir(localPath(desk, dir.join("/"))).catch(() => []);
+        for (const name of names)
+            if (/^(docker-)?compose\.ya?ml$/.test(name))
+                warnings.push(`${b.service}: ${[...dir, name].join("/")} is ignored; docker-compose is not supported, so each service is configured in deploy_app.`);
+    }
     /** Upload to a fresh temp file, move it over the target, then verify the server checksum. */
     async upload(desk, f, target, replace) {
         const tmp = [TEMP, TEMP_PREFIX + randomUUID()];

package/dist/key.d.ts

@@ -0,0 +1,9 @@
+/** A saved key and the Constructor it belongs to. */
+export interface SavedKey {
+    url: string;
+    key: string;
+}
+/** The saved key, or undefined when none was saved. A broken file throws. */
+export declare function readKeyFile(file: string): Promise<SavedKey | undefined>;
+/** Saves the key for one Constructor, mode 600, replacing the file in one step. */
+export declare function saveKeyFile(file: string, url: string, key: string): Promise<void>;

package/dist/key.js

@@ -0,0 +1,35 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { originOf } from "./config.js";
+/** The saved key, or undefined when none was saved. A broken file throws. */
+export async function readKeyFile(file) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return undefined;
+        throw new Error("unreadable");
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        // Never echo the contents: they hold the key.
+        throw new Error("not valid JSON");
+    }
+    if (typeof data?.key !== "string" || typeof data?.url !== "string")
+        throw new Error("expected url and key");
+    return { url: originOf(data.url), key: data.key };
+}
+/** Saves the key for one Constructor, mode 600, replacing the file in one step. */
+export async function saveKeyFile(file, url, key) {
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    await writeFile(tmp, JSON.stringify({ url: originOf(url), key }) + "\n", {
+        mode: 0o600,
+    });
+    await rename(tmp, file);
+}

package/dist/location.d.ts

@@ -2,7 +2,9 @@ import { z } from "zod";
 /** Where a tool acts: a desk (project + desk), a project only, or a deployment-shaped input whose schema already allows a missing project_id. */
 export type Scope = "desk" | "project" | "deploy";
 /** Tool-facing schema: the engine schema plus desk_url, with the IDs it supplies made optional. */
-export declare function located(schema: z.ZodObject<any>, scope: Exclude<Scope, "deploy">): z.ZodObject<{
+export declare function located(schema: z.ZodObject<any>, scope: Exclude<Scope, "deploy">, 
+/** Inside a desk the IDs default to it, so neither a link nor IDs are required. */
+implied?: boolean): z.ZodObject<{
     [x: string]: any;
     project_id: z.ZodOptional<z.ZodString>;
     desk_id?: z.ZodOptional<z.ZodString> | undefined;

package/dist/location.js

@@ -1,7 +1,17 @@
 import { ToolError } from "./api.js";
+import { VERSION } from "./config.js";
 import { id, deskUrl } from "./schemas.js";
 /** Tool-facing schema: the engine schema plus desk_url, with the IDs it supplies made optional. */
-export function located(schema, scope) {
+export function located(schema, scope, 
+/** Inside a desk the IDs default to it, so neither a link nor IDs are required. */
+implied = false) {
+    const extended = schema.extend({
+        project_id: id.optional(),
+        ...("desk_id" in schema.shape ? { desk_id: id.optional() } : {}),
+        desk_url: deskUrl.optional(),
+    });
+    if (implied)
+        return extended;
     return schema
         .extend({
         project_id: id.optional(),
@@ -34,8 +44,8 @@ export function parseDeskUrl(link, baseUrl, fixed = false) {
     const base = new URL(baseUrl).origin;
     if (url.origin !== base)
         bad("wrong_environment", fixed
-            ? `The link is for ${url.origin}, but this MCP is fixed to ${base} by CONSTRUCTOR_BASE_URL. Ask the user for a link from ${base}.`
-            : `The link is for ${url.origin}, but the user is signed in to ${base}. If they work on ${url.origin}, tell them a sign-in window is about to open, then call sign_in with url set to this link; that replaces the sign-in to ${base}.`);
+            ? `The link is for ${url.origin}, but this MCP is fixed to ${base} by CONSTRUCTOR_BASE_URL or the desk it runs in. Ask the user for a link from ${base}.`
+            : `The link is for ${url.origin}, but the saved access key is for ${base}. If they work on ${url.origin}, the user saves a key for it in a terminal (it replaces the key for ${base}): npx -y -p constructor-research-mcp@${VERSION} constructor-research-set-key ${url.origin}. Never ask for the key in the chat.`);
     return { project_id: m[1], desk_id: m[2] };
 }
 /** Replace desk_url with the IDs it carries; explicit IDs must agree with it. */

package/dist/logs.js

@@ -188,9 +188,9 @@ export class LogFollower {
             catch (err) {
                 if (signal.aborted)
                     return;
-                if (err instanceof ToolError && err.code === "needs_auth") {
+                if (err instanceof ToolError && err.code === "needs_key") {
                     log.error =
-                        "The token expired while following this build log; the lines below may be incomplete.";
+                        "Constructor rejected the access key while following this build log; the lines below may be incomplete.";
                     return;
                 }
                 if (++failures > 8) {

package/dist/runtime.js

@@ -3,7 +3,7 @@ import { terminal } from "./deployment.js";
 import { ToolError } from "./api.js";
 import { waitCommand } from "./config.js";
 import { buildInput, deployInput, updateInput, lifecycleInput, getInput, } from "./schemas.js";
-export const paused = new Set(["needs_auth", "needs_upload"]);
+export const paused = new Set(["needs_key", "needs_upload"]);
 /** Tells the agent which unfinished deployments a new one ended, and what they changed that it does not. */
 function replacedNote(replaced) {
     if (!replaced?.length)
@@ -73,7 +73,7 @@ export class DeploymentRuntime {
             await this.engine.api.withBudget(15000, () => this.engine.get({ ...i, resume: true }));
         }
         let op = await this.engine.store.load(i.deployment_id);
-        if (op?.status === "needs_auth" &&
+        if (op?.status === "needs_key" &&
             i.resume &&
             i.files_uploaded === undefined) {
             await this.pause(i.deployment_id);
@@ -210,8 +210,8 @@ export class DeploymentRuntime {
                     : "background",
             next_action: op.status === "failed"
                 ? "Tell the user which stage/service failed and pass on the message. failure.log_tail has the last log lines when the MCP captured them; get_logs shows more. Do not investigate using browser or other tools."
-                : op.status === "needs_auth"
-                    ? `${this.engine.api.authHelp("The token expired or is invalid.")} Then check this deployment again.`
+                : op.status === "needs_key"
+                    ? `${this.engine.api.keyHelp("Constructor rejected the access key, or none is set.")} Then check this deployment again.`
                     : op.status === "needs_upload"
                         ? "Upload the listed files with sync_files, then call get_deployment with files_uploaded=true."
                         : op.status === "confirm_required"

package/dist/schemas.d.ts

@@ -225,8 +225,3 @@ export declare const syncFilesInput: z.ZodObject<{
     dry_run: z.ZodDefault<z.ZodBoolean>;
     confirm: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
-export declare const signInInput: z.ZodObject<{
-    url: z.ZodOptional<z.ZodString>;
-    wait_seconds: z.ZodDefault<z.ZodNumber>;
-    force: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strict>;

package/dist/schemas.js

@@ -257,21 +257,3 @@ export const syncFilesInput = z.strictObject({
         .default(false)
         .describe("Needed only when existing files would be replaced: the first call returns the list for the user to approve once; repeat with confirm=true."),
 });
-export const signInInput = z.strictObject({
-    url: z
-        .string()
-        .max(2000)
-        .optional()
-        .describe("Any link to the user's Constructor: a desk link, or just its address, e.g. https://acme.constructor.app. The user signs in there and the MCP works there afterwards, replacing any earlier sign-in. Pass it when the user names their Constructor or gives a link; omit it to sign in where the MCP works now (https://constructor.app unless the user signed in elsewhere)."),
-    wait_seconds: z
-        .number()
-        .int()
-        .min(0)
-        .max(25)
-        .default(20)
-        .describe("How long to wait for the user to finish signing in."),
-    force: z
-        .boolean()
-        .default(false)
-        .describe("Open the window even though a renewable session is saved (to switch account)."),
-});

package/dist/server.js

@@ -1,21 +1,33 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { configFromEnv, originOf, VERSION } from "./config.js";
+import { configFromEnv, VERSION } from "./config.js";
 import { PlatformApi, ToolError } from "./api.js";
 import { StateStore } from "./store.js";
-import { DeploymentEngine, terminal } from "./deployment.js";
+import { DeploymentEngine } from "./deployment.js";
 import { DeploymentRuntime } from "./runtime.js";
 import { FileManager, dockerignore } from "./files.js";
 import { basename } from "node:path";
 import { LogFollower } from "./logs.js";
 const RULES = "Dockerfile rules: one Dockerfile per service named Dockerfile or <name>.dockerfile; docker-compose is not supported. The Dockerfile must build everything itself; no separate setup script the user runs before the build. The app listens on 0.0.0.0 on a fixed port; only one port per service can be public. Services reach each other through internal references (bare host:port by default, http:// only when scheme is set), never localhost; do not bake compose-style fallback hosts (http://db:5432) into ENV. Files uploaded to a desk lose the executable bit: RUN chmod 0755 any entrypoint script you COPY. In nginx configs use only the IPv4 listen line. A volume belongs to one service; services cannot share a volume. Volume data survives restarts and image changes but is wiped if the service is deleted or the volume is removed or changed. The build context is the folder containing the Dockerfile, exactly like a local docker build in that folder. Test the image locally (docker build/run) before uploading.";
 import { located, resolveDeskUrl } from "./location.js";
+import { deskInstructions, diskPath } from "./desk.js";
+/** Tools whose project and desk default to the desk the MCP runs inside. */
+const DESK_DEFAULT = new Set([
+    "build_image",
+    "list_images",
+    "list_files",
+    "create_folder",
+    "sync_files",
+    "move_path",
+    "delete_path",
+    "deploy_app",
+    "update_app",
+    "start_app",
+    "stop_app",
+]);
 import { ZodError } from "zod";
-import { buildInput, listInput, deployInput, updateInput, lifecycleInput, getInput, logsInput, listFilesInput, createFolderInput, syncFilesInput, movePathInput, deletePathInput, signInInput, } from "./schemas.js";
-import { harnessOf, sessionFile } from "./config.js";
-import { sessionHost } from "./session.js";
-import { signIn } from "./signin.js";
+import { buildInput, listInput, deployInput, updateInput, lifecycleInput, getInput, logsInput, listFilesInput, createFolderInput, syncFilesInput, movePathInput, deletePathInput, } from "./schemas.js";
 async function main() {
     const config = configFromEnv();
     const api = new PlatformApi(config);
@@ -38,6 +50,28 @@ async function main() {
                     services.push(x);
                     continue;
                 }
+                // Inside the desk the MCP runs in, its project folder is the disk: nothing to upload.
+                const here = config.localDesk;
+                if (here && b.desk_id === here.deskId) {
+                    const at = diskPath(here, b.local_path);
+                    if (!at)
+                        throw new ToolError("invalid_input", `Service ${x.name}: local_path ${b.local_path} is outside this desk's project folder ${here.root}, which is the desk's disk. Move the sources into ${here.root}, then call again.`);
+                    const { local_path: _l, remote_path: _r, ...rest } = b;
+                    services.push({
+                        ...x,
+                        build: {
+                            ...rest,
+                            dockerfile: "/" +
+                                [
+                                    ...at.split("/"),
+                                    ...(b.dockerfile ?? "Dockerfile").split("/"),
+                                ]
+                                    .filter(Boolean)
+                                    .join("/"),
+                        },
+                    });
+                    continue;
+                }
                 if (!b.desk_id || !a.project_id)
                     throw new ToolError("invalid_input", `Service ${x.name}: local_path needs a disk. Pass desk_url (the desk link from the user) or build.desk_id with project_id.`);
                 const remote = (b.remote_path ?? basename(b.local_path))
@@ -117,12 +151,17 @@ async function main() {
             }
             : result;
     };
+    /** Inside a desk, the agent edits its files in place instead of asking for a desk link. */
+    const withDesk = (text) => config.localDesk
+        ? text.replace(/Where to act: ask the user for the Constructor desk link.*?if the user has not said where to deploy or where files live, ask\. /, deskInstructions(config.localDesk) + " ")
+        : text;
     const server = new McpServer({ name: "constructor-research", version: VERSION }, {
-        instructions: `Sign-in: the MCP works with one Constructor, https://constructor.app unless the user signed in to another. When the user asks to sign in, or names their Constructor or gives a link from it (e.g. https://acme.constructor.app), call sign_in with url set to that link. Where to act: ask the user for the Constructor desk link (they open the desk in the browser and copy the address; it contains /projects/<project>/desks/<desk>) and pass it as desk_url. Do not pick a project or desk yourself; if the user has not said where to deploy or where files live, ask. Ask the user only before replacing, renaming or deleting files on a disk, once per request for the whole list (the tools return confirm_required); creating folders and uploading new files need no question. ${RULES} For a local app, pass build.local_path (the folder with the Dockerfile) and deploy_app uploads it first. Hardware: leave it out; the default is used. Set hardware minimums only when the app cannot run without a GPU or a lot of RAM. Use deploy_app/update_app once for the WHOLE application. The MCP builds, resolves service URLs, configures and starts services in the background. IDs are automatic. To wait, call get_deployment(wait_seconds=20) again as often as needed (a loop of such calls is fine); never perform the deployment steps yourself. When the user asks to deploy or build, wait until the deployment is finished before answering, then give the public URL or what failed. On failure, tell the user the failed stage/service; failure.log_tail and get_logs show the last build or service log lines. Do not use browser or debugging tools. For source files: sync_files to the desk before building (the MCP checks each Dockerfile on the disk and reports warnings); after a needs_upload pause, sync and call get_deployment with files_uploaded=true. Started is not readiness.`,
+        instructions: withDesk(`Access: the MCP works with one Constructor and the user's personal access key for it, set up outside the chat. When a tool returns needs_key, pass its instructions on to the user; never ask for the key in the chat. Where to act: ask the user for the Constructor desk link (they open the desk in the browser and copy the address; it contains /projects/<project>/desks/<desk>) and pass it as desk_url. Do not pick a project or desk yourself; if the user has not said where to deploy or where files live, ask. Ask the user only before replacing, renaming or deleting files on a disk, once per request for the whole list (the tools return confirm_required); creating folders and uploading new files need no question. ${RULES} For a local app, pass build.local_path (the folder with the Dockerfile) and deploy_app uploads it first. Hardware: leave it out; the default is used. Set hardware minimums only when the app cannot run without a GPU or a lot of RAM. Use deploy_app/update_app once for the WHOLE application. The MCP builds, resolves service URLs, configures and starts services in the background. IDs are automatic. To wait, call get_deployment(wait_seconds=20) again as often as needed (a loop of such calls is fine); never perform the deployment steps yourself. When the user asks to deploy or build, wait until the deployment is finished before answering, then give the public URL or what failed. On failure, tell the user the failed stage/service; failure.log_tail and get_logs show the last build or service log lines. Do not use browser or debugging tools. For source files: sync_files to the desk before building (the MCP checks each Dockerfile on the disk and reports warnings); after a needs_upload pause, sync and call get_deployment with files_uploaded=true. Started is not readiness.`),
     });
     const register = (name, description, schema, fn, readOnly = false, budget = 20000, scope) => {
+        const here = config.localDesk && DESK_DEFAULT.has(name) ? config.localDesk : undefined;
         if (scope && scope !== "deploy")
-            schema = located(schema, scope);
+            schema = located(schema, scope, !!here);
         server.registerTool(name, {
             description,
             inputSchema: schema,
@@ -134,41 +173,21 @@ async function main() {
             },
         }, async (args) => {
             try {
-                await api.followSession();
-                // Nobody signed in yet: a desk link names the Constructor to sign in to.
-                if (args?.desk_url &&
-                    !config.baseUrlFixed &&
-                    !(await sessionHost(config.cookieFile)))
-                    try {
-                        api.aimed = config.baseUrl = originOf(args.desk_url);
-                    }
-                    catch { }
-                // Do not start a change on a token about to expire; checking on a deployment is still fine.
-                const before = await api.authLeft().catch(() => undefined);
-                const what = (renewable) => renewable ? "The login session ends" : "The token expires";
-                if (!readOnly &&
-                    name !== "get_deployment" &&
-                    name !== "sign_in" &&
-                    before !== undefined &&
-                    before.minutes < 3)
-                    throw new ToolError("needs_auth", api.authHelp(`${what(before.renewable)} in ${Math.max(0, Math.floor(before.minutes))} min, too soon to start this operation.`));
-                let result = await api.withBudget(budget, () => fn(scope
-                    ? resolveDeskUrl(args, config.baseUrl, scope, config.baseUrlFixed)
+                await api.refresh();
+                const result = await api.withBudget(budget, () => fn(scope
+                    ? resolveDeskUrl(
+                    // Inside a desk, a call that names no other desk acts on it.
+                    here &&
+                        !args?.desk_url &&
+                        (!args?.project_id ||
+                            args.project_id === here.projectId) &&
+                        (!args?.desk_id || args.desk_id === here.deskId)
+                        ? {
+                            ...args,
+                            desk_url: `${config.baseUrl}/research/projects/${here.projectId}/desks/${here.deskId}`,
+                        }
+                        : args, config.baseUrl, scope, config.baseUrlFixed)
                     : args));
-                const left = await api.authLeft().catch(() => undefined);
-                // A build can take half an hour; warn while there is still time to sign in again.
-                // A renewable session warns a day ahead.
-                const builds = ["deploy_app", "update_app", "build_image"].includes(name);
-                const limit = left?.renewable ? 24 * 60 : builds ? 40 : 10;
-                if (left !== undefined && left.minutes > 0 && left.minutes < limit)
-                    result = {
-                        ...result,
-                        auth_warning: `${what(left.renewable)} in ${left.minutes >= 120
-                            ? `${Math.floor(left.minutes / 60)} h`
-                            : `${Math.floor(left.minutes)} min`}${builds && !terminal.has(result.status)
-                            ? "; builds often take 10–30 min, and when it ends the deployment pauses as needs_auth until the user signs in again"
-                            : ""}. Ask the user to sign in again now: ${api.authHelp("")}`,
-                    };
                 return {
                     content: [
                         {
@@ -176,10 +195,7 @@ async function main() {
                             text: result.text ??
                                 (result.status
                                     ? `${result.status}${result.deployment_id ? ` (${result.deployment_id})` : ""}${result.message ? `: ${result.message}` : ""}`
-                                    : `Discovery result: ${result.total !== undefined ? result.total + " images" : Object.keys(result).join(", ")}. See structuredContent for details.`) +
-                                    (result.auth_warning
-                                        ? ` Warning: ${result.auth_warning}`
-                                        : ""),
+                                    : `Discovery result: ${result.total !== undefined ? result.total + " images" : Object.keys(result).join(", ")}. See structuredContent for details.`),
                         },
                     ],
                     // A preformatted text (build logs) is not repeated in structuredContent.
@@ -226,62 +242,7 @@ async function main() {
     register("update_app", "Update/add selected services in one request; preserve omitted settings. MCP handles builds, links and restarts in the background. Environment variables merge; supplied port/volume lists replace their lists. Resume a failed update using deployment_id and service overrides. The Dockerfile rules in deploy_app apply.", updateInput, checked((a) => runtime.update(a)), false, 60000, "deploy");
     register("start_app", "Start all or selected services as one operation. MCP handles all requests. Waits up to wait_seconds (default 20); remaining execution continues in the background. Started does not mean ready.", lifecycleInput, (a) => runtime.lifecycle("start", a), false, 20000, "project");
     register("stop_app", "Stop all or selected services as one operation. MCP handles all requests. Waits up to wait_seconds (default 20). Stopped means stop requests accepted, not verified teardown.", lifecycleInput, (a) => runtime.lifecycle("stop", a), false, 20000, "project");
-    register("get_deployment", "With deployment_id, observe/wait for background execution; the MCP owns execution. Each call waits up to wait_seconds (max 20); to wait longer, call again, as often as needed (a loop of get_deployment calls is fine), until execution is finished; do not answer the user while it is still in the background. Services carry status_changes and restarts_seen when the MCP saw the status change or a new container start. After sync_files (or manual upload) set files_uploaded=true; after cookie replacement checking the job resumes it. With no arguments, returns the map of all deployments: every deployment-enabled project with its applications and services (names, native statuses, public URLs, ports). With desk_url or project_id, returns that project's desks, images, hardware and applications; add application_id for one application. resume=false observes only. Never returns environment-variable values.", getInput, (a) => runtime.get(a), false, 20000, "deploy");
-    let signing;
-    register("sign_in", "Signs the user in to their Constructor: https://constructor.app unless url names another one (any link from it, e.g. https://acme.constructor.app). Call it when the user asks to sign in, or when a tool returns needs_auth, after telling the user a sign-in window is about to open. It opens a separate Chrome window at the sign-in page; the user signs in there and the window closes by itself. There is one sign-in at a time: signing in to another Constructor replaces it, and the MCP works there afterwards. The session is kept for this harness only, and the MCP renews it automatically for up to 14 days. Waits up to wait_seconds; while the user is still signing in it returns sign_in_pending: call it again (no second window opens), then repeat the call that needed auth.", signInInput, async (a) => {
-        const i = signInInput.parse(a);
-        if (!signing) {
-            let host = config.baseUrl;
-            if (i.url) {
-                try {
-                    host = originOf(i.url);
-                }
-                catch (e) {
-                    throw new ToolError("invalid_input", `url: ${e.message}`);
-                }
-                if (config.baseUrlFixed && host !== config.baseUrl)
-                    throw new ToolError("wrong_environment", `This MCP is fixed to ${config.baseUrl} by CONSTRUCTOR_BASE_URL; it cannot sign in to ${host}.`);
-            }
-            const signedIn = (await sessionHost(config.cookieFile)) === host;
-            const left = signedIn
-                ? await api.authLeft().catch(() => undefined)
-                : undefined;
-            if (!i.force && left?.renewable && left.minutes > 60)
-                return {
-                    status: "signed_in",
-                    message: `Already signed in to ${host}; the session renews automatically for another ${Math.floor(left.minutes / 1440)} days. Pass force=true to sign in again.`,
-                    session_file: config.cookieFile,
-                    host,
-                };
-            const state = {
-                done: false,
-                host,
-                promise: Promise.resolve(),
-            };
-            state.promise = signIn({ ...config, baseUrl: host }, config.cookieFile).then((r) => {
-                state.result = r;
-                state.done = true;
-                if (r.status === "signed_in")
-                    api.aimed = undefined;
-            });
-            signing = state;
-            api.signingIn = true;
-            void state.promise.finally(() => (api.signingIn = false));
-        }
-        const current = signing;
-        await Promise.race([
-            current.promise,
-            new Promise((r) => setTimeout(r, i.wait_seconds * 1000)),
-        ]);
-        if (!current.done)
-            return {
-                status: "sign_in_pending",
-                message: `A Chrome window is open at ${current.host}. Ask the user to sign in there; it closes by itself afterwards. Then call sign_in again to confirm, or repeat the call that needed auth.`,
-            };
-        signing = undefined;
-        await api.followSession();
-        return current.result;
-    }, true, 30000);
+    register("get_deployment", "With deployment_id, observe/wait for background execution; the MCP owns execution. Each call waits up to wait_seconds (max 20); to wait longer, call again, as often as needed (a loop of get_deployment calls is fine), until execution is finished; do not answer the user while it is still in the background. Services carry status_changes and restarts_seen when the MCP saw the status change or a new container start. After sync_files (or manual upload) set files_uploaded=true; after a new key is saved, checking the job resumes it. With no arguments, returns the map of all deployments: every deployment-enabled project with its applications and services (names, native statuses, public URLs, ports). With desk_url or project_id, returns that project's desks, images, hardware and applications; add application_id for one application. resume=false observes only. Never returns environment-variable values.", getInput, (a) => runtime.get(a), false, 20000, "deploy");
     register("get_logs", "Last lines (default 20, up to 50) of a build or service log: why a build or start failed, how far a long build got, what a starting service prints. Constructor serves logs only live: a build log while the build runs, a service log for its current container while it runs (both replayed from the start, then streamed). The MCP follows the builds and services it starts or shows and keeps their last 50 lines, so they stay readable after the build ends or the container restarts; anything else can be read only while it runs. When a new container starts, the lines of the one before stay, above a '--- new container' marker, and restarts_seen counts them: that answers whether a service keeps restarting and why. An empty service log on a running service usually means a crash loop.", logsInput, async (a) => {
         const i = logsInput.parse(a);
         let targets = [];
@@ -333,14 +294,11 @@ async function main() {
         process.once(signal, () => {
             void Promise.all([runtime.close(), logs.close()]).then(() => server.close());
         });
-    // Each harness keeps its own session, named after the client in the handshake.
     let recovered = false;
     server.server.oninitialized = () => {
-        if (!config.cookieFileFixed)
-            config.cookieFile = sessionFile(harnessOf(server.server.getClientVersion()?.name));
         if (!recovered) {
             recovered = true;
-            void api.followSession().finally(() => runtime.recover());
+            void api.refresh().finally(() => runtime.recover());
         }
     };
     await server.connect(new StdioServerTransport());

package/dist/set-key.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/set-key.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// Save a personal access key for the MCP without it appearing in the chat, a command line or the
+// shell history: the key is read from the terminal (hidden) or from stdin.
+// Usage: npx -y -p constructor-research-mcp constructor-research-set-key <Constructor link>
+import { configFromEnv, originOf } from "./config.js";
+import { cleanKey } from "./api.js";
+import { saveKeyFile } from "./key.js";
+const USAGE = "Usage: npx -y -p constructor-research-mcp constructor-research-set-key <Constructor link, e.g. https://acme.constructor.app>\nThen paste the access key (rk-…) when asked, or pipe it in on stdin.";
+/** One line from the terminal without echoing it, or all of stdin when piped. */
+async function readSecret(prompt) {
+    const input = process.stdin;
+    if (!input.isTTY) {
+        let text = "";
+        for await (const chunk of input)
+            text += chunk;
+        return text;
+    }
+    process.stderr.write(prompt);
+    input.setRawMode(true);
+    input.setEncoding("utf8");
+    return new Promise((resolve, reject) => {
+        let text = "";
+        const done = (value) => {
+            input.setRawMode(false);
+            input.pause();
+            input.off("data", onData);
+            process.stderr.write("\n");
+            value === undefined ? reject(new Error("cancelled")) : resolve(value);
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === "\r" || ch === "\n")
+                    return done(text);
+                if (ch === "\u0003" || ch === "\u0004")
+                    return done();
+                if (ch === "\u007f" || ch === "\b")
+                    text = text.slice(0, -1);
+                else if (ch >= " ")
+                    text += ch;
+            }
+        };
+        input.on("data", onData);
+        input.resume();
+    });
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length !== 1 || args[0].startsWith("-")) {
+        console.error(USAGE);
+        return 2;
+    }
+    let url;
+    try {
+        url = originOf(args[0]);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    const config = configFromEnv({ ...process.env, CONSTRUCTOR_BASE_URL: url });
+    let raw;
+    try {
+        raw = await readSecret(`Access key for ${url} (hidden): `);
+    }
+    catch {
+        console.error("Cancelled; nothing saved.");
+        return 1;
+    }
+    const key = cleanKey(raw);
+    if (!key) {
+        console.error("That is not an access key; nothing saved.");
+        return 1;
+    }
+    // Check the key with Constructor before saving it.
+    let status;
+    try {
+        const response = await fetch(`${url}${config.apiPath}/auth/session`, {
+            headers: {
+                "X-Research-AccessKey": `Bearer ${key}`,
+                Accept: "application/json",
+            },
+            redirect: "manual",
+            signal: AbortSignal.timeout(15000),
+        });
+        status = response.status;
+        await response.body?.cancel();
+    }
+    catch {
+        console.error(`Could not reach ${url} (VPN?); nothing saved.`);
+        return 1;
+    }
+    if (status === 401) {
+        console.error(`${url} rejected this key; nothing saved.`);
+        return 1;
+    }
+    if (status !== 200) {
+        console.error(`${url} answered HTTP ${status}: it may not have the public API yet; nothing saved.`);
+        return 1;
+    }
+    await saveKeyFile(config.keyFile, url, key);
+    console.log(`Key for ${url} saved to ${config.keyFile}. The MCP uses it from the next call; no restart needed.`);
+    return 0;
+}
+main().then((code) => (process.exitCode = code), () => {
+    console.error("Saving the key failed.");
+    process.exitCode = 1;
+});

package/dist/store.d.ts

@@ -70,7 +70,7 @@ export declare class StateStore {
      * harnesses' calls "busy" about half the time while anything was deploying.
      */
     lockWaitMs: number;
-    /** The Constructor API saved operations belong to; follows a sign-in to another host. */
+    /** The Constructor API saved operations belong to; follows a key saved for another host. */
     get endpoint(): string;
     private init;
     load(id: string): Promise<Operation | undefined>;