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

package/README.md

@@ -57,12 +57,24 @@ Deployment must be switched on for the project. If it is off and the key may not
 | `CONSTRUCTOR_STORAGE_PATH`          | `/api/platform-storage`                                                                         |
 | `CONSTRUCTOR_ACCESS_KEY`            | unset: the key file is used                                                                     |
 | `CONSTRUCTOR_KEY_FILE`              | `~/.config/constructor-research/access-key.json`                                                |
+| `CONSTRUCTOR_DESK_ROOT`             | `~/project` (inside a desk only)                                                                |
 | `CONSTRUCTOR_STATE_DIR`             | `~/.local/state/constructor-research-mcp`                                                       |
 | `CONSTRUCTOR_UPLOAD_SETTLE_SECONDS` | `30`                                                                                            |
 | `CONSTRUCTOR_READINESS_SECONDS`     | `60`                                                                                            |
 
 HTTPS is required except on localhost.
 
+## Inside a Constructor desk (VS Code)
+
+When the MCP runs in VS Code inside a Constructor Research desk, it finds that desk from the environment Constructor sets there (`ROLOS_PROJECT_ID`/`RESEARCH_PROJECT_ID`, `ROLOS_DESK_ID`/`RESEARCH_DESK_ID`, `ROLOS_API_SERVER`/`RESEARCH_API_SERVER`) and works in it:
+
+- the desk's project folder (`~/project`, or `CONSTRUCTOR_DESK_ROOT`) is its disk, so the agent creates and changes files there directly; nothing is uploaded, and `sync_files`, `list_files`, `create_folder`, `move_path` and `delete_path` answer `local_desk` for this desk;
+- `build_image`, `deploy_app`, `update_app`, `start_app`, `stop_app` and `list_images` act on this desk and project without a desk link; a `desk_url` or other IDs still name another desk;
+- `build.dockerfile` is the path inside the project folder (`/backend/Dockerfile`), or `build.local_path` names a folder inside it; Dockerfiles are checked from the local files;
+- the MCP works with the desk's Constructor (`ROLOS_API_SERVER`) unless `CONSTRUCTOR_BASE_URL` is set.
+
+`CONSTRUCTOR_LOCAL_DESK=0` turns this off.
+
 ## Thirteen tools
 
 | Tool                     | Agent's task                                                                        |

package/dist/config.d.ts

@@ -1,7 +1,10 @@
+import { type LocalDesk } from "./desk.js";
 export interface Config {
     /** The Constructor the MCP works with: CONSTRUCTOR_BASE_URL, else the one the saved key belongs to. */
     baseUrl: string;
     baseUrlFixed?: boolean;
+    /** The Constructor desk this MCP runs inside (VS Code in Constructor Research), if any. */
+    localDesk?: LocalDesk;
     apiPath: string;
     storagePath?: string;
     /** Build-log service root; build logs stream only while a build runs. */

package/dist/config.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { localDeskFromEnv } from "./desk.js";
 /** Where the MCP works unless CONSTRUCTOR_BASE_URL or the saved key names another Constructor. */
 export const DEFAULT_BASE_URL = "https://constructor.app";
 /** The origin of a Constructor link; HTTPS except on localhost. */
@@ -28,7 +29,9 @@ export function configFromEnv(env = process.env) {
         if (url.search || url.hash || url.pathname !== "/")
             throw new Error("CONSTRUCTOR_BASE_URL must be an origin without a path or credentials.");
     }
-    const baseUrl = originOf(fixed ?? DEFAULT_BASE_URL);
+    // Inside a Constructor desk, its Constructor is the one to work with.
+    const localDesk = localDeskFromEnv(env, originOf);
+    const baseUrl = originOf(fixed ?? localDesk?.server ?? DEFAULT_BASE_URL);
     const apiPath = env.CONSTRUCTOR_API_PATH ?? "/api/platform-account/v1";
     if (!/^\/[a-zA-Z0-9/_-]+$/.test(apiPath) || apiPath.includes("//"))
         throw new Error("Invalid CONSTRUCTOR_API_PATH.");
@@ -41,7 +44,8 @@ export function configFromEnv(env = process.env) {
     const expand = (s) => resolve(s.startsWith("~/") ? homedir() + s.slice(1) : s);
     return {
         baseUrl,
-        baseUrlFixed: !!fixed,
+        baseUrlFixed: !!fixed || !!localDesk?.server,
+        localDesk,
         apiPath: apiPath.replace(/\/$/, ""),
         storagePath: storagePath.replace(/\/$/, ""),
         keeperPath: keeperPath.replace(/\/$/, ""),

package/dist/desk.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The Constructor desk this MCP runs inside (VS Code in Constructor Research), from the
+ * environment Constructor sets there. Its project folder is the desk's disk, so the agent edits
+ * files in place and the MCP never uploads to it.
+ */
+export interface LocalDesk {
+    projectId: string;
+    deskId: string;
+    /** The desk's project folder on this machine; the disk root for builds. */
+    root: string;
+    /** The Constructor the desk belongs to. */
+    server?: string;
+}
+export declare function localDeskFromEnv(env: NodeJS.ProcessEnv, origin: (link: string) => string): LocalDesk | undefined;
+/**
+ * Disk path ("/a/Dockerfile") of a local path inside the desk's project folder, or undefined
+ * when it lies outside. Symlinks are resolved on both sides when the path exists.
+ */
+export declare function diskPath(desk: LocalDesk, local: string): string | undefined;
+/** Absolute local path of a disk path; refuses anything that escapes the project folder. */
+export declare function localPath(desk: LocalDesk, disk: string): string;
+/** What the agent is told about working inside the desk. */
+export declare function deskInstructions(desk: LocalDesk): string;

package/dist/desk.js

@@ -0,0 +1,52 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+const ID = /^[a-zA-Z0-9_-]{4,128}$/;
+export function localDeskFromEnv(env, origin) {
+    if (["0", "false", "off"].includes((env.CONSTRUCTOR_LOCAL_DESK ?? "").toLowerCase()))
+        return undefined;
+    const projectId = env.ROLOS_PROJECT_ID || env.RESEARCH_PROJECT_ID;
+    const deskId = env.ROLOS_DESK_ID || env.RESEARCH_DESK_ID;
+    if (!projectId || !deskId || !ID.test(projectId) || !ID.test(deskId))
+        return undefined;
+    let server;
+    try {
+        const s = env.ROLOS_API_SERVER || env.RESEARCH_API_SERVER;
+        server = s ? origin(s) : undefined;
+    }
+    catch {
+        server = undefined;
+    }
+    const home = env.HOME || homedir();
+    const root = resolve(env.CONSTRUCTOR_DESK_ROOT ?? join(home, "project"));
+    return { projectId, deskId, root, server };
+}
+/**
+ * Disk path ("/a/Dockerfile") of a local path inside the desk's project folder, or undefined
+ * when it lies outside. Symlinks are resolved on both sides when the path exists.
+ */
+export function diskPath(desk, local) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return resolve(p);
+        }
+    };
+    const rel = relative(real(desk.root), real(local));
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return undefined;
+    return "/" + rel.split(sep).filter(Boolean).join("/");
+}
+/** Absolute local path of a disk path; refuses anything that escapes the project folder. */
+export function localPath(desk, disk) {
+    const parts = disk.split("/").filter(Boolean);
+    if (parts.some((p) => p === ".." || p === "."))
+        throw new Error("Disk paths must not contain . or ..");
+    return join(desk.root, ...parts);
+}
+/** What the agent is told about working inside the desk. */
+export function deskInstructions(desk) {
+    return `This MCP runs inside Constructor desk ${desk.deskId} of project ${desk.projectId} (VS Code in Constructor Research). That desk's disk is the local folder ${desk.root}: create and change its files there directly with your own file and shell tools, and do not use sync_files, list_files, create_folder, move_path or delete_path for this desk. build_image, deploy_app, update_app, start_app, stop_app and list_images use this desk and project by default, so no desk link is needed; pass desk_url only when the user names another desk. When the Dockerfile and sources are ready, call deploy_app (or build_image) with build.dockerfile as the path inside ${desk.root} (for example /backend/Dockerfile), or build.local_path set to a folder inside ${desk.root}; nothing is uploaded.`;
+}

package/dist/files.d.ts

@@ -32,6 +32,10 @@ export declare class FileManager {
     /** Type of a path, or null when missing. */
     private stat;
     private mkcol;
+    /** The desk this MCP runs inside, when `desk` is it. */
+    private here;
+    /** File tools never touch the desk the MCP runs in: its files are local. */
+    private notHere;
     list(raw: unknown): Promise<{
         desk_id: string;
         path: string;
@@ -108,6 +112,8 @@ export declare class FileManager {
         missing: string[];
         warnings: string[];
     }>;
+    /** The same checks as on a disk, for the desk this MCP runs in: its files are local. */
+    private checkLocal;
     /** Upload to a fresh temp file, move it over the target, then verify the server checksum. */
     private upload;
 }

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;
@@ -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/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

@@ -2,7 +2,16 @@ 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(),
@@ -35,7 +44,7 @@ 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 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] };
 }

package/dist/login.d.ts

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

package/dist/login.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Sign in from a terminal; the MCP's sign_in tool does the same from an agent session.
+// Usage: npx -y -p constructor-research-mcp constructor-research-login [--url <any link to your Constructor>] --for claude-code|codex|opencode   (or --to <session file>)
+import { configFromEnv, HARNESSES, originOf, sessionArgs } from "./config.js";
+import { signIn } from "./signin.js";
+const config = configFromEnv();
+const args = process.argv.slice(2);
+const at = args.indexOf("--url");
+const url = at >= 0 ? args.splice(at, 2)[1] : undefined;
+const { file } = sessionArgs(args, config);
+if (!file || (at >= 0 && !url)) {
+    console.error(`Usage: npx -y -p constructor-research-mcp constructor-research-login [--url <any link to your Constructor>] --for ${HARNESSES.join("|")}   (or --to <session file>)`);
+    process.exit(2);
+}
+if (url) {
+    const host = originOf(url);
+    if (config.baseUrlFixed && host !== config.baseUrl) {
+        console.error(`CONSTRUCTOR_BASE_URL fixes the MCP to ${config.baseUrl}.`);
+        process.exit(2);
+    }
+    config.baseUrl = host;
+}
+const result = await signIn(config, file, () => console.log(`A Chrome window opened at ${config.baseUrl}. Sign in there; it closes by itself afterwards.`));
+(result.status === "signed_in" ? console.log : console.error)(result.message);
+process.exit(result.status === "signed_in" ? 0 : 1);

package/dist/server.js

@@ -11,6 +11,21 @@ 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, } from "./schemas.js";
 async function main() {
@@ -35,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))
@@ -114,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: `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.`,
+        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,
@@ -133,7 +175,18 @@ async function main() {
             try {
                 await api.refresh();
                 const result = await api.withBudget(budget, () => fn(scope
-                    ? resolveDeskUrl(args, config.baseUrl, scope, config.baseUrlFixed)
+                    ? 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));
                 return {
                     content: [

package/dist/session.d.ts

@@ -0,0 +1,21 @@
+/** The cookies the MCP keeps: the access token for requests, the refresh token to renew it. */
+export declare const SESSION_COOKIES: readonly ["ap_access_token", "ap_id_token", "ap_refresh_token"];
+/** Claims of a JWT, or undefined when it is not one. */
+export declare function claims(jwt?: string): Record<string, any> | undefined;
+/** Session cookies found in a Cookie header, a cURL, a Set-Cookie list or a bare JWT. */
+export declare function sessionCookies(text: string): Map<string, string>;
+/** The session saved in a cookie file; only its cookie line is read. */
+export declare function readSession(file: string): Promise<Map<string, string>>;
+/**
+ * The Constructor (an origin) a saved session belongs to: its host line, written at sign-in,
+ * or else the issuer of its access token. Undefined when nothing is saved.
+ */
+export declare function sessionHost(file: string): Promise<string | undefined>;
+/**
+ * Replaces the cookie line of a file with these cookies, keeping its other lines, and with
+ * `host` its host line. Written to a temporary file and renamed, mode 600, so a reader never
+ * sees half a token and a crash never loses the session.
+ */
+export declare function saveSession(file: string, cookies: Map<string, string>, host?: string): Promise<void>;
+/** New session cookies from a response's Set-Cookie headers. */
+export declare function setCookies(response: Response): Map<string, string>;

package/dist/session.js

@@ -0,0 +1,108 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+/** The cookies the MCP keeps: the access token for requests, the refresh token to renew it. */
+export const SESSION_COOKIES = [
+    "ap_access_token",
+    "ap_id_token",
+    "ap_refresh_token",
+];
+/** Claims of a JWT, or undefined when it is not one. */
+export function claims(jwt) {
+    try {
+        return JSON.parse(Buffer.from(jwt.split(".")[1], "base64url").toString());
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Session cookies found in a Cookie header, a cURL, a Set-Cookie list or a bare JWT. */
+export function sessionCookies(text) {
+    const found = new Map();
+    for (const name of SESSION_COOKIES) {
+        const value = [
+            ...text.matchAll(new RegExp(`(?:^|[\\s;'"])${name}=([\\w.~+/=-]+)`, "g")),
+        ].at(-1)?.[1];
+        if (value)
+            found.set(name, value);
+    }
+    const bare = /^\s*(ey[\w-]+\.[\w-]+\.[\w-]+)\s*$/.exec(text)?.[1];
+    if (bare && !found.size)
+        found.set("ap_access_token", bare);
+    return found;
+}
+/** Index of the line holding the tokens in a cookie file, or -1. */
+const cookieLine = (lines) => lines.findIndex((l) => /^\s*(Cookie:\s*)?(ey[\w-]+\.|.*\bap_(access|refresh)_token=)/.test(l));
+/** The session saved in a cookie file; only its cookie line is read. */
+export async function readSession(file) {
+    const lines = (await readFile(file, "utf8")).split(/\r?\n/);
+    const line = lines[cookieLine(lines)] ?? "";
+    if (/[\x00-\x1f]/.test(line))
+        return new Map();
+    return sessionCookies(line.trim().replace(/^Cookie:\s*/i, ""));
+}
+/** The line naming the Constructor the session belongs to. */
+const HOST = /^host=(\S+)\s*$/;
+/**
+ * The Constructor (an origin) a saved session belongs to: its host line, written at sign-in,
+ * or else the issuer of its access token. Undefined when nothing is saved.
+ */
+export async function sessionHost(file) {
+    let lines;
+    try {
+        lines = (await readFile(file, "utf8")).split(/\r?\n/);
+    }
+    catch {
+        return undefined;
+    }
+    const named = lines.map((l) => HOST.exec(l)?.[1]).find(Boolean);
+    const line = lines[cookieLine(lines)] ?? "";
+    const issuer = claims(sessionCookies(line.replace(/^\s*Cookie:\s*/i, "")).get("ap_access_token"))?.iss;
+    try {
+        return new URL(named ?? issuer).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Replaces the cookie line of a file with these cookies, keeping its other lines, and with
+ * `host` its host line. Written to a temporary file and renamed, mode 600, so a reader never
+ * sees half a token and a crash never loses the session.
+ */
+export async function saveSession(file, cookies, host) {
+    let lines = [];
+    try {
+        lines = (await readFile(file, "utf8")).split(/\r?\n/);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    const line = SESSION_COOKIES.filter((n) => cookies.get(n))
+        .map((n) => `${n}=${cookies.get(n)}`)
+        .join("; ");
+    const i = cookieLine(lines);
+    if (i >= 0)
+        lines[i] = line;
+    else
+        lines.unshift(line);
+    if (host) {
+        lines = lines.filter((l) => !HOST.test(l));
+        lines.splice(lines.indexOf(line) + 1, 0, `host=${host}`);
+    }
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    await writeFile(tmp, lines.join("\n").replace(/\n*$/, "\n"), {
+        mode: 0o600,
+        flag: "wx",
+    });
+    await rename(tmp, file);
+}
+/** New session cookies from a response's Set-Cookie headers. */
+export function setCookies(response) {
+    return sessionCookies(response.headers
+        .getSetCookie()
+        .map((c) => c.split(";")[0])
+        .join("; "));
+}

package/dist/set-token.d.ts

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

package/dist/set-token.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Save the session from a copied cURL (or a bare token) for the MCP without printing it.
+// Usage: npx -y -p constructor-research-mcp constructor-research-set-token <file with a copied cURL, or a token> --for claude-code|codex|opencode
+//        (or --to <session file>); the session belongs to the Constructor the cURL was sent to.
+import { readFileSync } from "node:fs";
+import { configFromEnv, HARNESSES, originOf, sessionArgs } from "./config.js";
+import { claims, saveSession, sessionCookies } from "./session.js";
+const { file: target, rest } = sessionArgs(process.argv.slice(2), configFromEnv());
+const source = rest[0];
+if (!source || !target) {
+    console.error(`Usage: npx -y -p constructor-research-mcp constructor-research-set-token <file with a copied cURL> --for ${HARNESSES.join("|")}   (or --to <session file>)`);
+    process.exit(2);
+}
+const text = readFileSync(source, "utf8");
+const found = sessionCookies(text);
+const token = found.get("ap_access_token");
+if (!token) {
+    console.error("No ap_access_token found in " + source + ".");
+    process.exit(1);
+}
+const { exp, max_slt } = claims(token) ?? {};
+if (exp && exp * 1000 <= Date.now() && !found.has("ap_refresh_token")) {
+    console.error("That token already expired at " +
+        new Date(exp * 1000).toISOString() +
+        "; copy a fresh one.");
+    process.exit(1);
+}
+// The Constructor the cURL was sent to; a bare token names its own issuer.
+const sent = /\bcurl\s+(?:-\S+\s+)*['"]?(https?:\/\/[^\s'"]+)/.exec(text)?.[1];
+let host;
+try {
+    host = sent ? originOf(sent) : undefined;
+}
+catch { }
+await saveSession(target, found, host);
+const time = (s) => new Date(s * 1000).toISOString().slice(0, 16).replace("T", " ") + " UTC";
+console.log("Saved to " +
+    target +
+    (host ? ` (for ${host})` : "") +
+    (found.has("ap_refresh_token")
+        ? `, with the refresh token: the MCP renews the session itself${max_slt ? " until " + time(max_slt) : ""}. The browser this cURL came from holds the same session, and a refresh token works once: whichever renews first logs the other out. The sign_in tool (or constructor-research-login) gives the MCP a session of its own.`
+        : exp
+            ? "; expires " +
+                time(exp) +
+                " (in " +
+                Math.round((exp * 1000 - Date.now()) / 60000) +
+                " min). Copy the cURL with the ap_refresh_token cookie, or use the sign_in tool, and the MCP renews it itself."
+            : "."));

package/dist/signin.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from "./config.js";
+export type SignInResult = {
+    status: "signed_in";
+    message: string;
+    session_file: string;
+    host: string;
+    until?: string;
+} | {
+    status: "sign_in_failed";
+    message: string;
+};
+/** A Chromium-based browser on macOS, Windows or Linux; CONSTRUCTOR_BROWSER overrides. */
+export declare function findBrowser(): string | undefined;
+/**
+ * Opens the sign-in window, waits for the user to sign in (up to 15 min), saves the
+ * session cookies to `file`, and closes the window at once. Never returns a token.
+ * `opened` runs once the window is up.
+ */
+export declare function signIn(config: Pick<Config, "baseUrl" | "apiPath" | "requestTimeoutMs">, file: string, opened?: () => void): Promise<SignInResult>;

package/dist/signin.js

@@ -0,0 +1,209 @@
+// Sign in to Constructor in a separate Chrome window and save the session.
+// The window uses a fresh temporary profile: a session nothing else holds, so the MCP can
+// renew it without logging out the user's own browser (a refresh token works only once).
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { claims, saveSession, setCookies, SESSION_COOKIES } from "./session.js";
+const SIGN_IN_MINUTES = 15;
+/** A Chromium-based browser on macOS, Windows or Linux; CONSTRUCTOR_BROWSER overrides. */
+export function findBrowser() {
+    if (process.env.CONSTRUCTOR_BROWSER)
+        return existsSync(process.env.CONSTRUCTOR_BROWSER)
+            ? process.env.CONSTRUCTOR_BROWSER
+            : undefined;
+    const env = process.env;
+    const installed = process.platform === "win32"
+        ? [env.PROGRAMFILES, env["PROGRAMFILES(X86)"], env.LOCALAPPDATA]
+            .filter((d) => !!d)
+            .flatMap((d) => [
+            join(d, "Google", "Chrome", "Application", "chrome.exe"),
+            join(d, "Microsoft", "Edge", "Application", "msedge.exe"),
+            join(d, "Chromium", "Application", "chrome.exe"),
+            join(d, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+        ])
+        : process.platform === "darwin"
+            ? [
+                "Google Chrome.app/Contents/MacOS/Google Chrome",
+                "Chromium.app/Contents/MacOS/Chromium",
+                "Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+                "Brave Browser.app/Contents/MacOS/Brave Browser",
+            ].flatMap((app) => [
+                join("/Applications", app),
+                join(homedir(), "Applications", app),
+            ])
+            : [];
+    // Then the PATH, as Linux installs them (and any OS where the user put one there).
+    const names = [
+        "google-chrome",
+        "google-chrome-stable",
+        "chromium",
+        "chromium-browser",
+        "microsoft-edge",
+        "brave-browser",
+        "chrome",
+        "msedge",
+    ];
+    const exts = process.platform === "win32"
+        ? (env.PATHEXT ?? ".EXE").split(";").filter(Boolean)
+        : [""];
+    const onPath = (env.PATH ?? "")
+        .split(delimiter)
+        .filter(Boolean)
+        .flatMap((dir) => names.flatMap((n) => exts.map((e) => join(dir, n + e.toLowerCase()))));
+    return [...installed, ...onPath].find((c) => existsSync(c));
+}
+/** Minimal Chrome DevTools Protocol client over the browser's WebSocket. */
+async function devtools(url) {
+    const ws = new WebSocket(url);
+    await new Promise((ok, fail) => {
+        ws.onopen = ok;
+        ws.onerror = () => fail(new Error("Could not connect to the browser."));
+    });
+    let id = 0;
+    const waiting = new Map();
+    ws.onmessage = (e) => {
+        const m = JSON.parse(String(e.data));
+        waiting.get(m.id)?.(m);
+        waiting.delete(m.id);
+    };
+    return {
+        send(method, params = {}) {
+            return new Promise((ok, fail) => {
+                const n = ++id;
+                waiting.set(n, (m) => m.error ? fail(new Error(m.error.message)) : ok(m.result));
+                ws.send(JSON.stringify({ id: n, method, params }));
+            });
+        },
+        close: () => ws.close(),
+    };
+}
+/**
+ * Opens the sign-in window, waits for the user to sign in (up to 15 min), saves the
+ * session cookies to `file`, and closes the window at once. Never returns a token.
+ * `opened` runs once the window is up.
+ */
+export async function signIn(config, file, opened = () => { }) {
+    const fallback = `save a session from a copied cURL instead: npx -y -p constructor-research-mcp constructor-research-set-token <file with the cURL> --to ${file}`;
+    const headless = !!process.env.CONSTRUCTOR_LOGIN_HEADLESS;
+    if (process.platform === "linux" &&
+        !headless &&
+        !process.env.DISPLAY &&
+        !process.env.WAYLAND_DISPLAY)
+        return {
+            status: "sign_in_failed",
+            message: `This machine has no screen to open a sign-in window on (no DISPLAY or WAYLAND_DISPLAY). Sign in where the MCP has a desktop, or ${fallback}.`,
+        };
+    const exe = findBrowser();
+    if (!exe)
+        return {
+            status: "sign_in_failed",
+            message: `No Chrome, Edge, Chromium or Brave found. Set CONSTRUCTOR_BROWSER in the MCP settings to the browser's executable, or ${fallback}.`,
+        };
+    const host = new URL(config.baseUrl).hostname;
+    const profile = await mkdtemp(join(tmpdir(), "constructor-login-"));
+    const chrome = spawn(exe, [
+        `--user-data-dir=${profile}`,
+        "--remote-debugging-port=0",
+        "--remote-allow-origins=http://127.0.0.1",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-sync",
+        // Tests run the browser without a window.
+        ...(headless ? ["--headless=new"] : []),
+        "--new-window",
+        `${config.baseUrl}/research/`,
+    ], { stdio: "ignore" });
+    let exited = false;
+    chrome.on("exit", () => (exited = true));
+    chrome.on("error", () => (exited = true));
+    const failed = (message) => ({
+        status: "sign_in_failed",
+        message,
+    });
+    try {
+        let port, path;
+        for (let i = 0; i < 300 && !port && !exited; i++) {
+            try {
+                [port, path] = (await readFile(join(profile, "DevToolsActivePort"), "utf8")).split("\n");
+            }
+            catch {
+                await delay(100);
+            }
+        }
+        if (!port)
+            return failed(`The browser did not start (${exe}); ${fallback}.`);
+        const cdp = await devtools(`ws://127.0.0.1:${port}${path}`);
+        opened();
+        const session = async () => {
+            const { cookies } = await cdp.send("Storage.getCookies");
+            return new Map(cookies
+                .filter((c) => SESSION_COOKIES.includes(c.name) &&
+                (c.domain.replace(/^\./, "") === host ||
+                    host.endsWith(c.domain.startsWith(".") ? c.domain : "." + c.domain)))
+                .map((c) => [c.name, c.value]));
+        };
+        const deadline = Date.now() + SIGN_IN_MINUTES * 60000;
+        let found;
+        while (!exited && Date.now() < deadline) {
+            const s = await session().catch(() => undefined);
+            const exp = claims(s?.get("ap_access_token"))?.exp;
+            if (s?.has("ap_refresh_token") && exp && exp * 1000 > Date.now()) {
+                // The page may still be loading; read again once it settles, then close at once so
+                // the window never renews this session itself.
+                await delay(3000);
+                found = (await session().catch(() => undefined)) ?? s;
+                break;
+            }
+            await delay(1000);
+        }
+        await cdp.send("Browser.close").catch(() => { });
+        cdp.close();
+        if (!found)
+            return failed(exited
+                ? "The window was closed before sign-in finished; nothing was saved."
+                : `No sign-in within ${SIGN_IN_MINUTES} min; nothing was saved.`);
+        // Check the access token without sending the refresh token, so nothing is renewed.
+        const response = await fetch(config.baseUrl + config.apiPath + "/auth/session", {
+            headers: {
+                Cookie: `ap_access_token=${found.get("ap_access_token")}`,
+                Accept: "application/json",
+            },
+            redirect: "manual",
+            signal: AbortSignal.timeout(config.requestTimeoutMs),
+        }).catch(() => undefined);
+        await response?.body?.cancel();
+        if (response?.status === 401)
+            return failed("Constructor rejected the new session; nothing was saved.");
+        await saveSession(file, new Map([...found, ...(response ? setCookies(response) : [])]), config.baseUrl);
+        const end = claims(found.get("ap_access_token"))?.max_slt;
+        const until = end
+            ? new Date(end * 1000).toISOString().slice(0, 16).replace("T", " ") +
+                " UTC"
+            : undefined;
+        return {
+            status: "signed_in",
+            message: `Signed in to ${config.baseUrl}. Session saved to ${file}` +
+                (until ? `; the MCP renews it automatically until ${until}.` : "."),
+            session_file: file,
+            host: config.baseUrl,
+            until,
+        };
+    }
+    catch (e) {
+        return failed(`Sign-in failed: ${e?.message ?? e}. Nothing was saved.`);
+    }
+    finally {
+        if (!exited) {
+            chrome.kill();
+            for (let i = 0; i < 50 && !exited; i++)
+                await delay(100);
+            if (!exited)
+                chrome.kill("SIGKILL"); // TerminateProcess on Windows
+        }
+        await rm(profile, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "constructor-research-mcp",
-  "version": "0.4.0-beta.1",
+  "version": "0.4.0-beta.2",
   "type": "module",
   "description": "Local deployment MCP for Constructor Research",
   "license": "MIT",