@topline-build/harness-mcp 0.9.4 → 0.9.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,17 @@
2
2
 
3
3
  All notable customer-visible Build MCP changes are recorded here. A source change is not a published package or customer release.
4
4
 
5
+ ## 0.9.6 - 2026-11-01
6
+
7
+ - `platform_prepare_artifact_validation` accepts the optional `idempotencyKey` that Topline's own tool list advertises. The package refused it before ("must NOT have additional properties") when it checked the call against its own schema.
8
+ - A call with an argument the tool doesn't take returns `invalid_arguments` and names the argument and the ones the tool does take, instead of a generic schema message.
9
+ - `build_session_not_active` (a closed or expired session) now says how to continue: keep local edits, start a new session on the same app at its current version, and repeat the call with the new `sessionId`.
10
+
11
+ ## 0.9.5 - 2026-11-01
12
+
13
+ - A Topline refusal wrapped as `platform_mcp_tool_error` keeps its code when the code is camelCase in part (for example `workspace_table_displayName_too_short`), from the message or from a JSON body. It was reported as a bare `platform_mcp_tool_error` before.
14
+ - A Topline refusal whose code has no recovery step of its own now says the same input fails the same way, as a 4xx already did, instead of offering a plain retry.
15
+
5
16
  ## 0.9.4 - 2026-11-01
6
17
 
7
18
  - `platform_init_artifact_app` takes an optional `starter`, one of the Build cookbook examples that ship a manifest (for example `internal-action-tool`, `private-api-first-app` or `live-operations-dashboard`). It scaffolds that recipe's page and private routes in dependency-free Node, each answering with a placeholder, and returns `recipe` with the example's docs id, its path in the Topline plugin and the steps still to do. Datasets, source bindings, secret bindings and Bedrock env are not declared; you add them from your own tables, sources and approved secrets. A starter works with the single shape only (`artifact_app_scaffold_starter_shape_conflict`); an unknown name returns `artifact_app_scaffold_starter_invalid` with the list.
@@ -41,7 +41,7 @@ export function externalBuildHelperTools(annotate) {
41
41
  tool("platform_record_acceptance_review", "Record the builder's acceptance review without impersonating the independent validator or removing required checks.", {
42
42
  ...mutation, checkId: id, status: { type: "string", enum: ["passed", "failed"] }, summary: { type: "string", minLength: 3, maxLength: 2000 }
43
43
  }, [...Object.keys(mutation), "checkId", "status", "summary"]),
44
- tool("platform_prepare_artifact_validation", "Prepare validation evidence for the exact private draft revision; missing required checks block readiness.", { ...session, artifactVersionId: id, deploymentRecordId: id }, ["sessionId", "artifactVersionId", "deploymentRecordId"], true),
44
+ tool("platform_prepare_artifact_validation", "Prepare validation evidence for the exact private draft revision; missing required checks block readiness.", { ...session, artifactVersionId: id, deploymentRecordId: id, idempotencyKey: requestKey }, ["sessionId", "artifactVersionId", "deploymentRecordId"], true),
45
45
  tool("platform_request_artifact_validation", "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval.", {
46
46
  ...deployed, summary: { type: "string", minLength: 3, maxLength: 4000 }, waitMs: { type: "integer", minimum: 0, maximum: 1000 },
47
47
  buildOk: { type: "boolean" }, typecheckOk: { type: "boolean" }, docImpact: { type: "string", enum: ["material", "none"] },
package/dist/index.d.ts CHANGED
@@ -42,7 +42,7 @@ type ToolProgressReporter = (progress: number, message: string) => void | Promis
42
42
  export type McpSurface = "build" | "topline" | "harness";
43
43
  export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
44
44
  export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
45
- export declare const HARNESS_MCP_VERSION = "0.9.4";
45
+ export declare const HARNESS_MCP_VERSION = "0.9.6";
46
46
  export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
47
47
  /** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
48
48
  export declare const TOPLINE_OAUTH_SCOPES: readonly string[];
package/dist/index.js CHANGED
@@ -19,7 +19,7 @@ const MCP_SURFACES = ["build", "topline", "harness"];
19
19
  export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
20
20
  const DEFAULT_TIMEOUT_MS = 120_000;
21
21
  export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
22
- export const HARNESS_MCP_VERSION = "0.9.4";
22
+ export const HARNESS_MCP_VERSION = "0.9.6";
23
23
  export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
24
24
  /** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
25
25
  export const TOPLINE_OAUTH_SCOPES = Object.freeze([
@@ -917,7 +917,7 @@ export async function callHarnessTool(opts, name, args, hooks) {
917
917
  throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
918
918
  }
919
919
  const outputError = tool.outputSchema
920
- ? validateJsonSchema(tool.outputSchema, result.structuredContent)
920
+ ? validateJsonSchema(tool.outputSchema, result.structuredContent, "field")
921
921
  : null;
922
922
  return outputError ? toolError(`Invalid output for ${name}: ${outputError}`) : result;
923
923
  }
@@ -2342,6 +2342,8 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
2342
2342
  ...Object.fromEntries([...DOMAIN_ERROR_CODES].map(code => [code, { retryable: false,
2343
2343
  recoveryAction: "Read current domain/address state and the original receipt with the saved pre-call key. Retain the exact original input. Review changed state, scopes or configuration before any new plan/key; never assume a rejected delivery means no effect." }])),
2344
2344
  domain_result_unknown: { retryable: false, recoveryAction: "The response did not establish an outcome. Recover the original receipt through platform_get_artifact_address (saved artifactId and apply key) or platform_read_artifact_domains (request/verify kind and key). Preserve the original plan/domain/input/key; an absent, pending or expired receipt does not authorize a fresh key. No mutation is replayed automatically." },
2345
+ invalid_arguments: { retryable: false, recoveryAction: "The package refused these arguments before calling Topline. The message names the argument that doesn't fit this tool's input schema; fix or drop it and call again." },
2346
+ build_session_not_active: { retryable: false, recoveryAction: "This build session is closed or expired, so it takes no more changes. Keep your local edits, call platform_start_build_session for the same artifactId with its current artifactVersionId (platform_artifact_status shows it), then repeat the refused call with the new sessionId." },
2345
2347
  build_session_tool_unavailable: { retryable: false, recoveryAction: "The connection's hosted Build tool list does not offer this build session tool, so the package does not list or run it. Call platform_capability_status to see what is missing, such as a scope or capability, and reconnect through browser sign-in with any missing scope. The package asks the host to list tools again, so the tool comes back once Topline offers it." },
2346
2348
  authorization_required: { retryable: false, recoveryAction: "Call platform_sign_in to start a fresh browser sign-in, and ask the person to choose Allow. If using a manual bearer token, replace the expired or revoked token instead. Recover existing artifact/deployment progress before retrying a write." },
2347
2349
  manual_token_sign_in_unavailable: { retryable: false, recoveryAction: "This connection uses a manual bearer token, which only its owner can replace. Ask the person to replace the token in their MCP configuration." },
@@ -2376,7 +2378,8 @@ export const BUILD_MCP_RECOVERY_ERRORS = Object.freeze(Object.fromEntries(Object
2376
2378
  export function structuredToolError(message) {
2377
2379
  const code = recoveryErrorCode(message);
2378
2380
  // A 4xx means the same request will be refused again; only 5xx, timeouts and rate limits are worth retrying unchanged.
2379
- const selected = BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable: /^platform_harness_http_error:5|timeout|rate_limited/.test(message), recoveryAction: /^platform_harness_http_error:4/.test(message)
2381
+ const retryable = /^platform_harness_http_error:5|timeout|rate_limited|unavailable|internal_error/.test(message);
2382
+ const selected = BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable, recoveryAction: !retryable && /^platform_harness_http_error:4|^platform_mcp_tool_error:/.test(message)
2380
2383
  ? "Topline refused this request as sent. Read the code, correct the input or state it names, then call the tool again; the same input fails the same way."
2381
2384
  : "Inspect the code and message, correct the input if needed, then retry the same tool." };
2382
2385
  const structuredContent = { ok: false, error: { code, message, ...selected } };
@@ -2393,7 +2396,7 @@ function hostedToolErrorCode(inner) {
2393
2396
  if (isRecord(parsed)) {
2394
2397
  const error = parsed.error;
2395
2398
  const code = isRecord(error) ? error.code : typeof error === "string" ? error : parsed.code;
2396
- if (typeof code === "string" && /^[a-z][a-z0-9_]{2,}$/.test(code))
2399
+ if (typeof code === "string" && /^[a-z][A-Za-z0-9_]{2,}$/.test(code))
2397
2400
  return code;
2398
2401
  }
2399
2402
  }
@@ -2402,9 +2405,12 @@ function hostedToolErrorCode(inner) {
2402
2405
  }
2403
2406
  // Only a code-shaped token (it has an underscore): plain English such as
2404
2407
  // "missing scope ..." or "not found" is a message, not a code.
2405
- return inner.match(/^([a-z][a-z0-9]*_[a-z0-9_]+)(?::|$|\s)/)?.[1] ?? null;
2408
+ // Documentation codes can be camelCase in part (`workspace_table_displayName_too_short`).
2409
+ return inner.match(/^([a-z][A-Za-z0-9]*_[A-Za-z0-9_]+)(?::|$|\s)/)?.[1] ?? null;
2406
2410
  }
2407
2411
  function recoveryErrorCode(message) {
2412
+ if (message.startsWith("Invalid arguments for "))
2413
+ return "invalid_arguments";
2408
2414
  if (/^platform_harness_http_error:401(?::|$)/.test(message))
2409
2415
  return "authorization_required";
2410
2416
  if (message.startsWith("platform_mcp_tool_error:")) {
@@ -2449,7 +2455,14 @@ function recoveryErrorCode(message) {
2449
2455
  return match?.[1] ?? "topline_mcp_tool_failed";
2450
2456
  }
2451
2457
  const jsonSchemaValidator = new AjvJsonSchemaValidator();
2452
- function validateJsonSchema(schema, value) {
2458
+ function validateJsonSchema(schema, value, kind = "argument") {
2459
+ // Name an unexpected argument; the validator's own text ("must NOT have additional properties") does not.
2460
+ const shape = schema;
2461
+ if (shape.additionalProperties === false && shape.properties && isRecord(value)) {
2462
+ const extra = Object.keys(value).filter((key) => !Object.hasOwn(shape.properties, key));
2463
+ if (extra.length)
2464
+ return `unexpected ${kind}${extra.length > 1 ? "s" : ""} ${extra.map((key) => `\`${key}\``).join(", ")}; this tool ${kind === "argument" ? "takes" : "returns"} ${Object.keys(shape.properties).map((key) => `\`${key}\``).join(", ")}`;
2465
+ }
2453
2466
  const result = jsonSchemaValidator.getValidator(schema)(value);
2454
2467
  return result.valid ? null : result.errorMessage;
2455
2468
  }
@@ -2,7 +2,7 @@
2
2
  "schemaVersion": 1,
3
3
  "package": {
4
4
  "name": "@topline-build/harness-mcp",
5
- "version": "0.9.4",
5
+ "version": "0.9.6",
6
6
  "bin": {
7
7
  "topline-mcp": "dist/cli.js"
8
8
  }
@@ -12,7 +12,7 @@
12
12
  "defaultVersion": "2025-11-25",
13
13
  "server": {
14
14
  "name": "topline-build-stdio",
15
- "version": "0.9.4"
15
+ "version": "0.9.6"
16
16
  }
17
17
  },
18
18
  "generatedFrom": {
@@ -318,7 +318,7 @@
318
318
  {
319
319
  "code": "invalid_arguments",
320
320
  "retryable": false,
321
- "recoveryAction": "Read current domain/address state and the original receipt with the saved pre-call key. Retain the exact original input. Review changed state, scopes or configuration before any new plan/key; never assume a rejected delivery means no effect."
321
+ "recoveryAction": "The package refused these arguments before calling Topline. The message names the argument that doesn't fit this tool's input schema; fix or drop it and call again."
322
322
  },
323
323
  {
324
324
  "code": "authorization_required",
@@ -340,6 +340,11 @@
340
340
  "retryable": false,
341
341
  "recoveryAction": "The response did not establish an outcome. Recover the original receipt through platform_get_artifact_address (saved artifactId and apply key) or platform_read_artifact_domains (request/verify kind and key). Preserve the original plan/domain/input/key; an absent, pending or expired receipt does not authorize a fresh key. No mutation is replayed automatically."
342
342
  },
343
+ {
344
+ "code": "build_session_not_active",
345
+ "retryable": false,
346
+ "recoveryAction": "This build session is closed or expired, so it takes no more changes. Keep your local edits, call platform_start_build_session for the same artifactId with its current artifactVersionId (platform_artifact_status shows it), then repeat the refused call with the new sessionId."
347
+ },
343
348
  {
344
349
  "code": "build_session_tool_unavailable",
345
350
  "retryable": false,
@@ -4469,6 +4474,12 @@
4469
4474
  "deploymentRecordId": {
4470
4475
  "type": "string",
4471
4476
  "format": "uuid"
4477
+ },
4478
+ "idempotencyKey": {
4479
+ "type": "string",
4480
+ "minLength": 1,
4481
+ "maxLength": 128,
4482
+ "pattern": "^[A-Za-z0-9._:-]+$"
4472
4483
  }
4473
4484
  },
4474
4485
  "required": [
@@ -2,7 +2,7 @@
2
2
 
3
3
  > Generated from `src/index.ts#BUILD_MCP_TOOLS`. Do not edit this file by hand.
4
4
 
5
- Package: `@topline-build/harness-mcp@0.9.4`
5
+ Package: `@topline-build/harness-mcp@0.9.6`
6
6
  Transport: `stdio`
7
7
  Default protocol: `2025-11-25`
8
8
  Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -60,11 +60,12 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
60
60
  - `idempotency_conflict` (not automatically retryable): Read current domain/address state and the original receipt with the saved pre-call key. Retain the exact original input. Review changed state, scopes or configuration before any new plan/key; never assume a rejected delivery means no effect.
61
61
  - `domain_setup_limit` (not automatically retryable): Read current domain/address state and the original receipt with the saved pre-call key. Retain the exact original input. Review changed state, scopes or configuration before any new plan/key; never assume a rejected delivery means no effect.
62
62
  - `domain_operation_failed` (not automatically retryable): Read current domain/address state and the original receipt with the saved pre-call key. Retain the exact original input. Review changed state, scopes or configuration before any new plan/key; never assume a rejected delivery means no effect.
63
- - `invalid_arguments` (not automatically retryable): Read current domain/address state and the original receipt with the saved pre-call key. Retain the exact original input. Review changed state, scopes or configuration before any new plan/key; never assume a rejected delivery means no effect.
63
+ - `invalid_arguments` (not automatically retryable): The package refused these arguments before calling Topline. The message names the argument that doesn't fit this tool's input schema; fix or drop it and call again.
64
64
  - `authorization_required` (not automatically retryable): Call platform_sign_in to start a fresh browser sign-in, and ask the person to choose Allow. If using a manual bearer token, replace the expired or revoked token instead. Recover existing artifact/deployment progress before retrying a write.
65
65
  - `scope_required` (not automatically retryable): Reconnect the Build MCP and approve the requested scope.
66
66
  - `domain_tools_require_build_oauth` (not automatically retryable): Read current domain/address state and the original receipt with the saved pre-call key. Retain the exact original input. Review changed state, scopes or configuration before any new plan/key; never assume a rejected delivery means no effect.
67
67
  - `domain_result_unknown` (not automatically retryable): The response did not establish an outcome. Recover the original receipt through platform_get_artifact_address (saved artifactId and apply key) or platform_read_artifact_domains (request/verify kind and key). Preserve the original plan/domain/input/key; an absent, pending or expired receipt does not authorize a fresh key. No mutation is replayed automatically.
68
+ - `build_session_not_active` (not automatically retryable): This build session is closed or expired, so it takes no more changes. Keep your local edits, call platform_start_build_session for the same artifactId with its current artifactVersionId (platform_artifact_status shows it), then repeat the refused call with the new sessionId.
68
69
  - `build_session_tool_unavailable` (not automatically retryable): The connection's hosted Build tool list does not offer this build session tool, so the package does not list or run it. Call platform_capability_status to see what is missing, such as a scope or capability, and reconnect through browser sign-in with any missing scope. The package asks the host to list tools again, so the tool comes back once Topline offers it.
69
70
  - `manual_token_sign_in_unavailable` (not automatically retryable): This connection uses a manual bearer token, which only its owner can replace. Ask the person to replace the token in their MCP configuration.
70
71
  - `sign_in_unavailable_on_harness_surface` (not automatically retryable): The harness surface signs in with a token, not a browser. Ask the person to check this connection's token.
@@ -4511,6 +4512,12 @@ Input schema:
4511
4512
  "deploymentRecordId": {
4512
4513
  "type": "string",
4513
4514
  "format": "uuid"
4515
+ },
4516
+ "idempotencyKey": {
4517
+ "type": "string",
4518
+ "minLength": 1,
4519
+ "maxLength": 128,
4520
+ "pattern": "^[A-Za-z0-9._:-]+$"
4514
4521
  }
4515
4522
  },
4516
4523
  "required": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topline-build/harness-mcp",
3
- "version": "0.9.4",
3
+ "version": "0.9.6",
4
4
  "description": "Topline Build MCP for creating and deploying artifact app drafts.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",