quick-proto-mcp — Model Context Protocol server (stdio)

npx quick-proto-mcp@latest runs a local MCP server so Claude Desktop / Cursor-style clients can publish Quick Proto previews with tools instead of invoking the CLI in a subprocess.

Requires Node 20+.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS; paths differ on Windows):

{
  "mcpServers": {
    "quick-proto": {
      "command": "npx",
      "args": ["-y", "quick-proto-mcp@latest"],
      "env": {
        "QP_API_KEY": "your-api-key"
      }
    }
  }
}

Restart Claude after edits.

Alternatively, save credentials once with npx quick-proto-cli auth login so ~/.config/quick-proto/credentials.json exists — then omit env unless you rely on CI-style keys only.

Self-hosted Quick Proto instances: set PROTO_BASE_URL to your app origin (http:// or https:// only) before starting MCP.

Security

• Trust model: MCP runs locally over stdio with your API key from env or ~/.config/quick-proto/credentials.json. Never put API keys in tool arguments.
• zipPath: Resolved with realpath, must be a regular file with a ZIP local header (PK\x03\x04). Allowed directories:
  • process.cwd() or the OS temp directory, or
  • Paths under comma-separated absolute dirs in QUICK_PROTO_UPLOAD_ROOT (each entry must be an existing directory). Refuses obvious sensitive names (credentials.json, .env*, anything under .ssh/).
• publish_prototype / publish_prototype_base64: Default visibility is organization. Pass visibility: "public" only when you intend anyone-with-link access.
• list_versions: Returns a reduced payload (no org-member list or uploader emails) to limit data sent to the model.
• Least privilege: Prefer API keys scoped to the minimum org/project access needed for automation.

Auth

Uses the same Better Auth API key as the CLI (QP_API_KEY, optional credentials file).

Breaking change: Older releases documented BUNDLE_API_KEY / PROTO_API_KEY — those names are no longer read; update MCP env, CI secrets, and shell exports to QP_API_KEY.

Remote sandbox (Claude cloud, /home/claude/...)

upload_version / publish_prototype read zipPath on the machine running the MCP Node process — not the chat sandbox. Paths must lie under cwd, the system temp directory, or QUICK_PROTO_UPLOAD_ROOT, and must be real ZIP files (see Security above).

If the model creates the zip inside a remote sandbox, use the *_base64 tools instead:

1. In the sandbox: base64 -w0 bundle.zip (or read bytes and base64-encode).
2. Call publish_prototype_base64 or upload_version_base64 with zipBase64 (raw base64 or data:application/zip;base64,...).

Also available: upload_starter_base64, release_base64.

Limits: Base64 lives inside the MCP JSON payload; the host may cap tool argument size before you hit the platform’s 100 MB limit. Small/medium site exports work well; huge bundles need a local zipPath or another transfer path.

Projects and chatSummary

• Listing projects — Call list_projects with an org slug (GET /api/bundles/:org) after list_orgs to discover existing prototypes before list_versions or upload.
• New projects — There is no separate create-project tool. The first bundle upload with a new project slug under an org creates the project (same as the dashboard “Create a new prototype”).
• chatSummary (required) — upload_version, upload_version_base64, publish_prototype, publish_prototype_base64, release, and release_base64 all require a chatSummary string: a short description of what the agent built or changed in that session, stored on the version for anyone who downloads it later.

Tools

| Tool | Purpose | | --- | --- | | list_orgs | Organizations for this key (GET /api/cli/me) | | list_projects | Project slugs + stats for an org (GET /api/bundles/:org) | | list_versions | Project bundle metadata + versions (project must exist after first upload; emails / org members omitted) | | upload_version | Upload SPA zip from local disk; chatSummary required; creates project if slug is new | | upload_version_base64 | Upload SPA zip from base64 (sandbox-friendly); chatSummary required | | set_project_visibility | PATCH visibility (public for link sharing) | | publish_prototype | Upload from path + set visibility; chatSummary required; creates project if slug is new | | publish_prototype_base64 | Same as publish_prototype but zipBase64; chatSummary required | | delete_version | DELETE one version | | get_download_url | Signed download URL (~15 min) | | upload_starter | Starter zip from path (project must already exist) | | upload_starter_base64 | Starter zip from base64 | | release | Bundle + starter zips from paths; chatSummary required on bundle | | release_base64 | Bundle + starter from base64; chatSummary required on bundle |

Manual check (MCP Inspector)

npm run build --workspace=quick-proto-mcp
npx @modelcontextprotocol/inspector@latest
# Transport: STDIO → command node → args: path/to/repo/packages/mcp/dist/index.js → cwd repo root if needed → env KEY

Prefer rebuilding first so dist/index.js matches source.

Publishing to npm

From repo root after bumping versions (publish quick-proto-client before quick-proto-cli and quick-proto-mcp, since both declare it as a dependency). prepack runs npm run build for each workspace before pack/publish.

npm install
npm run test --workspace=quick-proto-client
npm run test --workspace=quick-proto-cli
npm run test --workspace=quick-proto-mcp
npm publish --workspace=quick-proto-client --access public
npm publish --workspace=quick-proto-cli --access public
npm publish --workspace=quick-proto-mcp --access public

Dry run: append --dry-run.

Post-publish smoke: npx quick-proto-cli@latest --help and set QP_API_KEY when exercising orgs list or MCP list_orgs.

Troubleshooting

• 401 / 403 — missing or stale API key; org slug must match a membership on the platform.
• 422 on upload — zip missing index.html or malformed zip.