@topline-build/harness-mcp 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable customer-visible Build MCP changes are recorded here. A source change is not a published package or customer release.
+
+## Unreleased
+
+## 0.5.1 - 2026-09-18
+
+- Harden the bundled Claude certification script with strict tool isolation, effective-runtime proof, and noninteractive JSONL validation.
+- Update certification setup documentation and regression coverage.
+- Harden live certification CI and add an exact-version website documentation dispatch probe.
+
+## 0.5.0
+
+- Add local artifact initialization and package inspection.
+- Add workspace and draft discovery, durable deployment progress, trusted smoke validation, and plan-bound draft cleanup.
+- Add strict tool schemas, safety annotations, structured recovery guidance, OAuth hardening, and package-boundary protections.

package/README.md

@@ -1,128 +1,104 @@
 # Topline Build MCP
 
-Local stdio MCP connector for deploying Topline artifact app drafts from Codex,
-Claude Code, or another local MCP host.
+Local stdio MCP connector for creating, inspecting, and deploying private Topline artifact app drafts from Codex, Claude Code, or another MCP host.
 
-The normal auth path is OAuth with browser approval. The helper stores OAuth
-refresh tokens in the user's local Topline config directory, outside the project
-repo.
+The canonical customer guide is [Topline Build MCP documentation](https://topline.build/docs/build-mcp-guide). The package also ships a generated [runtime reference](docs/generated/build-mcp-reference.md) and [machine-readable manifest](docs/generated/build-mcp-manifest.json) for the exact package version.
 
-Required environment:
+## Quick start
 
-- `TOPLINE_API_URL` or `--url https://your-topline-host`
-
-Optional environment:
-
-- `TOPLINE_MCP_SURFACE` (`build` by default; `harness` for legacy compatibility)
-- `TOPLINE_MCP_PROTOCOL_VERSION`
-- `TOPLINE_WORKSPACE_ROOT`
-- `TOPLINE_MCP_AUTH_FILE`
-- `TOPLINE_MCP_SCOPES`
-- `TOPLINE_MCP_TIMEOUT_MS`
-- `TOPLINE_MCP_TOKEN` for advanced manual-token fallback
-
-Compatibility aliases are still accepted for older local setups:
+```bash
+npx -y @topline-build/harness-mcp --url https://YOUR-TOPLINE-HOST
+```
 
-- `PLATFORM_API_URL`
-- `PLATFORM_MCP_TOKEN`
-- `PLATFORM_WORKSPACE_ROOT`
-- `PLATFORM_MCP_PROTOCOL_VERSION`
+The first authenticated tool call normally opens Topline in a browser for OAuth approval. Refresh credentials are cached in the user's local Topline config directory, outside the project repository. Developer Access in Topline provides ready-to-use Codex and Claude Code configuration snippets without embedding a raw token.
 
-## Usage
+Set `TOPLINE_WORKSPACE_ROOT` when the MCP host starts outside the repository containing the artifact app:
 
 ```bash
+TOPLINE_API_URL=https://YOUR-TOPLINE-HOST \
+TOPLINE_WORKSPACE_ROOT=/path/to/workspace \
 npx -y @topline-build/harness-mcp
 ```
 
-For local checks:
+Run `npx -y @topline-build/harness-mcp --help` for every supported flag and environment variable. `TOPLINE_MCP_TOKEN` is an advanced manual-token fallback; browser-approved OAuth is preferred.
 
-```bash
-npx -y @topline-build/harness-mcp --help
-npx -y @topline-build/harness-mcp --url https://hawx.topline.build
-```
+## Typical workflow
+
+1. Use `platform_init_artifact_app` to create a starter, or point at an existing artifact app.
+2. Use `platform_inspect_artifact_app` to check local package boundaries and record its bundle SHA-256.
+3. Use `platform_deploy_artifact_app` with that SHA-256 to create or update a private draft.
+4. Use `platform_wait_artifact_deploy`, `platform_run_artifact_smoke`, and `platform_validate_artifact` for durable deployment and render evidence.
+5. Use the plan-then-delete tools for reviewed cleanup.
 
-Set `TOPLINE_WORKSPACE_ROOT` when your MCP host starts outside the repo that
-contains the artifact app.
-
-The app can live anywhere under that workspace. For source tracking, the MCP
-maps ordinary local folders to `artifact-apps/<manifest-id>` while preserving
-existing `artifact-apps/<name>` roots and workspace-root (`.`) apps. Deploys
-report manifest, packaging, draft creation, upload, and trusted-deployment
-progress to clients that support MCP progress notifications.
-Every deploy also receives a deterministic retry key. If a client loses the
-response and repeats the call, Topline resumes the same private draft instead
-of creating an ordinary duplicate.
-
-Topline Developer Access provides Build MCP snippets for Codex and Claude Code.
-Those snippets contain no raw token; the first tool call opens a browser
-approval flow scoped to artifact building.
-
-## Build workflow
-
-- `platform_init_artifact_app` creates a dependency-free starter in an empty
-  local directory.
-- `platform_connection_check` completes the one-time verification shown in
-  Developer Access.
-- `platform_list_build_workspaces` and `platform_list_artifact_drafts` discover
-  valid placement targets and recover existing drafts without exposing chat or
-  memory data.
-- `platform_deploy_artifact_app` packages the local app and deploys a private
-  draft through Topline's trusted runtime. Its `operationId` can be passed to
-  `platform_wait_artifact_deploy` for server-derived progress and recovery
-  after a disconnected client.
-- `platform_run_artifact_smoke` reruns trusted draft rendering and returns the
-  fresh evidence used by validation.
-- `platform_validate_artifact` returns bounded trusted smoke and rendered-page
-  evidence without requiring the agent to hold a browser session.
-- `platform_artifact_status`, `platform_read_artifact_logs`, and
-  `platform_open_artifact` inspect and hand off the draft.
-- `platform_plan_artifact_draft_delete` previews cleanup effects. Deletion uses
-  a separately approved `harness:artifact:delete` scope, the exact artifact id,
-  and the current plan token; stale plans fail closed.
-
-Tool failures include a stable error code, retryability, and a concrete
-recovery action in `structuredContent`.
-
-## Live certification
-
-After building the package, a release operator can exercise the real MCP client
-protocol, workspace discovery, deploy/resume, smoke, validation, and cleanup
-planning against a tenant:
+The generated reference is authoritative for tool names, input/output schemas, safety annotations, configuration, structured errors, and recovery guidance. Runtime `tools/list` and the reference are generated from the same registry.
+
+## Maintainers
+
+See [Documentation maintenance](docs/DOCUMENTATION_MAINTENANCE.md) before changing tools, flags, authentication, errors, packaging, or releases. Validate with:
 
 ```bash
+npm ci
+npm run docs:check
+npm run typecheck
+npm test
 npm run build
-TOPLINE_API_URL=https://tenant.example \
-TOPLINE_MCP_TOKEN=... \
-TOPLINE_WORKSPACE_ROOT=/path/to/workspace \
-TOPLINE_CERTIFICATION_APP_DIR=artifact-apps/certification \
-npm run certify:live
+npm pack --dry-run
 ```
 
-Set `TOPLINE_CERTIFICATION_CLEANUP=1` only when the certification draft should
-be removed after its cleanup plan is reviewed.
+Client certification has two explicit phases and writes a machine-readable JSON
+report. First run the read-only plan:
 
-## Storybook
+```bash
+TOPLINE_API_URL=https://YOUR-TOPLINE-HOST \
+TOPLINE_WORKSPACE_ROOT=/path/to/workspace \
+TOPLINE_CERTIFICATION_APP_DIR=artifact-apps/example \
+npm run certify:clients -- --agent-mediated --output certification-plan.json
+```
 
-Use the `platform_storybook_access` tool to get the tenant Storybook preview URL
-and the HTTP MCP client config. For clients with HTTP MCP OAuth support, use
-the returned `cursorMcpJson`:
+Review the reported bundle SHA-256. An authorized operator can then supply a
+short-lived manual token and apply that exact reviewed bundle:
 
-```json
-{
-  "mcpServers": {
-    "storybook": {
-      "url": "https://your-topline-host/api/design-systems/storybook/mcp",
-      "type": "http"
-    }
-  }
-}
+```bash
+TOPLINE_MCP_TOKEN=... npm run certify:clients -- \
+  --phase apply \
+  --expected-bundle-sha256 <reviewed-sha256> \
+  --require-all \
+  --output certification-apply.json
 ```
 
-Storybook MCP access uses the harness bearer/OAuth credentials with
-`harness:artifact:read`; OAuth discovery is available at
-`/.well-known/oauth-protected-resource/mcp/build`.
-
-If your MCP client does not support HTTP MCP OAuth, use the returned
-`manualBearerMcpJson` template with a read-scoped `TOPLINE_MCP_TOKEN` in the
-client's secret mechanism. Opening the visual preview URL in a browser still
-requires a signed-in Topline session.
+Normal customer setup should use browser-approved OAuth. The manual token is a
+noninteractive certification boundary only; never put it in CLI arguments,
+configuration files, reports, or logs. The report keeps actual CLI
+configuration health, SDK-level `protocolToolDiscovery`, and the optional
+provider-backed `clientMediatedRead` as separate evidence. `--agent-mediated`
+can consume provider model quota and runs only for clients whose CLI can reject
+user/global MCP configuration and disable every built-in tool. Claude Code is
+currently the supported mediated client; Codex and Cursor report
+`strict_client_tool_isolation_unavailable` instead of starting an agent with
+broader access. The Claude process uses strict MCP configuration, bare mode,
+no built-in tools, an allowlisted environment, an isolated OAuth cache, and a
+server exposing only `platform_inspect_artifact_app`. Its bare noninteractive
+permission bypass is accepted only when Claude's structured init event proves
+that this is the sole effective tool and MCP server. The write credential is
+available only to the direct exact-SHA apply path. Missing client CLIs, provider
+login, URL/app inputs, or credentials produce explicit `skipped` results and
+exit successfully by default; `--require-all` exits 2 for any skip. A failed
+check exits 1. Cursor may report that project MCP approval is required; approve
+it through Cursor, then rerun rather than changing global state from the
+script. Cleanup is separate and runs only with
+`TOPLINE_CERTIFICATION_CLEANUP=1`.
+
+CI's no-network self-test sets top-level `evidenceMode` to `simulated`; it is a
+schema/control-flow gate and must never be presented as live client evidence.
+
+A weekly and manually dispatchable GitHub canary runs one real Claude Code
+read-only call against the inert `fixtures/certification-app` package. It pins
+the client version, caps provider spend at USD 0.25, exposes only
+`platform_inspect_artifact_app`, passes an allowlisted process environment, and
+uploads the redacted JSON report for seven days. It requires the dedicated
+`TOPLINE_CERTIFICATION_ANTHROPIC_API_KEY` repository secret and fails closed
+when that credential is absent. It performs no Topline API write or customer
+deployment.
+
+Local validation and certification do not publish npm, deploy Topline, merge a
+documentation pull request, or release to customers.

package/dist/index.d.ts

@@ -30,11 +30,24 @@ export interface PackedArtifactAppBundle {
     excluded: string[];
 }
 type ToolProgressReporter = (progress: number, message: string) => void | Promise<void>;
-export declare const HARNESS_MCP_VERSION = "0.4.0";
+export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
+export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
+export declare const HARNESS_MCP_VERSION = "0.5.1";
+export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
+export interface BuildMcpSetupOption {
+    readonly flag: string;
+    readonly env: string;
+    readonly aliases?: readonly string[];
+    readonly required?: boolean;
+    readonly default?: string | number;
+    readonly allowed?: readonly string[];
+    readonly description: string;
+}
+export declare const BUILD_MCP_SETUP_OPTIONS: readonly BuildMcpSetupOption[];
 export declare function parseHarnessOptions(argv: string[], env?: Record<string, string | undefined>): HarnessMcpStdioOptions;
 export declare function runHarnessMcpStdioCli(): Promise<void>;
 export declare function cliInfo(argv: string[]): string | null;
-export declare function createHarnessMcpStdioServer(opts: HarnessMcpStdioOptions): McpServer;
+export declare function createHarnessMcpStdioServer(opts: HarnessMcpStdioOptions, toolAllowlist?: readonly string[]): McpServer;
 export declare function callHarnessTool(opts: HarnessMcpStdioOptions, name: string, args: unknown, hooks?: {
     onProgress?: ToolProgressReporter;
 }): Promise<CallToolResult>;
@@ -54,6 +67,26 @@ export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: R
     create: unknown;
     deploy: unknown;
 }>;
+export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
+    ok: boolean;
+    packageReady: boolean;
+    serverManifestValidationRequired: boolean;
+    appDir: string;
+    platformAppDir: string;
+    manifest: {
+        id: string | null;
+        manifestVersion: number | null;
+        title: string | null;
+        kind: string | null;
+    };
+    bundle: {
+        fileCount: number;
+        byteCount: number;
+        sha256: string;
+        excluded: string[];
+    };
+    nextAction: string;
+}>;
 export declare function waitForArtifactDeploy(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<Record<string, unknown>>;
 export declare function initArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
     ok: boolean;
@@ -129,6 +162,11 @@ export declare function storybookAccess(opts: HarnessMcpStdioOptions): {
 };
 export declare function packArtifactAppDirectory(appDir: string, archivePrefix?: string): Promise<PackedArtifactAppBundle>;
 export declare function listTools(): ListToolsResult;
+export interface BuildMcpRecoveryGuidance {
+    readonly retryable: boolean;
+    readonly recoveryAction: string;
+}
+export declare const BUILD_MCP_RECOVERY_ERRORS: Readonly<Record<string, BuildMcpRecoveryGuidance>>;
 export declare function getBearerToken(opts: HarnessMcpStdioOptions): Promise<string>;
 export declare function browserOpenCommand(url: string, platform?: string): {
     command: string;