@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 +14 -1
- package/README.md +10 -0
- package/dist/index.d.ts +31 -4
- package/dist/index.js +306 -41
- package/docs/generated/build-mcp-manifest.json +22 -12
- package/docs/generated/build-mcp-reference.md +16 -11
- package/package.json +1 -1
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
|
-
##
|
|
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
|
-
/**
|
|
6
|
-
|
|
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.
|
|
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
|
|
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.
|
|
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: "
|
|
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:
|
|
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
|
|
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
|
|
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)] : [...
|
|
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 (
|
|
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) },
|
|
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
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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 (
|
|
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 (
|
|
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 (
|
|
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 (
|
|
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 (
|
|
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 (
|
|
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,
|
|
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 (
|
|
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 (
|
|
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) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" }[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: "
|
|
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: {
|
|
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
|
|
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
|
-
|
|
1816
|
-
|
|
1817
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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.
|
|
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` |
|
|
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` | `
|
|
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
|
-
|
|
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": [
|