@topline-build/harness-mcp 0.6.0 → 0.8.0

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
@@ -4,6 +4,24 @@ All notable customer-visible Build MCP changes are recorded here. A source chang
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ ## 0.8.0 - source candidate
8
+
9
+ - 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
+ - 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.
11
+ - `platform_connection_check` no longer needs a verification code; a code is still accepted for manual checks.
12
+ - Report a missing browser opener instead of crashing, and print the sign-in address during login.
13
+ - `login` exits as soon as it finishes, explains a sign-in that timed out or was not approved, and fails if Topline cannot confirm the computer.
14
+ - The tool list refreshes an expired access token (never opening the browser), so hosted tools still appear in a chat started hours after sign-in. A manual token on `--surface topline` lists hosted tools too.
15
+ - 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
+ - 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
+
18
+ ## 0.7.0 - source candidate
19
+
20
+ - 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
+ - Require explicit new scopes and account-bound Build OAuth; preserve manual-token behavior for legacy tools.
22
+ - 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
+ - Discover enabled server capabilities and current hosted scoped contracts without initiating OAuth during discovery.
24
+
7
25
  ## 0.6.0 - pending publication
8
26
 
9
27
  - Add server-owned external build sessions, guarded artifact-private SQL, and full acceptance/reviewer forwarding.
package/README.md CHANGED
@@ -12,6 +12,16 @@ npx -y @topline-build/harness-mcp --url https://YOUR-TOPLINE-HOST
12
12
 
13
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. Developer Access in Topline provides ready-to-use Codex and Claude Code configuration snippets without embedding a raw token.
14
14
 
15
+ ### One Topline server (0.8.0)
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:
18
+
19
+ ```bash
20
+ npx -y @topline-build/harness-mcp login --url https://YOUR-TOPLINE-HOST
21
+ ```
22
+
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.
24
+
15
25
  Set `TOPLINE_WORKSPACE_ROOT` when the MCP host starts outside the repository containing the artifact app:
16
26
 
17
27
  ```bash
@@ -26,6 +36,10 @@ If a tool returns `authorization_required`, clear only that connection's OAuth c
26
36
 
27
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.
28
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.
40
+
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
+
29
43
  ## Typical workflow
30
44
 
31
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.
@@ -0,0 +1,11 @@
1
+ import type { ListToolsResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
2
+ type Annotate = (name: string, policy: {
3
+ readOnly: boolean;
4
+ destructive?: boolean;
5
+ idempotent?: boolean;
6
+ openWorld?: boolean;
7
+ }) => ToolAnnotations;
8
+ export declare function domainHelperTools(mcpToolAnnotations: Annotate): ListToolsResult["tools"];
9
+ export declare const DOMAIN_FORWARD_TOOLS: Set<string>;
10
+ export declare const DOMAIN_ERROR_CODES: Set<string>;
11
+ export {};
@@ -0,0 +1,53 @@
1
+ export function domainHelperTools(mcpToolAnnotations) {
2
+ const id = { type: "string", format: "uuid" };
3
+ const key = { type: "string", minLength: 1, maxLength: 128, pattern: "^[\\x21-\\x7E]+$" };
4
+ const recovery = { oneOf: [
5
+ { type: "object", additionalProperties: false, properties: { operationId: id }, required: ["operationId"] },
6
+ { type: "object", additionalProperties: false, properties: { idempotencyKey: key }, required: ["idempotencyKey"] },
7
+ ] };
8
+ const setupRecovery = { oneOf: [recovery.oneOf[0], { type: "object", additionalProperties: false,
9
+ properties: { kind: { enum: ["request", "verify"] }, idempotencyKey: key }, required: ["kind", "idempotencyKey"] }] };
10
+ const tool = (name, description, properties, required, _scopes, readOnly, extra = {}) => ({
11
+ name, description,
12
+ inputSchema: { type: "object", additionalProperties: false, properties, required, ...extra },
13
+ outputSchema: { type: "object", properties: { ok: { const: true } } },
14
+ annotations: mcpToolAnnotations(name, { readOnly, destructive: name === "platform_apply_artifact_address", idempotent: name !== "platform_plan_artifact_address", openWorld: name === "platform_verify_artifact_domain" }),
15
+ });
16
+ return [
17
+ tool("platform_read_artifact_domains", "Read connected company domains. With domainId, an explicitly scoped manager can read DNS/TLS setup state. With recovery, recover an original request/verify receipt by operation ID or its pre-call key; reads never retry setup or write DNS. Manager detail/recovery requires the setup capability.", {
18
+ limit: { type: "integer", minimum: 1, maximum: 100 }, cursor: { type: "integer", minimum: 0, maximum: 10000 }, includePending: { type: "boolean" },
19
+ domainId: id, zoneName: { type: "string", minLength: 1, maxLength: 253 }, recovery: setupRecovery,
20
+ }, [], ["harness:domains:read"], true, { oneOf: [
21
+ { not: { anyOf: [{ required: ["domainId"] }, { required: ["recovery"] }, { required: ["zoneName"] }] } },
22
+ { required: ["domainId"], not: { anyOf: ["limit", "cursor", "includePending", "recovery"].map(name => ({ required: [name] })) } },
23
+ { required: ["recovery"], not: { anyOf: ["domainId", "zoneName", "cursor", "limit", "includePending"].map(name => ({ required: [name] })) } },
24
+ ] }),
25
+ tool("platform_get_artifact_address", "Read an owned hosted app's exact company address, revision, connection and publication state. Optional recovery returns the original address-apply receipt under its current write scopes; it does not reapply. Saving an address never publishes an app or changes audience.", {
26
+ artifactId: id, recovery,
27
+ }, ["artifactId"], ["harness:domains:read", "harness:artifact:read"], true),
28
+ tool("platform_plan_artifact_address", "Store a ten-minute single-use address preview for the owned app. domainId=null explicitly detaches the company route. Show old/new URLs and readiness before applying; this changes no customer address or DNS.", {
29
+ artifactId: id, domainId: { type: ["string", "null"], format: "uuid" }, path: { type: "string", minLength: 1, maxLength: 70 },
30
+ }, ["artifactId", "domainId"], ["harness:domains:read", "harness:artifact:read", "harness:artifact:addresses:write"], false, { oneOf: [
31
+ { properties: { domainId: id }, required: ["path"] },
32
+ { properties: { domainId: { type: "null" } }, not: { required: ["path"] } },
33
+ ] }),
34
+ tool("platform_apply_artifact_address", "Apply the exact owned address plan with a stable pre-call key. Rechecks authority and address/domain revisions; consumes the plan once, including a no-op. Recover a lost response through the address-read tool before a new effect. No promotion, audience or DNS write.", {
35
+ planId: id, idempotencyKey: key,
36
+ }, ["planId", "idempotencyKey"], ["harness:domains:read", "harness:artifact:read", "harness:artifact:addresses:write"], false),
37
+ tool("platform_request_artifact_domain", "Manager-only request for an owned company subdomain. Save the key before calling. Returns exact ownership/routing DNS records; never writes customer DNS. The existing reconciler may make the first connected domain the initial default. No artifact is reassigned.", {
38
+ hostname: { type: "string", minLength: 1, maxLength: 253 }, idempotencyKey: key,
39
+ }, ["hostname", "idempotencyKey"], ["harness:domains:read", "harness:domains:manage"], false),
40
+ tool("platform_verify_artifact_domain", "Manager-only bounded ownership verification for the exact current domain generation and pre-call key. Matching DNS admits the existing TLS reconciler once. Same keys retain outcomes; use a new key only after a definite terminal no-admission outcome and covered retry intent. Read status through domain reads.", {
41
+ domainId: id, expectedConnectionGeneration: { type: "integer", minimum: 0 }, idempotencyKey: key,
42
+ }, ["domainId", "expectedConnectionGeneration", "idempotencyKey"], ["harness:domains:read", "harness:domains:manage"], false),
43
+ ];
44
+ }
45
+ export const DOMAIN_FORWARD_TOOLS = new Set(domainHelperTools(() => ({})).map(tool => tool.name));
46
+ export const DOMAIN_ERROR_CODES = new Set([
47
+ "capability_unavailable", "domain_manage_required", "artifact_not_found", "artifact_app_required", "domain_not_found", "domain_not_connected",
48
+ "operation_not_found", "hostname_required", "hostname_invalid", "subdomain_required", "topline_domain_not_customer_domain", "path_required",
49
+ "path_invalid", "path_reserved", "zone_invalid", "domain_path_in_use", "domain_already_claimed", "address_state_changed", "domain_state_changed",
50
+ "plan_expired", "plan_already_used", "verification_interrupted", "verification_pending", "verification_rate_limited", "waiting_for_dns",
51
+ "idempotency_conflict",
52
+ "domain_setup_limit", "domain_operation_failed", "invalid_arguments", "authorization_required", "scope_required", "domain_tools_require_build_oauth",
53
+ ]);
package/dist/index.d.ts CHANGED
@@ -2,8 +2,12 @@ import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
2
2
  import { type CallToolResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
3
3
  export interface HarnessMcpStdioOptions {
4
4
  apiUrl: string;
5
- /** Defaults to the Build MCP. Use harness only for legacy deployments. */
6
- surface?: "build" | "harness";
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.
9
+ */
10
+ surface?: McpSurface;
7
11
  token?: string;
8
12
  authFile: string;
9
13
  oauthScopes: string[];
@@ -12,6 +16,8 @@ export interface HarnessMcpStdioOptions {
12
16
  workspaceRoot: string;
13
17
  fetchImpl?: typeof fetch;
14
18
  openUrl?: (url: string) => void | Promise<void>;
19
+ /** Set by `login`, which already printed the sign-in address. */
20
+ quietOpenFailure?: boolean;
15
21
  }
16
22
  export interface StoredOAuthCredentials {
17
23
  issuer: string;
@@ -30,10 +36,13 @@ export interface PackedArtifactAppBundle {
30
36
  excluded: string[];
31
37
  }
32
38
  type ToolProgressReporter = (progress: number, message: string) => void | Promise<void>;
39
+ export type McpSurface = "build" | "topline" | "harness";
33
40
  export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
34
41
  export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
35
- export declare const HARNESS_MCP_VERSION = "0.6.0";
42
+ export declare const HARNESS_MCP_VERSION = "0.8.0";
36
43
  export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
44
+ /** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
45
+ export declare const TOPLINE_OAUTH_SCOPES: readonly string[];
37
46
  export interface BuildMcpSetupOption {
38
47
  readonly flag: string;
39
48
  readonly env: string;
@@ -44,8 +53,21 @@ export interface BuildMcpSetupOption {
44
53
  readonly description: string;
45
54
  }
46
55
  export declare const BUILD_MCP_SETUP_OPTIONS: readonly BuildMcpSetupOption[];
47
- export declare function parseHarnessOptions(argv: string[], env?: Record<string, string | undefined>): HarnessMcpStdioOptions;
56
+ export declare function parseHarnessOptions(argv: string[], env?: Record<string, string | undefined>, defaults?: {
57
+ surface?: McpSurface;
58
+ }): HarnessMcpStdioOptions;
48
59
  export declare function runHarnessMcpStdioCli(): Promise<void>;
60
+ /**
61
+ * `topline-mcp login`: sign in once during setup so the assistant's next chat
62
+ * starts already connected. Opens the browser, saves the refresh token to the
63
+ * same auth file the MCP server reads, then tells Topline this computer works.
64
+ */
65
+ export declare function runLoginCommand(argv: string[], env?: Record<string, string | undefined>, io?: {
66
+ log: (message: string) => void;
67
+ }, overrides?: Partial<Pick<HarnessMcpStdioOptions, "fetchImpl" | "openUrl" | "authFile">>): Promise<{
68
+ apiUrl: string;
69
+ verifiedAt: string | null;
70
+ }>;
49
71
  export declare function cliInfo(argv: string[]): string | null;
50
72
  export declare function createHarnessMcpStdioServer(opts: HarnessMcpStdioOptions, toolAllowlist?: readonly string[]): McpServer;
51
73
  export declare function callHarnessTool(opts: HarnessMcpStdioOptions, name: string, args: unknown, hooks?: {