@topline-build/harness-mcp 0.9.1 → 0.9.3
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 +23 -1
- package/README.md +7 -5
- package/dist/index.d.ts +12 -1
- package/dist/index.js +594 -28
- package/docs/generated/build-mcp-manifest.json +303 -6
- package/docs/generated/build-mcp-reference.md +282 -5
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,7 +2,29 @@
|
|
|
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.
|
|
5
|
+
## 0.9.3 - 2026-10-29
|
|
6
|
+
|
|
7
|
+
- `platform_run_artifact_smoke` and `platform_read_artifact_logs` accept `target: "sandbox"` with `sessionId` and `sandboxId`, so an assistant can check and read the logs of its own running dev sandbox. Both go to Topline's hosted tools, and the sandbox smoke keeps its screenshot.
|
|
8
|
+
- When Topline refuses this computer's saved sign-in (it expired or was revoked), the package now starts the browser sign-in itself instead of asking someone to clear the saved sign-in by hand. The tool returns `sign_in_required` with the sign-in address in `signInUrl` and as a link, so the assistant can ask the person to choose Allow and then call the tool again. The refused call is not replayed, a second refused call while the page is open reuses the same sign-in, and the saved sign-in is only replaced once the new one succeeds. A manual token still returns `authorization_required`.
|
|
9
|
+
- New `platform_sign_in` tool starts a fresh browser sign-in whenever the person asks to sign in to Topline again, signed in or not, and returns the address in `signInUrl`. The saved sign-in is only replaced once they choose Allow. `authorization_required` guidance now points to it, and a manual token gets `manual_token_sign_in_unavailable`.
|
|
10
|
+
- A refusal within 5 minutes of a finished browser sign-in returns `authorization_required` instead of opening another sign-in page, and two windows refreshing the same saved sign-in at once no longer open a needless browser sign-in.
|
|
11
|
+
- At startup, the Topline server (`--surface topline`) refreshes an expired saved sign-in right away and opens the browser sign-in when Topline refuses it, instead of starting with tools that fail. A temporary refresh failure keeps the saved sign-in.
|
|
12
|
+
- `sign_in_required` is not retryable (`retryable: false`); its recovery text tells the assistant to wait for the person to choose Allow, then call again, instead of retrying on its own.
|
|
13
|
+
- Before opening a browser sign-in after a refusal, the package re-reads the saved sign-in. When another window (or a refresh) renewed it while the call was on its way, the tool returns `sign_in_renewed` (retryable) and no page opens. Otherwise it tries one refresh first: when the refresh works, the tool returns `sign_in_renewed` ("Your Topline sign-in was renewed — try again.") instead of an Allow page, so a 401 for another reason (a gateway glitch) does not send the person to Allow. A temporary refresh failure keeps the original error. A 401 on a token obtained (refreshed or signed in) within the last 2 minutes (a time in the future does not count) skips the refresh and returns the original error with `retryable: false` and "Don't retry; report the error", so a 401 that is not about the sign-in cannot loop.
|
|
14
|
+
- Several Topline windows refused at once open one browser tab, not one each: the browser sign-in after a refusal now takes the same cross-process sign-in lock as the startup sign-in, and re-reads the saved sign-in after taking it. A window that does not get the lock returns `sign_in_required` with the waiting sign-in's address when it is a plain authorize address for this account (never a verifier), or says a sign-in is already waiting in the browser.
|
|
15
|
+
- Topline windows that did not run the sign-in watch the saved sign-in for up to the 5-minute sign-in window and ask the host to list tools again once, when the new sign-in lands.
|
|
16
|
+
- A sign-in after a signed-out state asks the host to list tools again even when Topline keeps the same OAuth client, and a hidden session tool then goes through to Topline. A token refresh does not count as a new sign-in, so it never triggers a relist.
|
|
17
|
+
- The saved sign-in file is replaced in one step (a temporary file in the same folder, then a rename, owner-only), so another window never reads a half-written file. When Windows keeps refusing the rename for about 1.5 s, the package writes the file in place instead, so a finished Allow is never lost. A symlinked auth file becomes a regular file at that path; the symlink's target is left as it was.
|
|
18
|
+
- A sign-in lock whose owner process has exited (including a 0.9.2 lock holding a bare pid) is taken over at once instead of blocking sign-in for 6 minutes, and the dead owner's sign-in address is never handed out. A process only rewrites or removes a lock it owns, and removes its own lock when it exits.
|
|
19
|
+
|
|
20
|
+
## 0.9.2 - 2026-10-24
|
|
21
|
+
|
|
22
|
+
- The Topline server (`--surface topline`) opens the browser sign-in as soon as it starts signed out, then asks the assistant to list tools again after you choose Allow, so a first chat no longer needs `login` beforehand. A tool call that needs a token while that browser approval is open waits for it instead of opening a second one. `login` still works for signing in ahead of time.
|
|
23
|
+
- Tool errors from Topline now carry Topline's own code (for example `artifact_external_session_active`, `external_private_tables_disabled` or `scope_required`) instead of the generic `platform_mcp_tool_error`, with recovery steps for that code. The full message is unchanged. `platform_mcp_tool_error` remains only when Topline gives no code, and its recovery text no longer suggests changing scopes.
|
|
24
|
+
- `build_session_id_required` names the session-only fields a session-less deploy passed (for example `build_session_id_required:idempotencyKey`), and says to remove them or start a session.
|
|
25
|
+
- `platform_run_artifact_smoke` takes an optional `sessionId`, so the holder of an open build session can rerun smoke without closing it (needs a Topline release with the matching change).
|
|
26
|
+
|
|
27
|
+
## 0.9.1 - 2026-10-23
|
|
6
28
|
|
|
7
29
|
- `--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
30
|
- 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.
|
package/README.md
CHANGED
|
@@ -7,10 +7,12 @@ The canonical customer guide is [Topline Build MCP documentation](https://toplin
|
|
|
7
7
|
## Quick start
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
npx -y @topline-build/harness-mcp --url https://YOUR-TOPLINE-HOST
|
|
10
|
+
npx -y @topline-build/harness-mcp@<version> --url https://YOUR-TOPLINE-HOST
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
The first authenticated tool call normally opens Topline in a browser for OAuth approval. Refresh credentials are cached in the user's local Topline config directory, outside the project repository.
|
|
13
|
+
The first authenticated tool call normally opens Topline in a browser for OAuth approval. Refresh credentials are cached in the user's local Topline config directory, outside the project repository.
|
|
14
|
+
|
|
15
|
+
Most people don't configure this package by hand. In Topline, **Developer Access > Connect an AI assistant > Set up Topline** copies a guided setup. The setup installs the `topline` plugin for Codex or Claude Code from the public marketplace [`topline-build/topline-plugins`](https://github.com/topline-build/topline-plugins), which runs a pinned version of this package. When you do configure it by hand, pin the version Developer Access shows (`@topline-build/harness-mcp@<version>`), because an unpinned `npx` can keep running an older cached copy.
|
|
14
16
|
|
|
15
17
|
### One Topline server (0.8.0)
|
|
16
18
|
|
|
@@ -20,7 +22,7 @@ Topline Developer Access now sets up one Topline connection per account. Its plu
|
|
|
20
22
|
npx -y @topline-build/harness-mcp login --url https://YOUR-TOPLINE-HOST
|
|
21
23
|
```
|
|
22
24
|
|
|
23
|
-
Run it on the computer where your browser opens. `login` opens the browser, waits up to 5 minutes for you to choose Allow, saves the refresh token where the server reads it, and records a connection check so Developer Access shows the computer as connected without a verification code. Start a new assistant chat afterwards so it loads the tools; the server refreshes the sign-in on its own after that. The plugin runs one exact package version. To update, copy the setup from Developer Access again (it shows "Update available" when a newer version is ready) and paste it into your assistant.
|
|
25
|
+
Run it on the computer where your browser opens. `login` opens the browser, waits up to 5 minutes for you to choose Allow, saves the refresh token where the server reads it, and records a connection check so Developer Access shows the computer as connected without a verification code. Start a new assistant chat afterwards so it loads the tools; the server refreshes the sign-in on its own after that. `login` is optional: when the Topline server starts signed out it opens the same browser sign-in itself and reloads its tools after you choose Allow. The plugin runs one exact package version. To update it, turn on marketplace auto-update in Claude Code (`/plugin` > Marketplaces), or run `codex plugin marketplace upgrade` in Codex. You can also copy the setup from Developer Access again (it shows "Update available" when a newer version is ready) and paste it into your assistant.
|
|
24
26
|
|
|
25
27
|
Set `TOPLINE_WORKSPACE_ROOT` when the MCP host starts outside the repository containing the artifact app:
|
|
26
28
|
|
|
@@ -32,7 +34,7 @@ npx -y @topline-build/harness-mcp
|
|
|
32
34
|
|
|
33
35
|
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.
|
|
34
36
|
|
|
35
|
-
If a tool returns `
|
|
37
|
+
If a tool returns `sign_in_required`, Topline refused the saved sign-in and the package has already opened a new browser sign-in: choose Allow (or open `signInUrl` if no page appeared), then call the tool again. When several windows are refused at once, only one opens the browser; the others return the same sign-in. If a tool returns `sign_in_renewed`, another window or a refresh already renewed the sign-in: just call the tool again. To sign in again at any time, ask your assistant to sign in to Topline again; it calls `platform_sign_in`, which opens the browser sign-in. If a tool returns `authorization_required` with a manual token, replace the expired or revoked token. Inspect existing artifact/deployment progress before retrying a write; the helper does not silently replay the rejected request.
|
|
36
38
|
|
|
37
39
|
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
40
|
|
|
@@ -44,7 +46,7 @@ Read connected domains and the current address, show the exact `platform_plan_ar
|
|
|
44
46
|
|
|
45
47
|
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
48
|
|
|
47
|
-
|
|
49
|
+
The `topline` surface (`--surface topline`, used by the plugin) carries Build and Workspace tools in one connection. On the earlier separate surfaces, 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
50
|
|
|
49
51
|
In session mode, `platform_deploy_artifact_app` requires the session ID, its exact current artifact version, a stable idempotency key, the session/checkout `inspectedSourceHash` and a fresh local `expectedBundleSha256`. The former pins the previously inspected remote source; the latter pins the local upload. Recover pending deployment and reviewer operations with their original IDs. Unknown work is never resubmitted by a status read. Add and run acceptance checks, prepare validation and request the independent review for the exact deployed revision. Approved output stays a private draft for an operator to publish.
|
|
50
52
|
|
package/dist/index.d.ts
CHANGED
|
@@ -28,6 +28,8 @@ export interface StoredOAuthCredentials {
|
|
|
28
28
|
accessTokenExpiresAt?: string;
|
|
29
29
|
refreshToken?: string;
|
|
30
30
|
scopes: string[];
|
|
31
|
+
/** When this access token was obtained (refresh or sign-in), so a refusal of a fresh one is not mistaken for a stale sign-in. */
|
|
32
|
+
obtainedAt?: string;
|
|
31
33
|
}
|
|
32
34
|
export interface PackedArtifactAppBundle {
|
|
33
35
|
body: Buffer;
|
|
@@ -40,7 +42,7 @@ type ToolProgressReporter = (progress: number, message: string) => void | Promis
|
|
|
40
42
|
export type McpSurface = "build" | "topline" | "harness";
|
|
41
43
|
export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
42
44
|
export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
|
|
43
|
-
export declare const HARNESS_MCP_VERSION = "0.9.
|
|
45
|
+
export declare const HARNESS_MCP_VERSION = "0.9.3";
|
|
44
46
|
export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
|
|
45
47
|
/** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
|
|
46
48
|
export declare const TOPLINE_OAUTH_SCOPES: readonly string[];
|
|
@@ -58,6 +60,14 @@ export declare function parseHarnessOptions(argv: string[], env?: Record<string,
|
|
|
58
60
|
surface?: McpSurface;
|
|
59
61
|
}): HarnessMcpStdioOptions;
|
|
60
62
|
export declare function runHarnessMcpStdioCli(): Promise<void>;
|
|
63
|
+
/**
|
|
64
|
+
* The one Topline server lists most of its tools only once signed in, so a
|
|
65
|
+
* first chat that starts signed out would see almost nothing. Start the browser
|
|
66
|
+
* sign-in as soon as the server is up instead, and tell the host to list tools
|
|
67
|
+
* again after Allow. Returns whether it signed in. Never throws: a sign-in that
|
|
68
|
+
* is ignored or refused leaves the on-demand sign-in of the first tool call.
|
|
69
|
+
*/
|
|
70
|
+
export declare function signInAtStartup(opts: HarnessMcpStdioOptions, onSignedIn: () => Promise<void>, log?: (message: string) => void): Promise<boolean>;
|
|
61
71
|
/**
|
|
62
72
|
* `topline-mcp login`: sign in once during setup so the assistant's next chat
|
|
63
73
|
* starts already connected. Opens the browser, saves the refresh token to the
|
|
@@ -74,6 +84,7 @@ export declare function createHarnessMcpStdioServer(opts: HarnessMcpStdioOptions
|
|
|
74
84
|
export declare function callHarnessTool(opts: HarnessMcpStdioOptions, name: string, args: unknown, hooks?: {
|
|
75
85
|
onProgress?: ToolProgressReporter;
|
|
76
86
|
inputSchema?: ListToolsResult["tools"][number]["inputSchema"];
|
|
87
|
+
onSignedIn?: () => Promise<void>;
|
|
77
88
|
}): Promise<CallToolResult>;
|
|
78
89
|
export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<{
|
|
79
90
|
operationId: string | null;
|