@topline-build/harness-mcp 0.9.8 → 0.9.10
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 +13 -0
- package/dist/artifact-starters.d.ts +10 -0
- package/dist/artifact-starters.js +35 -10
- package/dist/build-session-tools.js +4 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.js +12 -9
- package/docs/generated/build-mcp-manifest.json +27 -5
- package/docs/generated/build-mcp-reference.md +22 -4
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
All notable customer-visible Build MCP changes are recorded here. A source change is not a published package or customer release.
|
|
4
4
|
|
|
5
|
+
## 0.9.10 - 2026-11-08
|
|
6
|
+
|
|
7
|
+
- `platform_run_artifact_workspace_sql` takes `scope: "company"` to create and change company tables, matching the server. The Topline sign-in now asks for `harness:company:tables:write`, so your next launch asks you to approve it once.
|
|
8
|
+
- `platform_artifact_validation_status` accepts the optional `artifactVersionId` and `idempotencyKey` the server already takes.
|
|
9
|
+
- `artifact_version_conflict`'s recovery says that a build session always starts from the current version, and how to go back to older source.
|
|
10
|
+
- The viewer-scoped portal starter says it will filter rows once a dataset is connected, instead of saying it already does.
|
|
11
|
+
|
|
12
|
+
## 0.9.9 - 2026-11-02
|
|
13
|
+
|
|
14
|
+
- Dashboard starters from `platform_init_artifact_app` no longer declare their `/_artifact/data/*` route as an app route or call it from the page. The platform serves those paths itself, and only once a dataset or source binding declares them, so the placeholder answered 404 and a fresh deploy's smoke check failed. The page now shows each data route as not connected until it is declared.
|
|
15
|
+
- A session deploy missing integrity arguments names them (`build_session_deployment_arguments_required:expectedBundleSha256`) and gets its own recovery. `expectedBundleSha256`'s description says it is required with `sessionId`.
|
|
16
|
+
- `artifact_version_conflict`'s recovery separates a refused deploy (inspect and deploy again) from a refused validation request (don't deploy again: wait for the current deploy, run checks and smoke, prepare, then request validation).
|
|
17
|
+
|
|
5
18
|
## 0.9.8 - 2026-11-02
|
|
6
19
|
|
|
7
20
|
- `platform_record_acceptance_review`'s description and the `manual_result_requires_reviewer_skip` recovery no longer mention `evidence.reviewerCheck`, which the tool doesn't take. A passed review needs a check whose latest result the runner recorded as a skipped reviewer check.
|
|
@@ -7,6 +7,11 @@
|
|
|
7
7
|
* The scaffold is dependency-free Node and serves placeholder answers only:
|
|
8
8
|
* it never declares datasets, source bindings, secret bindings or Bedrock env,
|
|
9
9
|
* because those need the customer's own tables, sources and approved secrets.
|
|
10
|
+
* The platform itself serves /_artifact/data/* and /_artifact/knowledge/*, and
|
|
11
|
+
* only for a declared dataset, binding or grant, so app code never sees those
|
|
12
|
+
* requests. A starter's data route is therefore not a manifest route or a
|
|
13
|
+
* handler: the page shows it as not connected and never fetches it, so a
|
|
14
|
+
* fresh deploy's smoke check stays healthy instead of failing on a 404.
|
|
10
15
|
* Its structured tests are labelled scaffold checks, not proof of behavior.
|
|
11
16
|
*/
|
|
12
17
|
export type ArtifactStarterRoute = {
|
|
@@ -24,6 +29,11 @@ export type ArtifactStarter = {
|
|
|
24
29
|
};
|
|
25
30
|
export declare const ARTIFACT_STARTERS: ArtifactStarter[];
|
|
26
31
|
export declare const ARTIFACT_STARTER_IDS: string[];
|
|
32
|
+
/** Paths the platform serves itself once a dataset, source binding or knowledge grant declares them. */
|
|
33
|
+
export declare const PLATFORM_SERVED_ROUTE_PREFIXES: readonly ["/_artifact/data/", "/_artifact/knowledge/"];
|
|
34
|
+
export declare function isPlatformServedRoute(routePath: string): boolean;
|
|
35
|
+
/** The routes app code serves, which the manifest declares and the handler answers. */
|
|
36
|
+
export declare function artifactStarterAppRoutes(starter: ArtifactStarter): ArtifactStarterRoute[];
|
|
27
37
|
export declare function findArtifactStarter(id: string): ArtifactStarter | undefined;
|
|
28
38
|
export declare function artifactStarterRecipe(starter: ArtifactStarter): {
|
|
29
39
|
example: string;
|
|
@@ -7,6 +7,11 @@
|
|
|
7
7
|
* The scaffold is dependency-free Node and serves placeholder answers only:
|
|
8
8
|
* it never declares datasets, source bindings, secret bindings or Bedrock env,
|
|
9
9
|
* because those need the customer's own tables, sources and approved secrets.
|
|
10
|
+
* The platform itself serves /_artifact/data/* and /_artifact/knowledge/*, and
|
|
11
|
+
* only for a declared dataset, binding or grant, so app code never sees those
|
|
12
|
+
* requests. A starter's data route is therefore not a manifest route or a
|
|
13
|
+
* handler: the page shows it as not connected and never fetches it, so a
|
|
14
|
+
* fresh deploy's smoke check stays healthy instead of failing on a 404.
|
|
10
15
|
* Its structured tests are labelled scaffold checks, not proof of behavior.
|
|
11
16
|
*/
|
|
12
17
|
export const ARTIFACT_STARTERS = [
|
|
@@ -31,7 +36,7 @@ export const ARTIFACT_STARTERS = [
|
|
|
31
36
|
routes: [{ path: "/_artifact/data/branch-service-summary", note: "Placeholder for the recipe's live dataset." }],
|
|
32
37
|
nextSteps: [
|
|
33
38
|
"Find your own tables with the Workspace data catalog, then add the recipe's datasets[] and refreshSchedules[] with your SQL.",
|
|
34
|
-
"
|
|
39
|
+
"Once the dataset serves the route, fetch it from the page in place of the not-connected notice and replace its scaffold check."
|
|
35
40
|
]
|
|
36
41
|
},
|
|
37
42
|
{
|
|
@@ -54,7 +59,7 @@ export const ARTIFACT_STARTERS = [
|
|
|
54
59
|
],
|
|
55
60
|
nextSteps: [
|
|
56
61
|
"Find your own tables with the Workspace data catalog, then add the recipe's two datasets[] with your SQL.",
|
|
57
|
-
"
|
|
62
|
+
"Once the datasets serve the routes, fetch them from the page in place of the not-connected notices and replace their scaffold checks."
|
|
58
63
|
]
|
|
59
64
|
},
|
|
60
65
|
{
|
|
@@ -64,7 +69,7 @@ export const ARTIFACT_STARTERS = [
|
|
|
64
69
|
routes: [{ path: "/_artifact/data/service-health", note: "Placeholder for the materialized relation's dataset." }],
|
|
65
70
|
nextSteps: [
|
|
66
71
|
"Point a datasets[] entry at the existing materialized relation; the app never creates or refreshes it.",
|
|
67
|
-
"
|
|
72
|
+
"Once the dataset serves the route, fetch it from the page in place of the not-connected notice and replace its scaffold check."
|
|
68
73
|
]
|
|
69
74
|
},
|
|
70
75
|
{
|
|
@@ -74,7 +79,7 @@ export const ARTIFACT_STARTERS = [
|
|
|
74
79
|
routes: [{ path: "/_artifact/data/service-performance-report", note: "Placeholder for the precomputed report (windowDays 30 or 90)." }],
|
|
75
80
|
nextSteps: [
|
|
76
81
|
"Add the recipe's precomputed datasets[] entry (paramsSchema, warmParams) and its refresh schedule with your SQL.",
|
|
77
|
-
"
|
|
82
|
+
"Once the dataset serves the route, fetch it from the page in place of the not-connected notice and replace its scaffold check."
|
|
78
83
|
]
|
|
79
84
|
},
|
|
80
85
|
{
|
|
@@ -91,15 +96,26 @@ export const ARTIFACT_STARTERS = [
|
|
|
91
96
|
{
|
|
92
97
|
id: "viewer-scoped-customer-portal",
|
|
93
98
|
kind: "dashboard",
|
|
94
|
-
summary: "Read-only portal
|
|
99
|
+
summary: "Read-only portal starter: once you connect a dataset, each viewer will see only their own rows. Until then it shows no customer data.",
|
|
95
100
|
routes: [{ path: "/_artifact/data/customers", note: "Placeholder for the viewer-scoped source binding." }],
|
|
96
101
|
nextSteps: [
|
|
97
102
|
"Add the recipe's viewer-scoped sourceBindings[] entry for a source you already have, then switch viewerPolicy to tenant.",
|
|
98
|
-
"Keep viewerPolicy private until the binding filters every row to the signed-in viewer."
|
|
103
|
+
"Keep viewerPolicy private until the binding filters every row to the signed-in viewer.",
|
|
104
|
+
"Once the binding serves /_artifact/data/customers, fetch it from the page in place of the not-connected notice and replace its scaffold check."
|
|
99
105
|
]
|
|
100
106
|
}
|
|
101
107
|
];
|
|
102
108
|
export const ARTIFACT_STARTER_IDS = ARTIFACT_STARTERS.map((starter) => starter.id);
|
|
109
|
+
/** Paths the platform serves itself once a dataset, source binding or knowledge grant declares them. */
|
|
110
|
+
export const PLATFORM_SERVED_ROUTE_PREFIXES = ["/_artifact/data/", "/_artifact/knowledge/"];
|
|
111
|
+
export function isPlatformServedRoute(routePath) {
|
|
112
|
+
return PLATFORM_SERVED_ROUTE_PREFIXES.some((prefix) => routePath.startsWith(prefix));
|
|
113
|
+
}
|
|
114
|
+
/** The routes app code serves, which the manifest declares and the handler answers. */
|
|
115
|
+
export function artifactStarterAppRoutes(starter) {
|
|
116
|
+
return starter.routes.filter((route) => !isPlatformServedRoute(route.path));
|
|
117
|
+
}
|
|
118
|
+
const NOT_CONNECTED_TEXT = "Not connected yet. The platform serves this path once a datasets[] or sourceBindings[] entry declares it; until then the page does not call it.";
|
|
103
119
|
export function findArtifactStarter(id) {
|
|
104
120
|
return ARTIFACT_STARTERS.find((starter) => starter.id === id);
|
|
105
121
|
}
|
|
@@ -117,13 +133,21 @@ const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => ({ "&": "&
|
|
|
117
133
|
export function artifactStarterSource(starter, title) {
|
|
118
134
|
const safeTitle = escapeHtml(title);
|
|
119
135
|
const items = starter.routes
|
|
120
|
-
.map((route) =>
|
|
136
|
+
.map((route) => isPlatformServedRoute(route.path)
|
|
137
|
+
? `<li><code>${route.method ?? "GET"} ${escapeHtml(route.path)}</code> ${escapeHtml(route.note)} <span data-not-connected="${escapeHtml(route.path)}">${escapeHtml(NOT_CONNECTED_TEXT)}</span></li>`
|
|
138
|
+
: `<li><code>${route.method ?? "GET"} ${escapeHtml(route.path)}</code> ${escapeHtml(route.note)} <span data-route="${escapeHtml(route.path)}" data-method="${route.method ?? "GET"}">...</span></li>`)
|
|
121
139
|
.join("");
|
|
122
140
|
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>Starter from the <code>${starter.id}</code> recipe. ${escapeHtml(starter.summary)}</p><ul>${items}</ul></main><script type="module">for (const el of document.querySelectorAll("[data-route]")) { const method = el.dataset.method; fetch("." + el.dataset.route, { method, headers: { "content-type": "application/json" }, body: method === "POST" ? "{}" : undefined }).then((r) => el.textContent = "answers " + r.status).catch(() => el.textContent = "not reachable"); }</script></body></html>`;
|
|
123
|
-
const routes = starter.
|
|
141
|
+
const routes = artifactStarterAppRoutes(starter).map((route) => ({ path: route.path, method: route.method ?? "GET" }));
|
|
124
142
|
const tests = [
|
|
125
143
|
{ description: "Scaffold check: the page renders a visible app root.", required: true, status: "passed", summary: "Generated starter check; not proof of implemented behavior.", evidence: { selector: "data-platform-artifact-root", scaffold: true } },
|
|
126
|
-
...starter.routes.map((route) => ({
|
|
144
|
+
...starter.routes.map((route) => isPlatformServedRoute(route.path) ? ({
|
|
145
|
+
description: `Scaffold check: ${route.method ?? "GET"} ${route.path} is shown as not connected until its dataset or binding is declared.`,
|
|
146
|
+
required: false,
|
|
147
|
+
status: "passed",
|
|
148
|
+
summary: "Generated starter check; replace it with a check of the real data once the platform serves the route.",
|
|
149
|
+
evidence: { route: route.path, scaffold: true, platformServed: true }
|
|
150
|
+
}) : ({
|
|
127
151
|
description: `Scaffold check: ${route.method ?? "GET"} ${route.path} answers with a placeholder.`,
|
|
128
152
|
required: false,
|
|
129
153
|
status: "passed",
|
|
@@ -135,7 +159,8 @@ export function artifactStarterSource(starter, title) {
|
|
|
135
159
|
import path from "node:path";
|
|
136
160
|
|
|
137
161
|
// Starter from the Build cookbook recipe "${starter.id}". Every route below
|
|
138
|
-
// returns a placeholder; follow the recipe to make each one real.
|
|
162
|
+
// returns a placeholder; follow the recipe to make each one real. Data routes
|
|
163
|
+
// (/_artifact/data/*) are served by the platform once declared, never here.
|
|
139
164
|
const page = ${JSON.stringify(page)};
|
|
140
165
|
const routes = ${JSON.stringify(routes)};
|
|
141
166
|
|
|
@@ -19,8 +19,9 @@ export function externalBuildHelperTools(annotate) {
|
|
|
19
19
|
}, ["idempotencyKey", "budgetCents", "brief"]),
|
|
20
20
|
tool("platform_read_build_session", "Read the owned build session and original pending operations. Does not start another coder or deployment.", session, ["sessionId"], true),
|
|
21
21
|
tool("platform_close_build_session", "Stop new authoring and request pending-operation cancellation. Unknown effects retain their reservation; cancellation does not undo committed writes.", session, ["sessionId"]),
|
|
22
|
-
tool("platform_run_artifact_workspace_sql", "Run guarded
|
|
23
|
-
...mutation,
|
|
22
|
+
tool("platform_run_artifact_workspace_sql", "Run guarded SQL using the exact session, version and retry key. Without scope, or scope \"artifact\", it reads and writes this app's own build-checkpoint and cache tables. With scope \"company\", it creates, changes or drops a company table in company_data, or changes its rows, at once with no confirmation step; check the catalog before creating one, and declare tables an app uses in manifest tables[]. The company scope needs the harness:company:tables:write permission on your sign-in and the build session. CREATE TABLE/ADD COLUMN require documentation (company tables: a description and sensitivity for every column). Enforced non-admin writes remain denied; unknown writes are never replayed.", {
|
|
23
|
+
...mutation, scope: { type: "string", enum: ["artifact", "company"] },
|
|
24
|
+
sql: { type: "string", minLength: 1, maxLength: 20000 }, purpose: { type: "string", minLength: 3, maxLength: 500 },
|
|
24
25
|
params: { type: "object", additionalProperties: true }, maxRows: { type: "integer", minimum: 1, maximum: 5000 }, documentation: { type: "object" }, columnDocumentation: { type: "object" }
|
|
25
26
|
}, [...Object.keys(mutation), "sql", "purpose"]),
|
|
26
27
|
tool("platform_checkout_artifact_app", "Download exact saved app source through the owned session, verify archive hash/version/commit and extract regular source files into a new local directory. Missing source is never reconstructed.", {
|
|
@@ -48,7 +49,7 @@ export function externalBuildHelperTools(annotate) {
|
|
|
48
49
|
docImpactNotes: { type: "string", minLength: 12, maxLength: 2000 }, visualReview: { type: "object", additionalProperties: true }, dataValidation: { type: "object", additionalProperties: true }
|
|
49
50
|
}, [...Object.keys(deployed), "summary", "docImpact", "docImpactNotes", "visualReview"]),
|
|
50
51
|
tool("platform_artifact_validation_status", "Read the original validation result and pending prompts without starting another reviewer or deploy. Current authorization is rechecked before evidence delivery.", {
|
|
51
|
-
...session, operationId: id
|
|
52
|
+
...session, operationId: id, artifactVersionId: id, idempotencyKey: requestKey
|
|
52
53
|
}, ["sessionId", "operationId"], true),
|
|
53
54
|
tool("platform_answer_operator_prompt", "Answer the exact saved operator prompt on the original review operation. Appends guidance and reopens the same eligible session; cannot approve validation or widen the saved grant.", {
|
|
54
55
|
...session, operationId: id, promptId: id, idempotencyKey: requestKey, message: { type: "string", minLength: 3, maxLength: 4000 }
|
package/dist/index.d.ts
CHANGED
|
@@ -42,7 +42,7 @@ type ToolProgressReporter = (progress: number, message: string) => void | Promis
|
|
|
42
42
|
export type McpSurface = "build" | "topline" | "harness";
|
|
43
43
|
export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
44
44
|
export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
|
|
45
|
-
export declare const HARNESS_MCP_VERSION = "0.9.
|
|
45
|
+
export declare const HARNESS_MCP_VERSION = "0.9.10";
|
|
46
46
|
export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
|
|
47
47
|
/** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
|
|
48
48
|
export declare const TOPLINE_OAUTH_SCOPES: readonly string[];
|
package/dist/index.js
CHANGED
|
@@ -9,7 +9,7 @@ import path from "node:path";
|
|
|
9
9
|
import { gzipSync } from "node:zlib";
|
|
10
10
|
import { externalBuildHelperTools, EXTERNAL_BUILD_FORWARD_TOOLS, EXTERNAL_BUILD_SESSION_FORWARD_TOOLS, EXTERNAL_BUILD_SESSION_TOOLS } from "./build-session-tools.js";
|
|
11
11
|
import { domainHelperTools, DOMAIN_FORWARD_TOOLS, DOMAIN_ERROR_CODES } from "./domain-tools.js";
|
|
12
|
-
import { ARTIFACT_STARTER_IDS, artifactStarterRecipe, artifactStarterSource, findArtifactStarter } from "./artifact-starters.js";
|
|
12
|
+
import { ARTIFACT_STARTER_IDS, artifactStarterAppRoutes, artifactStarterRecipe, artifactStarterSource, findArtifactStarter } from "./artifact-starters.js";
|
|
13
13
|
import { boundedTransfer, extractArtifactSourceArchive, MAX_SOURCE_ARCHIVE_BYTES, safeSourcePath } from "./source-checkout.js";
|
|
14
14
|
import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
|
|
15
15
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
@@ -19,12 +19,12 @@ const MCP_SURFACES = ["build", "topline", "harness"];
|
|
|
19
19
|
export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
20
20
|
const DEFAULT_TIMEOUT_MS = 120_000;
|
|
21
21
|
export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
|
|
22
|
-
export const HARNESS_MCP_VERSION = "0.9.
|
|
22
|
+
export const HARNESS_MCP_VERSION = "0.9.10";
|
|
23
23
|
export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
|
|
24
24
|
/** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
|
|
25
25
|
export const TOPLINE_OAUTH_SCOPES = Object.freeze([
|
|
26
26
|
"harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete",
|
|
27
|
-
"harness:artifact:tables:write", "harness:artifact:validate", "harness:artifact:data:verify", "harness:assets:read",
|
|
27
|
+
"harness:artifact:tables:write", "harness:company:tables:write", "harness:artifact:validate", "harness:artifact:data:verify", "harness:assets:read",
|
|
28
28
|
"harness:secrets:metadata:read", "harness:domains:read", "harness:domains:manage", "harness:artifact:addresses:write",
|
|
29
29
|
"storyboard:read", "storyboard:write",
|
|
30
30
|
"docs:read", "chat:read", "chat:write", "workspace:write", "workspace:delete", "workspace:content:read",
|
|
@@ -947,8 +947,10 @@ export async function deployArtifactApp(opts, input, onProgress) {
|
|
|
947
947
|
if (sessionId) {
|
|
948
948
|
if (!servesBuild(opts))
|
|
949
949
|
throw new Error("external_session_requires_build_surface");
|
|
950
|
-
|
|
951
|
-
|
|
950
|
+
const missing = [["artifactVersionId", sessionVersion], ["idempotencyKey", idempotencyKey], ["inspectedSourceHash", inspectedSourceHash], ["expectedBundleSha256", expectedBundleSha256]]
|
|
951
|
+
.filter(([, value]) => !value).map(([name]) => name);
|
|
952
|
+
if (missing.length)
|
|
953
|
+
throw new Error(`build_session_deployment_arguments_required:${missing.join(",")}`);
|
|
952
954
|
const session = asRecord(await callHostedBuildTool(opts, "platform_read_build_session", { sessionId }));
|
|
953
955
|
// The server resolves a repeated operation key before checking current
|
|
954
956
|
// version/source. Do not reject a lost-response retry using the newer read.
|
|
@@ -1388,7 +1390,7 @@ export async function initArtifactApp(opts, input) {
|
|
|
1388
1390
|
build: { command: "node src/index.js --build", outputDir: "dist" },
|
|
1389
1391
|
validation: { localCommand: "node src/index.js --test", testCommand: "node src/index.js --test --artifact-tests-json" },
|
|
1390
1392
|
routes: starter
|
|
1391
|
-
? [{ path: "/", kind: "page", handler: "artifactApp" }, ...starter.
|
|
1393
|
+
? [{ path: "/", kind: "page", handler: "artifactApp" }, ...artifactStarterAppRoutes(starter).map((route) => ({ path: route.path, kind: "api", handler: "artifactApp" }))]
|
|
1392
1394
|
: [
|
|
1393
1395
|
{ path: "/", kind: "page", handler: "artifactApp" },
|
|
1394
1396
|
{ path: "/_artifact/health", kind: "api", handler: "artifactApp" }
|
|
@@ -1413,7 +1415,7 @@ export async function initArtifactApp(opts, input) {
|
|
|
1413
1415
|
files: ["artifact-app.json", "package.json", "src/index.js"],
|
|
1414
1416
|
...(starter ? { starter: starter.id, recipe: artifactStarterRecipe(starter) } : {}),
|
|
1415
1417
|
nextAction: starter
|
|
1416
|
-
? `Read the ${starter.id} recipe (docs id build-cookbook-example-${starter.id}) and replace
|
|
1418
|
+
? `Read the ${starter.id} recipe (docs id build-cookbook-example-${starter.id}) and replace the placeholder content with the real behavior (platform-served /_artifact/data/* routes are declared in the manifest, not handled in app code). Its tests are scaffold checks, not proof of behavior. Then run npm test in ${appDir} and call platform_inspect_artifact_app with the same appDir before deployment.`
|
|
1417
1419
|
: `Run npm test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
|
|
1418
1420
|
};
|
|
1419
1421
|
}
|
|
@@ -1926,7 +1928,7 @@ const BUILD_MCP_TOOLS = [
|
|
|
1926
1928
|
title: { type: "string" },
|
|
1927
1929
|
description: { type: "string" },
|
|
1928
1930
|
projectId: { type: "string", format: "uuid" },
|
|
1929
|
-
expectedBundleSha256: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "
|
|
1931
|
+
expectedBundleSha256: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "SHA-256 of the bundle from platform_inspect_artifact_app. Required with sessionId, optional otherwise; deployment fails locally if source changed after inspection." },
|
|
1930
1932
|
requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." },
|
|
1931
1933
|
sessionId: { type: "string", format: "uuid" },
|
|
1932
1934
|
artifactVersionId: { type: "string", format: "uuid", description: "Exact current version from the session or checkout; required with sessionId." },
|
|
@@ -2374,7 +2376,8 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
|
|
|
2374
2376
|
artifact_app_scaffold_starter_invalid: { retryable: false, recoveryAction: `Use one of the starters: ${ARTIFACT_STARTER_IDS.join(", ")}.` },
|
|
2375
2377
|
artifact_app_scaffold_starter_shape_conflict: { retryable: false, recoveryAction: "A starter scaffolds the single shape; leave shape out or set it to single." },
|
|
2376
2378
|
// Stale preconditions: the same input can never succeed, whatever HTTP status an older Topline sends.
|
|
2377
|
-
artifact_version_conflict: { retryable: false, recoveryAction: "The session moved to a newer version. Read the session (platform_read_build_session), keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash." },
|
|
2379
|
+
artifact_version_conflict: { retryable: false, recoveryAction: "The session moved to a newer version. Read the session (platform_read_build_session). A build session always starts from the app's current version; Build MCP can't check out an older saved version, so to go back, deploy source you saved before (or ask the coding agent in Topline to go back to version N). For a refused deploy: keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash. For a refused validation request: don't deploy again. Wait for the current version's deploy to settle (platform_deploy_operation), run its checks and smoke, prepare it with platform_prepare_artifact_validation, then call platform_request_artifact_validation with that prepared evidence." },
|
|
2380
|
+
build_session_deployment_arguments_required: { retryable: false, recoveryAction: "Inside a build session a deploy needs artifactVersionId, idempotencyKey, and the inspectedSourceHash and expectedBundleSha256 that platform_inspect_artifact_app returned. The fields named after the code are missing; add them and call again." },
|
|
2378
2381
|
artifact_source_conflict: { retryable: false, recoveryAction: "inspectedSourceHash no longer matches the session's source fence. Read the session for its current sourceHash (or check out again into a new directory), keep your local edits, inspect again, then deploy with the fresh hash." },
|
|
2379
2382
|
artifact_operation_pending: { retryable: false, recoveryAction: "Another operation on this app has not settled. Read it with platform_deploy_operation (a deploy that already landed settles on that read), or platform_read_build_session, then call this tool again once it is terminal." },
|
|
2380
2383
|
artifact_deploy_in_flight: { retryable: true, recoveryAction: "A deploy for this app is still running. Wait until platform_deploy_operation says it is terminal, then retry the call that was refused (checkout, delete or deploy)." },
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"package": {
|
|
4
4
|
"name": "@topline-build/harness-mcp",
|
|
5
|
-
"version": "0.9.
|
|
5
|
+
"version": "0.9.10",
|
|
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.9.
|
|
15
|
+
"version": "0.9.10"
|
|
16
16
|
}
|
|
17
17
|
},
|
|
18
18
|
"generatedFrom": {
|
|
@@ -473,7 +473,12 @@
|
|
|
473
473
|
{
|
|
474
474
|
"code": "artifact_version_conflict",
|
|
475
475
|
"retryable": false,
|
|
476
|
-
"recoveryAction": "The session moved to a newer version. Read the session (platform_read_build_session), keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash."
|
|
476
|
+
"recoveryAction": "The session moved to a newer version. Read the session (platform_read_build_session). A build session always starts from the app's current version; Build MCP can't check out an older saved version, so to go back, deploy source you saved before (or ask the coding agent in Topline to go back to version N). For a refused deploy: keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash. For a refused validation request: don't deploy again. Wait for the current version's deploy to settle (platform_deploy_operation), run its checks and smoke, prepare it with platform_prepare_artifact_validation, then call platform_request_artifact_validation with that prepared evidence."
|
|
477
|
+
},
|
|
478
|
+
{
|
|
479
|
+
"code": "build_session_deployment_arguments_required",
|
|
480
|
+
"retryable": false,
|
|
481
|
+
"recoveryAction": "Inside a build session a deploy needs artifactVersionId, idempotencyKey, and the inspectedSourceHash and expectedBundleSha256 that platform_inspect_artifact_app returned. The fields named after the code are missing; add them and call again."
|
|
477
482
|
},
|
|
478
483
|
{
|
|
479
484
|
"code": "artifact_source_conflict",
|
|
@@ -909,7 +914,7 @@
|
|
|
909
914
|
"expectedBundleSha256": {
|
|
910
915
|
"type": "string",
|
|
911
916
|
"pattern": "^[0-9a-fA-F]{64}$",
|
|
912
|
-
"description": "
|
|
917
|
+
"description": "SHA-256 of the bundle from platform_inspect_artifact_app. Required with sessionId, optional otherwise; deployment fails locally if source changed after inspection."
|
|
913
918
|
},
|
|
914
919
|
"requestId": {
|
|
915
920
|
"type": "string",
|
|
@@ -3549,7 +3554,7 @@
|
|
|
3549
3554
|
},
|
|
3550
3555
|
{
|
|
3551
3556
|
"name": "platform_run_artifact_workspace_sql",
|
|
3552
|
-
"description": "Run guarded
|
|
3557
|
+
"description": "Run guarded SQL using the exact session, version and retry key. Without scope, or scope \"artifact\", it reads and writes this app's own build-checkpoint and cache tables. With scope \"company\", it creates, changes or drops a company table in company_data, or changes its rows, at once with no confirmation step; check the catalog before creating one, and declare tables an app uses in manifest tables[]. The company scope needs the harness:company:tables:write permission on your sign-in and the build session. CREATE TABLE/ADD COLUMN require documentation (company tables: a description and sensitivity for every column). Enforced non-admin writes remain denied; unknown writes are never replayed.",
|
|
3553
3558
|
"annotations": {
|
|
3554
3559
|
"title": "Platform Run Artifact Workspace Sql",
|
|
3555
3560
|
"readOnlyHint": false,
|
|
@@ -3575,6 +3580,13 @@
|
|
|
3575
3580
|
"maxLength": 128,
|
|
3576
3581
|
"pattern": "^[A-Za-z0-9._:-]+$"
|
|
3577
3582
|
},
|
|
3583
|
+
"scope": {
|
|
3584
|
+
"type": "string",
|
|
3585
|
+
"enum": [
|
|
3586
|
+
"artifact",
|
|
3587
|
+
"company"
|
|
3588
|
+
]
|
|
3589
|
+
},
|
|
3578
3590
|
"sql": {
|
|
3579
3591
|
"type": "string",
|
|
3580
3592
|
"minLength": 1,
|
|
@@ -4742,6 +4754,16 @@
|
|
|
4742
4754
|
"operationId": {
|
|
4743
4755
|
"type": "string",
|
|
4744
4756
|
"format": "uuid"
|
|
4757
|
+
},
|
|
4758
|
+
"artifactVersionId": {
|
|
4759
|
+
"type": "string",
|
|
4760
|
+
"format": "uuid"
|
|
4761
|
+
},
|
|
4762
|
+
"idempotencyKey": {
|
|
4763
|
+
"type": "string",
|
|
4764
|
+
"minLength": 1,
|
|
4765
|
+
"maxLength": 128,
|
|
4766
|
+
"pattern": "^[A-Za-z0-9._:-]+$"
|
|
4745
4767
|
}
|
|
4746
4768
|
},
|
|
4747
4769
|
"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.9.
|
|
5
|
+
Package: `@topline-build/harness-mcp@0.9.10`
|
|
6
6
|
Transport: `stdio`
|
|
7
7
|
Default protocol: `2025-11-25`
|
|
8
8
|
Canonical guide: https://topline.build/docs/build-mcp-guide
|
|
@@ -91,7 +91,8 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
|
|
|
91
91
|
- `artifact_app_scaffold_shape_invalid` (not automatically retryable): Use shape single or web-and-api.
|
|
92
92
|
- `artifact_app_scaffold_starter_invalid` (not automatically retryable): Use one of the starters: bounded-bedrock-assistant, cache-warmed-multi-source-dashboard, internal-action-tool, live-operations-dashboard, materialized-sql-data-product, precomputed-s3-report, private-api-first-app, viewer-scoped-customer-portal.
|
|
93
93
|
- `artifact_app_scaffold_starter_shape_conflict` (not automatically retryable): A starter scaffolds the single shape; leave shape out or set it to single.
|
|
94
|
-
- `artifact_version_conflict` (not automatically retryable): The session moved to a newer version. Read the session (platform_read_build_session), keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash.
|
|
94
|
+
- `artifact_version_conflict` (not automatically retryable): The session moved to a newer version. Read the session (platform_read_build_session). A build session always starts from the app's current version; Build MCP can't check out an older saved version, so to go back, deploy source you saved before (or ask the coding agent in Topline to go back to version N). For a refused deploy: keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash. For a refused validation request: don't deploy again. Wait for the current version's deploy to settle (platform_deploy_operation), run its checks and smoke, prepare it with platform_prepare_artifact_validation, then call platform_request_artifact_validation with that prepared evidence.
|
|
95
|
+
- `build_session_deployment_arguments_required` (not automatically retryable): Inside a build session a deploy needs artifactVersionId, idempotencyKey, and the inspectedSourceHash and expectedBundleSha256 that platform_inspect_artifact_app returned. The fields named after the code are missing; add them and call again.
|
|
95
96
|
- `artifact_source_conflict` (not automatically retryable): inspectedSourceHash no longer matches the session's source fence. Read the session for its current sourceHash (or check out again into a new directory), keep your local edits, inspect again, then deploy with the fresh hash.
|
|
96
97
|
- `artifact_operation_pending` (not automatically retryable): Another operation on this app has not settled. Read it with platform_deploy_operation (a deploy that already landed settles on that read), or platform_read_build_session, then call this tool again once it is terminal.
|
|
97
98
|
- `artifact_deploy_in_flight` (retryable): A deploy for this app is still running. Wait until platform_deploy_operation says it is terminal, then retry the call that was refused (checkout, delete or deploy).
|
|
@@ -568,7 +569,7 @@ Input schema:
|
|
|
568
569
|
"expectedBundleSha256": {
|
|
569
570
|
"type": "string",
|
|
570
571
|
"pattern": "^[0-9a-fA-F]{64}$",
|
|
571
|
-
"description": "
|
|
572
|
+
"description": "SHA-256 of the bundle from platform_inspect_artifact_app. Required with sessionId, optional otherwise; deployment fails locally if source changed after inspection."
|
|
572
573
|
},
|
|
573
574
|
"requestId": {
|
|
574
575
|
"type": "string",
|
|
@@ -3457,7 +3458,7 @@ Output schema:
|
|
|
3457
3458
|
|
|
3458
3459
|
### `platform_run_artifact_workspace_sql`
|
|
3459
3460
|
|
|
3460
|
-
Run guarded
|
|
3461
|
+
Run guarded SQL using the exact session, version and retry key. Without scope, or scope "artifact", it reads and writes this app's own build-checkpoint and cache tables. With scope "company", it creates, changes or drops a company table in company_data, or changes its rows, at once with no confirmation step; check the catalog before creating one, and declare tables an app uses in manifest tables[]. The company scope needs the harness:company:tables:write permission on your sign-in and the build session. CREATE TABLE/ADD COLUMN require documentation (company tables: a description and sensitivity for every column). Enforced non-admin writes remain denied; unknown writes are never replayed.
|
|
3461
3462
|
|
|
3462
3463
|
Safety: read-only=false, destructive=false, idempotent=true, open-world=true.
|
|
3463
3464
|
|
|
@@ -3500,6 +3501,13 @@ Input schema:
|
|
|
3500
3501
|
"maxLength": 128,
|
|
3501
3502
|
"pattern": "^[A-Za-z0-9._:-]+$"
|
|
3502
3503
|
},
|
|
3504
|
+
"scope": {
|
|
3505
|
+
"type": "string",
|
|
3506
|
+
"enum": [
|
|
3507
|
+
"artifact",
|
|
3508
|
+
"company"
|
|
3509
|
+
]
|
|
3510
|
+
},
|
|
3503
3511
|
"sql": {
|
|
3504
3512
|
"type": "string",
|
|
3505
3513
|
"minLength": 1,
|
|
@@ -4785,6 +4793,16 @@ Input schema:
|
|
|
4785
4793
|
"operationId": {
|
|
4786
4794
|
"type": "string",
|
|
4787
4795
|
"format": "uuid"
|
|
4796
|
+
},
|
|
4797
|
+
"artifactVersionId": {
|
|
4798
|
+
"type": "string",
|
|
4799
|
+
"format": "uuid"
|
|
4800
|
+
},
|
|
4801
|
+
"idempotencyKey": {
|
|
4802
|
+
"type": "string",
|
|
4803
|
+
"minLength": 1,
|
|
4804
|
+
"maxLength": 128,
|
|
4805
|
+
"pattern": "^[A-Za-z0-9._:-]+$"
|
|
4788
4806
|
}
|
|
4789
4807
|
},
|
|
4790
4808
|
"required": [
|