Topline Build MCP

Local stdio MCP connector for creating, inspecting, and deploying private Topline artifact app drafts from Codex, Claude Code, or another MCP host.

The canonical customer guide is Topline Build MCP documentation. The package also ships a generated runtime reference and machine-readable manifest for the exact package version.

Quick start

npx -y @topline-build/harness-mcp --url https://YOUR-TOPLINE-HOST

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.

Set TOPLINE_WORKSPACE_ROOT when the MCP host starts outside the repository containing the artifact app:

TOPLINE_API_URL=https://YOUR-TOPLINE-HOST \
TOPLINE_WORKSPACE_ROOT=/path/to/workspace \
npx -y @topline-build/harness-mcp

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.

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.

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 before changing tools, flags, authentication, errors, packaging, or releases. Validate with:

npm ci
npm run docs:check
npm run typecheck
npm test
npm run build
npm pack --dry-run

Client certification has two explicit phases and writes a machine-readable JSON report. First run the read-only plan:

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:

TOPLINE_MCP_TOKEN=... npm run certify:clients -- \
  --phase apply \
  --expected-bundle-sha256 <reviewed-sha256> \
  --require-all \
  --output certification-apply.json

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.