# Local Build MCP Package Reference

> Generated from the pinned `docs/generated/build-mcp-manifest.json` package manifest. Do not edit this file directly.

- Package: `@topline-build/harness-mcp@0.5.0`
- Transport: `stdio`
- Default protocol version: `2025-11-25`
- Canonical website docs: https://topline.build/docs/build-mcp-guide
- Generated from: `src/index.ts#BUILD_MCP_TOOLS` via `npm run docs:generate`

Generated from the registry used by tools/list. Do not edit generated files by hand.

## Setup

```json
{
  "command": "npx -y @topline-build/harness-mcp --url https://YOUR-TOPLINE-HOST",
  "clientConfigs": {
    "json": {
      "mcpServers": {
        "topline-build": {
          "command": "npx",
          "args": [
            "-y",
            "@topline-build/harness-mcp",
            "--url",
            "https://YOUR-TOPLINE-HOST"
          ]
        }
      }
    },
    "codexToml": "[mcp_servers.topline-build]\ncommand = \"npx\"\nargs = [\"-y\", \"@topline-build/harness-mcp\", \"--url\", \"https://YOUR-TOPLINE-HOST\"]"
  },
  "options": [
    {
      "flag": "--url",
      "env": "TOPLINE_API_URL",
      "aliases": [
        "PLATFORM_API_URL",
        "OVERSITE_API_URL"
      ],
      "required": true,
      "description": "Topline tenant base URL. HTTPS is required except for loopback development."
    },
    {
      "flag": "--workspace-root",
      "env": "TOPLINE_WORKSPACE_ROOT",
      "aliases": [
        "PLATFORM_WORKSPACE_ROOT"
      ],
      "default": "current working directory",
      "description": "Local root that contains artifact app directories."
    },
    {
      "flag": "--surface",
      "env": "TOPLINE_MCP_SURFACE",
      "default": "build",
      "allowed": [
        "build",
        "harness"
      ],
      "description": "Build is the current surface; harness preserves legacy OAuth compatibility."
    },
    {
      "flag": "--protocol-version",
      "env": "TOPLINE_MCP_PROTOCOL_VERSION",
      "aliases": [
        "PLATFORM_MCP_PROTOCOL_VERSION"
      ],
      "default": "2025-11-25",
      "description": "MCP protocol version sent to Topline HTTP endpoints."
    },
    {
      "flag": "--auth-file",
      "env": "TOPLINE_MCP_AUTH_FILE",
      "aliases": [
        "PLATFORM_MCP_AUTH_FILE"
      ],
      "default": "per-tenant file in the local Topline config directory",
      "description": "OAuth credential cache. Keep it outside artifact app directories."
    },
    {
      "flag": "--scopes",
      "env": "TOPLINE_MCP_SCOPES",
      "aliases": [
        "PLATFORM_MCP_SCOPES"
      ],
      "default": "harness:artifact:read harness:artifact:write harness:artifact:deploy harness:artifact:delete",
      "description": "Space- or comma-separated OAuth scopes."
    },
    {
      "flag": "--timeout-ms",
      "env": "TOPLINE_MCP_TIMEOUT_MS",
      "aliases": [
        "PLATFORM_MCP_TIMEOUT_MS",
        "OVERSITE_MCP_TIMEOUT_MS"
      ],
      "default": 120000,
      "description": "Positive request timeout in milliseconds."
    },
    {
      "flag": "--token",
      "env": "TOPLINE_MCP_TOKEN",
      "aliases": [
        "PLATFORM_MCP_TOKEN",
        "OVERSITE_MCP_TOKEN"
      ],
      "description": "Advanced manual bearer-token fallback. Prefer browser-approved OAuth."
    }
  ]
}
```

## Authentication and scopes

```json
{
  "preferred": "OAuth 2.0 browser approval with a refresh token cached outside the project repository",
  "manualFallbackEnv": "TOPLINE_MCP_TOKEN",
  "defaultScopes": [
    "harness:artifact:read",
    "harness:artifact:write",
    "harness:artifact:deploy",
    "harness:artifact:delete"
  ]
}
```

## Errors and recovery

```json
{
  "outputSchema": {
    "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
  },
  "default": {
    "code": "topline_mcp_tool_failed",
    "retryable": false,
    "recoveryAction": "Inspect the code and message, correct the input if needed, then retry the same tool."
  },
  "catalog": [
    {
      "code": "platform_harness_timeout",
      "retryable": true,
      "recoveryAction": "Retry the call. For a deployment, use platform_list_artifact_drafts to recover the artifact and platform_wait_artifact_deploy to resume progress."
    },
    {
      "code": "platform_mcp_tool_error",
      "retryable": false,
      "recoveryAction": "Read the returned error code, correct the request or OAuth scopes, then retry."
    },
    {
      "code": "artifact_deploy_wait_timeout",
      "retryable": true,
      "recoveryAction": "Call platform_wait_artifact_deploy again with the same artifactId and operationId."
    },
    {
      "code": "artifact_delete_plan_stale",
      "retryable": true,
      "recoveryAction": "Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken."
    },
    {
      "code": "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."
    },
    {
      "code": "artifact_app_bundle_hardlink_forbidden",
      "retryable": false,
      "recoveryAction": "Replace the hard link with a regular file copied into appDir, then inspect again."
    },
    {
      "code": "artifact_app_auth_file_inside_app_dir",
      "retryable": false,
      "recoveryAction": "Move TOPLINE_MCP_AUTH_FILE outside appDir, reconnect the Build MCP, then inspect again."
    },
    {
      "code": "artifact_app_manifest_not_found",
      "retryable": false,
      "recoveryAction": "Create artifact-app.json inside appDir, or correct appDir, then inspect again."
    },
    {
      "code": "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."
    },
    {
      "code": "scope_required",
      "retryable": false,
      "recoveryAction": "Reconnect the Build MCP and approve the requested scope."
    },
    {
      "code": "artifact_app_scaffold_target_not_empty",
      "retryable": false,
      "recoveryAction": "Choose an empty appDir or deploy the existing app without scaffolding."
    }
  ]
}
```

## `platform_connection_check`

Complete the one-time Developer Access verification challenge for this Build MCP client.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Connection Check",
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "verificationCode": "example-verification-code"
    },
    "success": {
      "ok": true,
      "verified": true,
      "product": "build",
      "verifiedAt": "<verifiedAt>"
    }
  }
]
```

## `platform_init_artifact_app`

Create a minimal, validated artifact app starter inside the configured local workspace.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Init Artifact App",
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": false
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "appDir": "artifact-apps/example-app"
    },
    "success": {
      "ok": true,
      "appDir": "artifact-apps/example-app",
      "manifestId": "example-app",
      "title": "Example app",
      "files": [],
      "nextAction": "Follow the tool-provided next action."
    }
  }
]
```

## `platform_deploy_artifact_app`

Package a local artifact app directory, upload it, deploy a private draft, and return status.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Deploy Artifact App",
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "appDir": "artifact-apps/example-app"
    },
    "success": {
      "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": {}
    }
  }
]
```

## `platform_inspect_artifact_app`

Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Inspect Artifact App",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "appDir": "artifact-apps/example-app"
    },
    "success": {
      "ok": true,
      "packageReady": true,
      "serverManifestValidationRequired": true,
      "appDir": "artifact-apps/example-app",
      "platformAppDir": "<platformAppDir>",
      "manifest": {},
      "bundle": {},
      "nextAction": "Follow the tool-provided next action."
    }
  }
]
```

## `platform_list_build_workspaces`

List Topline workspaces available for artifact placement.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform List Build Workspaces",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {},
    "success": {
      "ok": true,
      "workspaces": []
    }
  }
]
```

## `platform_list_artifact_drafts`

Discover private artifact drafts created through this Build MCP connection.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform List Artifact Drafts",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {},
    "success": {
      "ok": true,
      "drafts": []
    }
  }
]
```

## `platform_deploy_operation`

Read durable server-side progress for one artifact deployment operation.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Deploy Operation",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "artifactId": "00000000-0000-4000-8000-000000000001",
      "operationId": "00000000-0000-4000-8000-000000000001"
    },
    "success": {
      "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": []
    }
  }
]
```

## `platform_wait_artifact_deploy`

Wait for a durable deployment operation and stream server-derived progress.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Wait Artifact Deploy",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "artifactId": "00000000-0000-4000-8000-000000000001",
      "operationId": "00000000-0000-4000-8000-000000000001"
    },
    "success": {
      "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": []
    }
  }
]
```

## `platform_artifact_status`

Read private draft deployment status for a hosted artifact app.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Artifact Status",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "artifactId": "00000000-0000-4000-8000-000000000001"
    },
    "success": {
      "ok": true,
      "phase": "<phase>",
      "artifactId": "00000000-0000-4000-8000-000000000001",
      "deployments": []
    }
  }
]
```

## `platform_read_artifact_logs`

Read bounded, redacted deployment logs for a hosted artifact app.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Read Artifact Logs",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "artifactId": "00000000-0000-4000-8000-000000000001"
    },
    "success": {
      "ok": true,
      "phase": "<phase>",
      "artifactId": "00000000-0000-4000-8000-000000000001"
    }
  }
]
```

## `platform_open_artifact`

Return the operator URL and latest draft/live URLs for a hosted artifact app.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Open Artifact",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "artifactId": "00000000-0000-4000-8000-000000000001"
    },
    "success": {
      "ok": true,
      "artifactId": "00000000-0000-4000-8000-000000000001",
      "openUrl": "<openUrl>",
      "draftUrl": "<draftUrl>",
      "liveUrl": "<liveUrl>",
      "versionUrl": "<versionUrl>"
    }
  }
]
```

## `platform_storybook_access`

Return the tenant Storybook preview URL and HTTP MCP server config.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Storybook Access",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {},
    "success": {
      "ok": true,
      "storybookUrl": "<storybookUrl>",
      "mcpUrl": "<mcpUrl>",
      "mcpServers": {}
    }
  }
]
```

## `platform_validate_artifact`

Read trusted smoke and health evidence for a private artifact draft without requiring a browser session.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Validate Artifact",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "artifactId": "00000000-0000-4000-8000-000000000001"
    },
    "success": {
      "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": {}
    }
  }
]
```

## `platform_run_artifact_smoke`

Rerun the trusted draft smoke check and return fresh rendered-page evidence.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Run Artifact Smoke",
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "artifactId": "00000000-0000-4000-8000-000000000001"
    },
    "success": {
      "ok": true,
      "phase": "<phase>",
      "artifactId": "00000000-0000-4000-8000-000000000001",
      "deploymentRecordId": "00000000-0000-4000-8000-000000000003",
      "smoke": {},
      "validation": {}
    }
  }
]
```

## `platform_plan_artifact_draft_delete`

Preview cleanup effects and receive the state-bound plan token required for deletion.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Plan Artifact Draft Delete",
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "artifactId": "00000000-0000-4000-8000-000000000001"
    },
    "success": {
      "ok": true,
      "phase": "<phase>",
      "artifactId": "00000000-0000-4000-8000-000000000001",
      "eligible": true,
      "effects": {},
      "planToken": "example-plan-token"
    }
  }
]
```

## `platform_delete_artifact_draft`

Permanently remove an unpromoted private draft created by this MCP connection after exact-id confirmation.

### Metadata and annotations

```json
{
  "annotations": {
    "title": "Platform Delete Artifact Draft",
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}
```

### 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
    }
  ]
}
```

### Examples

```json
[
  {
    "request": {
      "artifactId": "00000000-0000-4000-8000-000000000001",
      "confirmArtifactId": "00000000-0000-4000-8000-000000000001",
      "planToken": "example-plan-token"
    },
    "success": {
      "ok": true,
      "deleted": true,
      "artifactId": "00000000-0000-4000-8000-000000000001"
    }
  }
]
```