@topline-build/harness-mcp 0.1.2 → 0.4.0

package/README.md

@@ -1,4 +1,4 @@
-# Topline Harness MCP
+# Topline Build MCP
 
 Local stdio MCP connector for deploying Topline artifact app drafts from Codex,
 Claude Code, or another local MCP host.
@@ -13,6 +13,7 @@ Required environment:
 
 Optional environment:
 
+- `TOPLINE_MCP_SURFACE` (`build` by default; `harness` for legacy compatibility)
 - `TOPLINE_MCP_PROTOCOL_VERSION`
 - `TOPLINE_WORKSPACE_ROOT`
 - `TOPLINE_MCP_AUTH_FILE`
@@ -43,6 +44,85 @@ npx -y @topline-build/harness-mcp --url https://hawx.topline.build
 Set `TOPLINE_WORKSPACE_ROOT` when your MCP host starts outside the repo that
 contains the artifact app.
 
-Topline Developer Access provides harness-specific snippets for Codex and
-Claude Code. Those snippets contain no raw token; the first tool call opens a
-browser approval flow.
+The app can live anywhere under that workspace. For source tracking, the MCP
+maps ordinary local folders to `artifact-apps/<manifest-id>` while preserving
+existing `artifact-apps/<name>` roots and workspace-root (`.`) apps. Deploys
+report manifest, packaging, draft creation, upload, and trusted-deployment
+progress to clients that support MCP progress notifications.
+Every deploy also receives a deterministic retry key. If a client loses the
+response and repeats the call, Topline resumes the same private draft instead
+of creating an ordinary duplicate.
+
+Topline Developer Access provides Build MCP snippets for Codex and Claude Code.
+Those snippets contain no raw token; the first tool call opens a browser
+approval flow scoped to artifact building.
+
+## Build workflow
+
+- `platform_init_artifact_app` creates a dependency-free starter in an empty
+  local directory.
+- `platform_connection_check` completes the one-time verification shown in
+  Developer Access.
+- `platform_list_build_workspaces` and `platform_list_artifact_drafts` discover
+  valid placement targets and recover existing drafts without exposing chat or
+  memory data.
+- `platform_deploy_artifact_app` packages the local app and deploys a private
+  draft through Topline's trusted runtime. Its `operationId` can be passed to
+  `platform_wait_artifact_deploy` for server-derived progress and recovery
+  after a disconnected client.
+- `platform_run_artifact_smoke` reruns trusted draft rendering and returns the
+  fresh evidence used by validation.
+- `platform_validate_artifact` returns bounded trusted smoke and rendered-page
+  evidence without requiring the agent to hold a browser session.
+- `platform_artifact_status`, `platform_read_artifact_logs`, and
+  `platform_open_artifact` inspect and hand off the draft.
+- `platform_plan_artifact_draft_delete` previews cleanup effects. Deletion uses
+  a separately approved `harness:artifact:delete` scope, the exact artifact id,
+  and the current plan token; stale plans fail closed.
+
+Tool failures include a stable error code, retryability, and a concrete
+recovery action in `structuredContent`.
+
+## Live certification
+
+After building the package, a release operator can exercise the real MCP client
+protocol, workspace discovery, deploy/resume, smoke, validation, and cleanup
+planning against a tenant:
+
+```bash
+npm run build
+TOPLINE_API_URL=https://tenant.example \
+TOPLINE_MCP_TOKEN=... \
+TOPLINE_WORKSPACE_ROOT=/path/to/workspace \
+TOPLINE_CERTIFICATION_APP_DIR=artifact-apps/certification \
+npm run certify:live
+```
+
+Set `TOPLINE_CERTIFICATION_CLEANUP=1` only when the certification draft should
+be removed after its cleanup plan is reviewed.
+
+## Storybook
+
+Use the `platform_storybook_access` tool to get the tenant Storybook preview URL
+and the HTTP MCP client config. For clients with HTTP MCP OAuth support, use
+the returned `cursorMcpJson`:
+
+```json
+{
+  "mcpServers": {
+    "storybook": {
+      "url": "https://your-topline-host/api/design-systems/storybook/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+Storybook MCP access uses the harness bearer/OAuth credentials with
+`harness:artifact:read`; OAuth discovery is available at
+`/.well-known/oauth-protected-resource/mcp/build`.
+
+If your MCP client does not support HTTP MCP OAuth, use the returned
+`manualBearerMcpJson` template with a read-scoped `TOPLINE_MCP_TOKEN` in the
+client's secret mechanism. Opening the visual preview URL in a browser still
+requires a signed-in Topline session.

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
-import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type CallToolResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
 export interface HarnessMcpStdioOptions {
     apiUrl: string;
+    /** Defaults to the Build MCP. Use harness only for legacy deployments. */
+    surface?: "build" | "harness";
     token?: string;
     authFile: string;
     oauthScopes: string[];
@@ -27,17 +29,22 @@ export interface PackedArtifactAppBundle {
     sha256: string;
     excluded: string[];
 }
-export declare const HARNESS_MCP_VERSION = "0.1.2";
+type ToolProgressReporter = (progress: number, message: string) => void | Promise<void>;
+export declare const HARNESS_MCP_VERSION = "0.4.0";
 export declare function parseHarnessOptions(argv: string[], env?: Record<string, string | undefined>): HarnessMcpStdioOptions;
 export declare function runHarnessMcpStdioCli(): Promise<void>;
 export declare function cliInfo(argv: string[]): string | null;
 export declare function createHarnessMcpStdioServer(opts: HarnessMcpStdioOptions): McpServer;
-export declare function callHarnessTool(opts: HarnessMcpStdioOptions, name: string, args: unknown): Promise<CallToolResult>;
-export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
+export declare function callHarnessTool(opts: HarnessMcpStdioOptions, name: string, args: unknown, hooks?: {
+    onProgress?: ToolProgressReporter;
+}): Promise<CallToolResult>;
+export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<{
     ok: boolean;
     artifactId: string;
     artifactVersionId: string;
     manifestId: string | null;
+    clientRequestId: string;
+    operationId: string | null;
     bundle: {
         fileCount: number;
         byteCount: number;
@@ -47,6 +54,15 @@ export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: R
     create: unknown;
     deploy: unknown;
 }>;
+export declare function waitForArtifactDeploy(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<Record<string, unknown>>;
+export declare function initArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
+    ok: boolean;
+    appDir: string;
+    manifestId: string;
+    title: string;
+    files: string[];
+    nextAction: string;
+}>;
 export declare function getArtifactStatus(opts: HarnessMcpStdioOptions, artifactId: string, limit?: number): Promise<unknown>;
 export declare function readArtifactLogs(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<unknown>;
 export declare function openArtifact(opts: HarnessMcpStdioOptions, artifactId: string): Promise<{
@@ -72,9 +88,50 @@ export declare function openArtifact(opts: HarnessMcpStdioOptions, artifactId: s
     liveUrl: string | null;
     versionUrl: string | null;
 }>;
+export declare function storybookAccess(opts: HarnessMcpStdioOptions): {
+    ok: boolean;
+    storybookUrl: string;
+    previewUrl: string;
+    mcpUrl: string;
+    mcpServers: {
+        storybook: {
+            url: string;
+            type: string;
+        };
+    };
+    cursorMcpJson: {
+        mcpServers: {
+            storybook: {
+                url: string;
+                type: string;
+            };
+        };
+    };
+    manualBearerMcpJson: {
+        mcpServers: {
+            storybook: {
+                url: string;
+                type: string;
+                headers: {
+                    Authorization: string;
+                };
+            };
+        };
+    };
+    auth: {
+        mcp: string;
+        preview: string;
+        resourceMetadataUrl: string;
+        scope: string;
+        manualBearerEnv: string;
+    };
+    operatorAction: string;
+};
 export declare function packArtifactAppDirectory(appDir: string, archivePrefix?: string): Promise<PackedArtifactAppBundle>;
+export declare function listTools(): ListToolsResult;
 export declare function getBearerToken(opts: HarnessMcpStdioOptions): Promise<string>;
 export declare function browserOpenCommand(url: string, platform?: string): {
     command: string;
     args: string[];
 };
+export {};

package/dist/index.js

@@ -8,12 +8,13 @@ import path from "node:path";
 import { gzipSync } from "node:zlib";
 import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.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";
 const DEFAULT_TIMEOUT_MS = 120_000;
-const SERVER_NAME = "topline-harness-stdio";
-export const HARNESS_MCP_VERSION = "0.1.2";
-const DEFAULT_OAUTH_SCOPES = ["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy"];
+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"];
 const BLOCK_SIZE = 512;
 const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
 const MAX_UNPACKED_BYTES = 512 * 1024 * 1024;
@@ -34,6 +35,9 @@ export function parseHarnessOptions(argv, env = process.env) {
     const token = getArg("--token") || firstEnv(env, "TOPLINE_MCP_TOKEN", "PLATFORM_MCP_TOKEN", "OVERSITE_MCP_TOKEN") || undefined;
     const timeoutRaw = getArg("--timeout-ms") || firstEnv(env, "TOPLINE_MCP_TIMEOUT_MS", "PLATFORM_MCP_TIMEOUT_MS", "OVERSITE_MCP_TIMEOUT_MS");
     const protocolVersion = getArg("--protocol-version") || firstEnv(env, "TOPLINE_MCP_PROTOCOL_VERSION", "PLATFORM_MCP_PROTOCOL_VERSION") || DEFAULT_MCP_PROTOCOL_VERSION;
+    const surfaceRaw = getArg("--surface") || firstEnv(env, "TOPLINE_MCP_SURFACE") || "build";
+    if (surfaceRaw !== "build" && surfaceRaw !== "harness")
+        throw new Error("TOPLINE_MCP_SURFACE must be build or harness");
     const workspaceRoot = path.resolve(getArg("--workspace-root") || firstEnv(env, "TOPLINE_WORKSPACE_ROOT", "PLATFORM_WORKSPACE_ROOT") || process.cwd());
     const timeoutMs = timeoutRaw ? Number(timeoutRaw) : DEFAULT_TIMEOUT_MS;
     if (!apiUrl)
@@ -41,13 +45,14 @@ export function parseHarnessOptions(argv, env = process.env) {
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
         throw new Error("TOPLINE_MCP_TIMEOUT_MS must be a positive number");
     const normalizedApiUrl = normalizeApiUrl(apiUrl);
-    const authFile = path.resolve(getArg("--auth-file") || firstEnv(env, "TOPLINE_MCP_AUTH_FILE", "PLATFORM_MCP_AUTH_FILE") || defaultAuthFile(normalizedApiUrl));
+    const authFile = path.resolve(getArg("--auth-file") || firstEnv(env, "TOPLINE_MCP_AUTH_FILE", "PLATFORM_MCP_AUTH_FILE") || defaultAuthFile(normalizedApiUrl, surfaceRaw));
     const scopes = (getArg("--scopes") || firstEnv(env, "TOPLINE_MCP_SCOPES", "PLATFORM_MCP_SCOPES") || DEFAULT_OAUTH_SCOPES.join(" "))
         .split(/[\s,]+/)
         .map((scope) => scope.trim())
         .filter(Boolean);
     return {
         apiUrl: normalizedApiUrl,
+        surface: surfaceRaw,
         token,
         authFile,
         oauthScopes: scopes.length > 0 ? [...new Set(scopes)] : DEFAULT_OAUTH_SCOPES,
@@ -78,6 +83,7 @@ export function cliInfo(argv) {
         "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",
@@ -90,40 +96,86 @@ export function cliInfo(argv) {
 export function createHarnessMcpStdioServer(opts) {
     const mcp = new McpServer({ name: SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: {} } });
     mcp.setRequestHandler(ListToolsRequestSchema, async () => listTools());
-    mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+    mcp.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+        const reportsProgress = req.params.name === "platform_deploy_artifact_app" || req.params.name === "platform_wait_artifact_deploy";
         try {
-            return await callHarnessTool(opts, req.params.name, req.params.arguments ?? {});
+            const result = await callHarnessTool(opts, req.params.name, req.params.arguments ?? {}, reportsProgress
+                ? { onProgress: (progress, message) => sendProgress(extra, progress, 1, message) }
+                : undefined);
+            return result;
         }
         catch (err) {
-            return {
-                content: [{ type: "text", text: redactSecrets(err instanceof Error ? err.message : String(err), opts) }],
-                isError: true
-            };
+            if (err instanceof McpError)
+                throw err;
+            if (reportsProgress)
+                await sendProgress(extra, 1, 1, "Failed artifact deployment");
+            return structuredToolError(redactSecrets(err instanceof Error ? err.message : String(err), opts));
         }
     });
     return mcp;
 }
-export async function callHarnessTool(opts, name, args) {
+export async function callHarnessTool(opts, name, args, hooks) {
     const input = isRecord(args) ? args : {};
+    const tool = listTools().tools.find((candidate) => candidate.name === name);
+    if (!tool)
+        throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
+    const inputError = validateJsonSchema(tool.inputSchema, input);
+    if (inputError)
+        return toolError(`Invalid arguments for ${name}: ${inputError}`);
+    let result;
     switch (name) {
+        case "platform_connection_check":
+        case "platform_list_build_workspaces":
+        case "platform_list_artifact_drafts":
+        case "platform_deploy_operation":
+        case "platform_validate_artifact":
+        case "platform_run_artifact_smoke":
+        case "platform_plan_artifact_draft_delete":
+        case "platform_delete_artifact_draft":
+            result = toolResult(await callHostedBuildTool(opts, name, input));
+            break;
         case "platform_deploy_artifact_app":
-            return toolResult(await deployArtifactApp(opts, input));
+            result = toolResult(await deployArtifactApp(opts, input, hooks?.onProgress));
+            break;
         case "platform_artifact_status":
-            return toolResult(await getArtifactStatus(opts, stringArg(input, "artifactId"), numberArg(input, "limit")));
+            result = toolResult(await getArtifactStatus(opts, stringArg(input, "artifactId"), numberArg(input, "limit")));
+            break;
         case "platform_read_artifact_logs":
-            return toolResult(await readArtifactLogs(opts, input));
+            result = toolResult(await readArtifactLogs(opts, input));
+            break;
         case "platform_open_artifact":
-            return toolResult(await openArtifact(opts, stringArg(input, "artifactId")));
+            result = toolResult(await openArtifact(opts, stringArg(input, "artifactId")));
+            break;
+        case "platform_storybook_access":
+            result = toolResult(storybookAccess(opts));
+            break;
+        case "platform_wait_artifact_deploy":
+            result = toolResult(await waitForArtifactDeploy(opts, input, hooks?.onProgress));
+            break;
+        case "platform_init_artifact_app":
+            result = toolResult(await initArtifactApp(opts, input));
+            break;
         default:
-            return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
     }
+    const outputError = tool.outputSchema
+        ? validateJsonSchema(tool.outputSchema, result.structuredContent)
+        : null;
+    return outputError ? toolError(`Invalid output for ${name}: ${outputError}`) : result;
 }
-export async function deployArtifactApp(opts, input) {
+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 platformAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
+    const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
     const manifest = await readManifest(absoluteAppDir);
+    const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
+    const clientRequestId = optionalString(input, "requestId") ?? createHash("sha256")
+        .update(JSON.stringify({ apiUrl: platformBaseUrl(opts), appDir: platformAppDir, manifestId: manifest.id ?? null }))
+        .digest("hex");
+    await onProgress?.(0.2, "Packaging local artifact app");
     const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
+    await onProgress?.(0.4, "Creating private artifact draft");
     const created = await fetchJson(opts, artifactAppsPath(opts), {
         method: "POST",
         headers: await jsonHeaders(opts),
@@ -132,6 +184,8 @@ export async function deployArtifactApp(opts, input) {
             title: optionalString(input, "title"),
             description: optionalString(input, "description"),
             projectId: optionalString(input, "projectId"),
+            clientRequestId,
+            bundleSha256: bundle.sha256,
             manifest
         })
     });
@@ -141,6 +195,7 @@ export async function deployArtifactApp(opts, input) {
     const artifactId = stringValue(createdRecord.artifactId, "artifactId");
     const artifactVersionId = stringValue(createdRecord.artifactVersionId, "artifactVersionId");
     const bearerToken = await getBearerToken(opts);
+    await onProgress?.(0.6, "Uploading bundle and waiting for trusted draft deployment");
     const deployed = await fetchJson(opts, `${artifactAppsPath(opts)}/${encodeURIComponent(artifactId)}/deploy-bundle`, {
         method: "POST",
         headers: {
@@ -152,11 +207,16 @@ export async function deployArtifactApp(opts, input) {
         },
         body: bundle.body
     });
+    await onProgress?.(1, "Completed trusted draft deployment");
+    const deployedRecord = asRecord(deployed);
+    const operationId = typeof deployedRecord.taskId === "string" ? deployedRecord.taskId : null;
     return {
         ok: true,
         artifactId,
         artifactVersionId,
         manifestId: typeof manifest.id === "string" ? manifest.id : null,
+        clientRequestId,
+        operationId,
         bundle: {
             fileCount: bundle.fileCount,
             byteCount: bundle.byteCount,
@@ -167,6 +227,103 @@ export async function deployArtifactApp(opts, input) {
         deploy: deployed
     };
 }
+async function callHostedBuildTool(opts, name, input) {
+    if (mcpSurface(opts) !== "build")
+        throw new Error(`${name}_requires_build_surface`);
+    const headers = await jsonHeaders(opts);
+    const payload = asRecord(await fetchJson(opts, `${platformBaseUrl(opts)}/mcp/build`, {
+        method: "POST",
+        headers: { ...headers, accept: "application/json, text/event-stream" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: `stdio-${Date.now()}`,
+            method: "tools/call",
+            params: { name, arguments: input }
+        })
+    }));
+    if (payload.error) {
+        const error = asRecord(payload.error);
+        throw new Error(`platform_mcp_tool_error:${String(error.message ?? "unknown_error")}`);
+    }
+    const result = asRecord(payload.result);
+    if (result.isError === true) {
+        const content = Array.isArray(result.content) ? result.content.filter(isRecord) : [];
+        const message = content.find((item) => item.type === "text" && typeof item.text === "string")?.text;
+        throw new Error(`platform_mcp_tool_error:${String(message ?? "tool_failed")}`);
+    }
+    if (isRecord(result.structuredContent))
+        return result.structuredContent;
+    throw new Error(`platform_mcp_tool_output_missing:${name}`);
+}
+export async function waitForArtifactDeploy(opts, input, onProgress) {
+    const artifactId = stringArg(input, "artifactId");
+    const operationId = stringArg(input, "operationId");
+    const timeoutSeconds = Math.min(Math.max(numberArg(input, "timeoutSeconds") ?? 300, 1), 900);
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let afterSeq = 0;
+    let latest = {};
+    while (Date.now() < deadline) {
+        latest = asRecord(await callHostedBuildTool(opts, "platform_deploy_operation", { artifactId, operationId, afterSeq }));
+        const progress = typeof latest.progress === "number" ? latest.progress : 0.7;
+        const events = Array.isArray(latest.events) ? latest.events.filter(isRecord) : [];
+        const eventMessage = [...events].reverse().find((event) => typeof event.message === "string")?.message;
+        await onProgress?.(progress, typeof eventMessage === "string" ? eventMessage : `Artifact deployment: ${String(latest.phase ?? latest.taskStatus ?? "running")}`);
+        if (typeof latest.nextSeq === "number")
+            afterSeq = latest.nextSeq;
+        if (latest.terminal === true) {
+            if (latest.successful !== true)
+                throw new Error(`artifact_deploy_failed:${String(latest.taskStatus ?? "failed")}`);
+            return latest;
+        }
+        const waitMs = typeof latest.nextPollAfterMs === "number" ? Math.min(Math.max(latest.nextPollAfterMs, 250), 10_000) : 2_000;
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+    throw new Error(`artifact_deploy_wait_timeout:${operationId}`);
+}
+export async function initArtifactApp(opts, input) {
+    const appDir = stringArg(input, "appDir");
+    const title = optionalString(input, "title") ?? "Topline artifact";
+    const manifestId = (optionalString(input, "manifestId") ?? path.basename(appDir))
+        .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);
+    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 });
+    const manifest = {
+        manifestVersion: 2,
+        id: manifestId,
+        title,
+        kind: "tool",
+        runtime: { target: "aws_lambda_function_url", region: "us-west-2", entryPoint: "artifactApp" },
+        build: { command: "node src/index.js --build", outputDir: "dist" },
+        validation: { localCommand: "node src/index.js --test", testCommand: "node src/index.js --test --artifact-tests-json" },
+        routes: [
+            { path: "/", kind: "page", handler: "artifactApp" },
+            { path: "/_artifact/health", kind: "api", handler: "artifactApp" }
+        ],
+        sourceBindings: [],
+        env: ["ARTIFACT_ID", "ARTIFACT_VERSION_ID", "ARTIFACT_MANIFEST_URI", "PLATFORM_ARTIFACT_ID", "PLATFORM_ARTIFACT_VERSION_ID", "PLATFORM_ARTIFACT_MANIFEST_URI"],
+        viewerPolicy: "private"
+    };
+    const packageJson = { name: manifestId, private: true, type: "module", main: "src/index.js", scripts: { build: "node src/index.js --build", test: "node src/index.js --test" } };
+    const safeTitle = title.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
+    const source = `import { mkdirSync, writeFileSync } from "node:fs";\nimport path from "node:path";\n\nconst page = ${JSON.stringify(`<!doctype html><html><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p>Ready.</p></main></body></html>`)};\n\nexport function artifactApp(_req, res) {\n  res.setHeader("content-type", "text/html; charset=utf-8");\n  res.end(page);\n}\n\nif (process.argv.includes("--build")) {\n  mkdirSync("dist", { recursive: true });\n  writeFileSync(path.join("dist", "index.html"), page, "utf8");\n}\n\nif (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {\n  console.log(JSON.stringify({ tests: [{ description: "The artifact renders a visible app root.", required: true, status: "passed", summary: "The page includes data-platform-artifact-root.", evidence: { selector: "data-platform-artifact-root" } }] }));\n} else if (process.argv.includes("--build") || process.argv.includes("--test")) {\n  console.log("artifact app template ok");\n}\n`;
+    await Promise.all([
+        writeFile(path.join(absoluteAppDir, "artifact-app.json"), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" }),
+        writeFile(path.join(absoluteAppDir, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`, { flag: "wx" }),
+        writeFile(path.join(absoluteAppDir, "src", "index.js"), source, { flag: "wx" })
+    ]);
+    return {
+        ok: true,
+        appDir: workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir),
+        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.`
+    };
+}
 export async function getArtifactStatus(opts, artifactId, limit) {
     const query = new URLSearchParams();
     if (limit)
@@ -223,6 +380,36 @@ export async function openArtifact(opts, artifactId) {
         versionUrl: typeof draft?.versionUrl === "string" ? draft.versionUrl : typeof live?.versionUrl === "string" ? live.versionUrl : null
     };
 }
+export function storybookAccess(opts) {
+    const baseUrl = platformBaseUrl(opts);
+    const storybookUrl = `${baseUrl}/api/design-systems/storybook/`;
+    const mcpUrl = `${baseUrl}/api/design-systems/storybook/mcp`;
+    const mcpServers = { storybook: { url: mcpUrl, type: "http" } };
+    const manualBearerMcpServers = {
+        storybook: {
+            url: mcpUrl,
+            type: "http",
+            headers: { Authorization: "Bearer <TOPLINE_MCP_TOKEN>" }
+        }
+    };
+    return {
+        ok: true,
+        storybookUrl,
+        previewUrl: storybookUrl,
+        mcpUrl,
+        mcpServers,
+        cursorMcpJson: { mcpServers },
+        manualBearerMcpJson: { mcpServers: manualBearerMcpServers },
+        auth: {
+            mcp: "topline_harness_bearer_with_harness_artifact_read",
+            preview: "topline_browser_session",
+            resourceMetadataUrl: `${baseUrl}/.well-known/oauth-protected-resource/mcp/${mcpSurface(opts)}`,
+            scope: "harness:artifact:read",
+            manualBearerEnv: "TOPLINE_MCP_TOKEN"
+        },
+        operatorAction: "Use cursorMcpJson for MCP clients with HTTP OAuth support. If your client requires static headers, use manualBearerMcpJson with a read-scoped TOPLINE_MCP_TOKEN. Open the preview URL in a browser signed in to Topline."
+    };
+}
 export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
     const root = path.resolve(appDir);
     const prefix = archivePrefix ? validateArchivePrefix(archivePrefix) : "";
@@ -380,6 +567,10 @@ async function fetchJson(opts, url, init) {
             payload = { detail: text.slice(0, 500) };
         }
         if (!response.ok) {
+            const code = isRecord(payload) && typeof payload.error === "string" ? payload.error : null;
+            if (code === "artifact_source_git_app_dir_mismatch") {
+                throw new Error("artifact_source_git_app_dir_mismatch: Use the same local app/source root as the existing artifact, or deploy without artifactId to create a new draft.");
+            }
             throw new Error(`platform_harness_http_error:${response.status}:${redactSecrets(JSON.stringify(payload), opts)}`);
         }
         return payload;
@@ -393,72 +584,359 @@ async function fetchJson(opts, url, init) {
         clearTimeout(timeout);
     }
 }
-function listTools() {
+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"]
+                }
+            },
             {
                 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" },
+                        appDir: { type: "string", minLength: 1 },
                         artifactId: { type: "string" },
                         title: { type: "string" },
                         description: { type: "string" },
-                        projectId: { 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: ["appDir"]
+                    required: ["ok", "artifactId", "artifactVersionId", "clientRequestId", "operationId", "bundle", "create", "deploy"]
                 }
             },
+            {
+                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" }, 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", 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"] }
+            },
+            {
+                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"] }
+            },
             {
                 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" }, limit: { type: "number" } },
-                    required: ["artifactId"]
+                    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"]
                 }
             },
             {
                 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" },
+                        artifactId: { type: "string", minLength: 1 },
                         deploymentRecordId: { type: "string" },
                         environment: { type: "string", enum: ["draft", "live"] },
-                        limit: { type: "number" },
+                        limit: { type: "integer", minimum: 1, maximum: 200 },
                         severity: { type: "string" },
                         contains: { type: "string" },
-                        since: { type: "string" },
-                        windowMinutes: { type: "number" },
+                        since: { type: "string", format: "date-time" },
+                        windowMinutes: { type: "integer", minimum: 1, maximum: 1440 },
                         trace: { type: "string" },
                         requestId: { type: "string" },
                         route: { type: "string" }
                     },
-                    required: ["artifactId"]
+                    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"]
                 }
             },
             {
                 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" } },
-                    required: ["artifactId"]
+                    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"]
+                }
+            },
+            {
+                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"]
+                }
+            },
+            {
+                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"]
+                }
+            },
+            {
+                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"] }
+            },
+            {
+                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"] }
+            },
+            {
+                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)
+    };
+}
+function withRecoveryOutputSchema(tool) {
+    if (!tool.outputSchema)
+        return tool;
+    return {
+        ...tool,
+        outputSchema: {
+            type: "object",
+            oneOf: [
+                tool.outputSchema,
+                {
+                    type: "object",
+                    properties: {
+                        ok: { const: false },
+                        error: {
+                            type: "object",
+                            properties: {
+                                code: { type: "string" },
+                                message: { type: "string" },
+                                retryable: { type: "boolean" },
+                                recoveryAction: { type: "string" }
+                            },
+                            required: ["code", "message", "retryable", "recoveryAction"],
+                            additionalProperties: false
+                        }
+                    },
+                    required: ["ok", "error"],
+                    additionalProperties: false
+                }
+            ]
+        }
+    };
+}
+function mcpToolAnnotations(name, policy) {
+    return {
+        title: name.split("_").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" "),
+        readOnlyHint: policy.readOnly,
+        destructiveHint: policy.destructive ?? false,
+        ...(policy.idempotent ? { idempotentHint: true } : {}),
+        openWorldHint: policy.openWorld ?? false
     };
 }
 function toolResult(value) {
+    const structuredContent = value;
+    const content = [{ type: "text", text: JSON.stringify(value, null, 2) }];
+    const seen = new Set();
+    for (const field of ["url", "openUrl", "promotionUrl", "draftUrl", "liveUrl", "versionUrl", "storybookUrl", "mcpUrl"]) {
+        const uri = structuredContent[field];
+        if (typeof uri !== "string" || !/^https?:\/\//.test(uri) || seen.has(uri))
+            continue;
+        seen.add(uri);
+        content.push({ type: "resource_link", uri, name: field });
+    }
+    return { content, structuredContent };
+}
+function toolError(message) {
+    return structuredToolError(message);
+}
+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 structuredContent = { ok: false, error: { code, message, ...selected } };
     return {
-        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
-        structuredContent: value
+        content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
+        structuredContent,
+        isError: true
     };
 }
+function recoveryErrorCode(message) {
+    const known = [
+        "artifact_delete_plan_stale",
+        "artifact_deploy_wait_timeout",
+        "artifact_app_scaffold_target_not_empty",
+        "platform_harness_timeout",
+        "platform_mcp_tool_error",
+        "scope_required"
+    ].find((candidate) => message.includes(candidate));
+    if (known)
+        return known;
+    const match = message.match(/(?:^|:)([a-z][a-z0-9_]{2,})(?::|$)/);
+    return match?.[1] ?? "topline_mcp_tool_failed";
+}
+const jsonSchemaValidator = new AjvJsonSchemaValidator();
+function validateJsonSchema(schema, value) {
+    const result = jsonSchemaValidator.getValidator(schema)(value);
+    return result.valid ? null : result.errorMessage;
+}
+async function sendProgress(extra, progress, total, message) {
+    const progressToken = extra?._meta?.progressToken;
+    if (typeof progressToken !== "string" && typeof progressToken !== "number")
+        return;
+    try {
+        await extra.sendNotification({ method: "notifications/progress", params: { progressToken, progress, total, message } });
+    }
+    catch {
+        // Progress is optional; a disconnected client must not change the tool result.
+    }
+}
 async function jsonHeaders(opts) {
     const bearerToken = await getBearerToken(opts);
     return {
@@ -514,7 +992,7 @@ function isRefreshTokenRejected(err) {
 }
 async function runOAuthLogin(opts) {
     const issuer = platformBaseUrl(opts);
-    const resource = `${issuer}/mcp/harness`;
+    const resource = `${issuer}/mcp/${mcpSurface(opts)}`;
     const callback = await startOAuthCallbackServer();
     try {
         const registration = await oauthFetchJson(opts, `${issuer}/oauth/register`, {
@@ -617,6 +1095,11 @@ async function readStoredOAuthCredentials(opts) {
         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);
+        if (issuer !== expectedIssuer || resource !== `${expectedIssuer}/mcp/${mcpSurface(opts)}`)
+            return null;
+        if (!opts.oauthScopes.every((scope) => scopes.includes(scope)))
+            return null;
         return {
             issuer,
             resource,
@@ -720,9 +1203,21 @@ function artifactAppsPath(opts) {
 function platformBaseUrl(opts) {
     return opts.apiUrl.replace(/\/api\/harness$/, "").replace(/\/$/, "");
 }
-function defaultAuthFile(apiUrl) {
-    const key = createHash("sha256").update(platformBaseUrl({ apiUrl })).digest("hex").slice(0, 16);
-    return path.join(os.homedir(), ".topline", "harness-mcp", `${key}.json`);
+function mcpSurface(opts) {
+    return opts.surface ?? "build";
+}
+function logicalArtifactAppDir(workspaceAppDir, manifest) {
+    if (workspaceAppDir === "." || workspaceAppDir.startsWith("artifact-apps/"))
+        return workspaceAppDir;
+    const manifestId = typeof manifest.id === "string" ? manifest.id.trim() : "";
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9])?$/.test(manifestId)) {
+        throw new Error("artifact_app_manifest_id_not_safe_for_source_root");
+    }
+    return `artifact-apps/${manifestId}`;
+}
+function defaultAuthFile(apiUrl, surface) {
+    const key = createHash("sha256").update(`${platformBaseUrl({ apiUrl })}:${surface}`).digest("hex").slice(0, 16);
+    return path.join(os.homedir(), ".topline", "build-mcp", `${key}.json`);
 }
 function normalizeApiUrl(raw) {
     let url;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@topline-build/harness-mcp",
-  "version": "0.1.2",
-  "description": "Local stdio MCP connector for deploying Topline artifact app drafts.",
+  "version": "0.4.0",
+  "description": "Topline Build MCP for creating and deploying artifact app drafts.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,7 +35,8 @@
     "mcp:stdio": "node dist/cli.js",
     "prepack": "npm run build",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "certify:live": "node scripts/certify-live.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0"