@topline-build/harness-mcp 0.8.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 +3 -1
- package/dist/index.d.ts +6 -1
- package/dist/index.js +76 -4
- package/docs/generated/build-mcp-manifest.json +15 -2
- package/docs/generated/build-mcp-reference.md +10 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,7 +2,9 @@
|
|
|
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.
|
|
6
8
|
|
|
7
9
|
## 0.8.0 - source candidate
|
|
8
10
|
|
package/dist/index.d.ts
CHANGED
|
@@ -39,7 +39,7 @@ type ToolProgressReporter = (progress: number, message: string) => void | Promis
|
|
|
39
39
|
export type McpSurface = "build" | "topline" | "harness";
|
|
40
40
|
export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
41
41
|
export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
|
|
42
|
-
export declare const HARNESS_MCP_VERSION = "0.
|
|
42
|
+
export declare const HARNESS_MCP_VERSION = "0.9.0";
|
|
43
43
|
export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
|
|
44
44
|
/** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
|
|
45
45
|
export declare const TOPLINE_OAUTH_SCOPES: readonly string[];
|
|
@@ -126,6 +126,11 @@ export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input:
|
|
|
126
126
|
manifestVersion: number | null;
|
|
127
127
|
title: string | null;
|
|
128
128
|
kind: string | null;
|
|
129
|
+
parts: {
|
|
130
|
+
name: string | null;
|
|
131
|
+
kind: string | null;
|
|
132
|
+
dir: string | null;
|
|
133
|
+
}[];
|
|
129
134
|
};
|
|
130
135
|
bundle: {
|
|
131
136
|
fileCount: number;
|
package/dist/index.js
CHANGED
|
@@ -17,7 +17,7 @@ const MCP_SURFACES = ["build", "topline", "harness"];
|
|
|
17
17
|
export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
18
18
|
const DEFAULT_TIMEOUT_MS = 120_000;
|
|
19
19
|
export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
|
|
20
|
-
export const HARNESS_MCP_VERSION = "0.
|
|
20
|
+
export const HARNESS_MCP_VERSION = "0.9.0";
|
|
21
21
|
export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
|
|
22
22
|
/** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
|
|
23
23
|
export const TOPLINE_OAUTH_SCOPES = Object.freeze([
|
|
@@ -591,7 +591,14 @@ export async function inspectArtifactApp(opts, input) {
|
|
|
591
591
|
id: typeof manifest.id === "string" ? manifest.id : null,
|
|
592
592
|
manifestVersion: typeof manifest.manifestVersion === "number" ? manifest.manifestVersion : null,
|
|
593
593
|
title: typeof manifest.title === "string" ? manifest.title : null,
|
|
594
|
-
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
|
+
: []
|
|
595
602
|
},
|
|
596
603
|
bundle: {
|
|
597
604
|
fileCount: bundle.fileCount,
|
|
@@ -791,6 +798,11 @@ export async function initArtifactApp(opts, input) {
|
|
|
791
798
|
const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
|
|
792
799
|
if (existsSync(absoluteAppDir) && (await readdir(absoluteAppDir)).length > 0)
|
|
793
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");
|
|
794
806
|
await mkdir(path.join(absoluteAppDir, "src"), { recursive: true });
|
|
795
807
|
const manifest = {
|
|
796
808
|
manifestVersion: 2,
|
|
@@ -825,6 +837,55 @@ export async function initArtifactApp(opts, input) {
|
|
|
825
837
|
nextAction: `Run npm test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
|
|
826
838
|
};
|
|
827
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
|
+
}
|
|
828
889
|
export async function getArtifactStatus(opts, artifactId, limit) {
|
|
829
890
|
const query = new URLSearchParams();
|
|
830
891
|
if (limit)
|
|
@@ -1227,7 +1288,16 @@ const BUILD_MCP_TOOLS = [
|
|
|
1227
1288
|
annotations: mcpToolAnnotations("platform_init_artifact_app", { readOnly: false }),
|
|
1228
1289
|
inputSchema: {
|
|
1229
1290
|
type: "object",
|
|
1230
|
-
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
|
+
},
|
|
1231
1301
|
required: ["appDir"],
|
|
1232
1302
|
additionalProperties: false
|
|
1233
1303
|
},
|
|
@@ -1666,7 +1736,8 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
|
|
|
1666
1736
|
artifact_app_manifest_not_found: { retryable: false, recoveryAction: "Create artifact-app.json inside appDir, or correct appDir, then inspect again." },
|
|
1667
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." },
|
|
1668
1738
|
scope_required: { retryable: false, recoveryAction: "Reconnect the Build MCP and approve the requested scope." },
|
|
1669
|
-
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." }
|
|
1670
1741
|
};
|
|
1671
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)])));
|
|
1672
1743
|
function structuredToolError(message) {
|
|
@@ -1688,6 +1759,7 @@ function recoveryErrorCode(message) {
|
|
|
1688
1759
|
"artifact_delete_plan_stale",
|
|
1689
1760
|
"artifact_deploy_wait_timeout",
|
|
1690
1761
|
"artifact_app_scaffold_target_not_empty",
|
|
1762
|
+
"artifact_app_scaffold_shape_invalid",
|
|
1691
1763
|
"platform_harness_timeout",
|
|
1692
1764
|
"platform_mcp_tool_error",
|
|
1693
1765
|
"scope_required"
|
|
@@ -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": {
|
|
@@ -386,6 +386,11 @@
|
|
|
386
386
|
"code": "artifact_app_scaffold_target_not_empty",
|
|
387
387
|
"retryable": false,
|
|
388
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."
|
|
389
394
|
}
|
|
390
395
|
]
|
|
391
396
|
},
|
|
@@ -512,6 +517,14 @@
|
|
|
512
517
|
},
|
|
513
518
|
"title": {
|
|
514
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."
|
|
515
528
|
}
|
|
516
529
|
},
|
|
517
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
|
|
@@ -75,6 +75,7 @@ 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
|
|
|
@@ -233,6 +234,14 @@ Input schema:
|
|
|
233
234
|
},
|
|
234
235
|
"title": {
|
|
235
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."
|
|
236
245
|
}
|
|
237
246
|
},
|
|
238
247
|
"required": [
|