@topline-build/harness-mcp 0.1.0 → 0.1.2

package/README.md

@@ -9,7 +9,7 @@ repo.
 
 Required environment:
 
-- `TOPLINE_API_URL`
+- `TOPLINE_API_URL` or `--url https://your-topline-host`
 
 Optional environment:
 
@@ -17,6 +17,7 @@ Optional environment:
 - `TOPLINE_WORKSPACE_ROOT`
 - `TOPLINE_MCP_AUTH_FILE`
 - `TOPLINE_MCP_SCOPES`
+- `TOPLINE_MCP_TIMEOUT_MS`
 - `TOPLINE_MCP_TOKEN` for advanced manual-token fallback
 
 Compatibility aliases are still accepted for older local setups:
@@ -32,6 +33,16 @@ Compatibility aliases are still accepted for older local setups:
 npx -y @topline-build/harness-mcp
 ```
 
+For local checks:
+
+```bash
+npx -y @topline-build/harness-mcp --help
+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.

package/dist/index.d.ts

@@ -27,8 +27,10 @@ export interface PackedArtifactAppBundle {
     sha256: string;
     excluded: string[];
 }
+export declare const HARNESS_MCP_VERSION = "0.1.2";
 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<{
@@ -70,5 +72,9 @@ export declare function openArtifact(opts: HarnessMcpStdioOptions, artifactId: s
     liveUrl: string | null;
     versionUrl: string | null;
 }>;
-export declare function packArtifactAppDirectory(appDir: string): Promise<PackedArtifactAppBundle>;
+export declare function packArtifactAppDirectory(appDir: string, archivePrefix?: string): Promise<PackedArtifactAppBundle>;
 export declare function getBearerToken(opts: HarnessMcpStdioOptions): Promise<string>;
+export declare function browserOpenCommand(url: string, platform?: string): {
+    command: string;
+    args: string[];
+};

package/dist/index.js

@@ -12,6 +12,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 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 BLOCK_SIZE = 512;
 const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
@@ -26,7 +27,7 @@ export function parseHarnessOptions(argv, env = process.env) {
             return undefined;
         const value = argv[index + 1]?.trim();
         if (!value || value.startsWith("--"))
-            throw new Error(`missing_platform_harness_arg:${name}`);
+            throw new Error(`Missing value for ${name}`);
         return value;
     };
     const apiUrl = getArg("--url") || firstEnv(env, "TOPLINE_API_URL", "PLATFORM_API_URL", "OVERSITE_API_URL");
@@ -36,9 +37,9 @@ export function parseHarnessOptions(argv, env = process.env) {
     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");
+        throw new Error("Set TOPLINE_API_URL or pass --url https://your-topline-host");
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
-        throw new Error("invalid_platform_mcp_timeout");
+        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 scopes = (getArg("--scopes") || firstEnv(env, "TOPLINE_MCP_SCOPES", "PLATFORM_MCP_SCOPES") || DEFAULT_OAUTH_SCOPES.join(" "))
@@ -56,12 +57,38 @@ export function parseHarnessOptions(argv, env = process.env) {
     };
 }
 export async function runHarnessMcpStdioCli() {
-    const opts = parseHarnessOptions(process.argv.slice(2));
+    const argv = process.argv.slice(2);
+    const info = cliInfo(argv);
+    if (info) {
+        console.log(info);
+        return;
+    }
+    const opts = parseHarnessOptions(argv);
     const mcp = createHarnessMcpStdioServer(opts);
     await mcp.connect(new StdioServerTransport());
 }
+export function cliInfo(argv) {
+    if (argv.includes("--version") || argv.includes("-v"))
+        return HARNESS_MCP_VERSION;
+    if (!argv.includes("--help") && !argv.includes("-h"))
+        return null;
+    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_TOKEN         Optional manual token fallback",
+        "  TOPLINE_MCP_AUTH_FILE     Optional OAuth credential cache path",
+        "  TOPLINE_MCP_TIMEOUT_MS    Defaults to 120000",
+        "",
+        "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: "0.1.0" }, { capabilities: { tools: {} } });
+    const mcp = new McpServer({ name: SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: {} } });
     mcp.setRequestHandler(ListToolsRequestSchema, async () => listTools());
     mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
         try {
@@ -94,7 +121,9 @@ export async function callHarnessTool(opts, name, args) {
 export async function deployArtifactApp(opts, input) {
     const appDir = stringArg(input, "appDir");
     const absoluteAppDir = resolveWorkspacePath(opts.workspaceRoot, appDir);
+    const platformAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
     const manifest = await readManifest(absoluteAppDir);
+    const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
     const created = await fetchJson(opts, artifactAppsPath(opts), {
         method: "POST",
         headers: await jsonHeaders(opts),
@@ -111,7 +140,6 @@ export async function deployArtifactApp(opts, input) {
         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",
@@ -120,7 +148,7 @@ export async function deployArtifactApp(opts, input) {
             "content-type": "application/gzip",
             "MCP-Protocol-Version": opts.protocolVersion,
             "x-platform-artifact-version-id": artifactVersionId,
-            "x-platform-app-dir": "."
+            "x-platform-app-dir": platformAppDir
         },
         body: bundle.body
     });
@@ -195,8 +223,9 @@ export async function openArtifact(opts, artifactId) {
         versionUrl: typeof draft?.versionUrl === "string" ? draft.versionUrl : typeof live?.versionUrl === "string" ? live.versionUrl : null
     };
 }
-export async function packArtifactAppDirectory(appDir) {
+export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
     const root = path.resolve(appDir);
+    const prefix = archivePrefix ? validateArchivePrefix(archivePrefix) : "";
     const files = [];
     const excluded = [];
     await walk(root, root, files, excluded);
@@ -209,7 +238,7 @@ export async function packArtifactAppDirectory(appDir) {
         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(tarHeader(prefix ? `${prefix}/${file.relative}` : file.relative, content.length));
         chunks.push(content);
         chunks.push(Buffer.alloc(padSize(content.length)));
     }
@@ -262,11 +291,20 @@ function resolveWorkspacePath(workspaceRoot, inputPath) {
         throw new Error("appDir_must_be_inside_workspace_root");
     return resolved;
 }
+function workspaceRelativeAppDir(workspaceRoot, absoluteAppDir) {
+    const relative = toPosix(path.relative(path.resolve(workspaceRoot), path.resolve(absoluteAppDir)));
+    return relative ? validateArchivePrefix(relative) : ".";
+}
+function validateArchivePrefix(prefix) {
+    const normalized = toPosix(prefix).replace(/^\/+|\/+$/g, "");
+    validateRelativePath(normalized);
+    return normalized;
+}
 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 === ".."))
+    if (parts.some((part) => 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}`);
@@ -443,7 +481,9 @@ export async function getBearerToken(opts) {
             await writeStoredOAuthCredentials(opts, refreshed);
             return refreshed.accessToken;
         }
-        catch {
+        catch (err) {
+            if (!isRefreshTokenRejected(err))
+                throw err;
             // Fall through to an interactive login; the stored refresh token may have been revoked.
         }
     }
@@ -468,6 +508,10 @@ async function refreshOAuthToken(opts, stored) {
     });
     return credentialsFromTokenResponse(stored.issuer, stored.resource, stored.clientId, stored.scopes, token);
 }
+function isRefreshTokenRejected(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return /^topline_oauth_http_error:(400|401):/.test(message) && /invalid_(grant|token)/i.test(message);
+}
 async function runOAuthLogin(opts) {
     const issuer = platformBaseUrl(opts);
     const resource = `${issuer}/mcp/harness`;
@@ -497,8 +541,9 @@ async function runOAuthLogin(opts) {
         authUrl.searchParams.set("code_challenge", challenge);
         authUrl.searchParams.set("code_challenge_method", "S256");
         authUrl.searchParams.set("state", state);
+        const codePromise = callback.waitForCode(state);
         await openBrowser(opts, authUrl.toString());
-        const code = await callback.waitForCode(state);
+        const code = await codePromise;
         const token = await oauthFetchJson(opts, `${issuer}/oauth/token`, {
             method: "POST",
             headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
@@ -523,11 +568,22 @@ async function oauthFetchJson(opts, url, init) {
     try {
         const response = await (opts.fetchImpl ?? fetch)(url, { ...init, signal: controller.signal });
         const text = await response.text();
-        const payload = text ? JSON.parse(text) : {};
+        let payload = {};
+        try {
+            payload = text ? JSON.parse(text) : {};
+        }
+        catch {
+            payload = { detail: text.slice(0, 500) };
+        }
         if (!response.ok)
             throw new Error(`topline_oauth_http_error:${response.status}:${redactSecrets(JSON.stringify(payload), opts)}`);
         return payload;
     }
+    catch (err) {
+        if (controller.signal.aborted)
+            throw new Error("topline_oauth_timeout");
+        throw err;
+    }
     finally {
         clearTimeout(timeout);
     }
@@ -582,7 +638,7 @@ async function writeStoredOAuthCredentials(opts, credentials) {
 async function startOAuthCallbackServer() {
     let resolveCode = null;
     let rejectCode = null;
-    let expectedState = "";
+    let expectedState = null;
     const codePromise = new Promise((resolve, reject) => {
         resolveCode = resolve;
         rejectCode = reject;
@@ -591,7 +647,13 @@ async function startOAuthCallbackServer() {
         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) {
+        if (!expectedState || url.pathname !== "/callback" || 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>");
+            return;
+        }
+        const error = url.searchParams.get("error");
+        if (error || !code) {
             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"));
@@ -634,8 +696,7 @@ async function openBrowser(opts, url) {
         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];
+    const { command, args } = browserOpenCommand(url);
     try {
         const child = spawn(command, args, { detached: true, stdio: "ignore" });
         child.unref();
@@ -644,6 +705,13 @@ async function openBrowser(opts, url) {
         console.error(`Open this URL to authorize Topline MCP:\n${url}`);
     }
 }
+export function browserOpenCommand(url, platform = process.platform) {
+    if (platform === "win32")
+        return { command: "rundll32.exe", args: ["url.dll,FileProtocolHandler", url] };
+    if (platform === "darwin")
+        return { command: "open", args: [url] };
+    return { command: "xdg-open", args: [url] };
+}
 function artifactAppsPath(opts) {
     return opts.apiUrl.endsWith("/api/harness")
         ? `${opts.apiUrl}/artifact-apps`
@@ -657,9 +725,15 @@ function defaultAuthFile(apiUrl) {
     return path.join(os.homedir(), ".topline", "harness-mcp", `${key}.json`);
 }
 function normalizeApiUrl(raw) {
-    const url = new URL(raw);
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error("TOPLINE_API_URL must be an http(s) URL");
+    }
     if (url.protocol !== "http:" && url.protocol !== "https:")
-        throw new Error("invalid_platform_api_url_scheme");
+        throw new Error("TOPLINE_API_URL must be an http(s) URL");
     return url.toString().replace(/\/$/g, "");
 }
 function firstEnv(env, ...keys) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topline-build/harness-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local stdio MCP connector for deploying Topline artifact app drafts.",
   "type": "module",
   "main": "./dist/index.js",