@topline-build/harness-mcp 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# Topline Harness MCP
+
+Local stdio MCP connector for deploying Topline artifact app drafts from Codex,
+Claude Code, or another local MCP host.
+
+The normal auth path is OAuth with browser approval. The helper stores OAuth
+refresh tokens in the user's local Topline config directory, outside the project
+repo.
+
+Required environment:
+
+- `TOPLINE_API_URL`
+
+Optional environment:
+
+- `TOPLINE_MCP_PROTOCOL_VERSION`
+- `TOPLINE_WORKSPACE_ROOT`
+- `TOPLINE_MCP_AUTH_FILE`
+- `TOPLINE_MCP_SCOPES`
+- `TOPLINE_MCP_TOKEN` for advanced manual-token fallback
+
+Compatibility aliases are still accepted for older local setups:
+
+- `PLATFORM_API_URL`
+- `PLATFORM_MCP_TOKEN`
+- `PLATFORM_WORKSPACE_ROOT`
+- `PLATFORM_MCP_PROTOCOL_VERSION`
+
+## Usage
+
+```bash
+npx -y @topline-build/harness-mcp
+```
+
+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.

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runHarnessMcpStdioCli } from "./index.js";
+runHarnessMcpStdioCli().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export interface HarnessMcpStdioOptions {
+    apiUrl: string;
+    token?: string;
+    authFile: string;
+    oauthScopes: string[];
+    timeoutMs: number;
+    protocolVersion: string;
+    workspaceRoot: string;
+    fetchImpl?: typeof fetch;
+    openUrl?: (url: string) => void | Promise<void>;
+}
+export interface StoredOAuthCredentials {
+    issuer: string;
+    resource: string;
+    clientId: string;
+    accessToken?: string;
+    accessTokenExpiresAt?: string;
+    refreshToken?: string;
+    scopes: string[];
+}
+export interface PackedArtifactAppBundle {
+    body: Buffer;
+    fileCount: number;
+    byteCount: number;
+    sha256: string;
+    excluded: string[];
+}
+export declare function parseHarnessOptions(argv: string[], env?: Record<string, string | undefined>): HarnessMcpStdioOptions;
+export declare function runHarnessMcpStdioCli(): Promise<void>;
+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<{
+    ok: boolean;
+    artifactId: string;
+    artifactVersionId: string;
+    manifestId: string | null;
+    bundle: {
+        fileCount: number;
+        byteCount: number;
+        sha256: string;
+        excluded: string[];
+    };
+    create: unknown;
+    deploy: unknown;
+}>;
+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<{
+    ok: boolean;
+    artifactId: string;
+    openUrl: string;
+    promotionUrl: string;
+    livePromotion: {
+        exposedInMcp: boolean;
+        operatorAction: string;
+    };
+    sourceHandoff: {
+        readOnly: boolean;
+        url: string;
+        operatorAction: string;
+    };
+    scheduleHandoff: {
+        readOnly: boolean;
+        url: string;
+        operatorAction: string;
+    };
+    draftUrl: string | null;
+    liveUrl: string | null;
+    versionUrl: string | null;
+}>;
+export declare function packArtifactAppDirectory(appDir: string): Promise<PackedArtifactAppBundle>;
+export declare function getBearerToken(opts: HarnessMcpStdioOptions): Promise<string>;

package/dist/index.js

@@ -0,0 +1,711 @@
+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 { createServer } from "node:http";
+import os from "node:os";
+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";
+const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const SERVER_NAME = "topline-harness-stdio";
+const DEFAULT_OAUTH_SCOPES = ["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy"];
+const BLOCK_SIZE = 512;
+const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+const MAX_UNPACKED_BYTES = 512 * 1024 * 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"]);
+export function parseHarnessOptions(argv, env = process.env) {
+    const getArg = (name) => {
+        const index = argv.indexOf(name);
+        if (index < 0)
+            return undefined;
+        const value = argv[index + 1]?.trim();
+        if (!value || value.startsWith("--"))
+            throw new Error(`missing_platform_harness_arg:${name}`);
+        return value;
+    };
+    const apiUrl = getArg("--url") || firstEnv(env, "TOPLINE_API_URL", "PLATFORM_API_URL", "OVERSITE_API_URL");
+    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 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)
+        throw new Error("missing_platform_api_url");
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new Error("invalid_platform_mcp_timeout");
+    const normalizedApiUrl = normalizeApiUrl(apiUrl);
+    const authFile = path.resolve(getArg("--auth-file") || firstEnv(env, "TOPLINE_MCP_AUTH_FILE", "PLATFORM_MCP_AUTH_FILE") || defaultAuthFile(normalizedApiUrl));
+    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,
+        token,
+        authFile,
+        oauthScopes: scopes.length > 0 ? [...new Set(scopes)] : DEFAULT_OAUTH_SCOPES,
+        timeoutMs: Math.floor(timeoutMs),
+        protocolVersion,
+        workspaceRoot
+    };
+}
+export async function runHarnessMcpStdioCli() {
+    const opts = parseHarnessOptions(process.argv.slice(2));
+    const mcp = createHarnessMcpStdioServer(opts);
+    await mcp.connect(new StdioServerTransport());
+}
+export function createHarnessMcpStdioServer(opts) {
+    const mcp = new McpServer({ name: SERVER_NAME, version: "0.1.0" }, { capabilities: { tools: {} } });
+    mcp.setRequestHandler(ListToolsRequestSchema, async () => listTools());
+    mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+        try {
+            return await callHarnessTool(opts, req.params.name, req.params.arguments ?? {});
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: redactSecrets(err instanceof Error ? err.message : String(err), opts) }],
+                isError: true
+            };
+        }
+    });
+    return mcp;
+}
+export async function callHarnessTool(opts, name, args) {
+    const input = isRecord(args) ? args : {};
+    switch (name) {
+        case "platform_deploy_artifact_app":
+            return toolResult(await deployArtifactApp(opts, input));
+        case "platform_artifact_status":
+            return toolResult(await getArtifactStatus(opts, stringArg(input, "artifactId"), numberArg(input, "limit")));
+        case "platform_read_artifact_logs":
+            return toolResult(await readArtifactLogs(opts, input));
+        case "platform_open_artifact":
+            return toolResult(await openArtifact(opts, stringArg(input, "artifactId")));
+        default:
+            return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+}
+export async function deployArtifactApp(opts, input) {
+    const appDir = stringArg(input, "appDir");
+    const absoluteAppDir = resolveWorkspacePath(opts.workspaceRoot, appDir);
+    const manifest = await readManifest(absoluteAppDir);
+    const created = await fetchJson(opts, artifactAppsPath(opts), {
+        method: "POST",
+        headers: await jsonHeaders(opts),
+        body: JSON.stringify({
+            artifactId: optionalString(input, "artifactId"),
+            title: optionalString(input, "title"),
+            description: optionalString(input, "description"),
+            projectId: optionalString(input, "projectId"),
+            manifest
+        })
+    });
+    const createdRecord = asRecord(created);
+    if (createdRecord.ok !== true)
+        throw new Error(`artifact_app_create_failed:${JSON.stringify(createdRecord)}`);
+    const artifactId = stringValue(createdRecord.artifactId, "artifactId");
+    const artifactVersionId = stringValue(createdRecord.artifactVersionId, "artifactVersionId");
+    const bundle = await packArtifactAppDirectory(absoluteAppDir);
+    const bearerToken = await getBearerToken(opts);
+    const deployed = await fetchJson(opts, `${artifactAppsPath(opts)}/${encodeURIComponent(artifactId)}/deploy-bundle`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${bearerToken}`,
+            "content-type": "application/gzip",
+            "MCP-Protocol-Version": opts.protocolVersion,
+            "x-platform-artifact-version-id": artifactVersionId,
+            "x-platform-app-dir": "."
+        },
+        body: bundle.body
+    });
+    return {
+        ok: true,
+        artifactId,
+        artifactVersionId,
+        manifestId: typeof manifest.id === "string" ? manifest.id : null,
+        bundle: {
+            fileCount: bundle.fileCount,
+            byteCount: bundle.byteCount,
+            sha256: bundle.sha256,
+            excluded: bundle.excluded
+        },
+        create: created,
+        deploy: deployed
+    };
+}
+export async function getArtifactStatus(opts, artifactId, limit) {
+    const query = new URLSearchParams();
+    if (limit)
+        query.set("limit", String(limit));
+    const suffix = query.toString() ? `?${query}` : "";
+    return fetchJson(opts, `${artifactAppsPath(opts)}/${encodeURIComponent(artifactId)}/deployments${suffix}`, {
+        method: "GET",
+        headers: await jsonHeaders(opts)
+    });
+}
+export async function readArtifactLogs(opts, input) {
+    const artifactId = stringArg(input, "artifactId");
+    const query = new URLSearchParams();
+    for (const key of ["deploymentRecordId", "environment", "limit", "severity", "contains", "since", "windowMinutes", "trace", "requestId", "route"]) {
+        const value = input[key];
+        if (typeof value === "string" && value.trim())
+            query.set(key, value.trim());
+        if (typeof value === "number" && Number.isFinite(value))
+            query.set(key, String(value));
+    }
+    const suffix = query.toString() ? `?${query}` : "";
+    return fetchJson(opts, `${artifactAppsPath(opts)}/${encodeURIComponent(artifactId)}/logs${suffix}`, {
+        method: "GET",
+        headers: await jsonHeaders(opts)
+    });
+}
+export async function openArtifact(opts, artifactId) {
+    const status = asRecord(await getArtifactStatus(opts, artifactId, 10));
+    const deployments = Array.isArray(status.deployments) ? status.deployments.filter(isRecord) : [];
+    const draft = deployments.find((deployment) => deployment.environment === "draft") ?? null;
+    const live = deployments.find((deployment) => deployment.environment === "live" && deployment.deploymentState === "promoted") ?? null;
+    const baseUrl = platformBaseUrl(opts);
+    return {
+        ok: true,
+        artifactId,
+        openUrl: `${baseUrl}/artifacts/${encodeURIComponent(artifactId)}`,
+        promotionUrl: `${baseUrl}/artifacts/${encodeURIComponent(artifactId)}`,
+        livePromotion: {
+            exposedInMcp: false,
+            operatorAction: "Review the draft in Topline and publish/promote from the artifact UI."
+        },
+        sourceHandoff: {
+            readOnly: true,
+            url: `${baseUrl}/settings/sources`,
+            operatorAction: "Review or change source bindings in the Topline sources UI."
+        },
+        scheduleHandoff: {
+            readOnly: true,
+            url: `${baseUrl}/automations?tab=schedules`,
+            operatorAction: "Review or change artifact schedules in the Topline automations UI."
+        },
+        draftUrl: typeof draft?.draftUrl === "string" ? draft.draftUrl : null,
+        liveUrl: typeof live?.liveUrl === "string" ? live.liveUrl : null,
+        versionUrl: typeof draft?.versionUrl === "string" ? draft.versionUrl : typeof live?.versionUrl === "string" ? live.versionUrl : null
+    };
+}
+export async function packArtifactAppDirectory(appDir) {
+    const root = path.resolve(appDir);
+    const files = [];
+    const excluded = [];
+    await walk(root, root, files, excluded);
+    if (files.length === 0)
+        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)
+            throw new Error(`artifact_app_bundle_unpacked_too_large:${MAX_UNPACKED_BYTES}`);
+        const content = await readFile(file.absolute);
+        chunks.push(tarHeader(file.relative, content.length));
+        chunks.push(content);
+        chunks.push(Buffer.alloc(padSize(content.length)));
+    }
+    chunks.push(Buffer.alloc(BLOCK_SIZE * 2));
+    const body = gzipSync(Buffer.concat(chunks));
+    if (body.length > MAX_BUNDLE_BYTES)
+        throw new Error(`artifact_app_bundle_too_large:${MAX_BUNDLE_BYTES}`);
+    return {
+        body,
+        fileCount: files.length,
+        byteCount,
+        sha256: createHash("sha256").update(body).digest("hex"),
+        excluded
+    };
+}
+async function walk(root, current, files, excluded) {
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+        const absolute = path.join(current, entry.name);
+        const relative = toPosix(path.relative(root, absolute));
+        validateRelativePath(relative);
+        const stat = await lstat(absolute);
+        if (stat.isSymbolicLink())
+            throw new Error(`artifact_app_bundle_symlink_forbidden:${relative}`);
+        if (shouldExclude(relative, entry.isDirectory())) {
+            excluded.push(relative);
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await walk(root, absolute, files, excluded);
+        }
+        else if (entry.isFile()) {
+            files.push({ absolute, relative, size: stat.size });
+            if (files.length > MAX_FILES)
+                throw new Error(`artifact_app_bundle_file_limit:${MAX_FILES}`);
+        }
+    }
+}
+async function readManifest(appDir) {
+    const manifestPath = path.join(appDir, "artifact-app.json");
+    const parsed = JSON.parse(await readFile(manifestPath, "utf8"));
+    if (!isRecord(parsed))
+        throw new Error("artifact_app_manifest_must_be_object");
+    return parsed;
+}
+function resolveWorkspacePath(workspaceRoot, inputPath) {
+    const resolved = path.resolve(workspaceRoot, inputPath);
+    const relative = path.relative(workspaceRoot, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error("appDir_must_be_inside_workspace_root");
+    return resolved;
+}
+function validateRelativePath(relative) {
+    if (!relative || relative.startsWith("/") || /^[A-Za-z]:\//.test(relative))
+        throw new Error("artifact_app_bundle_path_invalid");
+    const parts = relative.split("/").filter(Boolean);
+    if (parts.some((part) => part === ".."))
+        throw new Error(`artifact_app_bundle_path_escape:${relative}`);
+    if (parts.length > MAX_DEPTH)
+        throw new Error(`artifact_app_bundle_depth_limit:${MAX_DEPTH}`);
+}
+function shouldExclude(relative, isDirectory) {
+    const parts = relative.split("/").filter(Boolean);
+    const name = parts[parts.length - 1] ?? "";
+    if (name.startsWith(".env"))
+        return true;
+    if (parts.some((part) => part === ".git" || part === "node_modules"))
+        return true;
+    if (isDirectory && FORBIDDEN_DIRS.has(name))
+        return true;
+    return false;
+}
+function tarHeader(name, size) {
+    const header = Buffer.alloc(BLOCK_SIZE);
+    const { fileName, prefix } = splitTarName(name);
+    header.write(fileName, 0, 100, "utf8");
+    writeOctal(header, 100, 8, 0o644);
+    writeOctal(header, 108, 8, 0);
+    writeOctal(header, 116, 8, 0);
+    writeOctal(header, 124, 12, size);
+    writeOctal(header, 136, 12, Math.floor(Date.now() / 1000));
+    header.fill(0x20, 148, 156);
+    header.write("0", 156, 1, "utf8");
+    header.write("ustar", 257, 5, "utf8");
+    header.write("00", 263, 2, "utf8");
+    if (prefix)
+        header.write(prefix, 345, 155, "utf8");
+    let checksum = 0;
+    for (const byte of header)
+        checksum += byte;
+    const checksumText = checksum.toString(8).padStart(6, "0");
+    header.write(checksumText, 148, 6, "ascii");
+    header[154] = 0;
+    header[155] = 0x20;
+    return header;
+}
+function splitTarName(name) {
+    if (Buffer.byteLength(name) <= 100)
+        return { fileName: name, prefix: "" };
+    const parts = name.split("/");
+    for (let i = parts.length - 1; i > 0; i -= 1) {
+        const fileName = parts.slice(i).join("/");
+        const prefix = parts.slice(0, i).join("/");
+        if (Buffer.byteLength(fileName) <= 100 && Buffer.byteLength(prefix) <= 155) {
+            return { fileName, prefix };
+        }
+    }
+    throw new Error(`artifact_app_bundle_path_too_long:${name}`);
+}
+function writeOctal(header, offset, length, value) {
+    const text = value.toString(8).padStart(length - 1, "0").slice(-(length - 1));
+    header.write(text, offset, length - 1, "ascii");
+    header[offset + length - 1] = 0;
+}
+function padSize(size) {
+    const remainder = size % BLOCK_SIZE;
+    return remainder === 0 ? 0 : BLOCK_SIZE - remainder;
+}
+async function fetchJson(opts, url, init) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs);
+    try {
+        const response = await (opts.fetchImpl ?? fetch)(url, { ...init, signal: controller.signal });
+        const text = await response.text();
+        let payload = {};
+        try {
+            payload = text ? JSON.parse(text) : {};
+        }
+        catch {
+            payload = { detail: text.slice(0, 500) };
+        }
+        if (!response.ok) {
+            throw new Error(`platform_harness_http_error:${response.status}:${redactSecrets(JSON.stringify(payload), opts)}`);
+        }
+        return payload;
+    }
+    catch (err) {
+        if (controller.signal.aborted)
+            throw new Error("platform_harness_timeout");
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function listTools() {
+    return {
+        tools: [
+            {
+                name: "platform_deploy_artifact_app",
+                description: "Package a local artifact app directory, upload it, deploy a private draft, and return status.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        appDir: { type: "string" },
+                        artifactId: { type: "string" },
+                        title: { type: "string" },
+                        description: { type: "string" },
+                        projectId: { type: "string" }
+                    },
+                    required: ["appDir"]
+                }
+            },
+            {
+                name: "platform_artifact_status",
+                description: "Read private draft deployment status for a hosted artifact app.",
+                inputSchema: {
+                    type: "object",
+                    properties: { artifactId: { type: "string" }, limit: { type: "number" } },
+                    required: ["artifactId"]
+                }
+            },
+            {
+                name: "platform_read_artifact_logs",
+                description: "Read bounded, redacted deployment logs for a hosted artifact app.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        artifactId: { type: "string" },
+                        deploymentRecordId: { type: "string" },
+                        environment: { type: "string", enum: ["draft", "live"] },
+                        limit: { type: "number" },
+                        severity: { type: "string" },
+                        contains: { type: "string" },
+                        since: { type: "string" },
+                        windowMinutes: { type: "number" },
+                        trace: { type: "string" },
+                        requestId: { type: "string" },
+                        route: { type: "string" }
+                    },
+                    required: ["artifactId"]
+                }
+            },
+            {
+                name: "platform_open_artifact",
+                description: "Return the operator URL and latest draft/live URLs for a hosted artifact app.",
+                inputSchema: {
+                    type: "object",
+                    properties: { artifactId: { type: "string" } },
+                    required: ["artifactId"]
+                }
+            }
+        ]
+    };
+}
+function toolResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+        structuredContent: value
+    };
+}
+async function jsonHeaders(opts) {
+    const bearerToken = await getBearerToken(opts);
+    return {
+        accept: "application/json",
+        authorization: `Bearer ${bearerToken}`,
+        "content-type": "application/json",
+        "MCP-Protocol-Version": opts.protocolVersion
+    };
+}
+export async function getBearerToken(opts) {
+    if (opts.token?.trim())
+        return opts.token.trim();
+    const stored = await readStoredOAuthCredentials(opts);
+    if (stored?.accessToken && stored.accessTokenExpiresAt && new Date(stored.accessTokenExpiresAt).getTime() - Date.now() > 60_000) {
+        return stored.accessToken;
+    }
+    if (stored?.refreshToken && stored.clientId) {
+        try {
+            const refreshed = await refreshOAuthToken(opts, stored);
+            await writeStoredOAuthCredentials(opts, refreshed);
+            return refreshed.accessToken;
+        }
+        catch {
+            // Fall through to an interactive login; the stored refresh token may have been revoked.
+        }
+    }
+    const loggedIn = await runOAuthLogin(opts);
+    await writeStoredOAuthCredentials(opts, loggedIn);
+    return loggedIn.accessToken;
+}
+async function refreshOAuthToken(opts, stored) {
+    if (!stored.refreshToken)
+        throw new Error("missing_topline_refresh_token");
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: stored.clientId,
+        refresh_token: stored.refreshToken,
+        resource: stored.resource,
+        scope: stored.scopes.join(" ")
+    });
+    const token = await oauthFetchJson(opts, `${stored.issuer}/oauth/token`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body
+    });
+    return credentialsFromTokenResponse(stored.issuer, stored.resource, stored.clientId, stored.scopes, token);
+}
+async function runOAuthLogin(opts) {
+    const issuer = platformBaseUrl(opts);
+    const resource = `${issuer}/mcp/harness`;
+    const callback = await startOAuthCallbackServer();
+    try {
+        const registration = await oauthFetchJson(opts, `${issuer}/oauth/register`, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({
+                client_name: "Topline local MCP helper",
+                redirect_uris: [callback.redirectUri],
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                token_endpoint_auth_method: "none"
+            })
+        });
+        const clientId = stringValue(asRecord(registration).client_id, "client_id");
+        const verifier = randomBytes(32).toString("base64url");
+        const challenge = createHash("sha256").update(verifier).digest("base64url");
+        const state = randomBytes(24).toString("base64url");
+        const authUrl = new URL(`${issuer}/oauth/authorize`);
+        authUrl.searchParams.set("response_type", "code");
+        authUrl.searchParams.set("client_id", clientId);
+        authUrl.searchParams.set("redirect_uri", callback.redirectUri);
+        authUrl.searchParams.set("scope", opts.oauthScopes.join(" "));
+        authUrl.searchParams.set("resource", resource);
+        authUrl.searchParams.set("code_challenge", challenge);
+        authUrl.searchParams.set("code_challenge_method", "S256");
+        authUrl.searchParams.set("state", state);
+        await openBrowser(opts, authUrl.toString());
+        const code = await callback.waitForCode(state);
+        const token = await oauthFetchJson(opts, `${issuer}/oauth/token`, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                client_id: clientId,
+                code,
+                redirect_uri: callback.redirectUri,
+                code_verifier: verifier,
+                resource
+            })
+        });
+        return credentialsFromTokenResponse(issuer, resource, clientId, opts.oauthScopes, token);
+    }
+    finally {
+        await callback.close();
+    }
+}
+async function oauthFetchJson(opts, url, init) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs);
+    try {
+        const response = await (opts.fetchImpl ?? fetch)(url, { ...init, signal: controller.signal });
+        const text = await response.text();
+        const payload = text ? JSON.parse(text) : {};
+        if (!response.ok)
+            throw new Error(`topline_oauth_http_error:${response.status}:${redactSecrets(JSON.stringify(payload), opts)}`);
+        return payload;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function credentialsFromTokenResponse(issuer, resource, clientId, requestedScopes, token) {
+    const record = asRecord(token);
+    const accessToken = stringValue(record.access_token, "access_token");
+    const refreshToken = stringValue(record.refresh_token, "refresh_token");
+    const expiresIn = typeof record.expires_in === "number" && Number.isFinite(record.expires_in) ? record.expires_in : 3600;
+    const scopeText = typeof record.scope === "string" && record.scope.trim() ? record.scope.trim() : requestedScopes.join(" ");
+    return {
+        issuer,
+        resource,
+        clientId,
+        accessToken,
+        accessTokenExpiresAt: new Date(Date.now() + Math.max(60, Math.floor(expiresIn)) * 1000).toISOString(),
+        refreshToken,
+        scopes: scopeText.split(/[\s,]+/).filter(Boolean)
+    };
+}
+async function readStoredOAuthCredentials(opts) {
+    if (!existsSync(opts.authFile))
+        return null;
+    try {
+        const parsed = JSON.parse(await readFile(opts.authFile, "utf8"));
+        if (!isRecord(parsed))
+            return null;
+        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;
+        if (!issuer || !resource || !clientId)
+            return null;
+        return {
+            issuer,
+            resource,
+            clientId,
+            accessToken: typeof parsed.accessToken === "string" ? parsed.accessToken : undefined,
+            accessTokenExpiresAt: typeof parsed.accessTokenExpiresAt === "string" ? parsed.accessTokenExpiresAt : undefined,
+            refreshToken: typeof parsed.refreshToken === "string" ? parsed.refreshToken : undefined,
+            scopes
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeStoredOAuthCredentials(opts, credentials) {
+    await mkdir(path.dirname(opts.authFile), { recursive: true });
+    await writeFile(opts.authFile, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+}
+async function startOAuthCallbackServer() {
+    let resolveCode = null;
+    let rejectCode = null;
+    let expectedState = "";
+    const codePromise = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+    });
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        if (url.pathname !== "/callback" || !code || state !== expectedState) {
+            res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+            res.end("<!doctype html><meta charset=\"utf-8\"><h1>Topline authorization failed</h1>");
+            rejectCode?.(new Error("topline_oauth_callback_invalid"));
+            return;
+        }
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end("<!doctype html><meta charset=\"utf-8\"><h1>Topline authorization complete</h1><p>You can return to your coding harness.</p>");
+        resolveCode?.(code);
+    });
+    await listen(server);
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("topline_oauth_callback_listen_failed");
+    return {
+        redirectUri: `http://127.0.0.1:${address.port}/callback`,
+        waitForCode: async (state) => {
+            expectedState = state;
+            return await Promise.race([
+                codePromise,
+                new Promise((_resolve, reject) => setTimeout(() => reject(new Error("topline_oauth_login_timeout")), 5 * 60 * 1000))
+            ]);
+        },
+        close: () => closeServer(server)
+    };
+}
+function listen(server) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve) => server.close(() => resolve()));
+}
+async function openBrowser(opts, url) {
+    if (opts.openUrl) {
+        await opts.openUrl(url);
+        return;
+    }
+    const command = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        child.unref();
+    }
+    catch {
+        console.error(`Open this URL to authorize Topline MCP:\n${url}`);
+    }
+}
+function artifactAppsPath(opts) {
+    return opts.apiUrl.endsWith("/api/harness")
+        ? `${opts.apiUrl}/artifact-apps`
+        : `${opts.apiUrl}/api/harness/artifact-apps`;
+}
+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 normalizeApiUrl(raw) {
+    const url = new URL(raw);
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new Error("invalid_platform_api_url_scheme");
+    return url.toString().replace(/\/$/g, "");
+}
+function firstEnv(env, ...keys) {
+    for (const key of keys) {
+        const value = env[key]?.trim();
+        if (value)
+            return value;
+    }
+    return null;
+}
+function stringArg(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${key}_required`);
+    return value.trim();
+}
+function optionalString(args, key) {
+    const value = args[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function numberArg(args, key) {
+    const value = args[key];
+    if (typeof value === "number" && Number.isFinite(value))
+        return Math.floor(value);
+    if (typeof value === "string" && value.trim() && Number.isFinite(Number(value)))
+        return Math.floor(Number(value));
+    return undefined;
+}
+function stringValue(value, key) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${key}_missing_from_platform_response`);
+    return value.trim();
+}
+function asRecord(value) {
+    return isRecord(value) ? value : {};
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toPosix(value) {
+    return value.replace(/\\/g, "/");
+}
+function redactSecrets(value, opts) {
+    const token = opts.token?.trim();
+    const withoutStatic = token ? value.split(token).join("[redacted]") : value;
+    return withoutStatic
+        .replace(/ovmcp_[A-Za-z0-9_-]+/g, "[redacted]")
+        .replace(/tlmcp_(?:at|rt|code)_[A-Za-z0-9_-]+/g, "[redacted]");
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@topline-build/harness-mcp",
+  "version": "0.1.0",
+  "description": "Local stdio MCP connector for deploying Topline artifact app drafts.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/topline-build/topline-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/topline-build/topline-mcp/issues"
+  },
+  "homepage": "https://github.com/topline-build/topline-mcp#readme",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "bin": {
+    "topline-mcp": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "mcp:stdio": "node dist/cli.js",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.8"
+  }
+}