constructor-research-mcp 0.0.0-stage → 0.3.0

package/dist/api.js

@@ -0,0 +1,280 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { setTimeout as delay } from "node:timers/promises";
+import { DEFAULT_BASE_URL } from "./config.js";
+import { claims, readSession, saveSession, sessionHost, setCookies, } from "./session.js";
+import { withLock } from "./store.js";
+export class ToolError extends Error {
+    code;
+    status;
+    apiCode;
+    constructor(code, message, status, apiCode) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.apiCode = apiCode;
+    }
+}
+export const segment = (s) => encodeURIComponent(s);
+/** `exp` (seconds) of the ap_access_token JWT, if readable. */
+export function expiry(cookie) {
+    const token = /(?:^|;\s*)ap_access_token=([^;\s]+)/.exec(cookie)?.[1];
+    const exp = claims(token)?.exp;
+    return typeof exp === "number" ? exp : undefined;
+}
+/** Renew the access token when it has less than this left (it lasts an hour). */
+const RENEW_MS = 10 * 60000;
+export class PlatformApi {
+    config;
+    deadline = new AsyncLocalStorage();
+    constructor(config) {
+        this.config = config;
+    }
+    /** End of the current call's time budget (epoch ms); Infinity outside one. */
+    deadlineMs() {
+        return this.deadline.getStore() ?? Infinity;
+    }
+    withBudget(milliseconds, fn) {
+        return this.deadline.run(Date.now() + milliseconds, fn);
+    }
+    /** How to supply a fresh token, with the exact file this MCP reads. */
+    authHelp(what = "Not signed in to Constructor.") {
+        const to = this.config.cookieFile;
+        return `${what} ${this.signingIn
+            ? "A sign-in window is already open: ask the user to finish signing in there, then call sign_in to confirm."
+            : "Tell the user a sign-in window is about to open, then call the sign_in tool: the user signs in in a separate Chrome window that closes by itself, and the MCP renews the session automatically for up to 14 days."} Without a desktop browser, the user runs: npx -y -p constructor-research-mcp constructor-research-set-token <file with a copied cURL> --to ${to}. Then repeat the same call.`;
+    }
+    /**
+     * Works with the Constructor the saved session belongs to; without one, with the host of the
+     * last desk link the user gave, or the default. CONSTRUCTOR_BASE_URL fixes it instead.
+     */
+    async followSession() {
+        if (this.config.baseUrlFixed)
+            return;
+        const host = await sessionHost(this.config.cookieFile);
+        this.config.baseUrl = host ?? this.aimed ?? DEFAULT_BASE_URL;
+    }
+    /** The host of a desk link given while nobody is signed in: sign_in opens there. */
+    aimed;
+    /** Set while the sign_in tool's window is open. */
+    signingIn = false;
+    /**
+     * Time left on the saved credentials: the login session when it can be renewed
+     * (`max_slt`, the latest renewal the server allows), else the access token.
+     */
+    async authLeft() {
+        const saved = await readSession(this.config.cookieFile);
+        const access = claims(saved.get("ap_access_token"));
+        const renewable = saved.has("ap_refresh_token");
+        const end = renewable ? access?.max_slt : access?.exp;
+        if (renewable && end === undefined)
+            return undefined;
+        if (typeof end !== "number")
+            return undefined;
+        return { minutes: (end * 1000 - Date.now()) / 60000, renewable };
+    }
+    renewing;
+    /** The Cookie header for a request: only the access token, renewed first when it runs low. */
+    async cookie() {
+        let saved;
+        try {
+            saved = await readSession(this.config.cookieFile);
+        }
+        catch {
+            saved = new Map();
+        }
+        let token = saved.get("ap_access_token");
+        const exp = expiry(`ap_access_token=${token}`);
+        // Never send one Constructor's session to another.
+        const owner = await sessionHost(this.config.cookieFile);
+        if (owner && owner !== this.config.baseUrl)
+            throw new ToolError("needs_auth", this.authHelp(`${this.config.cookieFile} holds a session for ${owner}, but this MCP works with ${this.config.baseUrl}.`));
+        if (saved.has("ap_refresh_token") &&
+            (!token || (exp !== undefined && exp * 1000 - Date.now() < RENEW_MS)))
+            token = await (this.renewing ??= this.renew().finally(() => (this.renewing = undefined)));
+        else if (!token)
+            throw new ToolError("needs_auth", this.authHelp());
+        else if (exp !== undefined && exp * 1000 <= Date.now())
+            throw new ToolError("needs_auth", this.authHelp(`Token expired at ${new Date(exp * 1000).toISOString().slice(11, 16)} UTC.`));
+        return `ap_access_token=${token}`;
+    }
+    /**
+     * Trades the refresh token for new tokens and saves them before anything else. A refresh
+     * token works once, so several MCP processes sharing the file renew under one lock, and
+     * a process that waited uses the tokens another one just saved.
+     */
+    renew() {
+        const file = this.config.cookieFile;
+        return withLock(file + ".lock", async () => {
+            const saved = await readSession(file);
+            const token = saved.get("ap_access_token");
+            const exp = expiry(`ap_access_token=${token}`);
+            const valid = !!token && (exp === undefined || exp * 1000 > Date.now());
+            const refresh = saved.get("ap_refresh_token");
+            if (!refresh ||
+                (exp !== undefined && exp * 1000 - Date.now() >= RENEW_MS))
+                return this.usable(token, valid);
+            let response;
+            try {
+                response = await fetch(this.config.baseUrl + this.config.apiPath + "/auth/session", {
+                    // Without an access token the server must renew; the browser does the same.
+                    headers: {
+                        Cookie: `ap_refresh_token=${refresh}`,
+                        Accept: "application/json",
+                    },
+                    redirect: "manual",
+                    signal: AbortSignal.timeout(this.config.requestTimeoutMs),
+                });
+            }
+            catch {
+                if (valid)
+                    return token;
+                throw new ToolError("connection_error", "Could not reach Constructor to renew the session; repeat the same call.");
+            }
+            await response.body?.cancel();
+            const fresh = setCookies(response);
+            if (fresh.has("ap_access_token") && fresh.has("ap_refresh_token")) {
+                await saveSession(file, new Map([...saved, ...fresh]));
+                return fresh.get("ap_access_token");
+            }
+            if (response.status === 401) {
+                // The refresh token is spent; drop it so the file behaves like a plain token.
+                saved.delete("ap_refresh_token");
+                await saveSession(file, saved);
+                if (valid)
+                    return token;
+                throw new ToolError("needs_auth", this.authHelp("The saved login session can no longer be renewed: its refresh token was already used (a browser holding the same session renews it too) or the session reached its 14-day limit."));
+            }
+            if (valid)
+                return token;
+            throw new ToolError("connection_error", `Constructor answered HTTP ${response.status} without new tokens while renewing the session; repeat the same call.`);
+        }, 15000, () => new ToolError("busy", `Another process is renewing the session (${file}.lock); repeat the same call.`));
+    }
+    usable(token, valid) {
+        if (valid)
+            return token;
+        throw new ToolError("needs_auth", this.authHelp(token ? "Token expired." : undefined));
+    }
+    /**
+     * WebDAV request to a disk's project folder; callers interpret statuses other than 401.
+     * The storage gateway answers 502/503/504 now and then under load; requests that are
+     * safe to repeat (all but MOVE and DELETE) are retried a few times with backoff.
+     */
+    async storage(method, desk, path, init = {}) {
+        const cookie = await this.cookie();
+        const retries = ["MOVE", "DELETE"].includes(method)
+            ? []
+            : this.storageRetryMs;
+        for (let attempt = 0;; attempt++) {
+            const remaining = (this.deadline.getStore() ?? Infinity) - Date.now();
+            if (remaining <= 0)
+                throw new ToolError("connection_error", "Operation time budget exhausted; repeat the same call to continue.");
+            const wait = retries[attempt];
+            const again = wait !== undefined && wait < remaining - 1000;
+            let response;
+            try {
+                response = await fetch(this.config.baseUrl + this.davRoot(desk) + path, {
+                    method,
+                    headers: { Cookie: cookie, ...init.headers },
+                    body: init.body,
+                    redirect: "manual",
+                    signal: AbortSignal.timeout(Math.max(1, Math.floor(Math.min(60000, remaining)))),
+                });
+            }
+            catch {
+                if (again) {
+                    await delay(wait);
+                    continue;
+                }
+                throw new ToolError("connection_error", "Storage connection failed or timed out. Repeating the same call is safe.");
+            }
+            if ([502, 503, 504].includes(response.status) && again) {
+                await response.body?.cancel();
+                await delay(wait);
+                continue;
+            }
+            if (response.status === 401)
+                throw new ToolError("needs_auth", this.authHelp("Constructor rejected the token (expired or invalid)."), 401);
+            return response;
+        }
+    }
+    /**
+     * Opens a build-log stream. It stays open while the build runs; the caller reads the
+     * body and aborts through `signal`. 401 becomes needs_auth; other statuses are returned.
+     */
+    async stream(path, signal) {
+        const cookie = await this.cookie();
+        let response;
+        try {
+            response = await fetch(this.config.baseUrl +
+                (this.config.keeperPath ?? "/api/platform-keeper") +
+                path, {
+                headers: { Cookie: cookie, Accept: "text/event-stream" },
+                redirect: "manual",
+                signal,
+            });
+        }
+        catch {
+            throw new ToolError("connection_error", "Build log connection failed or timed out.");
+        }
+        if (response.status === 401) {
+            await response.body?.cancel();
+            throw new ToolError("needs_auth", this.authHelp("Constructor rejected the token (expired or invalid)."), 401);
+        }
+        return response;
+    }
+    /** Backoff before each storage retry; tests shorten it. */
+    storageRetryMs = [1000, 2000, 4000];
+    /** Server-side path of a disk's project folder, used for WebDAV Destination headers. */
+    davRoot(desk) {
+        return `${this.config.storagePath ?? "/api/platform-storage"}/desks/${segment(desk)}/dav/project/`;
+    }
+    async request(method, path, body) {
+        const cookie = await this.cookie();
+        const remaining = (this.deadline.getStore() ?? Infinity) - Date.now();
+        if (remaining <= 0)
+            throw new ToolError("connection_error", "Operation time budget exhausted before sending the next request; resume with get_deployment.");
+        let response;
+        try {
+            response = await fetch(this.config.baseUrl + this.config.apiPath + path, {
+                method,
+                headers: {
+                    Cookie: cookie,
+                    Accept: "application/json",
+                    ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                redirect: "manual",
+                signal: AbortSignal.timeout(Math.max(1, Math.floor(Math.min(this.config.requestTimeoutMs, remaining)))),
+            });
+        }
+        catch {
+            throw new ToolError(method === "GET" ? "connection_error" : "uncertain_outcome", method === "GET"
+                ? "API connection failed or timed out; retry the read."
+                : "The API request may have been applied. Inspect resources before retrying this mutation.");
+        }
+        if (response.status === 401)
+            throw new ToolError("needs_auth", this.authHelp("Constructor rejected the token (expired or invalid)."), 401);
+        if (!response.ok) {
+            if (method !== "GET" && response.status >= 500)
+                throw new ToolError("uncertain_outcome", `Constructor API returned HTTP ${response.status}. The mutation may have been applied; inspect resources before retrying.`, response.status);
+            let apiCode;
+            try {
+                const d = (await response.json());
+                if (typeof d?.details?.error_code === "number")
+                    apiCode = d.details.error_code;
+            }
+            catch {
+                /* Error bodies can contain secrets; never echo them. */
+            }
+            throw new ToolError("api_error", `Constructor API returned HTTP ${response.status}${apiCode ? ` (error ${apiCode})` : ""}.`, response.status, apiCode);
+        }
+        if (response.status === 204)
+            return undefined;
+        try {
+            return (await response.json());
+        }
+        catch {
+            throw new ToolError(method === "GET" ? "invalid_response" : "uncertain_outcome", "API returned an invalid response. Inspect resources before retrying a mutation.");
+        }
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+export interface Config {
+    /** The Constructor the MCP works with: the signed-in one, unless CONSTRUCTOR_BASE_URL fixes it. */
+    baseUrl: string;
+    baseUrlFixed?: boolean;
+    apiPath: string;
+    storagePath?: string;
+    /** Build-log service root; build logs stream only while a build runs. */
+    keeperPath?: string;
+    /** Session file; each harness gets its own unless CONSTRUCTOR_COOKIE_FILE fixes one. */
+    cookieFile: string;
+    cookieFileFixed?: boolean;
+    stateDir: string;
+    requestTimeoutMs: number;
+    /** How long to wait for public URLs to answer after start; 0 disables the check. */
+    readinessSeconds?: number;
+    /** Pause between uploading to a disk and building from it; 0 disables. */
+    uploadSettleSeconds?: number;
+}
+/** Where the MCP works until the user signs in somewhere else. */
+export declare const DEFAULT_BASE_URL = "https://constructor.app";
+/** The origin of a Constructor link; HTTPS except on localhost. */
+export declare function originOf(link: string): string;
+export declare function configFromEnv(env?: NodeJS.ProcessEnv): Config;
+/** Harnesses with their own session: one sign-in each, nothing shared between them. */
+export declare const HARNESSES: readonly ["claude-code", "codex", "opencode"];
+/** The harness behind an MCP client name (from the initialize handshake). */
+export declare function harnessOf(client?: string): string;
+/** Where a harness's Constructor session is kept (mode 600). */
+export declare function sessionFile(harness: string): string;
+/**
+ * Session file named on a command line: --for <harness> or --to <file>; without either,
+ * CONSTRUCTOR_COOKIE_FILE. Returns the remaining arguments too.
+ */
+export declare function sessionArgs(args: string[], config: Config): {
+    file: string;
+    rest: string[];
+} | {
+    file: undefined;
+    rest: string[];
+};
+/** Shell command that waits for deployments, carrying the settings that differ from the defaults. */
+export declare function waitCommand(config: Config, ids: string[]): string;
+/**
+ * How to run the wait CLI of this very version. Run through npx, the MCP lives in npx's
+ * cache, whose folder npm may replace at any time, so the hint names the package instead.
+ */
+export declare function waitProgram(script?: string): string;

package/dist/config.js

@@ -0,0 +1,127 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Where the MCP works until the user signs in somewhere else. */
+export const DEFAULT_BASE_URL = "https://constructor.app";
+/** The origin of a Constructor link; HTTPS except on localhost. */
+export function originOf(link) {
+    let url;
+    try {
+        url = new URL(link.trim());
+    }
+    catch {
+        throw new Error(`${link} is not a valid link.`);
+    }
+    if (url.username || url.password)
+        throw new Error("The link must not carry credentials.");
+    if (url.protocol !== "https:" &&
+        !(url.protocol === "http:" &&
+            ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+        throw new Error("HTTPS is required except on localhost.");
+    return url.origin;
+}
+export function configFromEnv(env = process.env) {
+    const fixed = env.CONSTRUCTOR_BASE_URL;
+    if (fixed) {
+        const url = new URL(fixed);
+        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);
+    const apiPath = env.CONSTRUCTOR_API_PATH ?? "/api/platform-account";
+    if (!/^\/[a-zA-Z0-9/_-]+$/.test(apiPath) || apiPath.includes("//"))
+        throw new Error("Invalid CONSTRUCTOR_API_PATH.");
+    const storagePath = env.CONSTRUCTOR_STORAGE_PATH ?? "/api/platform-storage";
+    if (!/^\/[a-zA-Z0-9/_-]+$/.test(storagePath) || storagePath.includes("//"))
+        throw new Error("Invalid CONSTRUCTOR_STORAGE_PATH.");
+    const keeperPath = env.CONSTRUCTOR_KEEPER_PATH ?? "/api/platform-keeper";
+    if (!/^\/[a-zA-Z0-9/_-]+$/.test(keeperPath) || keeperPath.includes("//"))
+        throw new Error("Invalid CONSTRUCTOR_KEEPER_PATH.");
+    const expand = (s) => resolve(s.startsWith("~/") ? homedir() + s.slice(1) : s);
+    return {
+        baseUrl,
+        baseUrlFixed: !!fixed,
+        apiPath: apiPath.replace(/\/$/, ""),
+        storagePath: storagePath.replace(/\/$/, ""),
+        keeperPath: keeperPath.replace(/\/$/, ""),
+        cookieFile: env.CONSTRUCTOR_COOKIE_FILE
+            ? expand(env.CONSTRUCTOR_COOKIE_FILE)
+            : sessionFile("default"),
+        cookieFileFixed: !!env.CONSTRUCTOR_COOKIE_FILE,
+        stateDir: expand(env.CONSTRUCTOR_STATE_DIR ?? "~/.local/state/constructor-research-mcp"),
+        requestTimeoutMs: 15000,
+        uploadSettleSeconds: Math.max(0, Math.min(300, Number(env.CONSTRUCTOR_UPLOAD_SETTLE_SECONDS ?? 30) || 0)),
+        readinessSeconds: Math.max(0, Math.min(300, Number(env.CONSTRUCTOR_READINESS_SECONDS ?? 60) || 0)),
+    };
+}
+/** Harnesses with their own session: one sign-in each, nothing shared between them. */
+export const HARNESSES = ["claude-code", "codex", "opencode"];
+/** The harness behind an MCP client name (from the initialize handshake). */
+export function harnessOf(client) {
+    const name = (client ?? "").toLowerCase();
+    if (name.includes("claude"))
+        return "claude-code";
+    if (name.includes("codex"))
+        return "codex";
+    if (name.includes("opencode"))
+        return "opencode";
+    return name.replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "") || "default";
+}
+/** Where a harness's Constructor session is kept (mode 600). */
+export function sessionFile(harness) {
+    return join(homedir(), ".config", "constructor-research", "sessions", `${harness}.txt`);
+}
+/**
+ * Session file named on a command line: --for <harness> or --to <file>; without either,
+ * CONSTRUCTOR_COOKIE_FILE. Returns the remaining arguments too.
+ */
+export function sessionArgs(args, config) {
+    const value = (flag) => {
+        const i = args.indexOf(flag);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const to = value("--to"), harness = value("--for");
+    const rest = args.filter((_, n) => !["--to", "--for"].includes(args[n]) &&
+        !["--to", "--for"].includes(args[n - 1]));
+    if (to)
+        return { file: resolve(to), rest };
+    if (harness && HARNESSES.includes(harness))
+        return { file: sessionFile(harness), rest };
+    if (!harness && config.cookieFileFixed)
+        return { file: config.cookieFile, rest };
+    return { file: undefined, rest };
+}
+const quote = (s) => /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+/** Shell command that waits for deployments, carrying the settings that differ from the defaults. */
+export function waitCommand(config, ids) {
+    const defaults = configFromEnv({});
+    const env = [
+        // The wait command reads the host from the session, as the MCP does, unless it is fixed.
+        [
+            "CONSTRUCTOR_BASE_URL",
+            config.baseUrlFixed ? config.baseUrl : undefined,
+            undefined,
+        ],
+        ["CONSTRUCTOR_API_PATH", config.apiPath, defaults.apiPath],
+        ["CONSTRUCTOR_STORAGE_PATH", config.storagePath, defaults.storagePath],
+        ["CONSTRUCTOR_KEEPER_PATH", config.keeperPath, defaults.keeperPath],
+        ["CONSTRUCTOR_COOKIE_FILE", config.cookieFile, defaults.cookieFile],
+        ["CONSTRUCTOR_STATE_DIR", config.stateDir, defaults.stateDir],
+    ]
+        .filter(([, value, standard]) => value !== standard)
+        .map(([name, value]) => `${name}=${quote(value)} `)
+        .join("");
+    return `${env}${waitProgram()} ${ids.join(" ")}`;
+}
+/**
+ * How to run the wait CLI of this very version. Run through npx, the MCP lives in npx's
+ * cache, whose folder npm may replace at any time, so the hint names the package instead.
+ */
+export function waitProgram(script = fileURLToPath(import.meta.url)) {
+    const wait = join(script, "..", "wait.js");
+    if (!script.includes(`${sep}_npx${sep}`))
+        return `node ${quote(wait)}`;
+    const { name, version } = JSON.parse(readFileSync(join(script, "..", "..", "package.json"), "utf8"));
+    return `npx -y -p ${name}@${version} constructor-research-wait`;
+}

package/dist/deployment.d.ts

@@ -0,0 +1,94 @@
+import { PlatformApi } from "./api.js";
+import { StateStore, type Operation } from "./store.js";
+import type { FileManager } from "./files.js";
+import type { LogFollower } from "./logs.js";
+export declare const terminal: Set<string>;
+export declare class DeploymentEngine {
+    readonly api: PlatformApi;
+    readonly store: StateStore;
+    /** Set by the server so a build retry can re-check and re-upload its sources. */
+    files?: FileManager;
+    logs?: LogFollower;
+    /** Native statuses this MCP saw each service go through, oldest first. */
+    private seen;
+    /**
+     * Adds what the MCP observed to a service view: the status changes it saw and the new
+     * containers it saw starting in the service log. Constructor reports neither, so an
+     * agent can tell a restart loop from a stable service. Follows the log to keep seeing.
+     */
+    private observed;
+    /** Builds of this operation that are still running get their log followed. */
+    private followLogs;
+    /** How long a file tool waits for a stopped desk storage to start. */
+    filesystemWaitMs: number;
+    /** HTTP status of a public URL, or null when nothing answers. */
+    probeUrl: (url: string) => Promise<number | null>;
+    constructor(api: PlatformApi, store: StateStore);
+    /** Hold a build while files uploaded to its disk may not have reached the builder yet. */
+    private settling;
+    private deskLink;
+    /**
+     * The platform briefly reports error while it retries, so an error counts only
+     * when seen twice for the same image. The first confirmed failure is rebuilt
+     * once under a new name, after re-uploading (local_path) and re-checking the
+     * Dockerfile on the disk.
+     */
+    private buildError;
+    private buildFailed;
+    /** Poll public URLs after start until they answer or readinessSeconds pass. */
+    private ready;
+    private root;
+    private rows;
+    private project;
+    private apps;
+    private app;
+    private images;
+    desk(project: string, id: string): Promise<any>;
+    /**
+     * The desk record plus a running file storage. A desk nobody opened recently has
+     * its storage stopped (WebDAV answers 502/503), so start it as the browser does
+     * and wait; it takes about 30-40 s.
+     */
+    filesDesk(project: string, id: string): Promise<any>;
+    listImages(raw: unknown): Promise<{
+        results: any[];
+        total: number;
+    }>;
+    deploy(raw: unknown): Promise<any>;
+    update(raw: unknown): Promise<any>;
+    buildImage(raw: unknown): Promise<any>;
+    lifecycle(kind: "start" | "stop", raw: unknown): Promise<any>;
+    private submit;
+    /**
+     * Ends unfinished deployments of the same application, so an older one cannot apply its
+     * images after the newer one. Builds it already submitted keep running on Constructor
+     * but are not used. Called under the store lock, so no step of theirs is mid-flight.
+     */
+    private supersede;
+    private resume;
+    observe(id: string): Promise<any>;
+    /** Map of every deployment-enabled project with its applications and services. */
+    private overview;
+    get(raw: unknown): Promise<any>;
+    private mutate;
+    private advance;
+    private advanceBuild;
+    private advanceLifecycle;
+    private advanceApp;
+    private serviceBody;
+    /** readiness: http_ok / not_responding / no_public_url once checked, else unverified. */
+    readinessView(op: Operation): {
+        readiness: string;
+        message: string | undefined;
+        readiness_checks?: undefined;
+    } | {
+        readiness: string;
+        readiness_checks: Record<string, {
+            url: string;
+            status: number | null;
+            ok: boolean;
+        }> | undefined;
+        message: string;
+    };
+    private view;
+}