@topline-build/harness-mcp 0.4.0 → 0.5.1

package/dist/index.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, readdir, readFile, lstat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, realpath, lstat, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import os from "node:os";
 import path from "node:path";
@@ -10,14 +10,29 @@ import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
-const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
+export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_TIMEOUT_MS = 120_000;
-const SERVER_NAME = "topline-build-stdio";
-export const HARNESS_MCP_VERSION = "0.4.0";
-const DEFAULT_OAUTH_SCOPES = ["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"];
+export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
+export const HARNESS_MCP_VERSION = "0.5.1";
+export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
+export const BUILD_MCP_SETUP_OPTIONS = Object.freeze([
+    { flag: "--url", env: "TOPLINE_API_URL", aliases: ["PLATFORM_API_URL", "OVERSITE_API_URL"], required: true, description: "Topline tenant base URL. HTTPS is required except for loopback development." },
+    { flag: "--workspace-root", env: "TOPLINE_WORKSPACE_ROOT", aliases: ["PLATFORM_WORKSPACE_ROOT"], default: "current working directory", description: "Local root that contains artifact app directories." },
+    { flag: "--surface", env: "TOPLINE_MCP_SURFACE", default: "build", allowed: ["build", "harness"], description: "Build is the current surface; harness preserves legacy OAuth compatibility." },
+    { flag: "--protocol-version", env: "TOPLINE_MCP_PROTOCOL_VERSION", aliases: ["PLATFORM_MCP_PROTOCOL_VERSION"], default: DEFAULT_MCP_PROTOCOL_VERSION, description: "MCP protocol version sent to Topline HTTP endpoints." },
+    { flag: "--auth-file", env: "TOPLINE_MCP_AUTH_FILE", aliases: ["PLATFORM_MCP_AUTH_FILE"], default: "per-tenant file in the local Topline config directory", description: "OAuth credential cache. Keep it outside artifact app directories." },
+    { flag: "--scopes", env: "TOPLINE_MCP_SCOPES", aliases: ["PLATFORM_MCP_SCOPES"], default: DEFAULT_OAUTH_SCOPES.join(" "), description: "Space- or comma-separated OAuth scopes." },
+    { flag: "--timeout-ms", env: "TOPLINE_MCP_TIMEOUT_MS", aliases: ["PLATFORM_MCP_TIMEOUT_MS", "OVERSITE_MCP_TIMEOUT_MS"], default: DEFAULT_TIMEOUT_MS, description: "Positive request timeout in milliseconds." },
+    { flag: "--token", env: "TOPLINE_MCP_TOKEN", aliases: ["PLATFORM_MCP_TOKEN", "OVERSITE_MCP_TOKEN"], description: "Advanced manual bearer-token fallback. Prefer browser-approved OAuth." }
+].map((option) => Object.freeze({
+    ...option,
+    ...(option.aliases ? { aliases: Object.freeze(option.aliases) } : {}),
+    ...(option.allowed ? { allowed: Object.freeze(option.allowed) } : {})
+})));
 const BLOCK_SIZE = 512;
 const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
 const MAX_UNPACKED_BYTES = 512 * 1024 * 1024;
+const MAX_MANIFEST_BYTES = 512 * 1024;
 const MAX_FILES = 25_000;
 const MAX_DEPTH = 64;
 const FORBIDDEN_DIRS = new Set([".git", "node_modules", ".next", ".vite", ".turbo", ".cache", "dist", "build", "coverage"]);
@@ -55,7 +70,7 @@ export function parseHarnessOptions(argv, env = process.env) {
         surface: surfaceRaw,
         token,
         authFile,
-        oauthScopes: scopes.length > 0 ? [...new Set(scopes)] : DEFAULT_OAUTH_SCOPES,
+        oauthScopes: scopes.length > 0 ? [...new Set(scopes)] : [...DEFAULT_OAUTH_SCOPES],
         timeoutMs: Math.floor(timeoutMs),
         protocolVersion,
         workspaceRoot
@@ -80,23 +95,29 @@ export function cliInfo(argv) {
     return [
         "Usage: topline-mcp --url https://your-topline-host [--workspace-root <path>]",
         "",
-        "Environment:",
-        "  TOPLINE_API_URL           Required unless --url is passed",
-        "  TOPLINE_WORKSPACE_ROOT    Defaults to the current working directory",
-        "  TOPLINE_MCP_SURFACE       Defaults to build; harness keeps legacy OAuth compatibility",
-        "  TOPLINE_MCP_TOKEN         Optional manual token fallback",
-        "  TOPLINE_MCP_AUTH_FILE     Optional OAuth credential cache path",
-        "  TOPLINE_MCP_TIMEOUT_MS    Defaults to 120000",
+        "Options and environment:",
+        ...BUILD_MCP_SETUP_OPTIONS.map((option) => {
+            const requirement = option.required ? "required" : `default: ${option.default ?? "optional"}`;
+            return `  ${option.flag.padEnd(20)} ${option.env} (${requirement})`;
+        }),
         "",
         "Examples:",
         "  npx -y @topline-build/harness-mcp --url https://hawx.topline.build",
         "  TOPLINE_API_URL=https://hawx.topline.build npx -y @topline-build/harness-mcp"
     ].join("\n");
 }
-export function createHarnessMcpStdioServer(opts) {
-    const mcp = new McpServer({ name: SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: {} } });
-    mcp.setRequestHandler(ListToolsRequestSchema, async () => listTools());
+export function createHarnessMcpStdioServer(opts, toolAllowlist) {
+    const allowedTools = toolAllowlist ? new Set(toolAllowlist) : null;
+    const listedTools = () => {
+        const listed = listTools();
+        return allowedTools ? { ...listed, tools: listed.tools.filter((tool) => allowedTools.has(tool.name)) } : listed;
+    };
+    const mcp = new McpServer({ name: BUILD_MCP_SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: {} } });
+    mcp.setRequestHandler(ListToolsRequestSchema, async () => listedTools());
     mcp.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+        if (allowedTools && !allowedTools.has(req.params.name)) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`);
+        }
         const reportsProgress = req.params.name === "platform_deploy_artifact_app" || req.params.name === "platform_wait_artifact_deploy";
         try {
             const result = await callHarnessTool(opts, req.params.name, req.params.arguments ?? {}, reportsProgress
@@ -137,6 +158,9 @@ export async function callHarnessTool(opts, name, args, hooks) {
         case "platform_deploy_artifact_app":
             result = toolResult(await deployArtifactApp(opts, input, hooks?.onProgress));
             break;
+        case "platform_inspect_artifact_app":
+            result = toolResult(await inspectArtifactApp(opts, input));
+            break;
         case "platform_artifact_status":
             result = toolResult(await getArtifactStatus(opts, stringArg(input, "artifactId"), numberArg(input, "limit")));
             break;
@@ -166,7 +190,8 @@ export async function callHarnessTool(opts, name, args, hooks) {
 export async function deployArtifactApp(opts, input, onProgress) {
     await onProgress?.(0, "Reading artifact manifest");
     const appDir = stringArg(input, "appDir");
-    const absoluteAppDir = resolveWorkspacePath(opts.workspaceRoot, appDir);
+    const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
+    await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
     const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
     const manifest = await readManifest(absoluteAppDir);
     const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
@@ -175,6 +200,10 @@ export async function deployArtifactApp(opts, input, onProgress) {
         .digest("hex");
     await onProgress?.(0.2, "Packaging local artifact app");
     const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
+    const expectedBundleSha256 = optionalString(input, "expectedBundleSha256")?.toLowerCase();
+    if (expectedBundleSha256 && bundle.sha256 !== expectedBundleSha256) {
+        throw new Error("artifact_app_bundle_changed_after_inspection");
+    }
     await onProgress?.(0.4, "Creating private artifact draft");
     const created = await fetchJson(opts, artifactAppsPath(opts), {
         method: "POST",
@@ -227,6 +256,35 @@ export async function deployArtifactApp(opts, input, onProgress) {
         deploy: deployed
     };
 }
+export async function inspectArtifactApp(opts, input) {
+    const appDir = stringArg(input, "appDir");
+    const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
+    await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
+    const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
+    const manifest = await readManifest(absoluteAppDir);
+    const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
+    const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
+    return {
+        ok: true,
+        packageReady: true,
+        serverManifestValidationRequired: true,
+        appDir: workspaceAppDir,
+        platformAppDir,
+        manifest: {
+            id: typeof manifest.id === "string" ? manifest.id : null,
+            manifestVersion: typeof manifest.manifestVersion === "number" ? manifest.manifestVersion : null,
+            title: typeof manifest.title === "string" ? manifest.title : null,
+            kind: typeof manifest.kind === "string" ? manifest.kind : null
+        },
+        bundle: {
+            fileCount: bundle.fileCount,
+            byteCount: bundle.byteCount,
+            sha256: bundle.sha256,
+            excluded: bundle.excluded
+        },
+        nextAction: "Call platform_deploy_artifact_app with the same appDir and expectedBundleSha256 set to bundle.sha256 when this local package is ready to deploy."
+    };
+}
 async function callHostedBuildTool(opts, name, input) {
     if (mcpSurface(opts) !== "build")
         throw new Error(`${name}_requires_build_surface`);
@@ -287,7 +345,7 @@ export async function initArtifactApp(opts, input) {
         .toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
     if (!manifestId || manifestId.length > 80)
         throw new Error("artifact_manifest_id_invalid");
-    const absoluteAppDir = resolveWorkspacePath(opts.workspaceRoot, appDir);
+    const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
     if (existsSync(absoluteAppDir) && (await readdir(absoluteAppDir)).length > 0)
         throw new Error("artifact_app_scaffold_target_not_empty");
     await mkdir(path.join(absoluteAppDir, "src"), { recursive: true });
@@ -321,7 +379,7 @@ export async function initArtifactApp(opts, input) {
         manifestId,
         title,
         files: ["artifact-app.json", "package.json", "src/index.js"],
-        nextAction: `Run npm test in ${appDir}, then call platform_deploy_artifact_app with the same appDir.`
+        nextAction: `Run npm test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
     };
 }
 export async function getArtifactStatus(opts, artifactId, limit) {
@@ -412,6 +470,8 @@ export function storybookAccess(opts) {
 }
 export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
     const root = path.resolve(appDir);
+    if ((await lstat(root)).isSymbolicLink())
+        throw new Error("artifact_app_bundle_symlink_forbidden:.");
     const prefix = archivePrefix ? validateArchivePrefix(archivePrefix) : "";
     const files = [];
     const excluded = [];
@@ -420,11 +480,13 @@ export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
         throw new Error("artifact_app_bundle_empty");
     let byteCount = 0;
     const chunks = [];
-    for (const file of files.sort((a, b) => a.relative.localeCompare(b.relative))) {
-        byteCount += file.size;
-        if (byteCount > MAX_UNPACKED_BYTES)
+    for (const file of files.sort((a, b) => compareUtf8Paths(a.relative, b.relative))) {
+        if (byteCount + file.size > MAX_UNPACKED_BYTES)
             throw new Error(`artifact_app_bundle_unpacked_too_large:${MAX_UNPACKED_BYTES}`);
         const content = await readFile(file.absolute);
+        byteCount += content.length;
+        if (byteCount > MAX_UNPACKED_BYTES)
+            throw new Error(`artifact_app_bundle_unpacked_too_large:${MAX_UNPACKED_BYTES}`);
         chunks.push(tarHeader(prefix ? `${prefix}/${file.relative}` : file.relative, content.length));
         chunks.push(content);
         chunks.push(Buffer.alloc(padSize(content.length)));
@@ -438,9 +500,12 @@ export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
         fileCount: files.length,
         byteCount,
         sha256: createHash("sha256").update(body).digest("hex"),
-        excluded
+        excluded: excluded.sort(compareUtf8Paths)
     };
 }
+function compareUtf8Paths(left, right) {
+    return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
 async function walk(root, current, files, excluded) {
     const entries = await readdir(current, { withFileTypes: true });
     for (const entry of entries) {
@@ -458,6 +523,8 @@ async function walk(root, current, files, excluded) {
             await walk(root, absolute, files, excluded);
         }
         else if (entry.isFile()) {
+            if (stat.nlink > 1)
+                throw new Error(`artifact_app_bundle_hardlink_forbidden:${relative}`);
             files.push({ absolute, relative, size: stat.size });
             if (files.length > MAX_FILES)
                 throw new Error(`artifact_app_bundle_file_limit:${MAX_FILES}`);
@@ -466,7 +533,32 @@ async function walk(root, current, files, excluded) {
 }
 async function readManifest(appDir) {
     const manifestPath = path.join(appDir, "artifact-app.json");
-    const parsed = JSON.parse(await readFile(manifestPath, "utf8"));
+    let stat;
+    try {
+        stat = await lstat(manifestPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new Error("artifact_app_manifest_not_found");
+        throw error;
+    }
+    if (stat.isSymbolicLink()) {
+        throw new Error("artifact_app_bundle_symlink_forbidden:artifact-app.json");
+    }
+    if (!stat.isFile())
+        throw new Error("artifact_app_manifest_must_be_file");
+    if (stat.size > MAX_MANIFEST_BYTES)
+        throw new Error(`artifact_app_manifest_too_large:${MAX_MANIFEST_BYTES}`);
+    const source = await readFile(manifestPath, "utf8");
+    if (Buffer.byteLength(source) > MAX_MANIFEST_BYTES)
+        throw new Error(`artifact_app_manifest_too_large:${MAX_MANIFEST_BYTES}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        throw new Error("artifact_app_manifest_invalid_json");
+    }
     if (!isRecord(parsed))
         throw new Error("artifact_app_manifest_must_be_object");
     return parsed;
@@ -474,10 +566,61 @@ async function readManifest(appDir) {
 function resolveWorkspacePath(workspaceRoot, inputPath) {
     const resolved = path.resolve(workspaceRoot, inputPath);
     const relative = path.relative(workspaceRoot, resolved);
-    if (relative.startsWith("..") || path.isAbsolute(relative))
+    if (pathEscapesRoot(relative))
         throw new Error("appDir_must_be_inside_workspace_root");
     return resolved;
 }
+async function resolveWorkspacePathSafely(workspaceRoot, inputPath) {
+    const root = path.resolve(workspaceRoot);
+    const resolved = resolveWorkspacePath(root, inputPath);
+    const rootRealPath = await realpath(root);
+    let existingPath = root;
+    let candidatePath = root;
+    const relative = path.relative(root, resolved);
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        candidatePath = path.join(candidatePath, segment);
+        try {
+            const stat = await lstat(candidatePath);
+            if (stat.isSymbolicLink()) {
+                throw new Error(`appDir_symlink_forbidden:${toPosix(path.relative(root, candidatePath))}`);
+            }
+            existingPath = candidatePath;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+    const existingRealPath = await realpath(existingPath);
+    const realRelative = path.relative(rootRealPath, existingRealPath);
+    if (pathEscapesRoot(realRelative)) {
+        throw new Error("appDir_must_resolve_inside_workspace_root");
+    }
+    return resolved;
+}
+function pathEscapesRoot(relativePath) {
+    return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+}
+async function assertAuthFileOutsideAppDir(authFile, appDir) {
+    const relative = path.relative(path.resolve(appDir), path.resolve(authFile));
+    if (!pathEscapesRoot(relative))
+        throw new Error("artifact_app_auth_file_inside_app_dir");
+    let realAuthFile;
+    let realAppDir;
+    try {
+        realAuthFile = await realpath(authFile);
+        realAppDir = await realpath(appDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    const realRelative = path.relative(realAppDir, realAuthFile);
+    if (!pathEscapesRoot(realRelative))
+        throw new Error("artifact_app_auth_file_inside_app_dir");
+}
 function workspaceRelativeAppDir(workspaceRoot, absoluteAppDir) {
     const relative = toPosix(path.relative(path.resolve(workspaceRoot), path.resolve(absoluteAppDir)));
     return relative ? validateArchivePrefix(relative) : ".";
@@ -515,7 +658,9 @@ function tarHeader(name, size) {
     writeOctal(header, 108, 8, 0);
     writeOctal(header, 116, 8, 0);
     writeOctal(header, 124, 12, size);
-    writeOctal(header, 136, 12, Math.floor(Date.now() / 1000));
+    // Content-identical retries must produce the same bundle hash. A wall-clock
+    // mtime would make every archive look new even when no source file changed.
+    writeOctal(header, 136, 12, 0);
     header.fill(0x20, 148, 156);
     header.write("0", 156, 1, "utf8");
     header.write("ustar", 257, 5, "utf8");
@@ -584,255 +729,283 @@ async function fetchJson(opts, url, init) {
         clearTimeout(timeout);
     }
 }
-export function listTools() {
-    return {
-        tools: [
-            {
-                name: "platform_connection_check",
-                description: "Complete the one-time Developer Access verification challenge for this Build MCP client.",
-                annotations: mcpToolAnnotations("platform_connection_check", { readOnly: false, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        verificationCode: { type: "string", minLength: 16, maxLength: 80 }
-                    },
-                    required: ["verificationCode"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" }, verified: { type: "boolean" }, product: { type: "string", enum: ["build"] }, verifiedAt: { type: "string" }
-                    },
-                    required: ["ok", "verified", "product", "verifiedAt"]
-                }
-            },
-            {
-                name: "platform_init_artifact_app",
-                description: "Create a minimal, validated artifact app starter inside the configured local workspace.",
-                annotations: mcpToolAnnotations("platform_init_artifact_app", { readOnly: false }),
-                inputSchema: {
-                    type: "object",
-                    properties: { appDir: { type: "string", minLength: 1 }, manifestId: { type: "string" }, title: { type: "string" } },
-                    required: ["appDir"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: { ok: { type: "boolean" }, appDir: { type: "string" }, manifestId: { type: "string" }, title: { type: "string" }, files: { type: "array", items: { type: "string" } }, nextAction: { type: "string" } },
-                    required: ["ok", "appDir", "manifestId", "title", "files", "nextAction"]
-                }
+const BUILD_MCP_TOOLS = [
+    {
+        name: "platform_connection_check",
+        description: "Complete the one-time Developer Access verification challenge for this Build MCP client.",
+        annotations: mcpToolAnnotations("platform_connection_check", { readOnly: false, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                verificationCode: { type: "string", minLength: 16, maxLength: 80 }
             },
-            {
-                name: "platform_deploy_artifact_app",
-                description: "Package a local artifact app directory, upload it, deploy a private draft, and return status.",
-                annotations: mcpToolAnnotations("platform_deploy_artifact_app", { readOnly: false, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        appDir: { type: "string", minLength: 1 },
-                        artifactId: { type: "string" },
-                        title: { type: "string" },
-                        description: { type: "string" },
-                        projectId: { type: "string" },
-                        requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." }
-                    },
-                    required: ["appDir"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" },
-                        artifactId: { type: "string" },
-                        artifactVersionId: { type: "string" },
-                        clientRequestId: { type: "string" },
-                        operationId: { type: ["string", "null"] },
-                        bundle: { type: "object" },
-                        create: { type: "object" },
-                        deploy: { type: "object" }
-                    },
-                    required: ["ok", "artifactId", "artifactVersionId", "clientRequestId", "operationId", "bundle", "create", "deploy"]
-                }
+            required: ["verificationCode"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, verified: { type: "boolean" }, product: { type: "string", enum: ["build"] }, verifiedAt: { type: "string" }
             },
-            {
-                name: "platform_list_build_workspaces",
-                description: "List Topline workspaces available for artifact placement.",
-                annotations: mcpToolAnnotations("platform_list_build_workspaces", { readOnly: true, openWorld: true }),
-                inputSchema: { type: "object", properties: {}, additionalProperties: false },
-                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, workspaces: { type: "array", items: { type: "object" } } }, required: ["ok", "workspaces"] }
+            required: ["ok", "verified", "product", "verifiedAt"]
+        }
+    },
+    {
+        name: "platform_init_artifact_app",
+        description: "Create a minimal, validated artifact app starter inside the configured local workspace.",
+        annotations: mcpToolAnnotations("platform_init_artifact_app", { readOnly: false }),
+        inputSchema: {
+            type: "object",
+            properties: { appDir: { type: "string", minLength: 1 }, manifestId: { type: "string" }, title: { type: "string" } },
+            required: ["appDir"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: { ok: { type: "boolean" }, appDir: { type: "string" }, manifestId: { type: "string" }, title: { type: "string" }, files: { type: "array", items: { type: "string" } }, nextAction: { type: "string" } },
+            required: ["ok", "appDir", "manifestId", "title", "files", "nextAction"]
+        }
+    },
+    {
+        name: "platform_deploy_artifact_app",
+        description: "Package a local artifact app directory, upload it, deploy a private draft, and return status.",
+        annotations: mcpToolAnnotations("platform_deploy_artifact_app", { readOnly: false, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                appDir: { type: "string", minLength: 1 },
+                artifactId: { type: "string", format: "uuid" },
+                title: { type: "string" },
+                description: { type: "string" },
+                projectId: { type: "string", format: "uuid" },
+                expectedBundleSha256: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "Optional SHA-256 from platform_inspect_artifact_app; deployment fails locally if source changed." },
+                requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." }
             },
-            {
-                name: "platform_list_artifact_drafts",
-                description: "Discover private artifact drafts created through this Build MCP connection.",
-                annotations: mcpToolAnnotations("platform_list_artifact_drafts", { readOnly: true, openWorld: true }),
-                inputSchema: { type: "object", properties: { projectId: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 100 } }, additionalProperties: false },
-                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, drafts: { type: "array", items: { type: "object" } } }, required: ["ok", "drafts"] }
+            required: ["appDir"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" },
+                artifactId: { type: "string" },
+                artifactVersionId: { type: "string" },
+                clientRequestId: { type: "string" },
+                operationId: { type: ["string", "null"] },
+                bundle: { type: "object" },
+                create: { type: "object" },
+                deploy: { type: "object" }
             },
-            {
-                name: "platform_deploy_operation",
-                description: "Read durable server-side progress for one artifact deployment operation.",
-                annotations: mcpToolAnnotations("platform_deploy_operation", { readOnly: true, openWorld: true }),
-                inputSchema: { type: "object", properties: { artifactId: { type: "string", minLength: 1 }, operationId: { type: "string", minLength: 1 }, afterSeq: { type: "integer", minimum: 0 } }, required: ["artifactId", "operationId"], additionalProperties: false },
-                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
+            required: ["ok", "artifactId", "artifactVersionId", "clientRequestId", "operationId", "bundle", "create", "deploy"]
+        }
+    },
+    {
+        name: "platform_inspect_artifact_app",
+        description: "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.",
+        annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
+        inputSchema: {
+            type: "object",
+            properties: { appDir: { type: "string", minLength: 1 } },
+            required: ["appDir"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" },
+                packageReady: { type: "boolean" },
+                serverManifestValidationRequired: { type: "boolean" },
+                appDir: { type: "string" },
+                platformAppDir: { type: "string" },
+                manifest: { type: "object" },
+                bundle: { type: "object" },
+                nextAction: { type: "string" }
             },
-            {
-                name: "platform_wait_artifact_deploy",
-                description: "Wait for a durable deployment operation and stream server-derived progress.",
-                annotations: mcpToolAnnotations("platform_wait_artifact_deploy", { readOnly: true, openWorld: true }),
-                inputSchema: { type: "object", properties: { artifactId: { type: "string", minLength: 1 }, operationId: { type: "string", minLength: 1 }, timeoutSeconds: { type: "integer", minimum: 1, maximum: 900 } }, required: ["artifactId", "operationId"], additionalProperties: false },
-                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
+            required: ["ok", "packageReady", "serverManifestValidationRequired", "appDir", "platformAppDir", "manifest", "bundle", "nextAction"]
+        }
+    },
+    {
+        name: "platform_list_build_workspaces",
+        description: "List Topline workspaces available for artifact placement.",
+        annotations: mcpToolAnnotations("platform_list_build_workspaces", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, workspaces: { type: "array", items: { type: "object" } } }, required: ["ok", "workspaces"] }
+    },
+    {
+        name: "platform_list_artifact_drafts",
+        description: "Discover private artifact drafts created through this Build MCP connection.",
+        annotations: mcpToolAnnotations("platform_list_artifact_drafts", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: { projectId: { type: "string", format: "uuid" }, limit: { type: "integer", minimum: 1, maximum: 100 } }, additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, drafts: { type: "array", items: { type: "object" } } }, required: ["ok", "drafts"] }
+    },
+    {
+        name: "platform_deploy_operation",
+        description: "Read durable server-side progress for one artifact deployment operation.",
+        annotations: mcpToolAnnotations("platform_deploy_operation", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" }, operationId: { type: "string", format: "uuid" }, afterSeq: { type: "integer", minimum: 0 } }, required: ["artifactId", "operationId"], additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
+    },
+    {
+        name: "platform_wait_artifact_deploy",
+        description: "Wait for a durable deployment operation and stream server-derived progress.",
+        annotations: mcpToolAnnotations("platform_wait_artifact_deploy", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" }, operationId: { type: "string", format: "uuid" }, timeoutSeconds: { type: "integer", minimum: 1, maximum: 900 } }, required: ["artifactId", "operationId"], additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
+    },
+    {
+        name: "platform_artifact_status",
+        description: "Read private draft deployment status for a hosted artifact app.",
+        annotations: mcpToolAnnotations("platform_artifact_status", { readOnly: true, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: { artifactId: { type: "string", format: "uuid" }, limit: { type: "integer", minimum: 1, maximum: 50 } },
+            required: ["artifactId"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" },
+                deployments: { type: "array", items: { type: "object" } }
             },
-            {
-                name: "platform_artifact_status",
-                description: "Read private draft deployment status for a hosted artifact app.",
-                annotations: mcpToolAnnotations("platform_artifact_status", { readOnly: true, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: { artifactId: { type: "string", minLength: 1 }, limit: { type: "integer", minimum: 1, maximum: 50 } },
-                    required: ["artifactId"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" },
-                        deployments: { type: "array", items: { type: "object" } }
-                    },
-                    required: ["ok", "phase", "artifactId", "deployments"]
-                }
+            required: ["ok", "phase", "artifactId", "deployments"]
+        }
+    },
+    {
+        name: "platform_read_artifact_logs",
+        description: "Read bounded, redacted deployment logs for a hosted artifact app.",
+        annotations: mcpToolAnnotations("platform_read_artifact_logs", { readOnly: true, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                artifactId: { type: "string", format: "uuid" },
+                deploymentRecordId: { type: "string", format: "uuid" },
+                environment: { type: "string", enum: ["draft", "live"] },
+                limit: { type: "integer", minimum: 1, maximum: 200 },
+                severity: { type: "string" },
+                contains: { type: "string" },
+                since: { type: "string", format: "date-time" },
+                windowMinutes: { type: "integer", minimum: 1, maximum: 1440 },
+                trace: { type: "string" },
+                requestId: { type: "string" },
+                route: { type: "string" }
             },
-            {
-                name: "platform_read_artifact_logs",
-                description: "Read bounded, redacted deployment logs for a hosted artifact app.",
-                annotations: mcpToolAnnotations("platform_read_artifact_logs", { readOnly: true, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        artifactId: { type: "string", minLength: 1 },
-                        deploymentRecordId: { type: "string" },
-                        environment: { type: "string", enum: ["draft", "live"] },
-                        limit: { type: "integer", minimum: 1, maximum: 200 },
-                        severity: { type: "string" },
-                        contains: { type: "string" },
-                        since: { type: "string", format: "date-time" },
-                        windowMinutes: { type: "integer", minimum: 1, maximum: 1440 },
-                        trace: { type: "string" },
-                        requestId: { type: "string" },
-                        route: { type: "string" }
-                    },
-                    required: ["artifactId"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" },
-                        phase: { type: "string" },
-                        artifactId: { type: "string" },
-                        entries: { type: "array", items: { type: "object" } }
-                    },
-                    required: ["ok", "phase", "artifactId"]
-                }
+            required: ["artifactId"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" },
+                phase: { type: "string" },
+                artifactId: { type: "string" },
+                entries: { type: "array", items: { type: "object" } }
             },
-            {
-                name: "platform_open_artifact",
-                description: "Return the operator URL and latest draft/live URLs for a hosted artifact app.",
-                annotations: mcpToolAnnotations("platform_open_artifact", { readOnly: true, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: { artifactId: { type: "string", minLength: 1 } },
-                    required: ["artifactId"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" }, artifactId: { type: "string" }, openUrl: { type: "string" },
-                        draftUrl: { type: ["string", "null"] }, liveUrl: { type: ["string", "null"] }, versionUrl: { type: ["string", "null"] }
-                    },
-                    required: ["ok", "artifactId", "openUrl", "draftUrl", "liveUrl", "versionUrl"]
-                }
+            required: ["ok", "phase", "artifactId"]
+        }
+    },
+    {
+        name: "platform_open_artifact",
+        description: "Return the operator URL and latest draft/live URLs for a hosted artifact app.",
+        annotations: mcpToolAnnotations("platform_open_artifact", { readOnly: true, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: { artifactId: { type: "string", format: "uuid" } },
+            required: ["artifactId"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, artifactId: { type: "string" }, openUrl: { type: "string" },
+                draftUrl: { type: ["string", "null"] }, liveUrl: { type: ["string", "null"] }, versionUrl: { type: ["string", "null"] }
             },
-            {
-                name: "platform_storybook_access",
-                description: "Return the tenant Storybook preview URL and HTTP MCP server config.",
-                annotations: mcpToolAnnotations("platform_storybook_access", { readOnly: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: {},
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" }, storybookUrl: { type: "string" }, mcpUrl: { type: "string" }, mcpServers: { type: "object" }
-                    },
-                    required: ["ok", "storybookUrl", "mcpUrl", "mcpServers"]
-                }
+            required: ["ok", "artifactId", "openUrl", "draftUrl", "liveUrl", "versionUrl"]
+        }
+    },
+    {
+        name: "platform_storybook_access",
+        description: "Return the tenant Storybook preview URL and HTTP MCP server config.",
+        annotations: mcpToolAnnotations("platform_storybook_access", { readOnly: true }),
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, storybookUrl: { type: "string" }, mcpUrl: { type: "string" }, mcpServers: { type: "object" }
             },
-            {
-                name: "platform_validate_artifact",
-                description: "Read trusted smoke and health evidence for a private artifact draft without requiring a browser session.",
-                annotations: mcpToolAnnotations("platform_validate_artifact", { readOnly: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        artifactId: { type: "string", minLength: 1 },
-                        deploymentRecordId: { type: "string", minLength: 1 }
-                    },
-                    required: ["artifactId"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: {
-                        ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" },
-                        deploymentRecordId: { type: "string" }, deploymentState: { type: "string" },
-                        healthy: { type: "boolean" }, checkedAt: { type: ["string", "null"] },
-                        draftUrl: { type: ["string", "null"] }, smoke: { type: ["object", "null"] }
-                    },
-                    required: ["ok", "phase", "artifactId", "deploymentRecordId", "deploymentState", "healthy", "checkedAt", "draftUrl", "smoke"]
-                }
+            required: ["ok", "storybookUrl", "mcpUrl", "mcpServers"]
+        }
+    },
+    {
+        name: "platform_validate_artifact",
+        description: "Read trusted smoke and health evidence for a private artifact draft without requiring a browser session.",
+        annotations: mcpToolAnnotations("platform_validate_artifact", { readOnly: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                artifactId: { type: "string", format: "uuid" },
+                deploymentRecordId: { type: "string", format: "uuid" }
             },
-            {
-                name: "platform_run_artifact_smoke",
-                description: "Rerun the trusted draft smoke check and return fresh rendered-page evidence.",
-                annotations: mcpToolAnnotations("platform_run_artifact_smoke", { readOnly: false, openWorld: true }),
-                inputSchema: { type: "object", properties: { artifactId: { type: "string", minLength: 1 }, deploymentRecordId: { type: "string", minLength: 1 } }, required: ["artifactId"], additionalProperties: false },
-                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, deploymentRecordId: { type: "string" }, smoke: { type: "object" }, validation: { type: "object" } }, required: ["ok", "phase", "artifactId", "deploymentRecordId", "smoke", "validation"] }
+            required: ["artifactId"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" },
+                deploymentRecordId: { type: "string" }, deploymentState: { type: "string" },
+                healthy: { type: "boolean" }, checkedAt: { type: ["string", "null"] },
+                draftUrl: { type: ["string", "null"] }, smoke: { type: ["object", "null"] }
             },
-            {
-                name: "platform_plan_artifact_draft_delete",
-                description: "Preview cleanup effects and receive the state-bound plan token required for deletion.",
-                annotations: mcpToolAnnotations("platform_plan_artifact_draft_delete", { readOnly: true, openWorld: true }),
-                inputSchema: { type: "object", properties: { artifactId: { type: "string", minLength: 1 } }, required: ["artifactId"], additionalProperties: false },
-                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, eligible: { type: "boolean" }, effects: { type: "object" }, planToken: { type: "string" } }, required: ["ok", "phase", "artifactId", "eligible", "effects", "planToken"] }
+            required: ["ok", "phase", "artifactId", "deploymentRecordId", "deploymentState", "healthy", "checkedAt", "draftUrl", "smoke"]
+        }
+    },
+    {
+        name: "platform_run_artifact_smoke",
+        description: "Rerun the trusted draft smoke check and return fresh rendered-page evidence.",
+        annotations: mcpToolAnnotations("platform_run_artifact_smoke", { readOnly: false, openWorld: true }),
+        inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" }, deploymentRecordId: { type: "string", format: "uuid" } }, required: ["artifactId"], additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, deploymentRecordId: { type: "string" }, smoke: { type: "object" }, validation: { type: "object" } }, required: ["ok", "phase", "artifactId", "deploymentRecordId", "smoke", "validation"] }
+    },
+    {
+        name: "platform_plan_artifact_draft_delete",
+        description: "Preview cleanup effects and receive the state-bound plan token required for deletion.",
+        annotations: mcpToolAnnotations("platform_plan_artifact_draft_delete", { readOnly: true, openWorld: true }),
+        inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" } }, required: ["artifactId"], additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, eligible: { type: "boolean" }, effects: { type: "object" }, planToken: { type: "string" } }, required: ["ok", "phase", "artifactId", "eligible", "effects", "planToken"] }
+    },
+    {
+        name: "platform_delete_artifact_draft",
+        description: "Permanently remove an unpromoted private draft created by this MCP connection after exact-id confirmation.",
+        annotations: mcpToolAnnotations("platform_delete_artifact_draft", { readOnly: false, destructive: true, openWorld: true }),
+        inputSchema: {
+            type: "object",
+            properties: {
+                artifactId: { type: "string", format: "uuid" },
+                confirmArtifactId: { type: "string", format: "uuid" },
+                planToken: { type: "string", minLength: 1 }
             },
-            {
-                name: "platform_delete_artifact_draft",
-                description: "Permanently remove an unpromoted private draft created by this MCP connection after exact-id confirmation.",
-                annotations: mcpToolAnnotations("platform_delete_artifact_draft", { readOnly: false, destructive: true, openWorld: true }),
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        artifactId: { type: "string", minLength: 1 },
-                        confirmArtifactId: { type: "string", minLength: 1 },
-                        planToken: { type: "string", minLength: 1 }
-                    },
-                    required: ["artifactId", "confirmArtifactId", "planToken"],
-                    additionalProperties: false
-                },
-                outputSchema: {
-                    type: "object",
-                    properties: { ok: { type: "boolean" }, deleted: { type: "boolean" }, artifactId: { type: "string" } },
-                    required: ["ok", "deleted", "artifactId"]
-                }
-            }
-        ].map(withRecoveryOutputSchema)
-    };
+            required: ["artifactId", "confirmArtifactId", "planToken"],
+            additionalProperties: false
+        },
+        outputSchema: {
+            type: "object",
+            properties: { ok: { type: "boolean" }, deleted: { type: "boolean" }, artifactId: { type: "string" } },
+            required: ["ok", "deleted", "artifactId"]
+        }
+    }
+].map(withRecoveryOutputSchema);
+export function listTools() {
+    // Preserve the original tools/list isolation boundary: callers must not be
+    // able to mutate the registry used by later requests or input validation.
+    return { tools: structuredClone(BUILD_MCP_TOOLS) };
 }
-function withRecoveryOutputSchema(tool) {
+function withRecoveryOutputSchema(value) {
+    const tool = value;
     if (!tool.outputSchema)
         return tool;
     return {
@@ -889,17 +1062,23 @@ function toolResult(value) {
 function toolError(message) {
     return structuredToolError(message);
 }
+const BUILD_MCP_RECOVERY_ERROR_VALUES = {
+    platform_harness_timeout: { retryable: true, recoveryAction: "Retry the call. For a deployment, use platform_list_artifact_drafts to recover the artifact and platform_wait_artifact_deploy to resume progress." },
+    platform_mcp_tool_error: { retryable: false, recoveryAction: "Read the returned error code, correct the request or OAuth scopes, then retry." },
+    artifact_deploy_wait_timeout: { retryable: true, recoveryAction: "Call platform_wait_artifact_deploy again with the same artifactId and operationId." },
+    artifact_delete_plan_stale: { retryable: true, recoveryAction: "Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken." },
+    artifact_app_bundle_changed_after_inspection: { retryable: true, recoveryAction: "Call platform_inspect_artifact_app again, review the new bundle hash, then retry deployment with that hash." },
+    artifact_app_bundle_hardlink_forbidden: { retryable: false, recoveryAction: "Replace the hard link with a regular file copied into appDir, then inspect again." },
+    artifact_app_auth_file_inside_app_dir: { retryable: false, recoveryAction: "Move TOPLINE_MCP_AUTH_FILE outside appDir, reconnect the Build MCP, then inspect again." },
+    artifact_app_manifest_not_found: { retryable: false, recoveryAction: "Create artifact-app.json inside appDir, or correct appDir, then inspect again." },
+    artifact_app_manifest_too_large: { retryable: false, recoveryAction: "Keep artifact-app.json below 512 KiB. Move application data and source into separate files, then inspect again." },
+    scope_required: { retryable: false, recoveryAction: "Reconnect the Build MCP and approve the requested scope." },
+    artifact_app_scaffold_target_not_empty: { retryable: false, recoveryAction: "Choose an empty appDir or deploy the existing app without scaffolding." }
+};
+export const BUILD_MCP_RECOVERY_ERRORS = Object.freeze(Object.fromEntries(Object.entries(BUILD_MCP_RECOVERY_ERROR_VALUES).map(([code, guidance]) => [code, Object.freeze(guidance)])));
 function structuredToolError(message) {
     const code = recoveryErrorCode(message);
-    const recovery = {
-        platform_harness_timeout: { retryable: true, recoveryAction: "Retry the call. For a deployment, use platform_list_artifact_drafts to recover the artifact and platform_wait_artifact_deploy to resume progress." },
-        platform_mcp_tool_error: { retryable: false, recoveryAction: "Read the returned error code, correct the request or OAuth scopes, then retry." },
-        artifact_deploy_wait_timeout: { retryable: true, recoveryAction: "Call platform_wait_artifact_deploy again with the same artifactId and operationId." },
-        artifact_delete_plan_stale: { retryable: true, recoveryAction: "Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken." },
-        scope_required: { retryable: false, recoveryAction: "Reconnect the Build MCP and approve the requested scope." },
-        artifact_app_scaffold_target_not_empty: { retryable: false, recoveryAction: "Choose an empty appDir or deploy the existing app without scaffolding." }
-    };
-    const selected = recovery[code] ?? { retryable: /^platform_harness_http_error:5|timeout|rate_limited/.test(message), recoveryAction: "Inspect the code and message, correct the input if needed, then retry the same tool." };
+    const selected = BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable: /^platform_harness_http_error:5|timeout|rate_limited/.test(message), recoveryAction: "Inspect the code and message, correct the input if needed, then retry the same tool." };
     const structuredContent = { ok: false, error: { code, message, ...selected } };
     return {
         content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
@@ -946,9 +1125,30 @@ async function jsonHeaders(opts) {
         "MCP-Protocol-Version": opts.protocolVersion
     };
 }
+const inFlightBearerTokenRequests = new Map();
 export async function getBearerToken(opts) {
     if (opts.token?.trim())
         return opts.token.trim();
+    const key = [
+        path.resolve(opts.authFile),
+        platformBaseUrl(opts),
+        mcpSurface(opts),
+        [...opts.oauthScopes].sort().join(" ")
+    ].join("\0");
+    const existing = inFlightBearerTokenRequests.get(key);
+    if (existing)
+        return existing;
+    const pending = getOAuthBearerToken(opts);
+    inFlightBearerTokenRequests.set(key, pending);
+    try {
+        return await pending;
+    }
+    finally {
+        if (inFlightBearerTokenRequests.get(key) === pending)
+            inFlightBearerTokenRequests.delete(key);
+    }
+}
+async function getOAuthBearerToken(opts) {
     const stored = await readStoredOAuthCredentials(opts);
     if (stored?.accessToken && stored.accessTokenExpiresAt && new Date(stored.accessTokenExpiresAt).getTime() - Date.now() > 60_000) {
         return stored.accessToken;
@@ -1092,7 +1292,7 @@ async function readStoredOAuthCredentials(opts) {
         const issuer = typeof parsed.issuer === "string" ? parsed.issuer : "";
         const resource = typeof parsed.resource === "string" ? parsed.resource : "";
         const clientId = typeof parsed.clientId === "string" ? parsed.clientId : "";
-        const scopes = Array.isArray(parsed.scopes) ? parsed.scopes.filter((scope) => typeof scope === "string") : DEFAULT_OAUTH_SCOPES;
+        const scopes = Array.isArray(parsed.scopes) ? parsed.scopes.filter((scope) => typeof scope === "string") : [...DEFAULT_OAUTH_SCOPES];
         if (!issuer || !resource || !clientId)
             return null;
         const expectedIssuer = platformBaseUrl(opts);
@@ -1229,8 +1429,19 @@ function normalizeApiUrl(raw) {
     }
     if (url.protocol !== "http:" && url.protocol !== "https:")
         throw new Error("TOPLINE_API_URL must be an http(s) URL");
+    if (url.username || url.password)
+        throw new Error("TOPLINE_API_URL must not include credentials");
+    if (url.search || url.hash)
+        throw new Error("TOPLINE_API_URL must not include a query or fragment");
+    if (url.protocol !== "https:" && !isLoopbackHostname(url.hostname)) {
+        throw new Error("TOPLINE_API_URL must use https except for loopback development");
+    }
     return url.toString().replace(/\/$/g, "");
 }
+function isLoopbackHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "[::1]" || normalized === "::1";
+}
 function firstEnv(env, ...keys) {
     for (const key of keys) {
         const value = env[key]?.trim();
@@ -1273,8 +1484,22 @@ function toPosix(value) {
 }
 function redactSecrets(value, opts) {
     const token = opts.token?.trim();
-    const withoutStatic = token ? value.split(token).join("[redacted]") : value;
-    return withoutStatic
+    let redacted = token ? value.split(token).join("[redacted]") : value;
+    const localPaths = [opts.authFile, opts.workspaceRoot, os.homedir()]
+        .map((candidate) => path.resolve(candidate))
+        .filter((candidate, index, all) => candidate.length > path.parse(candidate).root.length && all.indexOf(candidate) === index)
+        .sort((left, right) => right.length - left.length);
+    for (const localPath of localPaths) {
+        const variants = new Set([
+            localPath,
+            toPosix(localPath),
+            JSON.stringify(localPath).slice(1, -1),
+            JSON.stringify(toPosix(localPath)).slice(1, -1)
+        ]);
+        for (const variant of variants)
+            redacted = redacted.split(variant).join("[local-path]");
+    }
+    return redacted
         .replace(/ovmcp_[A-Za-z0-9_-]+/g, "[redacted]")
         .replace(/tlmcp_(?:at|rt|code)_[A-Za-z0-9_-]+/g, "[redacted]");
 }