@topline-build/harness-mcp 0.8.0 → 0.9.1

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,9 +2,19 @@
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
- ## Unreleased
5
+ ## 0.9.1 - source candidate
6
6
 
7
- ## 0.8.0 - source candidate
7
+ - `--surface topline` no longer asks for `workspace:todo:write`. Topline retired that scope and leaves it out of every grant, so the package treated each fresh sign-in as incomplete and opened the browser again on the next launch (and twice during `topline-mcp login`). A retired scope named in `TOPLINE_MCP_SCOPES` or `--scopes` is dropped too. Existing sign-ins are reused without another approval.
8
+ - The default `build` surface lists and forwards hosted Build tools the way `--surface topline` does, so new hosted Build tools reach Codex, Claude Code and Cursor without a package release. Local tools (init, inspect, deploy, checkout, materialize and the rest of the package's own list) stay local and win over a hosted tool of the same name. Hosted `platform_create_artifact_app` and `platform_bedrock_local_token_command` stay off. A manual token on `build` keeps the package's own list.
9
+ - Build session tools (start, read and close a session, workspace SQL, checkout, materialize, assets, secrets, acceptance and validation) follow the hosted list, on `build` and on `--surface topline`: they are listed only while the connection's hosted tool list offers them. Today that list follows the granted scopes and the `harness.workforce` capability. OAuth users without the asset, secret, workspace SQL or validation scopes therefore no longer see those tools listed; Topline refused them anyway, and they come back after reconnecting with those scopes. Signed out, or before the first good listing, every session tool stays listed. A call to a hidden one returns `build_session_tool_unavailable` without reaching Topline and asks the host to list tools again; after a reconnect with a changed grant the call goes through to Topline. `platform_capability_status` is always listed.
10
+ - A failed hosted tool listing (network, 5xx, timeout or any error other than a rejected sign-in) keeps the last good list for the life of the process while the same sign-in holds, and lists the package's own tools before any good listing. The next tool call asks the host to list again, so one error never hides tools for the rest of the chat. A rejected sign-in (revoked or invalid refresh token, or a 401 from the hosted list) counts as signed out and clears the last good list, as does signing out. This applies to `--surface topline` too.
11
+ - Session tools that only forward to Topline take the hosted input schema when the hosted list provides one.
12
+
13
+ ## 0.9.0 - 2026-10-14
14
+
15
+ - `platform_init_artifact_app` takes `shape: "web-and-api"` to scaffold one artifact with a static website part and an API part under one address, instead of two artifacts. `platform_inspect_artifact_app` lists an app's parts.
16
+
17
+ ## 0.8.0 - 2026-10-13
8
18
 
9
19
  - Add `--surface topline`: one Topline server per account. It runs the local Build tools and lists and forwards every hosted tool the person's grant allows (Workspace tools included), so assistants see one Topline entry.
10
20
  - Add `topline-mcp login --url <account>`: opens the browser once during setup, saves the refresh token to the auth file the server reads, then records a code-free connection check so Topline Developer Access shows the computer as connected.
@@ -15,20 +25,20 @@ All notable customer-visible Build MCP changes are recorded here. A source chang
15
25
  - Every request to the Topline account carries `x-topline-mcp-version`. Topline uses it to show "Update available" in Developer Access and, when this package is older than the account needs, to answer tool calls with `topline_mcp_update_required` and how to update (copy setup again).
16
26
  - The combined server does not list or forward hosted `platform_create_artifact_app` or `platform_bedrock_local_token_command`; the local package, upload and deploy flow stays the only Build write path.
17
27
 
18
- ## 0.7.0 - source candidate
28
+ ## 0.7.0 - 2026-10-12
19
29
 
20
30
  - Add exactly six gated company-domain tools: connected-domain/status/recovery reads, owned-app address reads, single-use plan/apply, manager registration and ownership verification.
21
31
  - Require explicit new scopes and account-bound Build OAuth; preserve manual-token behavior for legacy tools.
22
32
  - Retain original keys and typed recovery context after a lost response. Domain reads never retry setup, apply an address, publish an app or write provider DNS.
23
33
  - Discover enabled server capabilities and current hosted scoped contracts without initiating OAuth during discovery.
24
34
 
25
- ## 0.6.0 - pending publication
35
+ ## 0.6.0 - 2026-10-12
26
36
 
27
37
  - Add server-owned external build sessions, guarded artifact-private SQL, and full acceptance/reviewer forwarding.
28
38
  - Check out exact artifact source and materialize selected assets through authenticated same-account transfers with hash, revision, archive and local-path checks.
29
39
  - Bind local draft create/deploy to the existing session identity, checked-out version, inspected source hash and stable operation keys. Additional asset, secret-metadata and data-verification scopes require explicit consent.
30
40
 
31
- ## 0.5.3 - pending publication
41
+ ## 0.5.3 - 2026-09-28
32
42
 
33
43
  - Add tenant-scoped Storyboard state, guarded edit, and exact-draft publication tools to Build MCP.
34
44
  - Check out the published Storyboard source for local Storybook iteration and submit source-only edits as a private, server-validated draft.
package/README.md CHANGED
@@ -14,7 +14,7 @@ The first authenticated tool call normally opens Topline in a browser for OAuth
14
14
 
15
15
  ### One Topline server (0.8.0)
16
16
 
17
- Topline Developer Access now sets up one Topline connection per account. Its plugin runs this package with `--surface topline`: the local Build tools plus every hosted tool your seat and grant allow, including Workspace tools, under one server entry. Sign in once during setup:
17
+ Topline Developer Access now sets up one Topline connection per account. Its plugin runs this package with `--surface topline`: the local Build tools plus every hosted tool your seat and grant allow, including Workspace tools, under one server entry. The default `build` surface does the same for hosted Build tools (0.9.1); local tools stay local. A manual `--token` on `build` keeps the package's own list. On both surfaces, build session tools follow the hosted list: they are listed only while the connection's hosted tool list offers them, and stay listed while signed out. If listing hosted tools fails temporarily, the server keeps the last good list for the same sign-in, or the package's own tools before the first one. Sign in once during setup:
18
18
 
19
19
  ```bash
20
20
  npx -y @topline-build/harness-mcp login --url https://YOUR-TOPLINE-HOST
@@ -36,13 +36,13 @@ If a tool returns `authorization_required`, clear only that connection's OAuth c
36
36
 
37
37
  Storyboard authoring uses separate `storyboard:read` and `storyboard:write` OAuth scopes. Request them explicitly with `--scopes` (or `TOPLINE_MCP_SCOPES`) and reconnect so Topline can approve the expanded grant; they are not part of the default artifact scopes. `platform_get_design_system_state` shows the published commit and current draft. `platform_checkout_design_system` creates a local checkout of that published source; run `npm ci` and `npm run storybook` there to iterate, then call `platform_submit_design_system_draft` with the exact published commit and draft ID from the state read. Wait for a successful server build, inspect the private preview, and call `platform_publish_design_system` with the reviewed run and commit values. Alternatively, `platform_edit_design_system` asks Topline's guarded coding agent to edit a draft in an existing writable Storyboard conversation. A timed-out write should be recovered by reading state before another submission. The separate Storybook reference MCP endpoint does not accept source writes.
38
38
 
39
- The 0.7.0 source candidate adds six company-domain tools for a compatible, explicitly enabled server. Request `harness:domains:read` and `harness:artifact:read` for discovery and owned-app address reads; add `harness:artifact:addresses:write` for plan/apply. Setup and full DNS/TLS details also require `harness:domains:manage` and the existing organization-manager capability. These scopes are never implicit defaults. All six require account-bound Build OAuth; unbound manual tokens cannot use them. Runtime discovery follows server gates and, once signed in, current hosted scopes and roles. The helper sends a tool-list change notification after first sign-in so clients can discover authorized setup and recovery selectors.
39
+ Since 0.7.0 the package includes six company-domain tools for a compatible, explicitly enabled server. Request `harness:domains:read` and `harness:artifact:read` for discovery and owned-app address reads; add `harness:artifact:addresses:write` for plan/apply. Setup and full DNS/TLS details also require `harness:domains:manage` and the existing organization-manager capability. These scopes are never implicit defaults. All six require account-bound Build OAuth; unbound manual tokens cannot use them. Runtime discovery follows server gates and, once signed in, current hosted scopes and roles. The helper sends a tool-list change notification after first sign-in so clients can discover authorized setup and recovery selectors.
40
40
 
41
41
  Read connected domains and the current address, show the exact `platform_plan_artifact_address` preview, then apply that single-use plan. Save every mutation key before calling. Recover a lost apply response through `platform_get_artifact_address` with the saved artifact ID and key. Recover a lost registration/verification response through `platform_read_artifact_domains` with its kind and key, even if the response containing the new domain ID was lost. Reads never replay writes. Pending, absent or expired receipts do not authorize a new key. A definite terminal DNS no-admission result permits a fresh verification key only within covered setup/retry intent, after a fresh generation read and the ten-second interval. Read-only polling stops after five minutes and reports the saved recovery context; it never verifies automatically. Saving an address does not publish the app, change access, or write DNS. Exact DNS records must be saved by the customer or a separately authorized DNS connection.
42
42
 
43
43
  ## Typical workflow
44
44
 
45
- The 0.6.0 source adds session authoring; npm publication and a compatible customer API rollout are separate prerequisites. Start `platform_start_build_session` with an existing artifact's exact version or a new app manifest, a stable idempotency key and a Topline operation budget. External client model charges stay separate. For existing apps, `platform_checkout_artifact_app` writes exact saved source into a new local directory and returns its version, commit and source hash. Never reconstruct missing source from its manifest.
45
+ Session authoring (published in 0.6.0) needs a compatible customer API. Start `platform_start_build_session` with an existing artifact's exact version or a new app manifest, a stable idempotency key and a Topline operation budget. External client model charges stay separate. For existing apps, `platform_checkout_artifact_app` writes exact saved source into a new local directory and returns its version, commit and source hash. Never reconstruct missing source from its manifest.
46
46
 
47
47
  Keep Build and Workspace as separate same-account connections. Workspace supplies catalog, SQL and trusted calculations through `data:read`. Reusable assets, approved secret metadata, private table writes, validation and finite artifact data verification each require their separately consented Build scopes: `harness:assets:read`, `harness:secrets:metadata:read`, `harness:artifact:tables:write`, `harness:artifact:validate`, and `harness:artifact:data:verify`. The defaults remain the existing artifact scopes; request an expanded set explicitly and reconnect. Secret discovery returns approved references only, never values.
48
48
 
@@ -6,4 +6,12 @@ type Annotate = (name: string, policy: {
6
6
  }) => ToolAnnotations;
7
7
  export declare function externalBuildHelperTools(annotate: Annotate): ListToolsResult["tools"];
8
8
  export declare const EXTERNAL_BUILD_FORWARD_TOOLS: Set<string>;
9
+ /**
10
+ * Session tools listed only while the hosted Build list offers them. Each
11
+ * calls the hosted tool of the same name; checkout and materialize then do
12
+ * their local transfer. Capability status stays listed so it can say why.
13
+ */
14
+ export declare const EXTERNAL_BUILD_SESSION_TOOLS: ReadonlySet<string>;
15
+ /** Session tools that only call the hosted tool of the same name, so they can take its input schema. */
16
+ export declare const EXTERNAL_BUILD_SESSION_FORWARD_TOOLS: ReadonlySet<string>;
9
17
  export {};
@@ -61,3 +61,14 @@ export const EXTERNAL_BUILD_FORWARD_TOOLS = new Set([
61
61
  "platform_list_asset_folders", "platform_list_assets", "platform_list_build_secrets", "platform_add_acceptance_check", "platform_run_acceptance_checks",
62
62
  "platform_record_acceptance_review", "platform_prepare_artifact_validation", "platform_request_artifact_validation", "platform_artifact_validation_status", "platform_answer_operator_prompt"
63
63
  ]);
64
+ /**
65
+ * Session tools listed only while the hosted Build list offers them. Each
66
+ * calls the hosted tool of the same name; checkout and materialize then do
67
+ * their local transfer. Capability status stays listed so it can say why.
68
+ */
69
+ export const EXTERNAL_BUILD_SESSION_TOOLS = new Set([
70
+ ...[...EXTERNAL_BUILD_FORWARD_TOOLS].filter((name) => name !== "platform_capability_status"),
71
+ "platform_checkout_artifact_app", "platform_materialize_assets"
72
+ ]);
73
+ /** Session tools that only call the hosted tool of the same name, so they can take its input schema. */
74
+ export const EXTERNAL_BUILD_SESSION_FORWARD_TOOLS = new Set([...EXTERNAL_BUILD_SESSION_TOOLS].filter((name) => EXTERNAL_BUILD_FORWARD_TOOLS.has(name)));
package/dist/index.d.ts CHANGED
@@ -3,9 +3,10 @@ import { type CallToolResult, type ListToolsResult } from "@modelcontextprotocol
3
3
  export interface HarnessMcpStdioOptions {
4
4
  apiUrl: string;
5
5
  /**
6
- * Defaults to the Build MCP. `topline` is the one server per account: local
7
- * Build tools plus every hosted tool the person's grant allows. Use harness
8
- * only for legacy deployments.
6
+ * Defaults to the Build MCP: local Build tools plus the hosted Build tools
7
+ * the person's OAuth grant allows. `topline` is the one server per account:
8
+ * local Build tools plus every hosted tool the person's grant allows. Use
9
+ * harness only for legacy deployments.
9
10
  */
10
11
  surface?: McpSurface;
11
12
  token?: string;
@@ -39,7 +40,7 @@ type ToolProgressReporter = (progress: number, message: string) => void | Promis
39
40
  export type McpSurface = "build" | "topline" | "harness";
40
41
  export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
41
42
  export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
42
- export declare const HARNESS_MCP_VERSION = "0.8.0";
43
+ export declare const HARNESS_MCP_VERSION = "0.9.1";
43
44
  export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
44
45
  /** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
45
46
  export declare const TOPLINE_OAUTH_SCOPES: readonly string[];
@@ -72,6 +73,7 @@ export declare function cliInfo(argv: string[]): string | null;
72
73
  export declare function createHarnessMcpStdioServer(opts: HarnessMcpStdioOptions, toolAllowlist?: readonly string[]): McpServer;
73
74
  export declare function callHarnessTool(opts: HarnessMcpStdioOptions, name: string, args: unknown, hooks?: {
74
75
  onProgress?: ToolProgressReporter;
76
+ inputSchema?: ListToolsResult["tools"][number]["inputSchema"];
75
77
  }): Promise<CallToolResult>;
76
78
  export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<{
77
79
  operationId: string | null;
@@ -126,6 +128,11 @@ export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input:
126
128
  manifestVersion: number | null;
127
129
  title: string | null;
128
130
  kind: string | null;
131
+ parts: {
132
+ name: string | null;
133
+ kind: string | null;
134
+ dir: string | null;
135
+ }[];
129
136
  };
130
137
  bundle: {
131
138
  fileCount: number;
package/dist/index.js CHANGED
@@ -6,7 +6,7 @@ import { createServer } from "node:http";
6
6
  import os from "node:os";
7
7
  import path from "node:path";
8
8
  import { gzipSync } from "node:zlib";
9
- import { externalBuildHelperTools, EXTERNAL_BUILD_FORWARD_TOOLS } from "./build-session-tools.js";
9
+ import { externalBuildHelperTools, EXTERNAL_BUILD_FORWARD_TOOLS, EXTERNAL_BUILD_SESSION_FORWARD_TOOLS, EXTERNAL_BUILD_SESSION_TOOLS } from "./build-session-tools.js";
10
10
  import { domainHelperTools, DOMAIN_FORWARD_TOOLS, DOMAIN_ERROR_CODES } from "./domain-tools.js";
11
11
  import { boundedTransfer, extractArtifactSourceArchive, MAX_SOURCE_ARCHIVE_BYTES, safeSourcePath } from "./source-checkout.js";
12
12
  import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
@@ -17,7 +17,7 @@ const MCP_SURFACES = ["build", "topline", "harness"];
17
17
  export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
18
18
  const DEFAULT_TIMEOUT_MS = 120_000;
19
19
  export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
20
- export const HARNESS_MCP_VERSION = "0.8.0";
20
+ export const HARNESS_MCP_VERSION = "0.9.1";
21
21
  export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
22
22
  /** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
23
23
  export const TOPLINE_OAUTH_SCOPES = Object.freeze([
@@ -26,11 +26,16 @@ export const TOPLINE_OAUTH_SCOPES = Object.freeze([
26
26
  "harness:secrets:metadata:read", "harness:domains:read", "harness:domains:manage", "harness:artifact:addresses:write",
27
27
  "storyboard:read", "storyboard:write",
28
28
  "docs:read", "chat:read", "chat:write", "workspace:write", "workspace:delete", "workspace:content:read",
29
- "workspace:content:write", "workspace:content:delete", "workspace:todo:write", "workspace:skills:read",
29
+ "workspace:content:write", "workspace:content:delete", "workspace:skills:read",
30
30
  "workspace:skills:write", "workspace:access:manage", "schedules:read", "schedules:write", "schedules:delete",
31
31
  "workforce:read", "workforce:write", "memory:read", "preferences:write", "glossary:read", "glossary:write",
32
32
  "company_knowledge:propose", "company_knowledge:write", "customer_profiles:read", "data:read"
33
33
  ]);
34
+ /**
35
+ * Scopes Topline no longer grants. It drops them from every grant, so asking for one
36
+ * makes a fresh grant look incomplete and reopens the browser on every launch.
37
+ */
38
+ const RETIRED_OAUTH_SCOPES = new Set(["workspace:todo:write"]);
34
39
  export const BUILD_MCP_SETUP_OPTIONS = Object.freeze([
35
40
  { 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." },
36
41
  { flag: "--workspace-root", env: "TOPLINE_WORKSPACE_ROOT", aliases: ["PLATFORM_WORKSPACE_ROOT"], default: "current working directory", description: "Local root that contains artifact app directories." },
@@ -81,7 +86,7 @@ export function parseHarnessOptions(argv, env = process.env, defaults = {}) {
81
86
  const scopes = (getArg("--scopes") || firstEnv(env, "TOPLINE_MCP_SCOPES", "PLATFORM_MCP_SCOPES") || defaultScopes.join(" "))
82
87
  .split(/[\s,]+/)
83
88
  .map((scope) => scope.trim())
84
- .filter(Boolean);
89
+ .filter((scope) => scope && !RETIRED_OAUTH_SCOPES.has(scope));
85
90
  return {
86
91
  apiUrl: normalizedApiUrl,
87
92
  surface: surfaceRaw,
@@ -179,8 +184,27 @@ export function cliInfo(argv) {
179
184
  }
180
185
  export function createHarnessMcpStdioServer(opts, toolAllowlist) {
181
186
  let discoveredGrant = null;
187
+ // The last tools/list built from a successful hosted listing, bound to the
188
+ // sign-in it was made with. A temporary listing failure reuses it for the
189
+ // life of the process instead of hiding tools; signing out clears it.
190
+ let lastHostedListing = null;
191
+ let hostedListingFailed = false;
192
+ // Session tools the most recent listing left out; calls to them are refused.
193
+ let hiddenSessionTools = new Set();
194
+ // Hosted input schemas for session tools that only forward, from the last good listing.
195
+ let hostedSessionSchemas = new Map();
196
+ // Only the newest listing writes shared state, so a slow older one cannot overwrite it.
197
+ let listingGeneration = 0;
182
198
  const grantTag = (stored) => stored?.accessToken && Date.parse(stored.accessTokenExpiresAt ?? "") > Date.now()
183
199
  ? JSON.stringify([stored.clientId, stored.resource, [...stored.scopes].sort()]) : null;
200
+ // Identifies one sign-in regardless of access-token expiry: each browser
201
+ // sign-in registers a new client.
202
+ const signInTag = async () => {
203
+ if (opts.token)
204
+ return "manual-token";
205
+ const stored = await readStoredOAuthCredentials(opts).catch(() => null);
206
+ return stored ? JSON.stringify([stored.issuer, stored.clientId, stored.resource, [...stored.scopes].sort()]) : null;
207
+ };
184
208
  const allowedTools = toolAllowlist ? new Set(toolAllowlist) : null;
185
209
  const listedTools = () => {
186
210
  const listed = listTools();
@@ -191,35 +215,91 @@ export function createHarnessMcpStdioServer(opts, toolAllowlist) {
191
215
  const listed = listedTools();
192
216
  if (!servesBuild(opts) || (opts.token && mcpSurface(opts) !== "topline"))
193
217
  return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name)) };
218
+ const generation = ++listingGeneration;
219
+ const newest = () => generation === listingGeneration;
220
+ let names = new Set();
221
+ // Signed out (or the sign-in was rejected): the package's own list, with
222
+ // session tools listed so first-run users see them.
223
+ const signedOut = () => {
224
+ if (newest()) {
225
+ lastHostedListing = null;
226
+ hiddenSessionTools = new Set();
227
+ hostedSessionSchemas = new Map();
228
+ }
229
+ return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name) || names.has(tool.name)).map(tool => tool.name === "platform_read_artifact_domains"
230
+ ? { ...tool, inputSchema: { type: "object", additionalProperties: false, properties: { limit: { type: "integer", minimum: 1, maximum: 100 }, cursor: { type: "integer", minimum: 0, maximum: 10000 } } } }
231
+ : tool) };
232
+ };
194
233
  // Public deployment metadata never initiates OAuth or changes consent.
195
234
  // Unknown/old servers fail closed for this default-off family.
196
235
  try {
197
236
  const metadata = asRecord(await fetchJson({ ...opts, timeoutMs: Math.min(opts.timeoutMs, 5000) }, hostedMcpUrl(opts), { method: "GET" }));
198
- const names = new Set(Array.isArray(metadata.tools) ? metadata.tools.map(item => typeof item === "string" ? item : asRecord(item).name) : []);
237
+ names = new Set(Array.isArray(metadata.tools) ? metadata.tools.map(item => typeof item === "string" ? item : asRecord(item).name) : []);
199
238
  // Listing never opens the browser, but it does refresh an expired access
200
- // token so hosted tools still appear in a chat started hours later.
201
- const bearer = await getBearerTokenWithoutSignIn(opts).catch(() => null);
202
- if (bearer) {
203
- const payload = asRecord(await fetchJson({ ...opts, timeoutMs: Math.min(opts.timeoutMs, 5000) }, hostedMcpUrl(opts), {
239
+ // token so hosted tools still appear in a chat started hours later. A
240
+ // rejected sign-in counts as signed out; a temporary refresh failure
241
+ // after a good listing keeps that listing.
242
+ let bearer = null;
243
+ try {
244
+ bearer = await getBearerTokenWithoutSignIn(opts);
245
+ }
246
+ catch (error) {
247
+ if (lastHostedListing && !isSignInRejected(error))
248
+ throw error;
249
+ }
250
+ if (!bearer)
251
+ return signedOut();
252
+ let payload;
253
+ try {
254
+ payload = asRecord(await fetchJson({ ...opts, timeoutMs: Math.min(opts.timeoutMs, 5000) }, hostedMcpUrl(opts), {
204
255
  method: "POST", headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json", accept: "application/json, text/event-stream" },
205
256
  body: JSON.stringify({ jsonrpc: "2.0", id: "domain-discovery", method: "tools/list", params: {} }),
206
257
  }));
207
- const remote = asRecord(payload.result).tools;
208
- if (!Array.isArray(remote))
209
- throw new Error("domain_discovery_unavailable");
210
- const contracts = new Map(remote.filter(isRecord).map(tool => [tool.name, tool]));
258
+ }
259
+ catch (error) {
260
+ if (isSignInRejected(error))
261
+ return signedOut();
262
+ throw error;
263
+ }
264
+ const remote = asRecord(payload.result).tools;
265
+ if (!Array.isArray(remote))
266
+ throw new Error("domain_discovery_unavailable");
267
+ const contracts = new Map(remote.filter(isRecord).map(tool => [tool.name, tool]));
268
+ const hostedSchema = (name) => isRecord(contracts.get(name)?.inputSchema)
269
+ ? contracts.get(name).inputSchema : undefined;
270
+ // Session tools follow the hosted list: listed only while it offers them.
271
+ const hidden = new Set(listed.tools.map(tool => tool.name).filter(name => EXTERNAL_BUILD_SESSION_TOOLS.has(name) && !contracts.has(name)));
272
+ const schemas = new Map(listed.tools.map(tool => tool.name)
273
+ .filter(name => EXTERNAL_BUILD_SESSION_FORWARD_TOOLS.has(name) && !hidden.has(name) && hostedSchema(name))
274
+ .map(name => [name, hostedSchema(name)]));
275
+ const local = listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name) || (names.has(tool.name) && contracts.has(tool.name)))
276
+ .filter(tool => !hidden.has(tool.name))
277
+ .map(tool => DOMAIN_FORWARD_TOOLS.has(tool.name) ? { ...tool, inputSchema: contracts.get(tool.name).inputSchema }
278
+ : schemas.has(tool.name) ? { ...tool, inputSchema: schemas.get(tool.name) } : tool);
279
+ const tools = [...local, ...hostedOnlyTools(opts, remote, allowedTools)];
280
+ const signIn = await signInTag();
281
+ if (newest()) {
211
282
  if (!opts.token)
212
283
  discoveredGrant = grantTag(await readStoredOAuthCredentials(opts));
213
- const local = listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name) || (names.has(tool.name) && contracts.has(tool.name)))
214
- .map(tool => DOMAIN_FORWARD_TOOLS.has(tool.name) ? { ...tool, inputSchema: contracts.get(tool.name).inputSchema } : tool);
215
- return { tools: [...local, ...hostedOnlyTools(opts, remote, allowedTools)] };
284
+ lastHostedListing = { tools, hiddenSessionTools: hidden, signIn };
285
+ hiddenSessionTools = hidden;
286
+ hostedSessionSchemas = schemas;
216
287
  }
217
- return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name) || names.has(tool.name)).map(tool => tool.name === "platform_read_artifact_domains"
218
- ? { ...tool, inputSchema: { type: "object", additionalProperties: false, properties: { limit: { type: "integer", minimum: 1, maximum: 100 }, cursor: { type: "integer", minimum: 0, maximum: 10000 } } } }
219
- : tool) };
288
+ return { tools: structuredClone(tools) };
220
289
  }
221
290
  catch {
222
- return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name)) };
291
+ // Network, 5xx or timeout: keep the last good listing while the same
292
+ // sign-in holds; before one exists, list the package's own tools. The
293
+ // next tool call asks the host to list again.
294
+ hostedListingFailed = true;
295
+ const last = lastHostedListing && lastHostedListing.signIn === await signInTag() ? lastHostedListing : null;
296
+ if (newest()) {
297
+ lastHostedListing = last;
298
+ hiddenSessionTools = last?.hiddenSessionTools ?? new Set();
299
+ if (!last)
300
+ hostedSessionSchemas = new Map();
301
+ }
302
+ return { tools: last ? structuredClone(last.tools) : listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name)) };
223
303
  }
224
304
  });
225
305
  mcp.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
@@ -227,16 +307,24 @@ export function createHarnessMcpStdioServer(opts, toolAllowlist) {
227
307
  throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`);
228
308
  }
229
309
  const reportsProgress = req.params.name === "platform_deploy_artifact_app" || req.params.name === "platform_wait_artifact_deploy";
310
+ let refusedHidden = false;
230
311
  try {
231
- if (mcpSurface(opts) === "topline" && !LOCAL_TOOL_NAMES.has(req.params.name)) {
312
+ // A changed sign-in (for example a reconnect with new scopes) may offer
313
+ // the tool again; Topline still checks, so the call goes through.
314
+ if (hiddenSessionTools.has(req.params.name) && (opts.token || grantTag(await readStoredOAuthCredentials(opts)) === discoveredGrant)) {
315
+ refusedHidden = true;
316
+ return structuredToolError("build_session_tool_unavailable");
317
+ }
318
+ if (forwardsHostedSurface(opts) && !LOCAL_TOOL_NAMES.has(req.params.name)) {
232
319
  if (!forwardsHostedTool(req.params.name))
233
320
  throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`);
234
321
  // Workspace and other hosted tools: Topline checks scopes and seat.
235
322
  return await forwardHostedTool(opts, req.params.name, req.params.arguments ?? {});
236
323
  }
237
- const result = await callHarnessTool(opts, req.params.name, req.params.arguments ?? {}, reportsProgress
238
- ? { onProgress: (progress, message) => sendProgress(extra, progress, 1, message) }
239
- : undefined);
324
+ const result = await callHarnessTool(opts, req.params.name, req.params.arguments ?? {}, {
325
+ ...(reportsProgress ? { onProgress: (progress, message) => sendProgress(extra, progress, 1, message) } : {}),
326
+ inputSchema: hostedSessionSchemas.get(req.params.name)
327
+ });
240
328
  return result;
241
329
  }
242
330
  catch (err) {
@@ -247,15 +335,24 @@ export function createHarnessMcpStdioServer(opts, toolAllowlist) {
247
335
  return structuredToolError(redactSecrets(err instanceof Error ? err.message : String(err), opts));
248
336
  }
249
337
  finally {
338
+ let listChanged = false;
250
339
  if (servesBuild(opts) && !opts.token) {
251
340
  const currentGrant = grantTag(await readStoredOAuthCredentials(opts));
252
341
  if (currentGrant !== discoveredGrant) {
253
342
  discoveredGrant = currentGrant;
254
343
  // First browser sign-in changes manager-only selector availability.
255
344
  // Tell MCP hosts to rediscover before setup status/recovery calls.
256
- await mcp.sendToolListChanged().catch(() => undefined);
345
+ listChanged = true;
257
346
  }
258
347
  }
348
+ if (hostedListingFailed || refusedHidden) {
349
+ // One failed listing, or a refused hidden tool, must not hide tools
350
+ // for the whole chat: the host lists again and sees current access.
351
+ hostedListingFailed = false;
352
+ listChanged = true;
353
+ }
354
+ if (listChanged)
355
+ await mcp.sendToolListChanged().catch(() => undefined);
259
356
  }
260
357
  });
261
358
  return mcp;
@@ -265,7 +362,8 @@ export async function callHarnessTool(opts, name, args, hooks) {
265
362
  const tool = listTools().tools.find((candidate) => candidate.name === name);
266
363
  if (!tool)
267
364
  throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
268
- const inputError = validateJsonSchema(tool.inputSchema, input);
365
+ // A forwarding session tool may be checked against the hosted schema it was listed with.
366
+ const inputError = validateJsonSchema(hooks?.inputSchema && EXTERNAL_BUILD_SESSION_FORWARD_TOOLS.has(name) ? hooks.inputSchema : tool.inputSchema, input);
269
367
  if (inputError)
270
368
  return toolError(`Invalid arguments for ${name}: ${inputError}`);
271
369
  let result;
@@ -591,7 +689,14 @@ export async function inspectArtifactApp(opts, input) {
591
689
  id: typeof manifest.id === "string" ? manifest.id : null,
592
690
  manifestVersion: typeof manifest.manifestVersion === "number" ? manifest.manifestVersion : null,
593
691
  title: typeof manifest.title === "string" ? manifest.title : null,
594
- kind: typeof manifest.kind === "string" ? manifest.kind : null
692
+ kind: typeof manifest.kind === "string" ? manifest.kind : null,
693
+ parts: Array.isArray(manifest.parts)
694
+ ? manifest.parts.filter(isRecord).map((part) => ({
695
+ name: typeof part.name === "string" ? part.name : null,
696
+ kind: typeof part.kind === "string" ? part.kind : null,
697
+ dir: typeof part.dir === "string" ? part.dir : null
698
+ }))
699
+ : []
595
700
  },
596
701
  bundle: {
597
702
  fileCount: bundle.fileCount,
@@ -791,6 +896,11 @@ export async function initArtifactApp(opts, input) {
791
896
  const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
792
897
  if (existsSync(absoluteAppDir) && (await readdir(absoluteAppDir)).length > 0)
793
898
  throw new Error("artifact_app_scaffold_target_not_empty");
899
+ const shape = optionalString(input, "shape") ?? "single";
900
+ if (shape === "web-and-api")
901
+ return initWebAndApiArtifactApp(opts, { appDir, absoluteAppDir, manifestId, title });
902
+ if (shape !== "single")
903
+ throw new Error("artifact_app_scaffold_shape_invalid");
794
904
  await mkdir(path.join(absoluteAppDir, "src"), { recursive: true });
795
905
  const manifest = {
796
906
  manifestVersion: 2,
@@ -825,6 +935,55 @@ export async function initArtifactApp(opts, input) {
825
935
  nextAction: `Run npm test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
826
936
  };
827
937
  }
938
+ const ARTIFACT_APP_ENV = ["ARTIFACT_ID", "ARTIFACT_VERSION_ID", "ARTIFACT_MANIFEST_URI", "PLATFORM_ARTIFACT_ID", "PLATFORM_ARTIFACT_VERSION_ID", "PLATFORM_ARTIFACT_MANIFEST_URI"];
939
+ /** One artifact with a static website part and a Node API part, routed by path under one address. */
940
+ async function initWebAndApiArtifactApp(opts, input) {
941
+ const { appDir, absoluteAppDir, manifestId, title } = input;
942
+ await mkdir(path.join(absoluteAppDir, "web", "src"), { recursive: true });
943
+ await mkdir(path.join(absoluteAppDir, "api", "src"), { recursive: true });
944
+ const manifest = {
945
+ manifestVersion: 2,
946
+ id: manifestId,
947
+ title,
948
+ kind: "tool",
949
+ runtime: { target: "aws_lambda_function_url", region: "us-west-2" },
950
+ parts: [
951
+ { name: "web", kind: "static", dir: "web", build: { command: "npm run build", outputDir: "dist" }, spa: true },
952
+ { name: "api", kind: "server", dir: "api", language: "node", entryPoint: "artifactApp" }
953
+ ],
954
+ validation: { localCommand: "node api/src/index.js --test", testCommand: "node api/src/index.js --test --artifact-tests-json" },
955
+ routes: [
956
+ { path: "/*", kind: "page", part: "web" },
957
+ { path: "/_artifact/api/*", kind: "api", part: "api" }
958
+ ],
959
+ sourceBindings: [],
960
+ env: ARTIFACT_APP_ENV,
961
+ viewerPolicy: "private"
962
+ };
963
+ const safeTitle = title.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
964
+ const webPackage = { name: `${manifestId}-web`, private: true, type: "module", scripts: { build: "node src/build.mjs" } };
965
+ const apiPackage = { name: `${manifestId}-api`, private: true, type: "module", main: "src/index.js" };
966
+ const page = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${safeTitle}</title></head><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p id="message">Loading...</p></main><script type="module" src="./app.js"></script></body></html>`;
967
+ const browserScript = `fetch("./_artifact/api/hello").then((response) => response.json()).then((body) => { document.getElementById("message").textContent = body.message; }).catch(() => { document.getElementById("message").textContent = "The API is not reachable yet."; });\n`;
968
+ const webBuild = `import { mkdirSync, writeFileSync } from "node:fs";\n\n// Asset URLs stay relative so the same files work on the draft, live, and version addresses.\nmkdirSync("dist", { recursive: true });\nwriteFileSync("dist/index.html", ${JSON.stringify(page)}, "utf8");\nwriteFileSync("dist/app.js", ${JSON.stringify(browserScript)}, "utf8");\nconsole.log("web build ok");\n`;
969
+ const apiSource = `export function artifactApp(req, res) {\n const url = new URL(req.url ?? "/", "http://artifact.local");\n res.setHeader("content-type", "application/json; charset=utf-8");\n if (url.pathname.endsWith("/_artifact/api/health")) {\n res.end(JSON.stringify({ ok: true, part: process.env.PLATFORM_ARTIFACT_PART ?? null }));\n return;\n }\n if (url.pathname.endsWith("/_artifact/api/hello")) {\n res.end(JSON.stringify({ ok: true, message: "Hello from the api part. Replace this endpoint with your API." }));\n return;\n }\n res.statusCode = 404;\n res.end(JSON.stringify({ error: "not_found" }));\n}\n\nif (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {\n console.log(JSON.stringify({ tests: [{ description: "The api part answers its hello route.", required: true, status: "passed", summary: "artifactApp handles /_artifact/api/hello." }] }));\n} else if (process.argv.includes("--test")) {\n console.log("api part ok");\n}\n`;
970
+ const files = [
971
+ ["artifact-app.json", `${JSON.stringify(manifest, null, 2)}\n`],
972
+ ["web/package.json", `${JSON.stringify(webPackage, null, 2)}\n`],
973
+ ["web/src/build.mjs", webBuild],
974
+ ["api/package.json", `${JSON.stringify(apiPackage, null, 2)}\n`],
975
+ ["api/src/index.js", apiSource]
976
+ ];
977
+ await Promise.all(files.map(([file, content]) => writeFile(path.join(absoluteAppDir, ...file.split("/")), content, { flag: "wx" })));
978
+ return {
979
+ ok: true,
980
+ appDir: workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir),
981
+ manifestId,
982
+ title,
983
+ files: files.map(([file]) => file),
984
+ nextAction: `Run npm run build in ${appDir}/web and node api/src/index.js --test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
985
+ };
986
+ }
828
987
  export async function getArtifactStatus(opts, artifactId, limit) {
829
988
  const query = new URLSearchParams();
830
989
  if (limit)
@@ -1227,7 +1386,16 @@ const BUILD_MCP_TOOLS = [
1227
1386
  annotations: mcpToolAnnotations("platform_init_artifact_app", { readOnly: false }),
1228
1387
  inputSchema: {
1229
1388
  type: "object",
1230
- properties: { appDir: { type: "string", minLength: 1 }, manifestId: { type: "string" }, title: { type: "string" } },
1389
+ properties: {
1390
+ appDir: { type: "string", minLength: 1 },
1391
+ manifestId: { type: "string" },
1392
+ title: { type: "string" },
1393
+ shape: {
1394
+ type: "string",
1395
+ enum: ["single", "web-and-api"],
1396
+ description: "single (default): one app. web-and-api: one artifact with a static website part and an API part under one address; use it instead of two artifacts."
1397
+ }
1398
+ },
1231
1399
  required: ["appDir"],
1232
1400
  additionalProperties: false
1233
1401
  },
@@ -1543,16 +1711,22 @@ const LOCAL_TOOL_NAMES = new Set(BUILD_MCP_TOOLS.map((tool) => tool.name));
1543
1711
  /**
1544
1712
  * Hosted Build tools this package deliberately replaces with its own local
1545
1713
  * flow (package, upload, deploy) or keeps off entirely. They are neither
1546
- * listed nor forwarded on the combined server.
1714
+ * listed nor forwarded on the Build or combined server.
1547
1715
  */
1548
1716
  const HOSTED_TOOLS_NOT_FORWARDED = new Set(["platform_create_artifact_app", "platform_bedrock_local_token_command"]);
1549
1717
  const forwardsHostedTool = (name) => !LOCAL_TOOL_NAMES.has(name) && !HOSTED_TOOLS_NOT_FORWARDED.has(name);
1550
1718
  /**
1551
- * On the combined Topline server, hosted tools this package does not run
1552
- * locally (Workspace tools, for example) are listed from Topline as-is.
1719
+ * The combined Topline server, and the Build server signed in through OAuth,
1720
+ * list and forward hosted tools this package does not run locally. A local
1721
+ * tool always wins over a hosted tool of the same name.
1722
+ */
1723
+ const forwardsHostedSurface = (opts) => mcpSurface(opts) === "topline" || (mcpSurface(opts) === "build" && !opts.token);
1724
+ /**
1725
+ * Hosted tools this package does not run locally (new hosted Build tools, or
1726
+ * Workspace tools on the combined server) are listed from Topline as-is.
1553
1727
  */
1554
1728
  function hostedOnlyTools(opts, remote, allowedTools) {
1555
- if (mcpSurface(opts) !== "topline")
1729
+ if (!forwardsHostedSurface(opts))
1556
1730
  return [];
1557
1731
  return remote.filter(isRecord)
1558
1732
  .filter((tool) => typeof tool.name === "string" && forwardsHostedTool(tool.name) && (!allowedTools || allowedTools.has(tool.name)) && isRecord(tool.inputSchema))
@@ -1655,6 +1829,7 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
1655
1829
  ...Object.fromEntries([...DOMAIN_ERROR_CODES].map(code => [code, { retryable: false,
1656
1830
  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." }])),
1657
1831
  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." },
1832
+ 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." },
1658
1833
  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." },
1659
1834
  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." },
1660
1835
  platform_mcp_tool_error: { retryable: false, recoveryAction: "Read the returned error code, correct the request or OAuth scopes, then retry." },
@@ -1666,7 +1841,8 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
1666
1841
  artifact_app_manifest_not_found: { retryable: false, recoveryAction: "Create artifact-app.json inside appDir, or correct appDir, then inspect again." },
1667
1842
  artifact_app_manifest_too_large: { retryable: false, recoveryAction: "Keep artifact-app.json below 512 KiB. Move application data and source into separate files, then inspect again." },
1668
1843
  scope_required: { retryable: false, recoveryAction: "Reconnect the Build MCP and approve the requested scope." },
1669
- artifact_app_scaffold_target_not_empty: { retryable: false, recoveryAction: "Choose an empty appDir or deploy the existing app without scaffolding." }
1844
+ artifact_app_scaffold_target_not_empty: { retryable: false, recoveryAction: "Choose an empty appDir or deploy the existing app without scaffolding." },
1845
+ artifact_app_scaffold_shape_invalid: { retryable: false, recoveryAction: "Use shape single or web-and-api." }
1670
1846
  };
1671
1847
  export const BUILD_MCP_RECOVERY_ERRORS = Object.freeze(Object.fromEntries(Object.entries(BUILD_MCP_RECOVERY_ERROR_VALUES).map(([code, guidance]) => [code, Object.freeze(guidance)])));
1672
1848
  function structuredToolError(message) {
@@ -1688,6 +1864,7 @@ function recoveryErrorCode(message) {
1688
1864
  "artifact_delete_plan_stale",
1689
1865
  "artifact_deploy_wait_timeout",
1690
1866
  "artifact_app_scaffold_target_not_empty",
1867
+ "artifact_app_scaffold_shape_invalid",
1691
1868
  "platform_harness_timeout",
1692
1869
  "platform_mcp_tool_error",
1693
1870
  "scope_required"
@@ -1817,6 +1994,11 @@ async function refreshOAuthToken(opts, stored) {
1817
1994
  });
1818
1995
  return credentialsFromTokenResponse(stored.issuer, stored.resource, stored.clientId, stored.scopes, token);
1819
1996
  }
1997
+ /** The sign-in itself was refused (revoked, expired or invalid), as opposed to a temporary failure. */
1998
+ function isSignInRejected(err) {
1999
+ const message = err instanceof Error ? err.message : String(err);
2000
+ return isRefreshTokenRejected(err) || /^(?:platform_harness|topline_oauth)_http_error:401(?::|$)/.test(message) || message === "missing_topline_refresh_token";
2001
+ }
1820
2002
  function isRefreshTokenRejected(err) {
1821
2003
  const message = err instanceof Error ? err.message : String(err);
1822
2004
  return /^topline_oauth_http_error:(400|401):/.test(message) && /invalid_(grant|token)/i.test(message);
@@ -2,7 +2,7 @@
2
2
  "schemaVersion": 1,
3
3
  "package": {
4
4
  "name": "@topline-build/harness-mcp",
5
- "version": "0.8.0",
5
+ "version": "0.9.1",
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.8.0"
15
+ "version": "0.9.1"
16
16
  }
17
17
  },
18
18
  "generatedFrom": {
@@ -337,6 +337,11 @@
337
337
  "retryable": false,
338
338
  "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."
339
339
  },
340
+ {
341
+ "code": "build_session_tool_unavailable",
342
+ "retryable": false,
343
+ "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."
344
+ },
340
345
  {
341
346
  "code": "platform_harness_timeout",
342
347
  "retryable": true,
@@ -386,6 +391,11 @@
386
391
  "code": "artifact_app_scaffold_target_not_empty",
387
392
  "retryable": false,
388
393
  "recoveryAction": "Choose an empty appDir or deploy the existing app without scaffolding."
394
+ },
395
+ {
396
+ "code": "artifact_app_scaffold_shape_invalid",
397
+ "retryable": false,
398
+ "recoveryAction": "Use shape single or web-and-api."
389
399
  }
390
400
  ]
391
401
  },
@@ -512,6 +522,14 @@
512
522
  },
513
523
  "title": {
514
524
  "type": "string"
525
+ },
526
+ "shape": {
527
+ "type": "string",
528
+ "enum": [
529
+ "single",
530
+ "web-and-api"
531
+ ],
532
+ "description": "single (default): one app. web-and-api: one artifact with a static website part and an API part under one address; use it instead of two artifacts."
515
533
  }
516
534
  },
517
535
  "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.8.0`
5
+ Package: `@topline-build/harness-mcp@0.9.1`
6
6
  Transport: `stdio`
7
7
  Default protocol: `2025-11-25`
8
8
  Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -65,6 +65,7 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
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_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.
68
69
  - `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.
69
70
  - `platform_mcp_tool_error` (not automatically retryable): Read the returned error code, correct the request or OAuth scopes, then retry.
70
71
  - `artifact_deploy_wait_timeout` (retryable): Call platform_wait_artifact_deploy again with the same artifactId and operationId.
@@ -75,6 +76,7 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
75
76
  - `artifact_app_manifest_not_found` (not automatically retryable): Create artifact-app.json inside appDir, or correct appDir, then inspect again.
76
77
  - `artifact_app_manifest_too_large` (not automatically retryable): Keep artifact-app.json below 512 KiB. Move application data and source into separate files, then inspect again.
77
78
  - `artifact_app_scaffold_target_not_empty` (not automatically retryable): Choose an empty appDir or deploy the existing app without scaffolding.
79
+ - `artifact_app_scaffold_shape_invalid` (not automatically retryable): Use shape single or web-and-api.
78
80
 
79
81
  ## Tools
80
82
 
@@ -233,6 +235,14 @@ Input schema:
233
235
  },
234
236
  "title": {
235
237
  "type": "string"
238
+ },
239
+ "shape": {
240
+ "type": "string",
241
+ "enum": [
242
+ "single",
243
+ "web-and-api"
244
+ ],
245
+ "description": "single (default): one app. web-and-api: one artifact with a static website part and an API part under one address; use it instead of two artifacts."
236
246
  }
237
247
  },
238
248
  "required": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topline-build/harness-mcp",
3
- "version": "0.8.0",
3
+ "version": "0.9.1",
4
4
  "description": "Topline Build MCP for creating and deploying artifact app drafts.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",