@topline-build/harness-mcp 0.7.0 → 0.9.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
@@ -2,7 +2,20 @@
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.0 - source candidate
6
+
7
+ - `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.
8
+
9
+ ## 0.8.0 - source candidate
10
+
11
+ - 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.
12
+ - 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.
13
+ - `platform_connection_check` no longer needs a verification code; a code is still accepted for manual checks.
14
+ - Report a missing browser opener instead of crashing, and print the sign-in address during login.
15
+ - `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.
16
+ - 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.
17
+ - 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).
18
+ - 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.
6
19
 
7
20
  ## 0.7.0 - source candidate
8
21
 
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
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.7.0";
42
+ export declare const HARNESS_MCP_VERSION = "0.9.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?: {
@@ -104,6 +126,11 @@ export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input:
104
126
  manifestVersion: number | null;
105
127
  title: string | null;
106
128
  kind: string | null;
129
+ parts: {
130
+ name: string | null;
131
+ kind: string | null;
132
+ dir: string | null;
133
+ }[];
107
134
  };
108
135
  bundle: {
109
136
  fileCount: number;
package/dist/index.js CHANGED
@@ -13,18 +13,31 @@ import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
13
13
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
14
14
  import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
15
15
  import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
16
+ const MCP_SURFACES = ["build", "topline", "harness"];
16
17
  export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
17
18
  const DEFAULT_TIMEOUT_MS = 120_000;
18
19
  export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
19
- export const HARNESS_MCP_VERSION = "0.7.0";
20
+ export const HARNESS_MCP_VERSION = "0.9.0";
20
21
  export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
22
+ /** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
23
+ export const TOPLINE_OAUTH_SCOPES = Object.freeze([
24
+ "harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete",
25
+ "harness:artifact:tables:write", "harness:artifact:validate", "harness:artifact:data:verify", "harness:assets:read",
26
+ "harness:secrets:metadata:read", "harness:domains:read", "harness:domains:manage", "harness:artifact:addresses:write",
27
+ "storyboard:read", "storyboard:write",
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",
30
+ "workspace:skills:write", "workspace:access:manage", "schedules:read", "schedules:write", "schedules:delete",
31
+ "workforce:read", "workforce:write", "memory:read", "preferences:write", "glossary:read", "glossary:write",
32
+ "company_knowledge:propose", "company_knowledge:write", "customer_profiles:read", "data:read"
33
+ ]);
21
34
  export const BUILD_MCP_SETUP_OPTIONS = Object.freeze([
22
35
  { 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." },
23
36
  { flag: "--workspace-root", env: "TOPLINE_WORKSPACE_ROOT", aliases: ["PLATFORM_WORKSPACE_ROOT"], default: "current working directory", description: "Local root that contains artifact app directories." },
24
- { flag: "--surface", env: "TOPLINE_MCP_SURFACE", default: "build", allowed: ["build", "harness"], description: "Build is the current surface; harness preserves legacy OAuth compatibility." },
37
+ { flag: "--surface", env: "TOPLINE_MCP_SURFACE", default: "build", allowed: ["build", "topline", "harness"], description: "topline is one server for Build and Workspace tools; build serves Build tools only; harness preserves legacy OAuth compatibility." },
25
38
  { flag: "--protocol-version", env: "TOPLINE_MCP_PROTOCOL_VERSION", aliases: ["PLATFORM_MCP_PROTOCOL_VERSION"], default: DEFAULT_MCP_PROTOCOL_VERSION, description: "MCP protocol version sent to Topline HTTP endpoints." },
26
39
  { flag: "--auth-file", env: "TOPLINE_MCP_AUTH_FILE", aliases: ["PLATFORM_MCP_AUTH_FILE"], default: "per-tenant file in the local Topline config directory", description: "OAuth credential cache. Keep it outside artifact app directories." },
27
- { flag: "--scopes", env: "TOPLINE_MCP_SCOPES", aliases: ["PLATFORM_MCP_SCOPES"], default: DEFAULT_OAUTH_SCOPES.join(" "), description: "Space- or comma-separated OAuth scopes." },
40
+ { flag: "--scopes", env: "TOPLINE_MCP_SCOPES", aliases: ["PLATFORM_MCP_SCOPES"], default: "Build scopes; every Topline scope with --surface topline", description: "Space- or comma-separated OAuth scopes." },
28
41
  { flag: "--timeout-ms", env: "TOPLINE_MCP_TIMEOUT_MS", aliases: ["PLATFORM_MCP_TIMEOUT_MS", "OVERSITE_MCP_TIMEOUT_MS"], default: DEFAULT_TIMEOUT_MS, description: "Positive request timeout in milliseconds." },
29
42
  { flag: "--token", env: "TOPLINE_MCP_TOKEN", aliases: ["PLATFORM_MCP_TOKEN", "OVERSITE_MCP_TOKEN"], description: "Advanced manual bearer-token fallback. Prefer browser-approved OAuth." }
30
43
  ].map((option) => Object.freeze({
@@ -39,7 +52,7 @@ const MAX_MANIFEST_BYTES = 512 * 1024;
39
52
  const MAX_FILES = 25_000;
40
53
  const MAX_DEPTH = 64;
41
54
  const FORBIDDEN_DIRS = new Set([".git", "node_modules", ".next", ".vite", ".turbo", ".cache", "dist", "build", "coverage"]);
42
- export function parseHarnessOptions(argv, env = process.env) {
55
+ export function parseHarnessOptions(argv, env = process.env, defaults = {}) {
43
56
  const getArg = (name) => {
44
57
  const index = argv.indexOf(name);
45
58
  if (index < 0)
@@ -53,9 +66,9 @@ export function parseHarnessOptions(argv, env = process.env) {
53
66
  const token = getArg("--token") || firstEnv(env, "TOPLINE_MCP_TOKEN", "PLATFORM_MCP_TOKEN", "OVERSITE_MCP_TOKEN") || undefined;
54
67
  const timeoutRaw = getArg("--timeout-ms") || firstEnv(env, "TOPLINE_MCP_TIMEOUT_MS", "PLATFORM_MCP_TIMEOUT_MS", "OVERSITE_MCP_TIMEOUT_MS");
55
68
  const protocolVersion = getArg("--protocol-version") || firstEnv(env, "TOPLINE_MCP_PROTOCOL_VERSION", "PLATFORM_MCP_PROTOCOL_VERSION") || DEFAULT_MCP_PROTOCOL_VERSION;
56
- const surfaceRaw = getArg("--surface") || firstEnv(env, "TOPLINE_MCP_SURFACE") || "build";
57
- if (surfaceRaw !== "build" && surfaceRaw !== "harness")
58
- throw new Error("TOPLINE_MCP_SURFACE must be build or harness");
69
+ const surfaceRaw = (getArg("--surface") || firstEnv(env, "TOPLINE_MCP_SURFACE") || defaults.surface || "build");
70
+ if (!MCP_SURFACES.includes(surfaceRaw))
71
+ throw new Error("TOPLINE_MCP_SURFACE must be build, topline or harness");
59
72
  const workspaceRoot = path.resolve(getArg("--workspace-root") || firstEnv(env, "TOPLINE_WORKSPACE_ROOT", "PLATFORM_WORKSPACE_ROOT") || process.cwd());
60
73
  const timeoutMs = timeoutRaw ? Number(timeoutRaw) : DEFAULT_TIMEOUT_MS;
61
74
  if (!apiUrl)
@@ -64,7 +77,8 @@ export function parseHarnessOptions(argv, env = process.env) {
64
77
  throw new Error("TOPLINE_MCP_TIMEOUT_MS must be a positive number");
65
78
  const normalizedApiUrl = normalizeApiUrl(apiUrl);
66
79
  const authFile = path.resolve(getArg("--auth-file") || firstEnv(env, "TOPLINE_MCP_AUTH_FILE", "PLATFORM_MCP_AUTH_FILE") || defaultAuthFile(normalizedApiUrl, surfaceRaw));
67
- const scopes = (getArg("--scopes") || firstEnv(env, "TOPLINE_MCP_SCOPES", "PLATFORM_MCP_SCOPES") || DEFAULT_OAUTH_SCOPES.join(" "))
80
+ const defaultScopes = surfaceRaw === "topline" ? TOPLINE_OAUTH_SCOPES : DEFAULT_OAUTH_SCOPES;
81
+ const scopes = (getArg("--scopes") || firstEnv(env, "TOPLINE_MCP_SCOPES", "PLATFORM_MCP_SCOPES") || defaultScopes.join(" "))
68
82
  .split(/[\s,]+/)
69
83
  .map((scope) => scope.trim())
70
84
  .filter(Boolean);
@@ -73,7 +87,7 @@ export function parseHarnessOptions(argv, env = process.env) {
73
87
  surface: surfaceRaw,
74
88
  token,
75
89
  authFile,
76
- oauthScopes: scopes.length > 0 ? [...new Set(scopes)] : [...DEFAULT_OAUTH_SCOPES],
90
+ oauthScopes: scopes.length > 0 ? [...new Set(scopes)] : [...defaultScopes],
77
91
  timeoutMs: Math.floor(timeoutMs),
78
92
  protocolVersion,
79
93
  workspaceRoot
@@ -81,6 +95,15 @@ export function parseHarnessOptions(argv, env = process.env) {
81
95
  }
82
96
  export async function runHarnessMcpStdioCli() {
83
97
  const argv = process.argv.slice(2);
98
+ if (argv[0] === "login") {
99
+ const info = cliInfo(argv.slice(1));
100
+ if (info) {
101
+ console.log(info);
102
+ return;
103
+ }
104
+ await runLoginCommand(argv.slice(1));
105
+ return;
106
+ }
84
107
  const info = cliInfo(argv);
85
108
  if (info) {
86
109
  console.log(info);
@@ -90,6 +113,49 @@ export async function runHarnessMcpStdioCli() {
90
113
  const mcp = createHarnessMcpStdioServer(opts);
91
114
  await mcp.connect(new StdioServerTransport());
92
115
  }
116
+ /**
117
+ * `topline-mcp login`: sign in once during setup so the assistant's next chat
118
+ * starts already connected. Opens the browser, saves the refresh token to the
119
+ * same auth file the MCP server reads, then tells Topline this computer works.
120
+ */
121
+ export async function runLoginCommand(argv, env = process.env, io = { log: (message) => console.log(message) }, overrides = {}) {
122
+ const parsed = { ...parseHarnessOptions(argv, env, { surface: "topline" }), ...overrides };
123
+ if (parsed.token)
124
+ throw new Error("topline-mcp login uses browser sign-in. Remove TOPLINE_MCP_TOKEN and try again.");
125
+ if (!servesBuild(parsed))
126
+ throw new Error("topline-mcp login supports --surface topline or build.");
127
+ const base = platformBaseUrl(parsed);
128
+ const opts = {
129
+ ...parsed,
130
+ openUrl: async (url) => {
131
+ io.log(`Opening your browser to sign in to Topline at ${base}.`);
132
+ io.log(`If it does not open, visit this address:\n${url}`);
133
+ await openBrowser({ ...parsed, quietOpenFailure: true }, url);
134
+ io.log("Waiting for you to choose Allow in the browser (up to 5 minutes).");
135
+ }
136
+ };
137
+ let credentials;
138
+ try {
139
+ credentials = await runOAuthLogin(opts);
140
+ }
141
+ catch (err) {
142
+ if (err instanceof Error && err.message === "topline_oauth_login_timeout") {
143
+ throw new Error("Sign-in did not finish within 5 minutes. Run this command on the computer where your browser opens, sign in to Topline, choose Allow, and try again. If Topline said you need access, ask an admin for Build access.");
144
+ }
145
+ if (err instanceof Error && err.message === "topline_oauth_callback_invalid") {
146
+ throw new Error("Sign-in was not approved in the browser. Run the command again and choose Allow.");
147
+ }
148
+ throw err;
149
+ }
150
+ await writeStoredOAuthCredentials(opts, credentials);
151
+ const check = asRecord(await callHostedBuildTool(opts, "platform_connection_check", {}));
152
+ if (check.verified !== true) {
153
+ throw new Error("Signed in, but Topline could not confirm this computer. Run the command again; if it keeps failing, check Developer Access in Topline.");
154
+ }
155
+ io.log(`Connected to Topline at ${base}. Developer Access now shows this computer as connected.`);
156
+ io.log("Start a new chat in your assistant to use the Topline tools.");
157
+ return { apiUrl: base, verifiedAt: typeof check.verifiedAt === "string" ? check.verifiedAt : null };
158
+ }
93
159
  export function cliInfo(argv) {
94
160
  if (argv.includes("--version") || argv.includes("-v"))
95
161
  return HARNESS_MCP_VERSION;
@@ -97,6 +163,7 @@ export function cliInfo(argv) {
97
163
  return null;
98
164
  return [
99
165
  "Usage: topline-mcp --url https://your-topline-host [--workspace-root <path>]",
166
+ " topline-mcp login --url https://your-topline-host Sign in once in the browser (one Topline server)",
100
167
  "",
101
168
  "Options and environment:",
102
169
  ...BUILD_MCP_SETUP_OPTIONS.map((option) => {
@@ -106,6 +173,7 @@ export function cliInfo(argv) {
106
173
  "",
107
174
  "Examples:",
108
175
  " npx -y @topline-build/harness-mcp --url https://hawx.topline.build",
176
+ " npx -y @topline-build/harness-mcp login --url https://hawx.topline.build",
109
177
  " TOPLINE_API_URL=https://hawx.topline.build npx -y @topline-build/harness-mcp"
110
178
  ].join("\n");
111
179
  }
@@ -121,26 +189,30 @@ export function createHarnessMcpStdioServer(opts, toolAllowlist) {
121
189
  const mcp = new McpServer({ name: BUILD_MCP_SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: { listChanged: true } } });
122
190
  mcp.setRequestHandler(ListToolsRequestSchema, async () => {
123
191
  const listed = listedTools();
124
- if (mcpSurface(opts) !== "build" || opts.token)
192
+ if (!servesBuild(opts) || (opts.token && mcpSurface(opts) !== "topline"))
125
193
  return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name)) };
126
194
  // Public deployment metadata never initiates OAuth or changes consent.
127
195
  // Unknown/old servers fail closed for this default-off family.
128
196
  try {
129
- const metadata = asRecord(await fetchJson({ ...opts, timeoutMs: Math.min(opts.timeoutMs, 5000) }, `${platformBaseUrl(opts)}/mcp/build`, { method: "GET" }));
197
+ const metadata = asRecord(await fetchJson({ ...opts, timeoutMs: Math.min(opts.timeoutMs, 5000) }, hostedMcpUrl(opts), { method: "GET" }));
130
198
  const names = new Set(Array.isArray(metadata.tools) ? metadata.tools.map(item => typeof item === "string" ? item : asRecord(item).name) : []);
131
- const stored = await readStoredOAuthCredentials(opts);
132
- if (stored?.accessToken && Date.parse(stored.accessTokenExpiresAt ?? "") > Date.now()) {
133
- const payload = asRecord(await fetchJson({ ...opts, timeoutMs: Math.min(opts.timeoutMs, 5000) }, `${platformBaseUrl(opts)}/mcp/build`, {
134
- method: "POST", headers: { authorization: `Bearer ${stored.accessToken}`, "content-type": "application/json", accept: "application/json, text/event-stream" },
199
+ // 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), {
204
+ method: "POST", headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json", accept: "application/json, text/event-stream" },
135
205
  body: JSON.stringify({ jsonrpc: "2.0", id: "domain-discovery", method: "tools/list", params: {} }),
136
206
  }));
137
207
  const remote = asRecord(payload.result).tools;
138
208
  if (!Array.isArray(remote))
139
209
  throw new Error("domain_discovery_unavailable");
140
210
  const contracts = new Map(remote.filter(isRecord).map(tool => [tool.name, tool]));
141
- discoveredGrant = grantTag(stored);
142
- return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name) || (names.has(tool.name) && contracts.has(tool.name)))
143
- .map(tool => DOMAIN_FORWARD_TOOLS.has(tool.name) ? { ...tool, inputSchema: contracts.get(tool.name).inputSchema } : tool) };
211
+ if (!opts.token)
212
+ 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)] };
144
216
  }
145
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"
146
218
  ? { ...tool, inputSchema: { type: "object", additionalProperties: false, properties: { limit: { type: "integer", minimum: 1, maximum: 100 }, cursor: { type: "integer", minimum: 0, maximum: 10000 } } } }
@@ -156,6 +228,12 @@ export function createHarnessMcpStdioServer(opts, toolAllowlist) {
156
228
  }
157
229
  const reportsProgress = req.params.name === "platform_deploy_artifact_app" || req.params.name === "platform_wait_artifact_deploy";
158
230
  try {
231
+ if (mcpSurface(opts) === "topline" && !LOCAL_TOOL_NAMES.has(req.params.name)) {
232
+ if (!forwardsHostedTool(req.params.name))
233
+ throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`);
234
+ // Workspace and other hosted tools: Topline checks scopes and seat.
235
+ return await forwardHostedTool(opts, req.params.name, req.params.arguments ?? {});
236
+ }
159
237
  const result = await callHarnessTool(opts, req.params.name, req.params.arguments ?? {}, reportsProgress
160
238
  ? { onProgress: (progress, message) => sendProgress(extra, progress, 1, message) }
161
239
  : undefined);
@@ -169,7 +247,7 @@ export function createHarnessMcpStdioServer(opts, toolAllowlist) {
169
247
  return structuredToolError(redactSecrets(err instanceof Error ? err.message : String(err), opts));
170
248
  }
171
249
  finally {
172
- if (mcpSurface(opts) === "build" && !opts.token) {
250
+ if (servesBuild(opts) && !opts.token) {
173
251
  const currentGrant = grantTag(await readStoredOAuthCredentials(opts));
174
252
  if (currentGrant !== discoveredGrant) {
175
253
  discoveredGrant = currentGrant;
@@ -244,7 +322,7 @@ export async function callHarnessTool(opts, name, args, hooks) {
244
322
  default:
245
323
  if (DOMAIN_FORWARD_TOOLS.has(name)) {
246
324
  try {
247
- if (mcpSurface(opts) !== "build" || opts.token)
325
+ if (!servesBuild(opts) || opts.token)
248
326
  throw new Error("domain_tools_require_build_oauth");
249
327
  result = toolResult(await callHostedBuildTool(opts, name, input));
250
328
  }
@@ -267,7 +345,7 @@ export async function callHarnessTool(opts, name, args, hooks) {
267
345
  break;
268
346
  }
269
347
  if (EXTERNAL_BUILD_FORWARD_TOOLS.has(name)) {
270
- if (mcpSurface(opts) !== "build")
348
+ if (!servesBuild(opts))
271
349
  throw new Error("external_session_requires_build_surface");
272
350
  result = toolResult(await callHostedBuildTool(opts, name, input));
273
351
  break;
@@ -303,7 +381,7 @@ export async function deployArtifactApp(opts, input, onProgress) {
303
381
  const inspectedSourceHash = optionalString(input, "inspectedSourceHash");
304
382
  let sessionArtifactId;
305
383
  if (sessionId) {
306
- if (mcpSurface(opts) !== "build")
384
+ if (!servesBuild(opts))
307
385
  throw new Error("external_session_requires_build_surface");
308
386
  if (!sessionVersion || !idempotencyKey || !inspectedSourceHash || !expectedBundleSha256)
309
387
  throw new Error("build_session_deployment_arguments_required");
@@ -405,7 +483,7 @@ async function fetchBuildTransfer(opts, advertisedPath, expectedPath, sha256, ma
405
483
  }
406
484
  }
407
485
  async function newBuildInputTarget(opts, input) {
408
- if (mcpSurface(opts) !== "build")
486
+ if (!servesBuild(opts))
409
487
  throw new Error("external_session_requires_build_surface");
410
488
  const target = await resolveWorkspacePathSafely(opts.workspaceRoot, stringArg(input, "targetDir"));
411
489
  if (existsSync(target))
@@ -513,7 +591,14 @@ export async function inspectArtifactApp(opts, input) {
513
591
  id: typeof manifest.id === "string" ? manifest.id : null,
514
592
  manifestVersion: typeof manifest.manifestVersion === "number" ? manifest.manifestVersion : null,
515
593
  title: typeof manifest.title === "string" ? manifest.title : null,
516
- kind: typeof manifest.kind === "string" ? manifest.kind : null
594
+ kind: typeof manifest.kind === "string" ? manifest.kind : null,
595
+ parts: Array.isArray(manifest.parts)
596
+ ? manifest.parts.filter(isRecord).map((part) => ({
597
+ name: typeof part.name === "string" ? part.name : null,
598
+ kind: typeof part.kind === "string" ? part.kind : null,
599
+ dir: typeof part.dir === "string" ? part.dir : null
600
+ }))
601
+ : []
517
602
  },
518
603
  bundle: {
519
604
  fileCount: bundle.fileCount,
@@ -525,10 +610,10 @@ export async function inspectArtifactApp(opts, input) {
525
610
  };
526
611
  }
527
612
  async function callHostedBuildTool(opts, name, input) {
528
- if (mcpSurface(opts) !== "build")
613
+ if (!servesBuild(opts))
529
614
  throw new Error(`${name}_requires_build_surface`);
530
615
  const headers = await jsonHeaders(opts);
531
- const payload = asRecord(await fetchJson(opts, `${platformBaseUrl(opts)}/mcp/build`, {
616
+ const payload = asRecord(await fetchJson(opts, hostedMcpUrl(opts), {
532
617
  method: "POST",
533
618
  headers: { ...headers, accept: "application/json, text/event-stream" },
534
619
  body: JSON.stringify({
@@ -553,7 +638,7 @@ async function callHostedBuildTool(opts, name, input) {
553
638
  throw new Error(`platform_mcp_tool_output_missing:${name}`);
554
639
  }
555
640
  async function checkoutDesignSystem(opts, input) {
556
- if (mcpSurface(opts) !== "build")
641
+ if (!servesBuild(opts))
557
642
  throw new Error("storyboard_requires_build_surface");
558
643
  const targetDir = stringArg(input, "targetDir");
559
644
  const target = await resolveWorkspacePathSafely(opts.workspaceRoot, targetDir);
@@ -636,7 +721,7 @@ async function readBoundedStoryboardBundle(response) {
636
721
  return Buffer.concat(chunks, bytes);
637
722
  }
638
723
  async function submitDesignSystemDraft(opts, input) {
639
- if (mcpSurface(opts) !== "build")
724
+ if (!servesBuild(opts))
640
725
  throw new Error("storyboard_requires_build_surface");
641
726
  const localDir = await resolveWorkspacePathSafely(opts.workspaceRoot, stringArg(input, "localDir"));
642
727
  await assertAuthFileOutsideAppDir(opts.authFile, localDir);
@@ -713,6 +798,11 @@ export async function initArtifactApp(opts, input) {
713
798
  const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
714
799
  if (existsSync(absoluteAppDir) && (await readdir(absoluteAppDir)).length > 0)
715
800
  throw new Error("artifact_app_scaffold_target_not_empty");
801
+ const shape = optionalString(input, "shape") ?? "single";
802
+ if (shape === "web-and-api")
803
+ return initWebAndApiArtifactApp(opts, { appDir, absoluteAppDir, manifestId, title });
804
+ if (shape !== "single")
805
+ throw new Error("artifact_app_scaffold_shape_invalid");
716
806
  await mkdir(path.join(absoluteAppDir, "src"), { recursive: true });
717
807
  const manifest = {
718
808
  manifestVersion: 2,
@@ -747,6 +837,55 @@ export async function initArtifactApp(opts, input) {
747
837
  nextAction: `Run npm test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
748
838
  };
749
839
  }
840
+ const ARTIFACT_APP_ENV = ["ARTIFACT_ID", "ARTIFACT_VERSION_ID", "ARTIFACT_MANIFEST_URI", "PLATFORM_ARTIFACT_ID", "PLATFORM_ARTIFACT_VERSION_ID", "PLATFORM_ARTIFACT_MANIFEST_URI"];
841
+ /** One artifact with a static website part and a Node API part, routed by path under one address. */
842
+ async function initWebAndApiArtifactApp(opts, input) {
843
+ const { appDir, absoluteAppDir, manifestId, title } = input;
844
+ await mkdir(path.join(absoluteAppDir, "web", "src"), { recursive: true });
845
+ await mkdir(path.join(absoluteAppDir, "api", "src"), { recursive: true });
846
+ const manifest = {
847
+ manifestVersion: 2,
848
+ id: manifestId,
849
+ title,
850
+ kind: "tool",
851
+ runtime: { target: "aws_lambda_function_url", region: "us-west-2" },
852
+ parts: [
853
+ { name: "web", kind: "static", dir: "web", build: { command: "npm run build", outputDir: "dist" }, spa: true },
854
+ { name: "api", kind: "server", dir: "api", language: "node", entryPoint: "artifactApp" }
855
+ ],
856
+ validation: { localCommand: "node api/src/index.js --test", testCommand: "node api/src/index.js --test --artifact-tests-json" },
857
+ routes: [
858
+ { path: "/*", kind: "page", part: "web" },
859
+ { path: "/_artifact/api/*", kind: "api", part: "api" }
860
+ ],
861
+ sourceBindings: [],
862
+ env: ARTIFACT_APP_ENV,
863
+ viewerPolicy: "private"
864
+ };
865
+ const safeTitle = title.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
866
+ const webPackage = { name: `${manifestId}-web`, private: true, type: "module", scripts: { build: "node src/build.mjs" } };
867
+ const apiPackage = { name: `${manifestId}-api`, private: true, type: "module", main: "src/index.js" };
868
+ 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>`;
869
+ 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`;
870
+ 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`;
871
+ 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`;
872
+ const files = [
873
+ ["artifact-app.json", `${JSON.stringify(manifest, null, 2)}\n`],
874
+ ["web/package.json", `${JSON.stringify(webPackage, null, 2)}\n`],
875
+ ["web/src/build.mjs", webBuild],
876
+ ["api/package.json", `${JSON.stringify(apiPackage, null, 2)}\n`],
877
+ ["api/src/index.js", apiSource]
878
+ ];
879
+ await Promise.all(files.map(([file, content]) => writeFile(path.join(absoluteAppDir, ...file.split("/")), content, { flag: "wx" })));
880
+ return {
881
+ ok: true,
882
+ appDir: workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir),
883
+ manifestId,
884
+ title,
885
+ files: files.map(([file]) => file),
886
+ 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.`
887
+ };
888
+ }
750
889
  export async function getArtifactStatus(opts, artifactId, limit) {
751
890
  const query = new URLSearchParams();
752
891
  if (limit)
@@ -1078,11 +1217,25 @@ function padSize(size) {
1078
1217
  const remainder = size % BLOCK_SIZE;
1079
1218
  return remainder === 0 ? 0 : BLOCK_SIZE - remainder;
1080
1219
  }
1220
+ /**
1221
+ * Requests to this Topline account carry the package version, so Topline can
1222
+ * ask an outdated computer to update. Other hosts (upload URLs) never see it.
1223
+ */
1224
+ function withPackageVersionHeader(opts, url, init) {
1225
+ let sameAccount = false;
1226
+ try {
1227
+ sameAccount = new URL(url).origin === new URL(platformBaseUrl(opts)).origin;
1228
+ }
1229
+ catch { /* leave the request as-is */ }
1230
+ if (!sameAccount || (init.headers !== undefined && (init.headers instanceof Headers || Array.isArray(init.headers))))
1231
+ return init;
1232
+ return { ...init, headers: { ...init.headers, "x-topline-mcp-version": HARNESS_MCP_VERSION } };
1233
+ }
1081
1234
  async function fetchJson(opts, url, init, timeoutMs = opts.timeoutMs) {
1082
1235
  const controller = new AbortController();
1083
1236
  const timeout = setTimeout(() => controller.abort(), timeoutMs);
1084
1237
  try {
1085
- const response = await (opts.fetchImpl ?? fetch)(url, { ...init, signal: controller.signal });
1238
+ const response = await (opts.fetchImpl ?? fetch)(url, { ...withPackageVersionHeader(opts, url, init), signal: controller.signal });
1086
1239
  const text = await response.text();
1087
1240
  let payload = {};
1088
1241
  try {
@@ -1112,20 +1265,19 @@ async function fetchJson(opts, url, init, timeoutMs = opts.timeoutMs) {
1112
1265
  const BUILD_MCP_TOOLS = [
1113
1266
  {
1114
1267
  name: "platform_connection_check",
1115
- description: "Complete the one-time Developer Access verification challenge for this Build MCP client.",
1268
+ description: "Tell Topline Developer Access that this signed-in client works. Run it with no arguments right after signing in. Pass verificationCode only when Developer Access shows one for a manual check.",
1116
1269
  annotations: mcpToolAnnotations("platform_connection_check", { readOnly: false, openWorld: true }),
1117
1270
  inputSchema: {
1118
1271
  type: "object",
1119
1272
  properties: {
1120
1273
  verificationCode: { type: "string", minLength: 16, maxLength: 80 }
1121
1274
  },
1122
- required: ["verificationCode"],
1123
1275
  additionalProperties: false
1124
1276
  },
1125
1277
  outputSchema: {
1126
1278
  type: "object",
1127
1279
  properties: {
1128
- ok: { type: "boolean" }, verified: { type: "boolean" }, product: { type: "string", enum: ["build"] }, verifiedAt: { type: "string" }
1280
+ ok: { type: "boolean" }, verified: { type: "boolean" }, product: { type: "string", enum: ["build", "topline"] }, verifiedAt: { type: "string" }
1129
1281
  },
1130
1282
  required: ["ok", "verified", "product", "verifiedAt"]
1131
1283
  }
@@ -1136,7 +1288,16 @@ const BUILD_MCP_TOOLS = [
1136
1288
  annotations: mcpToolAnnotations("platform_init_artifact_app", { readOnly: false }),
1137
1289
  inputSchema: {
1138
1290
  type: "object",
1139
- properties: { appDir: { type: "string", minLength: 1 }, manifestId: { type: "string" }, title: { type: "string" } },
1291
+ properties: {
1292
+ appDir: { type: "string", minLength: 1 },
1293
+ manifestId: { type: "string" },
1294
+ title: { type: "string" },
1295
+ shape: {
1296
+ type: "string",
1297
+ enum: ["single", "web-and-api"],
1298
+ 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."
1299
+ }
1300
+ },
1140
1301
  required: ["appDir"],
1141
1302
  additionalProperties: false
1142
1303
  },
@@ -1448,6 +1609,54 @@ const BUILD_MCP_TOOLS = [
1448
1609
  ...externalBuildHelperTools(mcpToolAnnotations),
1449
1610
  ...domainHelperTools(mcpToolAnnotations)
1450
1611
  ].map(withRecoveryOutputSchema);
1612
+ const LOCAL_TOOL_NAMES = new Set(BUILD_MCP_TOOLS.map((tool) => tool.name));
1613
+ /**
1614
+ * Hosted Build tools this package deliberately replaces with its own local
1615
+ * flow (package, upload, deploy) or keeps off entirely. They are neither
1616
+ * listed nor forwarded on the combined server.
1617
+ */
1618
+ const HOSTED_TOOLS_NOT_FORWARDED = new Set(["platform_create_artifact_app", "platform_bedrock_local_token_command"]);
1619
+ const forwardsHostedTool = (name) => !LOCAL_TOOL_NAMES.has(name) && !HOSTED_TOOLS_NOT_FORWARDED.has(name);
1620
+ /**
1621
+ * On the combined Topline server, hosted tools this package does not run
1622
+ * locally (Workspace tools, for example) are listed from Topline as-is.
1623
+ */
1624
+ function hostedOnlyTools(opts, remote, allowedTools) {
1625
+ if (mcpSurface(opts) !== "topline")
1626
+ return [];
1627
+ return remote.filter(isRecord)
1628
+ .filter((tool) => typeof tool.name === "string" && forwardsHostedTool(tool.name) && (!allowedTools || allowedTools.has(tool.name)) && isRecord(tool.inputSchema))
1629
+ .map((tool) => ({
1630
+ name: tool.name,
1631
+ ...(typeof tool.title === "string" ? { title: tool.title } : {}),
1632
+ ...(typeof tool.description === "string" ? { description: tool.description } : {}),
1633
+ inputSchema: tool.inputSchema,
1634
+ ...(isRecord(tool.outputSchema) ? { outputSchema: tool.outputSchema } : {}),
1635
+ ...(isRecord(tool.annotations) ? { annotations: tool.annotations } : {})
1636
+ }));
1637
+ }
1638
+ async function forwardHostedTool(opts, name, input) {
1639
+ const headers = await jsonHeaders(opts);
1640
+ const payload = asRecord(await fetchJson(opts, hostedMcpUrl(opts), {
1641
+ method: "POST",
1642
+ headers: { ...headers, accept: "application/json, text/event-stream" },
1643
+ body: JSON.stringify({ jsonrpc: "2.0", id: `stdio-${Date.now()}`, method: "tools/call", params: { name, arguments: isRecord(input) ? input : {} } })
1644
+ }));
1645
+ if (payload.error) {
1646
+ const message = String(asRecord(payload.error).message ?? "unknown_error");
1647
+ if (/unknown tool/i.test(message))
1648
+ throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
1649
+ throw new Error(`platform_mcp_tool_error:${message}`);
1650
+ }
1651
+ if (!isRecord(payload.result))
1652
+ throw new Error("platform_mcp_tool_error:empty_response");
1653
+ const result = payload.result;
1654
+ return {
1655
+ content: Array.isArray(result.content) ? result.content : [],
1656
+ ...(isRecord(result.structuredContent) ? { structuredContent: result.structuredContent } : {}),
1657
+ ...(result.isError === true ? { isError: true } : {})
1658
+ };
1659
+ }
1451
1660
  export function listTools() {
1452
1661
  // Preserve the original tools/list isolation boundary: callers must not be
1453
1662
  // able to mutate the registry used by later requests or input validation.
@@ -1527,7 +1736,8 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
1527
1736
  artifact_app_manifest_not_found: { retryable: false, recoveryAction: "Create artifact-app.json inside appDir, or correct appDir, then inspect again." },
1528
1737
  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." },
1529
1738
  scope_required: { retryable: false, recoveryAction: "Reconnect the Build MCP and approve the requested scope." },
1530
- artifact_app_scaffold_target_not_empty: { retryable: false, recoveryAction: "Choose an empty appDir or deploy the existing app without scaffolding." }
1739
+ artifact_app_scaffold_target_not_empty: { retryable: false, recoveryAction: "Choose an empty appDir or deploy the existing app without scaffolding." },
1740
+ artifact_app_scaffold_shape_invalid: { retryable: false, recoveryAction: "Use shape single or web-and-api." }
1531
1741
  };
1532
1742
  export const BUILD_MCP_RECOVERY_ERRORS = Object.freeze(Object.fromEntries(Object.entries(BUILD_MCP_RECOVERY_ERROR_VALUES).map(([code, guidance]) => [code, Object.freeze(guidance)])));
1533
1743
  function structuredToolError(message) {
@@ -1549,6 +1759,7 @@ function recoveryErrorCode(message) {
1549
1759
  "artifact_delete_plan_stale",
1550
1760
  "artifact_deploy_wait_timeout",
1551
1761
  "artifact_app_scaffold_target_not_empty",
1762
+ "artifact_app_scaffold_shape_invalid",
1552
1763
  "platform_harness_timeout",
1553
1764
  "platform_mcp_tool_error",
1554
1765
  "scope_required"
@@ -1606,6 +1817,41 @@ export async function getBearerToken(opts) {
1606
1817
  inFlightBearerTokenRequests.delete(key);
1607
1818
  }
1608
1819
  }
1820
+ /**
1821
+ * The stored or refreshed access token, or null when only a browser sign-in
1822
+ * would help. Never opens the browser. A manual token is returned as-is.
1823
+ */
1824
+ async function getBearerTokenWithoutSignIn(opts) {
1825
+ if (opts.token?.trim())
1826
+ return opts.token.trim();
1827
+ const stored = await readStoredOAuthCredentials(opts);
1828
+ if (stored?.accessToken && stored.accessTokenExpiresAt && new Date(stored.accessTokenExpiresAt).getTime() - Date.now() > 60_000) {
1829
+ return stored.accessToken;
1830
+ }
1831
+ if (!stored?.refreshToken || !stored.clientId)
1832
+ return null;
1833
+ return (await refreshStoredOAuthToken(opts, stored)).accessToken ?? null;
1834
+ }
1835
+ const inFlightRefreshes = new Map();
1836
+ /** Refresh tokens rotate, so concurrent refreshes of one token share a single request. */
1837
+ async function refreshStoredOAuthToken(opts, stored) {
1838
+ const key = `${path.resolve(opts.authFile)}\0${stored.refreshToken}`;
1839
+ const existing = inFlightRefreshes.get(key);
1840
+ if (existing)
1841
+ return existing;
1842
+ const pending = (async () => {
1843
+ const refreshed = await refreshOAuthToken(opts, stored);
1844
+ await writeStoredOAuthCredentials(opts, refreshed);
1845
+ return refreshed;
1846
+ })();
1847
+ inFlightRefreshes.set(key, pending);
1848
+ try {
1849
+ return await pending;
1850
+ }
1851
+ finally {
1852
+ inFlightRefreshes.delete(key);
1853
+ }
1854
+ }
1609
1855
  async function getOAuthBearerToken(opts) {
1610
1856
  const stored = await readStoredOAuthCredentials(opts);
1611
1857
  if (stored?.accessToken && stored.accessTokenExpiresAt && new Date(stored.accessTokenExpiresAt).getTime() - Date.now() > 60_000) {
@@ -1613,8 +1859,7 @@ async function getOAuthBearerToken(opts) {
1613
1859
  }
1614
1860
  if (stored?.refreshToken && stored.clientId) {
1615
1861
  try {
1616
- const refreshed = await refreshOAuthToken(opts, stored);
1617
- await writeStoredOAuthCredentials(opts, refreshed);
1862
+ const refreshed = await refreshStoredOAuthToken(opts, stored);
1618
1863
  return refreshed.accessToken;
1619
1864
  }
1620
1865
  catch (err) {
@@ -1678,6 +1923,8 @@ async function runOAuthLogin(opts) {
1678
1923
  authUrl.searchParams.set("code_challenge_method", "S256");
1679
1924
  authUrl.searchParams.set("state", state);
1680
1925
  const codePromise = callback.waitForCode(state);
1926
+ // A denial can land while the browser is still opening; it is reported below.
1927
+ codePromise.catch(() => undefined);
1681
1928
  await openBrowser(opts, authUrl.toString());
1682
1929
  const code = await codePromise;
1683
1930
  const token = await oauthFetchJson(opts, `${issuer}/oauth/token`, {
@@ -1812,10 +2059,17 @@ async function startOAuthCallbackServer() {
1812
2059
  redirectUri: `http://127.0.0.1:${address.port}/callback`,
1813
2060
  waitForCode: async (state) => {
1814
2061
  expectedState = state;
1815
- return await Promise.race([
1816
- codePromise,
1817
- new Promise((_resolve, reject) => setTimeout(() => reject(new Error("topline_oauth_login_timeout")), 5 * 60 * 1000))
1818
- ]);
2062
+ let timer;
2063
+ try {
2064
+ return await Promise.race([
2065
+ codePromise,
2066
+ new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error("topline_oauth_login_timeout")), 5 * 60 * 1000); })
2067
+ ]);
2068
+ }
2069
+ finally {
2070
+ // A pending timer would keep `topline-mcp login` alive after it succeeds.
2071
+ clearTimeout(timer);
2072
+ }
1819
2073
  },
1820
2074
  close: () => closeServer(server)
1821
2075
  };
@@ -1840,10 +2094,14 @@ async function openBrowser(opts, url) {
1840
2094
  const { command, args } = browserOpenCommand(url);
1841
2095
  try {
1842
2096
  const child = spawn(command, args, { detached: true, stdio: "ignore" });
2097
+ // A missing opener (no xdg-open, for example) reports asynchronously.
2098
+ child.on("error", () => { if (!opts.quietOpenFailure)
2099
+ console.error(`Open this URL to authorize Topline MCP:\n${url}`); });
1843
2100
  child.unref();
1844
2101
  }
1845
2102
  catch {
1846
- console.error(`Open this URL to authorize Topline MCP:\n${url}`);
2103
+ if (!opts.quietOpenFailure)
2104
+ console.error(`Open this URL to authorize Topline MCP:\n${url}`);
1847
2105
  }
1848
2106
  }
1849
2107
  export function browserOpenCommand(url, platform = process.platform) {
@@ -1864,6 +2122,13 @@ function platformBaseUrl(opts) {
1864
2122
  function mcpSurface(opts) {
1865
2123
  return opts.surface ?? "build";
1866
2124
  }
2125
+ /** Build tools run on the Build server and on the combined Topline server. */
2126
+ function servesBuild(opts) {
2127
+ return mcpSurface(opts) !== "harness";
2128
+ }
2129
+ function hostedMcpUrl(opts) {
2130
+ return `${platformBaseUrl(opts)}/mcp/${mcpSurface(opts) === "topline" ? "topline" : "build"}`;
2131
+ }
1867
2132
  function logicalArtifactAppDir(workspaceAppDir, manifest) {
1868
2133
  if (workspaceAppDir === "." || workspaceAppDir.startsWith("artifact-apps/"))
1869
2134
  return workspaceAppDir;
@@ -2,7 +2,7 @@
2
2
  "schemaVersion": 1,
3
3
  "package": {
4
4
  "name": "@topline-build/harness-mcp",
5
- "version": "0.7.0",
5
+ "version": "0.9.0",
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.7.0"
15
+ "version": "0.9.0"
16
16
  }
17
17
  },
18
18
  "generatedFrom": {
@@ -65,9 +65,10 @@
65
65
  "default": "build",
66
66
  "allowed": [
67
67
  "build",
68
+ "topline",
68
69
  "harness"
69
70
  ],
70
- "description": "Build is the current surface; harness preserves legacy OAuth compatibility."
71
+ "description": "topline is one server for Build and Workspace tools; build serves Build tools only; harness preserves legacy OAuth compatibility."
71
72
  },
72
73
  {
73
74
  "flag": "--protocol-version",
@@ -93,7 +94,7 @@
93
94
  "aliases": [
94
95
  "PLATFORM_MCP_SCOPES"
95
96
  ],
96
- "default": "harness:artifact:read harness:artifact:write harness:artifact:deploy harness:artifact:delete",
97
+ "default": "Build scopes; every Topline scope with --surface topline",
97
98
  "description": "Space- or comma-separated OAuth scopes."
98
99
  },
99
100
  {
@@ -385,13 +386,18 @@
385
386
  "code": "artifact_app_scaffold_target_not_empty",
386
387
  "retryable": false,
387
388
  "recoveryAction": "Choose an empty appDir or deploy the existing app without scaffolding."
389
+ },
390
+ {
391
+ "code": "artifact_app_scaffold_shape_invalid",
392
+ "retryable": false,
393
+ "recoveryAction": "Use shape single or web-and-api."
388
394
  }
389
395
  ]
390
396
  },
391
397
  "tools": [
392
398
  {
393
399
  "name": "platform_connection_check",
394
- "description": "Complete the one-time Developer Access verification challenge for this Build MCP client.",
400
+ "description": "Tell Topline Developer Access that this signed-in client works. Run it with no arguments right after signing in. Pass verificationCode only when Developer Access shows one for a manual check.",
395
401
  "annotations": {
396
402
  "title": "Platform Connection Check",
397
403
  "readOnlyHint": false,
@@ -407,9 +413,6 @@
407
413
  "maxLength": 80
408
414
  }
409
415
  },
410
- "required": [
411
- "verificationCode"
412
- ],
413
416
  "additionalProperties": false
414
417
  },
415
418
  "outputSchema": {
@@ -427,7 +430,8 @@
427
430
  "product": {
428
431
  "type": "string",
429
432
  "enum": [
430
- "build"
433
+ "build",
434
+ "topline"
431
435
  ]
432
436
  },
433
437
  "verifiedAt": {
@@ -482,9 +486,7 @@
482
486
  },
483
487
  "examples": [
484
488
  {
485
- "request": {
486
- "verificationCode": "example-verification-code"
487
- },
489
+ "request": {},
488
490
  "success": {
489
491
  "ok": true,
490
492
  "verified": true,
@@ -515,6 +517,14 @@
515
517
  },
516
518
  "title": {
517
519
  "type": "string"
520
+ },
521
+ "shape": {
522
+ "type": "string",
523
+ "enum": [
524
+ "single",
525
+ "web-and-api"
526
+ ],
527
+ "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."
518
528
  }
519
529
  },
520
530
  "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.7.0`
5
+ Package: `@topline-build/harness-mcp@0.9.0`
6
6
  Transport: `stdio`
7
7
  Default protocol: `2025-11-25`
8
8
  Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -21,10 +21,10 @@ The first authenticated tool call normally opens browser approval. Set `TOPLINE_
21
21
  | --- | --- | --- | --- |
22
22
  | `--url` | `TOPLINE_API_URL`, `PLATFORM_API_URL`, `OVERSITE_API_URL` | required | Topline tenant base URL. HTTPS is required except for loopback development. |
23
23
  | `--workspace-root` | `TOPLINE_WORKSPACE_ROOT`, `PLATFORM_WORKSPACE_ROOT` | `current working directory` | Local root that contains artifact app directories. |
24
- | `--surface` | `TOPLINE_MCP_SURFACE` | `build` | Build is the current surface; harness preserves legacy OAuth compatibility. |
24
+ | `--surface` | `TOPLINE_MCP_SURFACE` | `build` | topline is one server for Build and Workspace tools; build serves Build tools only; harness preserves legacy OAuth compatibility. |
25
25
  | `--protocol-version` | `TOPLINE_MCP_PROTOCOL_VERSION`, `PLATFORM_MCP_PROTOCOL_VERSION` | `2025-11-25` | MCP protocol version sent to Topline HTTP endpoints. |
26
26
  | `--auth-file` | `TOPLINE_MCP_AUTH_FILE`, `PLATFORM_MCP_AUTH_FILE` | `per-tenant file in the local Topline config directory` | OAuth credential cache. Keep it outside artifact app directories. |
27
- | `--scopes` | `TOPLINE_MCP_SCOPES`, `PLATFORM_MCP_SCOPES` | `harness:artifact:read harness:artifact:write harness:artifact:deploy harness:artifact:delete` | Space- or comma-separated OAuth scopes. |
27
+ | `--scopes` | `TOPLINE_MCP_SCOPES`, `PLATFORM_MCP_SCOPES` | `Build scopes; every Topline scope with --surface topline` | Space- or comma-separated OAuth scopes. |
28
28
  | `--timeout-ms` | `TOPLINE_MCP_TIMEOUT_MS`, `PLATFORM_MCP_TIMEOUT_MS`, `OVERSITE_MCP_TIMEOUT_MS` | `120000` | Positive request timeout in milliseconds. |
29
29
  | `--token` | `TOPLINE_MCP_TOKEN`, `PLATFORM_MCP_TOKEN`, `OVERSITE_MCP_TOKEN` | `optional` | Advanced manual bearer-token fallback. Prefer browser-approved OAuth. |
30
30
 
@@ -75,21 +75,20 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
75
75
  - `artifact_app_manifest_not_found` (not automatically retryable): Create artifact-app.json inside appDir, or correct appDir, then inspect again.
76
76
  - `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
77
  - `artifact_app_scaffold_target_not_empty` (not automatically retryable): Choose an empty appDir or deploy the existing app without scaffolding.
78
+ - `artifact_app_scaffold_shape_invalid` (not automatically retryable): Use shape single or web-and-api.
78
79
 
79
80
  ## Tools
80
81
 
81
82
  ### `platform_connection_check`
82
83
 
83
- Complete the one-time Developer Access verification challenge for this Build MCP client.
84
+ Tell Topline Developer Access that this signed-in client works. Run it with no arguments right after signing in. Pass verificationCode only when Developer Access shows one for a manual check.
84
85
 
85
86
  Safety: read-only=false, destructive=false, idempotent=false, open-world=true.
86
87
 
87
88
  Example request:
88
89
 
89
90
  ```json
90
- {
91
- "verificationCode": "example-verification-code"
92
- }
91
+ {}
93
92
  ```
94
93
 
95
94
  Example success:
@@ -115,9 +114,6 @@ Input schema:
115
114
  "maxLength": 80
116
115
  }
117
116
  },
118
- "required": [
119
- "verificationCode"
120
- ],
121
117
  "additionalProperties": false
122
118
  }
123
119
  ```
@@ -140,7 +136,8 @@ Output schema:
140
136
  "product": {
141
137
  "type": "string",
142
138
  "enum": [
143
- "build"
139
+ "build",
140
+ "topline"
144
141
  ]
145
142
  },
146
143
  "verifiedAt": {
@@ -237,6 +234,14 @@ Input schema:
237
234
  },
238
235
  "title": {
239
236
  "type": "string"
237
+ },
238
+ "shape": {
239
+ "type": "string",
240
+ "enum": [
241
+ "single",
242
+ "web-and-api"
243
+ ],
244
+ "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."
240
245
  }
241
246
  },
242
247
  "required": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topline-build/harness-mcp",
3
- "version": "0.7.0",
3
+ "version": "0.9.0",
4
4
  "description": "Topline Build MCP for creating and deploying artifact app drafts.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",