@topline-build/harness-mcp 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable customer-visible Build MCP changes are recorded here. A source chang
 
 ## Unreleased
 
+## 0.5.2 - 2026-09-26
+
+- Report rejected bearer credentials as `authorization_required`, with scoped cache-clearing and browser reconnect guidance instead of input-correction advice.
+- Guide connection-specific cache cleanup and recovery of existing deployment progress before a write is retried.
+- Report native client certification timeouts as failures even when partial output mentions authentication; a timed-out process is not proof of a missing provider session.
+
 ## 0.5.1 - 2026-09-18
 
 - Harden the bundled Claude certification script with strict tool isolation, effective-runtime proof, and noninteractive JSONL validation.

package/README.md

@@ -22,6 +22,8 @@ npx -y @topline-build/harness-mcp
 
 Run `npx -y @topline-build/harness-mcp --help` for every supported flag and environment variable. `TOPLINE_MCP_TOKEN` is an advanced manual-token fallback; browser-approved OAuth is preferred.
 
+If a tool returns `authorization_required`, clear only that connection's OAuth cache and reconnect through browser sign-in. Replace an expired or revoked manual token if using the fallback. Inspect existing artifact/deployment progress before retrying a write; the helper does not silently replay the rejected request.
+
 ## Typical workflow
 
 1. Use `platform_init_artifact_app` to create a starter, or point at an existing artifact app.

package/dist/index.d.ts

@@ -32,7 +32,7 @@ export interface PackedArtifactAppBundle {
 type ToolProgressReporter = (progress: number, message: string) => void | Promise<void>;
 export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
-export declare const HARNESS_MCP_VERSION = "0.5.1";
+export declare const HARNESS_MCP_VERSION = "0.5.2";
 export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
 export interface BuildMcpSetupOption {
     readonly flag: string;

package/dist/index.js

@@ -13,7 +13,7 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } fr
 export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_TIMEOUT_MS = 120_000;
 export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
-export const HARNESS_MCP_VERSION = "0.5.1";
+export const HARNESS_MCP_VERSION = "0.5.2";
 export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
 export const BUILD_MCP_SETUP_OPTIONS = Object.freeze([
     { flag: "--url", env: "TOPLINE_API_URL", aliases: ["PLATFORM_API_URL", "OVERSITE_API_URL"], required: true, description: "Topline tenant base URL. HTTPS is required except for loopback development." },
@@ -1063,6 +1063,7 @@ function toolError(message) {
     return structuredToolError(message);
 }
 const BUILD_MCP_RECOVERY_ERROR_VALUES = {
+    authorization_required: { retryable: false, recoveryAction: "Clear only this connection's cached OAuth credentials, then reconnect the Build MCP through browser sign-in. If using a manual bearer token, replace the expired or revoked token. Recover existing artifact/deployment progress before retrying a write." },
     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." },
@@ -1087,6 +1088,8 @@ function structuredToolError(message) {
     };
 }
 function recoveryErrorCode(message) {
+    if (/^platform_harness_http_error:401(?::|$)/.test(message))
+        return "authorization_required";
     const known = [
         "artifact_delete_plan_stale",
         "artifact_deploy_wait_timeout",

package/docs/generated/build-mcp-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "package": {
     "name": "@topline-build/harness-mcp",
-    "version": "0.5.1",
+    "version": "0.5.2",
     "bin": {
       "topline-mcp": "dist/cli.js"
     }
@@ -12,7 +12,7 @@
     "defaultVersion": "2025-11-25",
     "server": {
       "name": "topline-build-stdio",
-      "version": "0.5.1"
+      "version": "0.5.2"
     }
   },
   "generatedFrom": {
@@ -171,6 +171,11 @@
       "recoveryAction": "Inspect the code and message, correct the input if needed, then retry the same tool."
     },
     "catalog": [
+      {
+        "code": "authorization_required",
+        "retryable": false,
+        "recoveryAction": "Clear only this connection's cached OAuth credentials, then reconnect the Build MCP through browser sign-in. If using a manual bearer token, replace the expired or revoked token. Recover existing artifact/deployment progress before retrying a write."
+      },
       {
         "code": "platform_harness_timeout",
         "retryable": true,

package/docs/generated/build-mcp-reference.md

@@ -2,7 +2,7 @@
 
 > Generated from `src/index.ts#BUILD_MCP_TOOLS`. Do not edit this file by hand.
 
-Package: `@topline-build/harness-mcp@0.5.1`
+Package: `@topline-build/harness-mcp@0.5.2`
 Transport: `stdio`
 Default protocol: `2025-11-25`
 Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -32,6 +32,7 @@ The first authenticated tool call normally opens browser approval. Set `TOPLINE_
 
 Tool failures set `isError: true` and return `structuredContent.error` with `code`, `message`, `retryable`, and `recoveryAction`.
 
+- `authorization_required` (not automatically retryable): Clear only this connection's cached OAuth credentials, then reconnect the Build MCP through browser sign-in. If using a manual bearer token, replace the expired or revoked token. Recover existing artifact/deployment progress before retrying a write.
 - `platform_harness_timeout` (retryable): 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` (not automatically retryable): Read the returned error code, correct the request or OAuth scopes, then retry.
 - `artifact_deploy_wait_timeout` (retryable): Call platform_wait_artifact_deploy again with the same artifactId and operationId.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topline-build/harness-mcp",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Topline Build MCP for creating and deploying artifact app drafts.",
   "type": "module",
   "main": "./dist/index.js",

package/scripts/certify-live.mjs

@@ -218,9 +218,7 @@ async function agentMediatedRead(name, command, scratch, apiUrl, appDir, workspa
     "-p", "--verbose", "--output-format", "stream-json", prompt
   ], scratch, 180000, strictAgentEnvironment(process.env));
   if (!result.ok) {
-    return authUnavailable(result.output)
-      ? skipped("provider_credentials_or_client_session_unavailable")
-      : failed("client_mediated_read_failed", result.exitCode);
+    return clientMediatedFailure(result);
   }
   const usedTool = hasToolCallEvidence(result.output, "platform_inspect_artifact_app");
   const certified = hasAssistantCertificationEvidence(result.output);
@@ -344,6 +342,12 @@ async function certifyProtocol({ apiUrl, token, appDir, workspaceRoot }) {
 }
 
 function selfTestReport() {
+  const timedOutProbe = run({ executable: process.execPath, prefix: [] }, ["-e", "console.log('api key authentication required'); setInterval(() => {}, 1000)"], process.cwd(), 1000);
+  const timedOutFailure = clientMediatedFailure(timedOutProbe);
+  if (!timedOutProbe.timedOut || !authUnavailable(timedOutProbe.output) || timedOutFailure.status !== "failed" || timedOutFailure.reason !== "client_mediated_read_timed_out"
+    || clientMediatedFailure({ timedOut: false, output: "not logged in", exitCode: 1 }).status !== "skipped") {
+    throw new Error("client_timeout_classification_self_test_failed");
+  }
   const toolName = "platform_inspect_artifact_app";
   const promptOnly = JSON.stringify({ type: "user", content: `Call ${toolName} and print TOPLINE_CLIENT_READ_CERTIFIED.` });
   const toolEvent = JSON.stringify({ type: "item.completed", item: { type: "mcp_tool_call", tool: toolName } });
@@ -477,12 +481,20 @@ function run(command, commandArgs, cwd, timeout = 30000, env = clientProbeEnviro
   return {
     ok: result.status === 0,
     missing: result.error?.code === "ENOENT",
+    timedOut: result.error?.code === "ETIMEDOUT",
     exitCode: result.status,
     stdout: result.stdout || "",
     output: `${result.stdout || ""}\n${result.stderr || ""}`
   };
 }
 
+function clientMediatedFailure(result) {
+  if (result.timedOut) return failed("client_mediated_read_timed_out", result.exitCode);
+  return authUnavailable(result.output)
+    ? skipped("provider_credentials_or_client_session_unavailable")
+    : failed("client_mediated_read_failed", result.exitCode);
+}
+
 function authUnavailable(output) {
   return /not logged in|not authenticated|authentication required|api key|login required|please login|sign in|unable to locate credentials|security token|AccessDeniedException|UnrecognizedClientException/i.test(output);
 }