@topline-build/harness-mcp 0.2.0 → 0.5.0

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
+
+- Generate a versioned runtime reference and machine-readable documentation manifest from the registry used by MCP `tools/list`.
+- Enforce documentation freshness in tests, continuous integration, and release validation.
+- Define documentation ownership, pull request impact review, release synchronization, and recurring maintenance.
+- Notify the website of an exact npm release immediately, with daily recovery and a review-only pull request boundary.
+- Add machine-readable Codex, Claude Code, and Cursor certification with distinct CLI, protocol, client-mediated read, structured failure, and reviewed apply evidence.
+
+## 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,75 +1,102 @@
 # 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
 
-Set `TOPLINE_WORKSPACE_ROOT` when your MCP host starts outside the repo that
-contains the artifact app.
+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.
 
-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.
+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.
 
-## Storybook
+## Maintainers
 
-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`:
+See [Documentation maintenance](docs/DOCUMENTATION_MAINTENANCE.md) before changing tools, flags, authentication, errors, packaging, or releases. Validate with:
 
-```json
-{
-  "mcpServers": {
-    "storybook": {
-      "url": "https://your-topline-host/api/design-systems/storybook/mcp",
-      "type": "http"
-    }
-  }
-}
+```bash
+npm ci
+npm run docs:check
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
 ```
 
-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`.
+Client certification has two explicit phases and writes a machine-readable JSON
+report. First run the read-only plan:
+
+```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
+```
+
+Review the reported bundle SHA-256. An authorized operator can then supply a
+short-lived manual token and apply that exact reviewed bundle:
+
+```bash
+TOPLINE_MCP_TOKEN=... npm run certify:clients -- \
+  --phase apply \
+  --expected-bundle-sha256 <reviewed-sha256> \
+  --require-all \
+  --output certification-apply.json
+```
 
-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, safe mode,
+no built-in tools, an allowlisted environment, an isolated OAuth cache, and a
+server exposing only `platform_inspect_artifact_app`. 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

@@ -29,17 +29,35 @@ export interface PackedArtifactAppBundle {
     sha256: string;
     excluded: string[];
 }
-export declare const HARNESS_MCP_VERSION = "0.2.0";
+type ToolProgressReporter = (progress: number, message: string) => void | Promise<void>;
+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.0";
+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 callHarnessTool(opts: HarnessMcpStdioOptions, name: string, args: unknown): Promise<CallToolResult>;
-export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
+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>;
+export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<{
     ok: boolean;
     artifactId: string;
     artifactVersionId: string;
     manifestId: string | null;
+    clientRequestId: string;
+    operationId: string | null;
     bundle: {
         fileCount: number;
         byteCount: number;
@@ -49,6 +67,35 @@ 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;
+    appDir: string;
+    manifestId: string;
+    title: string;
+    files: string[];
+    nextAction: string;
+}>;
 export declare function getArtifactStatus(opts: HarnessMcpStdioOptions, artifactId: string, limit?: number): Promise<unknown>;
 export declare function readArtifactLogs(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<unknown>;
 export declare function openArtifact(opts: HarnessMcpStdioOptions, artifactId: string): Promise<{
@@ -115,8 +162,14 @@ 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;
     args: string[];
 };
+export {};