@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 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
- ## Unreleased
5
+ ## 0.9.0 - source candidate
6
+
7
+ - `platform_init_artifact_app` takes `shape: "web-and-api"` to scaffold one artifact with a static website part and an API part under one address, instead of two artifacts. `platform_inspect_artifact_app` lists an app's parts.
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.8.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.8.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) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
866
+ const webPackage = { name: `${manifestId}-web`, private: true, type: "module", scripts: { build: "node src/build.mjs" } };
867
+ const apiPackage = { name: `${manifestId}-api`, private: true, type: "module", main: "src/index.js" };
868
+ const page = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${safeTitle}</title></head><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p id="message">Loading...</p></main><script type="module" src="./app.js"></script></body></html>`;
869
+ const browserScript = `fetch("./_artifact/api/hello").then((response) => response.json()).then((body) => { document.getElementById("message").textContent = body.message; }).catch(() => { document.getElementById("message").textContent = "The API is not reachable yet."; });\n`;
870
+ const webBuild = `import { mkdirSync, writeFileSync } from "node:fs";\n\n// Asset URLs stay relative so the same files work on the draft, live, and version addresses.\nmkdirSync("dist", { recursive: true });\nwriteFileSync("dist/index.html", ${JSON.stringify(page)}, "utf8");\nwriteFileSync("dist/app.js", ${JSON.stringify(browserScript)}, "utf8");\nconsole.log("web build ok");\n`;
871
+ const apiSource = `export function artifactApp(req, res) {\n const url = new URL(req.url ?? "/", "http://artifact.local");\n res.setHeader("content-type", "application/json; charset=utf-8");\n if (url.pathname.endsWith("/_artifact/api/health")) {\n res.end(JSON.stringify({ ok: true, part: process.env.PLATFORM_ARTIFACT_PART ?? null }));\n return;\n }\n if (url.pathname.endsWith("/_artifact/api/hello")) {\n res.end(JSON.stringify({ ok: true, message: "Hello from the api part. Replace this endpoint with your API." }));\n return;\n }\n res.statusCode = 404;\n res.end(JSON.stringify({ error: "not_found" }));\n}\n\nif (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {\n console.log(JSON.stringify({ tests: [{ description: "The api part answers its hello route.", required: true, status: "passed", summary: "artifactApp handles /_artifact/api/hello." }] }));\n} else if (process.argv.includes("--test")) {\n console.log("api part ok");\n}\n`;
872
+ const files = [
873
+ ["artifact-app.json", `${JSON.stringify(manifest, null, 2)}\n`],
874
+ ["web/package.json", `${JSON.stringify(webPackage, null, 2)}\n`],
875
+ ["web/src/build.mjs", webBuild],
876
+ ["api/package.json", `${JSON.stringify(apiPackage, null, 2)}\n`],
877
+ ["api/src/index.js", apiSource]
878
+ ];
879
+ await Promise.all(files.map(([file, content]) => writeFile(path.join(absoluteAppDir, ...file.split("/")), content, { flag: "wx" })));
880
+ return {
881
+ ok: true,
882
+ appDir: workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir),
883
+ manifestId,
884
+ title,
885
+ files: files.map(([file]) => file),
886
+ nextAction: `Run npm run build in ${appDir}/web and node api/src/index.js --test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
887
+ };
888
+ }
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: { appDir: { type: "string", minLength: 1 }, manifestId: { type: "string" }, title: { type: "string" } },
1291
+ properties: {
1292
+ appDir: { type: "string", minLength: 1 },
1293
+ manifestId: { type: "string" },
1294
+ title: { type: "string" },
1295
+ shape: {
1296
+ type: "string",
1297
+ enum: ["single", "web-and-api"],
1298
+ description: "single (default): one app. web-and-api: one artifact with a static website part and an API part under one address; use it instead of two artifacts."
1299
+ }
1300
+ },
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.8.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.8.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.8.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": [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topline-build/harness-mcp",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "Topline Build MCP for creating and deploying artifact app drafts.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",