@topline-build/harness-mcp 0.4.0 → 0.5.0

package/docs/generated/build-mcp-reference.md

@@ -0,0 +1,2126 @@
+# Build MCP runtime reference
+
+> Generated from `src/index.ts#BUILD_MCP_TOOLS`. Do not edit this file by hand.
+
+Package: `@topline-build/harness-mcp@0.5.0`
+Transport: `stdio`
+Default protocol: `2025-11-25`
+Canonical guide: https://topline.build/docs/build-mcp-guide
+
+## Quick start
+
+```bash
+npx -y @topline-build/harness-mcp --url https://YOUR-TOPLINE-HOST
+```
+
+The first authenticated tool call normally opens browser approval. Set `TOPLINE_WORKSPACE_ROOT` when the MCP host starts outside the repository containing the artifact app.
+
+## Configuration
+
+| CLI flag | Environment | Default | Purpose |
+| --- | --- | --- | --- |
+| `--url` | `TOPLINE_API_URL`, `PLATFORM_API_URL`, `OVERSITE_API_URL` | required | Topline tenant base URL. HTTPS is required except for loopback development. |
+| `--workspace-root` | `TOPLINE_WORKSPACE_ROOT`, `PLATFORM_WORKSPACE_ROOT` | `current working directory` | Local root that contains artifact app directories. |
+| `--surface` | `TOPLINE_MCP_SURFACE` | `build` | Build is the current surface; harness preserves legacy OAuth compatibility. |
+| `--protocol-version` | `TOPLINE_MCP_PROTOCOL_VERSION`, `PLATFORM_MCP_PROTOCOL_VERSION` | `2025-11-25` | MCP protocol version sent to Topline HTTP endpoints. |
+| `--auth-file` | `TOPLINE_MCP_AUTH_FILE`, `PLATFORM_MCP_AUTH_FILE` | `per-tenant file in the local Topline config directory` | OAuth credential cache. Keep it outside artifact app directories. |
+| `--scopes` | `TOPLINE_MCP_SCOPES`, `PLATFORM_MCP_SCOPES` | `harness:artifact:read harness:artifact:write harness:artifact:deploy harness:artifact:delete` | Space- or comma-separated OAuth scopes. |
+| `--timeout-ms` | `TOPLINE_MCP_TIMEOUT_MS`, `PLATFORM_MCP_TIMEOUT_MS`, `OVERSITE_MCP_TIMEOUT_MS` | `120000` | Positive request timeout in milliseconds. |
+| `--token` | `TOPLINE_MCP_TOKEN`, `PLATFORM_MCP_TOKEN`, `OVERSITE_MCP_TOKEN` | `optional` | Advanced manual bearer-token fallback. Prefer browser-approved OAuth. |
+
+## Structured failures
+
+Tool failures set `isError: true` and return `structuredContent.error` with `code`, `message`, `retryable`, and `recoveryAction`.
+
+- `platform_harness_timeout` (retryable): Retry the call. For a deployment, use platform_list_artifact_drafts to recover the artifact and platform_wait_artifact_deploy to resume progress.
+- `platform_mcp_tool_error` (not automatically retryable): Read the returned error code, correct the request or OAuth scopes, then retry.
+- `artifact_deploy_wait_timeout` (retryable): Call platform_wait_artifact_deploy again with the same artifactId and operationId.
+- `artifact_delete_plan_stale` (retryable): Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken.
+- `artifact_app_bundle_changed_after_inspection` (retryable): Call platform_inspect_artifact_app again, review the new bundle hash, then retry deployment with that hash.
+- `artifact_app_bundle_hardlink_forbidden` (not automatically retryable): Replace the hard link with a regular file copied into appDir, then inspect again.
+- `artifact_app_auth_file_inside_app_dir` (not automatically retryable): Move TOPLINE_MCP_AUTH_FILE outside appDir, reconnect the Build MCP, then inspect again.
+- `artifact_app_manifest_not_found` (not automatically retryable): Create artifact-app.json inside appDir, or correct appDir, then inspect again.
+- `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.
+- `scope_required` (not automatically retryable): Reconnect the Build MCP and approve the requested scope.
+- `artifact_app_scaffold_target_not_empty` (not automatically retryable): Choose an empty appDir or deploy the existing app without scaffolding.
+
+## Tools
+
+### `platform_connection_check`
+
+Complete the one-time Developer Access verification challenge for this Build MCP client.
+
+Safety: read-only=false, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "verificationCode": "example-verification-code"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "verified": true,
+  "product": "build",
+  "verifiedAt": "<verifiedAt>"
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "verificationCode": {
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 80
+    }
+  },
+  "required": [
+    "verificationCode"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "verified": {
+          "type": "boolean"
+        },
+        "product": {
+          "type": "string",
+          "enum": [
+            "build"
+          ]
+        },
+        "verifiedAt": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "ok",
+        "verified",
+        "product",
+        "verifiedAt"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_init_artifact_app`
+
+Create a minimal, validated artifact app starter inside the configured local workspace.
+
+Safety: read-only=false, destructive=false, idempotent=false, open-world=false.
+
+Example request:
+
+```json
+{
+  "appDir": "artifact-apps/example-app"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "appDir": "artifact-apps/example-app",
+  "manifestId": "example-app",
+  "title": "Example app",
+  "files": [],
+  "nextAction": "Follow the tool-provided next action."
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "appDir": {
+      "type": "string",
+      "minLength": 1
+    },
+    "manifestId": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "appDir"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "appDir": {
+          "type": "string"
+        },
+        "manifestId": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "nextAction": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "ok",
+        "appDir",
+        "manifestId",
+        "title",
+        "files",
+        "nextAction"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_deploy_artifact_app`
+
+Package a local artifact app directory, upload it, deploy a private draft, and return status.
+
+Safety: read-only=false, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "appDir": "artifact-apps/example-app"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "artifactVersionId": "00000000-0000-4000-8000-000000000002",
+  "clientRequestId": "example-request",
+  "operationId": "00000000-0000-4000-8000-000000000004",
+  "bundle": {},
+  "create": {},
+  "deploy": {}
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "appDir": {
+      "type": "string",
+      "minLength": 1
+    },
+    "artifactId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "title": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "projectId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "expectedBundleSha256": {
+      "type": "string",
+      "pattern": "^[0-9a-fA-F]{64}$",
+      "description": "Optional SHA-256 from platform_inspect_artifact_app; deployment fails locally if source changed."
+    },
+    "requestId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Optional stable retry key; generated deterministically when omitted."
+    }
+  },
+  "required": [
+    "appDir"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "artifactId": {
+          "type": "string"
+        },
+        "artifactVersionId": {
+          "type": "string"
+        },
+        "clientRequestId": {
+          "type": "string"
+        },
+        "operationId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "bundle": {
+          "type": "object"
+        },
+        "create": {
+          "type": "object"
+        },
+        "deploy": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "ok",
+        "artifactId",
+        "artifactVersionId",
+        "clientRequestId",
+        "operationId",
+        "bundle",
+        "create",
+        "deploy"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_inspect_artifact_app`
+
+Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=false.
+
+Example request:
+
+```json
+{
+  "appDir": "artifact-apps/example-app"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "packageReady": true,
+  "serverManifestValidationRequired": true,
+  "appDir": "artifact-apps/example-app",
+  "platformAppDir": "<platformAppDir>",
+  "manifest": {},
+  "bundle": {},
+  "nextAction": "Follow the tool-provided next action."
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "appDir": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "appDir"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "packageReady": {
+          "type": "boolean"
+        },
+        "serverManifestValidationRequired": {
+          "type": "boolean"
+        },
+        "appDir": {
+          "type": "string"
+        },
+        "platformAppDir": {
+          "type": "string"
+        },
+        "manifest": {
+          "type": "object"
+        },
+        "bundle": {
+          "type": "object"
+        },
+        "nextAction": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "ok",
+        "packageReady",
+        "serverManifestValidationRequired",
+        "appDir",
+        "platformAppDir",
+        "manifest",
+        "bundle",
+        "nextAction"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_list_build_workspaces`
+
+List Topline workspaces available for artifact placement.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "workspaces": []
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "workspaces": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        }
+      },
+      "required": [
+        "ok",
+        "workspaces"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_list_artifact_drafts`
+
+Discover private artifact drafts created through this Build MCP connection.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "drafts": []
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "projectId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "drafts": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        }
+      },
+      "required": [
+        "ok",
+        "drafts"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_deploy_operation`
+
+Read durable server-side progress for one artifact deployment operation.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "operationId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "phase": "<phase>",
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "operationId": "00000000-0000-4000-8000-000000000004",
+  "taskStatus": "<taskStatus>",
+  "progress": 1,
+  "terminal": true,
+  "successful": true,
+  "events": []
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "operationId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "afterSeq": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "required": [
+    "artifactId",
+    "operationId"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "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"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_wait_artifact_deploy`
+
+Wait for a durable deployment operation and stream server-derived progress.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "operationId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "phase": "<phase>",
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "operationId": "00000000-0000-4000-8000-000000000004",
+  "taskStatus": "<taskStatus>",
+  "progress": 1,
+  "terminal": true,
+  "successful": true,
+  "events": []
+}
+```
+
+Input schema:
+
+```json
+{
+  "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
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "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"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_artifact_status`
+
+Read private draft deployment status for a hosted artifact app.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "artifactId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "phase": "<phase>",
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "deployments": []
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 50
+    }
+  },
+  "required": [
+    "artifactId"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "phase": {
+          "type": "string"
+        },
+        "artifactId": {
+          "type": "string"
+        },
+        "deployments": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        }
+      },
+      "required": [
+        "ok",
+        "phase",
+        "artifactId",
+        "deployments"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_read_artifact_logs`
+
+Read bounded, redacted deployment logs for a hosted artifact app.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "artifactId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "phase": "<phase>",
+  "artifactId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "deploymentRecordId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "environment": {
+      "type": "string",
+      "enum": [
+        "draft",
+        "live"
+      ]
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 200
+    },
+    "severity": {
+      "type": "string"
+    },
+    "contains": {
+      "type": "string"
+    },
+    "since": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "windowMinutes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 1440
+    },
+    "trace": {
+      "type": "string"
+    },
+    "requestId": {
+      "type": "string"
+    },
+    "route": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "artifactId"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "phase": {
+          "type": "string"
+        },
+        "artifactId": {
+          "type": "string"
+        },
+        "entries": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        }
+      },
+      "required": [
+        "ok",
+        "phase",
+        "artifactId"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_open_artifact`
+
+Return the operator URL and latest draft/live URLs for a hosted artifact app.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "artifactId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "openUrl": "<openUrl>",
+  "draftUrl": "<draftUrl>",
+  "liveUrl": "<liveUrl>",
+  "versionUrl": "<versionUrl>"
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid"
+    }
+  },
+  "required": [
+    "artifactId"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "artifactId": {
+          "type": "string"
+        },
+        "openUrl": {
+          "type": "string"
+        },
+        "draftUrl": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "liveUrl": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "versionUrl": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "ok",
+        "artifactId",
+        "openUrl",
+        "draftUrl",
+        "liveUrl",
+        "versionUrl"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_storybook_access`
+
+Return the tenant Storybook preview URL and HTTP MCP server config.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=false.
+
+Example request:
+
+```json
+{}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "storybookUrl": "<storybookUrl>",
+  "mcpUrl": "<mcpUrl>",
+  "mcpServers": {}
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "storybookUrl": {
+          "type": "string"
+        },
+        "mcpUrl": {
+          "type": "string"
+        },
+        "mcpServers": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "ok",
+        "storybookUrl",
+        "mcpUrl",
+        "mcpServers"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_validate_artifact`
+
+Read trusted smoke and health evidence for a private artifact draft without requiring a browser session.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=false.
+
+Example request:
+
+```json
+{
+  "artifactId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "phase": "<phase>",
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "deploymentRecordId": "00000000-0000-4000-8000-000000000003",
+  "deploymentState": "<deploymentState>",
+  "healthy": true,
+  "checkedAt": "<checkedAt>",
+  "draftUrl": "<draftUrl>",
+  "smoke": {}
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "deploymentRecordId": {
+      "type": "string",
+      "format": "uuid"
+    }
+  },
+  "required": [
+    "artifactId"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "phase": {
+          "type": "string"
+        },
+        "artifactId": {
+          "type": "string"
+        },
+        "deploymentRecordId": {
+          "type": "string"
+        },
+        "deploymentState": {
+          "type": "string"
+        },
+        "healthy": {
+          "type": "boolean"
+        },
+        "checkedAt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "draftUrl": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "smoke": {
+          "type": [
+            "object",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "ok",
+        "phase",
+        "artifactId",
+        "deploymentRecordId",
+        "deploymentState",
+        "healthy",
+        "checkedAt",
+        "draftUrl",
+        "smoke"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_run_artifact_smoke`
+
+Rerun the trusted draft smoke check and return fresh rendered-page evidence.
+
+Safety: read-only=false, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "artifactId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "phase": "<phase>",
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "deploymentRecordId": "00000000-0000-4000-8000-000000000003",
+  "smoke": {},
+  "validation": {}
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "deploymentRecordId": {
+      "type": "string",
+      "format": "uuid"
+    }
+  },
+  "required": [
+    "artifactId"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "phase": {
+          "type": "string"
+        },
+        "artifactId": {
+          "type": "string"
+        },
+        "deploymentRecordId": {
+          "type": "string"
+        },
+        "smoke": {
+          "type": "object"
+        },
+        "validation": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "ok",
+        "phase",
+        "artifactId",
+        "deploymentRecordId",
+        "smoke",
+        "validation"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_plan_artifact_draft_delete`
+
+Preview cleanup effects and receive the state-bound plan token required for deletion.
+
+Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "artifactId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "phase": "<phase>",
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "eligible": true,
+  "effects": {},
+  "planToken": "example-plan-token"
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid"
+    }
+  },
+  "required": [
+    "artifactId"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "phase": {
+          "type": "string"
+        },
+        "artifactId": {
+          "type": "string"
+        },
+        "eligible": {
+          "type": "boolean"
+        },
+        "effects": {
+          "type": "object"
+        },
+        "planToken": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "ok",
+        "phase",
+        "artifactId",
+        "eligible",
+        "effects",
+        "planToken"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_delete_artifact_draft`
+
+Permanently remove an unpromoted private draft created by this MCP connection after exact-id confirmation.
+
+Safety: read-only=false, destructive=true, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "artifactId": "00000000-0000-4000-8000-000000000001",
+  "confirmArtifactId": "00000000-0000-4000-8000-000000000001",
+  "planToken": "example-plan-token"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "deleted": true,
+  "artifactId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "confirmArtifactId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "planToken": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "artifactId",
+    "confirmArtifactId",
+    "planToken"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "deleted": {
+          "type": "boolean"
+        },
+        "artifactId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "ok",
+        "deleted",
+        "artifactId"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```