@topline-build/harness-mcp 0.9.13 → 0.9.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
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.14 - 2026-11-11
|
|
6
|
+
|
|
7
|
+
- `platform_wait_artifact_deploy` names the build's failure code (`artifact_deploy_failed:<code>`) instead of only `failed`, and its recovery says to read `platform_deploy_operation` for the build's own error instead of retrying the wait.
|
|
8
|
+
- `platform_inspect_artifact_app` runs the manifest and data-binding checks Topline's build would fail: every `datasets[]` entry needs a `name` and `route`, every `routes[]` entry a `path`, and each `./_artifact/data/<name>` the source fetches needs a matching dataset. `packageReady` is false and `problems` names each field or file until they are fixed.
|
|
9
|
+
- Descriptions match the server: with company tables on, workspace SQL without a scope runs against company tables; an approved review completes the build session (asking again returns `validation_already_completed`); `needs_fix` keeps it active; rendered smoke can report `passed_with_warnings`; and omitted `buildOk` / `typecheckOk` are read as not reported.
|
|
10
|
+
|
|
5
11
|
## 0.9.13 - 2026-11-10
|
|
6
12
|
|
|
7
13
|
- New `platform_read_logs`, for Topline staff only: bounded, redacted reads of the platform API and worker logs and of one-off task logs (connector syncs, one-off scripts, route optimization, link migrations, a coding task's runtime lines). It forwards to the hosted Build MCP, which checks operator access and audits every read.
|
|
@@ -19,7 +19,7 @@ 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 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.", {
|
|
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; when the build session's workspace.routing is company_tables there are no private tables and every statement runs against company tables, as with scope \"company\". A statement the database rejects returns sql_statement_failed:<SQLSTATE> (company tables: company_table_sql_failed:<SQLSTATE>) with a fixed hint. 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
23
|
...mutation, scope: { type: "string", enum: ["artifact", "company"] },
|
|
24
24
|
sql: { type: "string", minLength: 1, maxLength: 20000 }, purpose: { type: "string", minLength: 3, maxLength: 500 },
|
|
25
25
|
params: { type: "object", additionalProperties: true }, maxRows: { type: "integer", minimum: 1, maximum: 5000 }, documentation: { type: "object" }, columnDocumentation: { type: "object" }
|
|
@@ -38,14 +38,14 @@ export function externalBuildHelperTools(annotate) {
|
|
|
38
38
|
tool("platform_add_acceptance_check", "Add a required acceptance check bound to this build session and deployed revision. A semantic control query requires separate Build data-verification consent.", {
|
|
39
39
|
...mutation, description: { type: "string", minLength: 3, maxLength: 1000 }
|
|
40
40
|
}, [...Object.keys(mutation), "description"]),
|
|
41
|
-
tool("platform_run_acceptance_checks", "Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version, which also gates validation.", mutation, Object.keys(mutation)),
|
|
41
|
+
tool("platform_run_acceptance_checks", "Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version (passed, passed_with_warnings with qualityWarnings codes, failed with failingChecks, or not_run), which also gates validation.", mutation, Object.keys(mutation)),
|
|
42
42
|
tool("platform_record_acceptance_review", "Record the builder's review of a reviewer-only acceptance check. A passed result is accepted only for a check whose latest result platform_run_acceptance_checks recorded as a skipped reviewer check for this version, so run the checks first. Does not impersonate the independent validator or remove required checks.", {
|
|
43
43
|
...mutation, checkId: id, status: { type: "string", enum: ["passed", "failed"] }, summary: { type: "string", minLength: 3, maxLength: 2000 }
|
|
44
44
|
}, [...Object.keys(mutation), "checkId", "status", "summary"]),
|
|
45
45
|
tool("platform_prepare_artifact_validation", "Prepare validation evidence for the exact private draft revision; missing required checks block readiness.", { ...session, artifactVersionId: id, deploymentRecordId: id, idempotencyKey: requestKey }, ["sessionId", "artifactVersionId", "deploymentRecordId"], true),
|
|
46
|
-
tool("platform_request_artifact_validation", "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish.", {
|
|
46
|
+
tool("platform_request_artifact_validation", "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish and completes this build session; asking again returns validation_already_completed. A needs_fix review keeps the session active: fix, deploy a new version, smoke, then request a review of that version. If the draft isn't ready, the refusal names the blocker platform_prepare_artifact_validation reports.", {
|
|
47
47
|
...deployed, summary: { type: "string", minLength: 3, maxLength: 4000 }, waitMs: { type: "integer", minimum: 0, maximum: 1000, description: "Milliseconds to wait for the review before returning, 0 to 1000." },
|
|
48
|
-
buildOk: { type: "boolean" }, typecheckOk: { type: "boolean" }, docImpact: { type: "string", enum: ["material", "none"] },
|
|
48
|
+
buildOk: { type: "boolean", description: "Your own local build result. Omit if you did not run one; the reviewer is told separately that Topline's trusted build deployed this version." }, typecheckOk: { type: "boolean", description: "Your own local typecheck result. Omit if you did not run one." }, docImpact: { type: "string", enum: ["material", "none"] },
|
|
49
49
|
docImpactNotes: { type: "string", minLength: 12, maxLength: 2000 }, visualReview: { type: "object", additionalProperties: true }, dataValidation: { type: "object", additionalProperties: true }
|
|
50
50
|
}, [...Object.keys(deployed), "summary", "docImpact", "docImpactNotes", "visualReview"]),
|
|
51
51
|
tool("platform_artifact_validation_status", "Read the original validation result and pending prompts without starting another reviewer or deploy. operationId selects the review; the result names the artifactVersionId it reviewed, and a supplied artifactVersionId that differs is refused (validation_operation_version_mismatch). Use the operationId this build session's request returned; another session's operation is refused (validation_operation_not_found). Current authorization is rechecked before evidence delivery.", {
|
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.14";
|
|
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[];
|
|
@@ -131,6 +131,11 @@ export declare function materializeBuildAssets(opts: HarnessMcpStdioOptions, inp
|
|
|
131
131
|
export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
|
|
132
132
|
ok: boolean;
|
|
133
133
|
packageReady: boolean;
|
|
134
|
+
problems: {
|
|
135
|
+
code: string;
|
|
136
|
+
path: string;
|
|
137
|
+
detail: string;
|
|
138
|
+
}[];
|
|
134
139
|
serverManifestValidationRequired: boolean;
|
|
135
140
|
appDir: string;
|
|
136
141
|
platformAppDir: string;
|
|
@@ -153,6 +158,16 @@ export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input:
|
|
|
153
158
|
};
|
|
154
159
|
nextAction: string;
|
|
155
160
|
}>;
|
|
161
|
+
/**
|
|
162
|
+
* Round 11 P4: the checks Topline's server and trusted build run that a local inspect can repeat
|
|
163
|
+
* cheaply, so packageReady isn't true for a package the deploy will refuse: dataset and route
|
|
164
|
+
* fields the manifest needs, and ./_artifact/data/<name> references with no matching dataset.
|
|
165
|
+
*/
|
|
166
|
+
export declare function localPreflightProblems(appDir: string, manifest: Record<string, unknown>): Promise<Array<{
|
|
167
|
+
code: string;
|
|
168
|
+
path: string;
|
|
169
|
+
detail: string;
|
|
170
|
+
}>>;
|
|
156
171
|
export declare function waitForArtifactDeploy(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<Record<string, unknown>>;
|
|
157
172
|
export declare function initArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
|
|
158
173
|
ok: boolean;
|
package/dist/index.js
CHANGED
|
@@ -19,7 +19,7 @@ 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.14";
|
|
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([
|
|
@@ -1153,9 +1153,11 @@ export async function inspectArtifactApp(opts, input) {
|
|
|
1153
1153
|
const suppliedPlatformAppDir = optionalString(input, "platformAppDir");
|
|
1154
1154
|
const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
|
|
1155
1155
|
const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
|
|
1156
|
+
const problems = await localPreflightProblems(absoluteAppDir, manifest);
|
|
1156
1157
|
return {
|
|
1157
1158
|
ok: true,
|
|
1158
|
-
packageReady:
|
|
1159
|
+
packageReady: problems.length === 0,
|
|
1160
|
+
problems,
|
|
1159
1161
|
serverManifestValidationRequired: true,
|
|
1160
1162
|
appDir: workspaceAppDir,
|
|
1161
1163
|
platformAppDir,
|
|
@@ -1178,9 +1180,69 @@ export async function inspectArtifactApp(opts, input) {
|
|
|
1178
1180
|
sha256: bundle.sha256,
|
|
1179
1181
|
excluded: bundle.excluded
|
|
1180
1182
|
},
|
|
1181
|
-
nextAction:
|
|
1183
|
+
nextAction: problems.length
|
|
1184
|
+
? `Fix the ${problems.length === 1 ? "problem" : "problems"} listed in problems (each names its field or file), then inspect again. Topline's build would refuse this package as it is.`
|
|
1185
|
+
: "Call platform_deploy_artifact_app with the same appDir and expectedBundleSha256 set to bundle.sha256 when this local package is ready to deploy."
|
|
1182
1186
|
};
|
|
1183
1187
|
}
|
|
1188
|
+
const PREFLIGHT_SCAN_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".html", ".json", ".py", ".txt"]);
|
|
1189
|
+
const PREFLIGHT_SKIP_DIRS = new Set(["node_modules", ".git", ".next", ".vite", ".turbo", ".cache"]);
|
|
1190
|
+
/**
|
|
1191
|
+
* Round 11 P4: the checks Topline's server and trusted build run that a local inspect can repeat
|
|
1192
|
+
* cheaply, so packageReady isn't true for a package the deploy will refuse: dataset and route
|
|
1193
|
+
* fields the manifest needs, and ./_artifact/data/<name> references with no matching dataset.
|
|
1194
|
+
*/
|
|
1195
|
+
export async function localPreflightProblems(appDir, manifest) {
|
|
1196
|
+
const problems = [];
|
|
1197
|
+
const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
|
|
1198
|
+
const datasets = Array.isArray(manifest.datasets) ? manifest.datasets : [];
|
|
1199
|
+
datasets.forEach((dataset, index) => {
|
|
1200
|
+
const record = isRecord(dataset) ? dataset : {};
|
|
1201
|
+
for (const key of ["name", "route"]) {
|
|
1202
|
+
if (!nonEmpty(record[key]))
|
|
1203
|
+
problems.push({ code: "invalid_artifact_app_manifest", path: `datasets[${index}].${key}`, detail: `datasets[${index}].${key} must be a non-empty string${key === "route" ? " (the page's path, for example /_artifact/data/<name>)" : ""}` });
|
|
1204
|
+
}
|
|
1205
|
+
});
|
|
1206
|
+
const routes = Array.isArray(manifest.routes) ? manifest.routes : [];
|
|
1207
|
+
routes.forEach((route, index) => {
|
|
1208
|
+
if (!isRecord(route) || !nonEmpty(route.path))
|
|
1209
|
+
problems.push({ code: "invalid_artifact_app_manifest", path: `routes[${index}].path`, detail: `routes[${index}].path must be a non-empty string` });
|
|
1210
|
+
});
|
|
1211
|
+
const declared = new Set([
|
|
1212
|
+
...datasets.filter(isRecord).map((dataset) => dataset.name),
|
|
1213
|
+
...(Array.isArray(manifest.sourceBindings) ? manifest.sourceBindings : []).filter(isRecord).map((binding) => binding.name)
|
|
1214
|
+
].filter((name) => typeof name === "string"));
|
|
1215
|
+
const reported = new Set();
|
|
1216
|
+
let scanned = 0;
|
|
1217
|
+
const visit = async (dir) => {
|
|
1218
|
+
for (const entry of await readdir(dir, { withFileTypes: true })) {
|
|
1219
|
+
if (scanned > 5_000)
|
|
1220
|
+
return;
|
|
1221
|
+
const full = path.join(dir, entry.name);
|
|
1222
|
+
if (entry.isDirectory()) {
|
|
1223
|
+
if (!PREFLIGHT_SKIP_DIRS.has(entry.name))
|
|
1224
|
+
await visit(full);
|
|
1225
|
+
continue;
|
|
1226
|
+
}
|
|
1227
|
+
if (!entry.isFile() || !PREFLIGHT_SCAN_EXTENSIONS.has(path.extname(entry.name)))
|
|
1228
|
+
continue;
|
|
1229
|
+
scanned += 1;
|
|
1230
|
+
const content = await readFile(full, "utf8").catch(() => "");
|
|
1231
|
+
if (content.length > 2_000_000)
|
|
1232
|
+
continue;
|
|
1233
|
+
for (const match of content.matchAll(/\.\/_artifact\/data\/([A-Za-z0-9_-]+)/g)) {
|
|
1234
|
+
const rel = path.relative(appDir, full).replaceAll("\\", "/");
|
|
1235
|
+
const key = `${rel}:${match[1]}`;
|
|
1236
|
+
if (declared.has(match[1]) || reported.has(key))
|
|
1237
|
+
continue;
|
|
1238
|
+
reported.add(key);
|
|
1239
|
+
problems.push({ code: "undeclared_artifact_data_binding", path: rel, detail: `${rel} fetches ./_artifact/data/${match[1]}, but no datasets[] entry is named ${match[1]}. Declare it (with its route) or remove the reference.` });
|
|
1240
|
+
}
|
|
1241
|
+
}
|
|
1242
|
+
};
|
|
1243
|
+
await visit(appDir);
|
|
1244
|
+
return problems.slice(0, 25);
|
|
1245
|
+
}
|
|
1184
1246
|
async function callHostedBuildTool(opts, name, input) {
|
|
1185
1247
|
if (!servesBuild(opts))
|
|
1186
1248
|
throw new Error(`${name}_requires_build_surface`);
|
|
@@ -1351,8 +1413,12 @@ export async function waitForArtifactDeploy(opts, input, onProgress) {
|
|
|
1351
1413
|
if (typeof latest.nextSeq === "number")
|
|
1352
1414
|
afterSeq = latest.nextSeq;
|
|
1353
1415
|
if (latest.terminal === true) {
|
|
1354
|
-
if (latest.successful !== true)
|
|
1355
|
-
|
|
1416
|
+
if (latest.successful !== true) {
|
|
1417
|
+
// Round 11 P3: name the build's failure code, not just the task status.
|
|
1418
|
+
const failure = isRecord(latest.failure) ? latest.failure : {};
|
|
1419
|
+
const code = typeof failure.code === "string" && /^[a-z][a-z0-9_]{2,80}$/.test(failure.code) ? failure.code : String(latest.taskStatus ?? "failed");
|
|
1420
|
+
throw new Error(`artifact_deploy_failed:${code}`);
|
|
1421
|
+
}
|
|
1356
1422
|
return latest;
|
|
1357
1423
|
}
|
|
1358
1424
|
const waitMs = typeof latest.nextPollAfterMs === "number" ? Math.min(Math.max(latest.nextPollAfterMs, 250), 10_000) : 2_000;
|
|
@@ -1959,7 +2025,7 @@ const BUILD_MCP_TOOLS = [
|
|
|
1959
2025
|
},
|
|
1960
2026
|
{
|
|
1961
2027
|
name: "platform_inspect_artifact_app",
|
|
1962
|
-
description: "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.",
|
|
2028
|
+
description: "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft. Also runs the manifest and data-binding checks Topline's build would fail (datasets[].name and route, routes[].path, ./_artifact/data/<name> references with no matching dataset); packageReady is false and problems lists each one until they are fixed.",
|
|
1963
2029
|
annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
|
|
1964
2030
|
inputSchema: {
|
|
1965
2031
|
type: "object",
|
|
@@ -1972,6 +2038,7 @@ const BUILD_MCP_TOOLS = [
|
|
|
1972
2038
|
properties: {
|
|
1973
2039
|
ok: { type: "boolean" },
|
|
1974
2040
|
packageReady: { type: "boolean" },
|
|
2041
|
+
problems: { type: "array", items: { type: "object" }, description: "Checks Topline's build would fail: each has code, path (manifest field or file) and detail. packageReady is false while any remain." },
|
|
1975
2042
|
serverManifestValidationRequired: { type: "boolean" },
|
|
1976
2043
|
appDir: { type: "string" },
|
|
1977
2044
|
platformAppDir: { type: "string" },
|
|
@@ -2005,7 +2072,7 @@ const BUILD_MCP_TOOLS = [
|
|
|
2005
2072
|
},
|
|
2006
2073
|
{
|
|
2007
2074
|
name: "platform_wait_artifact_deploy",
|
|
2008
|
-
description: "Wait for a durable deployment operation and stream server-derived progress.",
|
|
2075
|
+
description: "Wait for a durable deployment operation and stream server-derived progress. A failed deploy returns artifact_deploy_failed:<failure code>; read platform_deploy_operation for the build's own error (failure.detail) and next step. A successful deploy returns the session's next sourceHash for the following deploy.",
|
|
2009
2076
|
annotations: mcpToolAnnotations("platform_wait_artifact_deploy", { readOnly: true, openWorld: true }),
|
|
2010
2077
|
inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" }, operationId: { type: "string", format: "uuid" }, timeoutSeconds: { type: "integer", minimum: 1, maximum: 900 } }, required: ["artifactId", "operationId"], additionalProperties: false },
|
|
2011
2078
|
outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
|
|
@@ -2402,6 +2469,9 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
|
|
|
2402
2469
|
build_session_id_required: { retryable: false, recoveryAction: "The fields named after the code only work inside a build session. Remove them for a plain deploy of an app you created over MCP, or start a session and pass its sessionId." },
|
|
2403
2470
|
artifact_external_session_active: { retryable: false, recoveryAction: "An open build session holds this app. If it is yours, pass its sessionId; otherwise close it with platform_close_build_session or wait for it to end." },
|
|
2404
2471
|
artifact_deploy_wait_timeout: { retryable: true, recoveryAction: "Call platform_wait_artifact_deploy again with the same artifactId and operationId." },
|
|
2472
|
+
// Round 11 P3: the wait names the failure code; the detail (the build's own error) is on the operation.
|
|
2473
|
+
artifact_deploy_failed: { retryable: false, recoveryAction: "The deploy finished and failed; the code after artifact_deploy_failed names why. Call platform_deploy_operation with the same artifactId and operationId for failure.detail (the build's own error) and failure.nextAction. Fix the source, run platform_inspect_artifact_app, then deploy again. Retrying the wait or redeploying the same source fails the same way." },
|
|
2474
|
+
validation_already_completed: { retryable: false, recoveryAction: "A review already approved this version and completed the build session. Don't request another review or start a new session to repeat it; read the verdict with platform_artifact_validation_status. Publishing is the person's step in Topline." },
|
|
2405
2475
|
artifact_delete_plan_stale: { retryable: true, recoveryAction: "Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken." },
|
|
2406
2476
|
artifact_app_bundle_changed_after_inspection: { retryable: true, recoveryAction: "Call platform_inspect_artifact_app again, review the new bundle hash, then retry deployment with that hash." },
|
|
2407
2477
|
artifact_app_bundle_hardlink_forbidden: { retryable: false, recoveryAction: "Replace the hard link with a regular file copied into appDir, then inspect again." },
|
|
@@ -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.14",
|
|
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.14"
|
|
16
16
|
}
|
|
17
17
|
},
|
|
18
18
|
"generatedFrom": {
|
|
@@ -420,6 +420,16 @@
|
|
|
420
420
|
"retryable": true,
|
|
421
421
|
"recoveryAction": "Call platform_wait_artifact_deploy again with the same artifactId and operationId."
|
|
422
422
|
},
|
|
423
|
+
{
|
|
424
|
+
"code": "artifact_deploy_failed",
|
|
425
|
+
"retryable": false,
|
|
426
|
+
"recoveryAction": "The deploy finished and failed; the code after artifact_deploy_failed names why. Call platform_deploy_operation with the same artifactId and operationId for failure.detail (the build's own error) and failure.nextAction. Fix the source, run platform_inspect_artifact_app, then deploy again. Retrying the wait or redeploying the same source fails the same way."
|
|
427
|
+
},
|
|
428
|
+
{
|
|
429
|
+
"code": "validation_already_completed",
|
|
430
|
+
"retryable": false,
|
|
431
|
+
"recoveryAction": "A review already approved this version and completed the build session. Don't request another review or start a new session to repeat it; read the verdict with platform_artifact_validation_status. Publishing is the person's step in Topline."
|
|
432
|
+
},
|
|
423
433
|
{
|
|
424
434
|
"code": "artifact_delete_plan_stale",
|
|
425
435
|
"retryable": true,
|
|
@@ -1060,7 +1070,7 @@
|
|
|
1060
1070
|
},
|
|
1061
1071
|
{
|
|
1062
1072
|
"name": "platform_inspect_artifact_app",
|
|
1063
|
-
"description": "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.",
|
|
1073
|
+
"description": "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft. Also runs the manifest and data-binding checks Topline's build would fail (datasets[].name and route, routes[].path, ./_artifact/data/<name> references with no matching dataset); packageReady is false and problems lists each one until they are fixed.",
|
|
1064
1074
|
"annotations": {
|
|
1065
1075
|
"title": "Platform Inspect Artifact App",
|
|
1066
1076
|
"readOnlyHint": true,
|
|
@@ -1097,6 +1107,13 @@
|
|
|
1097
1107
|
"packageReady": {
|
|
1098
1108
|
"type": "boolean"
|
|
1099
1109
|
},
|
|
1110
|
+
"problems": {
|
|
1111
|
+
"type": "array",
|
|
1112
|
+
"items": {
|
|
1113
|
+
"type": "object"
|
|
1114
|
+
},
|
|
1115
|
+
"description": "Checks Topline's build would fail: each has code, path (manifest field or file) and detail. packageReady is false while any remain."
|
|
1116
|
+
},
|
|
1100
1117
|
"serverManifestValidationRequired": {
|
|
1101
1118
|
"type": "boolean"
|
|
1102
1119
|
},
|
|
@@ -1515,7 +1532,7 @@
|
|
|
1515
1532
|
},
|
|
1516
1533
|
{
|
|
1517
1534
|
"name": "platform_wait_artifact_deploy",
|
|
1518
|
-
"description": "Wait for a durable deployment operation and stream server-derived progress.",
|
|
1535
|
+
"description": "Wait for a durable deployment operation and stream server-derived progress. A failed deploy returns artifact_deploy_failed:<failure code>; read platform_deploy_operation for the build's own error (failure.detail) and next step. A successful deploy returns the session's next sourceHash for the following deploy.",
|
|
1519
1536
|
"annotations": {
|
|
1520
1537
|
"title": "Platform Wait Artifact Deploy",
|
|
1521
1538
|
"readOnlyHint": true,
|
|
@@ -3736,7 +3753,7 @@
|
|
|
3736
3753
|
},
|
|
3737
3754
|
{
|
|
3738
3755
|
"name": "platform_run_artifact_workspace_sql",
|
|
3739
|
-
"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.",
|
|
3756
|
+
"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; when the build session's workspace.routing is company_tables there are no private tables and every statement runs against company tables, as with scope \"company\". A statement the database rejects returns sql_statement_failed:<SQLSTATE> (company tables: company_table_sql_failed:<SQLSTATE>) with a fixed hint. 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.",
|
|
3740
3757
|
"annotations": {
|
|
3741
3758
|
"title": "Platform Run Artifact Workspace Sql",
|
|
3742
3759
|
"readOnlyHint": false,
|
|
@@ -4445,7 +4462,7 @@
|
|
|
4445
4462
|
},
|
|
4446
4463
|
{
|
|
4447
4464
|
"name": "platform_run_acceptance_checks",
|
|
4448
|
-
"description": "Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version, which also gates validation.",
|
|
4465
|
+
"description": "Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version (passed, passed_with_warnings with qualityWarnings codes, failed with failingChecks, or not_run), which also gates validation.",
|
|
4449
4466
|
"annotations": {
|
|
4450
4467
|
"title": "Platform Run Acceptance Checks",
|
|
4451
4468
|
"readOnlyHint": false,
|
|
@@ -4768,7 +4785,7 @@
|
|
|
4768
4785
|
},
|
|
4769
4786
|
{
|
|
4770
4787
|
"name": "platform_request_artifact_validation",
|
|
4771
|
-
"description": "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish.",
|
|
4788
|
+
"description": "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish and completes this build session; asking again returns validation_already_completed. A needs_fix review keeps the session active: fix, deploy a new version, smoke, then request a review of that version. If the draft isn't ready, the refusal names the blocker platform_prepare_artifact_validation reports.",
|
|
4772
4789
|
"annotations": {
|
|
4773
4790
|
"title": "Platform Request Artifact Validation",
|
|
4774
4791
|
"readOnlyHint": false,
|
|
@@ -4810,10 +4827,12 @@
|
|
|
4810
4827
|
"description": "Milliseconds to wait for the review before returning, 0 to 1000."
|
|
4811
4828
|
},
|
|
4812
4829
|
"buildOk": {
|
|
4813
|
-
"type": "boolean"
|
|
4830
|
+
"type": "boolean",
|
|
4831
|
+
"description": "Your own local build result. Omit if you did not run one; the reviewer is told separately that Topline's trusted build deployed this version."
|
|
4814
4832
|
},
|
|
4815
4833
|
"typecheckOk": {
|
|
4816
|
-
"type": "boolean"
|
|
4834
|
+
"type": "boolean",
|
|
4835
|
+
"description": "Your own local typecheck result. Omit if you did not run one."
|
|
4817
4836
|
},
|
|
4818
4837
|
"docImpact": {
|
|
4819
4838
|
"type": "string",
|
|
@@ -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.14`
|
|
6
6
|
Transport: `stdio`
|
|
7
7
|
Default protocol: `2025-11-25`
|
|
8
8
|
Canonical guide: https://topline.build/docs/build-mcp-guide
|
|
@@ -81,6 +81,8 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
|
|
|
81
81
|
- `build_session_id_required` (not automatically retryable): The fields named after the code only work inside a build session. Remove them for a plain deploy of an app you created over MCP, or start a session and pass its sessionId.
|
|
82
82
|
- `artifact_external_session_active` (not automatically retryable): An open build session holds this app. If it is yours, pass its sessionId; otherwise close it with platform_close_build_session or wait for it to end.
|
|
83
83
|
- `artifact_deploy_wait_timeout` (retryable): Call platform_wait_artifact_deploy again with the same artifactId and operationId.
|
|
84
|
+
- `artifact_deploy_failed` (not automatically retryable): The deploy finished and failed; the code after artifact_deploy_failed names why. Call platform_deploy_operation with the same artifactId and operationId for failure.detail (the build's own error) and failure.nextAction. Fix the source, run platform_inspect_artifact_app, then deploy again. Retrying the wait or redeploying the same source fails the same way.
|
|
85
|
+
- `validation_already_completed` (not automatically retryable): A review already approved this version and completed the build session. Don't request another review or start a new session to repeat it; read the verdict with platform_artifact_validation_status. Publishing is the person's step in Topline.
|
|
84
86
|
- `artifact_delete_plan_stale` (retryable): Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken.
|
|
85
87
|
- `artifact_app_bundle_changed_after_inspection` (retryable): Call platform_inspect_artifact_app again, review the new bundle hash, then retry deployment with that hash.
|
|
86
88
|
- `artifact_app_bundle_hardlink_forbidden` (not automatically retryable): Replace the hard link with a regular file copied into appDir, then inspect again.
|
|
@@ -704,7 +706,7 @@ Output schema:
|
|
|
704
706
|
|
|
705
707
|
### `platform_inspect_artifact_app`
|
|
706
708
|
|
|
707
|
-
Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.
|
|
709
|
+
Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft. Also runs the manifest and data-binding checks Topline's build would fail (datasets[].name and route, routes[].path, ./_artifact/data/<name> references with no matching dataset); packageReady is false and problems lists each one until they are fixed.
|
|
708
710
|
|
|
709
711
|
Safety: read-only=true, destructive=false, idempotent=false, open-world=false.
|
|
710
712
|
|
|
@@ -769,6 +771,13 @@ Output schema:
|
|
|
769
771
|
"packageReady": {
|
|
770
772
|
"type": "boolean"
|
|
771
773
|
},
|
|
774
|
+
"problems": {
|
|
775
|
+
"type": "array",
|
|
776
|
+
"items": {
|
|
777
|
+
"type": "object"
|
|
778
|
+
},
|
|
779
|
+
"description": "Checks Topline's build would fail: each has code, path (manifest field or file) and detail. packageReady is false while any remain."
|
|
780
|
+
},
|
|
772
781
|
"serverManifestValidationRequired": {
|
|
773
782
|
"type": "boolean"
|
|
774
783
|
},
|
|
@@ -1207,7 +1216,7 @@ Output schema:
|
|
|
1207
1216
|
|
|
1208
1217
|
### `platform_wait_artifact_deploy`
|
|
1209
1218
|
|
|
1210
|
-
Wait for a durable deployment operation and stream server-derived progress.
|
|
1219
|
+
Wait for a durable deployment operation and stream server-derived progress. A failed deploy returns artifact_deploy_failed:<failure code>; read platform_deploy_operation for the build's own error (failure.detail) and next step. A successful deploy returns the session's next sourceHash for the following deploy.
|
|
1211
1220
|
|
|
1212
1221
|
Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
|
|
1213
1222
|
|
|
@@ -3652,7 +3661,7 @@ Output schema:
|
|
|
3652
3661
|
|
|
3653
3662
|
### `platform_run_artifact_workspace_sql`
|
|
3654
3663
|
|
|
3655
|
-
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.
|
|
3664
|
+
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; when the build session's workspace.routing is company_tables there are no private tables and every statement runs against company tables, as with scope "company". A statement the database rejects returns sql_statement_failed:<SQLSTATE> (company tables: company_table_sql_failed:<SQLSTATE>) with a fixed hint. 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.
|
|
3656
3665
|
|
|
3657
3666
|
Safety: read-only=false, destructive=false, idempotent=true, open-world=true.
|
|
3658
3667
|
|
|
@@ -4438,7 +4447,7 @@ Output schema:
|
|
|
4438
4447
|
|
|
4439
4448
|
### `platform_run_acceptance_checks`
|
|
4440
4449
|
|
|
4441
|
-
Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version, which also gates validation.
|
|
4450
|
+
Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version (passed, passed_with_warnings with qualityWarnings codes, failed with failingChecks, or not_run), which also gates validation.
|
|
4442
4451
|
|
|
4443
4452
|
Safety: read-only=false, destructive=false, idempotent=true, open-world=true.
|
|
4444
4453
|
|
|
@@ -4794,7 +4803,7 @@ Output schema:
|
|
|
4794
4803
|
|
|
4795
4804
|
### `platform_request_artifact_validation`
|
|
4796
4805
|
|
|
4797
|
-
Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish.
|
|
4806
|
+
Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish and completes this build session; asking again returns validation_already_completed. A needs_fix review keeps the session active: fix, deploy a new version, smoke, then request a review of that version. If the draft isn't ready, the refusal names the blocker platform_prepare_artifact_validation reports.
|
|
4798
4807
|
|
|
4799
4808
|
Safety: read-only=false, destructive=false, idempotent=true, open-world=true.
|
|
4800
4809
|
|
|
@@ -4856,10 +4865,12 @@ Input schema:
|
|
|
4856
4865
|
"description": "Milliseconds to wait for the review before returning, 0 to 1000."
|
|
4857
4866
|
},
|
|
4858
4867
|
"buildOk": {
|
|
4859
|
-
"type": "boolean"
|
|
4868
|
+
"type": "boolean",
|
|
4869
|
+
"description": "Your own local build result. Omit if you did not run one; the reviewer is told separately that Topline's trusted build deployed this version."
|
|
4860
4870
|
},
|
|
4861
4871
|
"typecheckOk": {
|
|
4862
|
-
"type": "boolean"
|
|
4872
|
+
"type": "boolean",
|
|
4873
|
+
"description": "Your own local typecheck result. Omit if you did not run one."
|
|
4863
4874
|
},
|
|
4864
4875
|
"docImpact": {
|
|
4865
4876
|
"type": "string",
|