MCP (local CLI server)

📘

This is the local server for block development

It runs on your machine against a project on disk. If you want to query analytics or manage push campaigns and segments from an AI client, use the hosted Tapcart MCP server instead — nothing to install.

Prerequisites

• Node.js >= 20
• An MCP-compatible client (e.g. Windsurf, Cursor)
• A Tapcart project on disk (with tapcart.config.json and an appId configured) — or use tapcart_project_create to scaffold one

Configure MCP Server

Windsurf: $HOME/.codeium/windsurf/mcp_config.json

Cursor: $HOME/.cursor/mcp.json

{
  "mcpServers": {
    "tapcart-cli": {
      "command": "npx",
      "args": ["-y", "@tapcart/tapcart-cli@latest", "mcp"],
      "disabled": false,
      "disabledTools": [],
      "env": {
        "TAPCART_ENV": "production",
        "TAPCART_LOG_LEVEL": "ERROR"
      }
    }
  }
}

After editing config, restart your MCP client / MCP server integration.

Authenticate

Run the tool:

• tapcart_auth_status

If you are not authenticated, run:

• tapcart_auth_login_instructions

Follow the returned instructions (it opens a browser login and writes credentials to your local ~/.tapcart/auth.json). Then re-run tapcart_auth_status. To clear stored credentials, run tapcart_auth_logout.

Quick Start (first tools to try)

1) Project sanity check

• Tool: tapcart_project_info
• Input:

{ "projectPath": "/absolute/path/to/your/tapcart-project" }

2) List remote blocks

• Tool: tapcart_blocks_listRemote
• Input:

{ "projectPath": "/absolute/path/to/your/tapcart-project" }

By default this returns an LLM-friendly summary (not full block code).
If you explicitly want full code payloads:

{ "projectPath": "/absolute/path/to/your/tapcart-project", "includeCode": true }

3) Pull a block locally

• Tool: tapcart_blocks_pull
• Input:

{ "projectPath": "/absolute/path/to/your/tapcart-project", "labels": ["MyBlock"] }

4) Push changes (safe by default)

Remote-write tools are mode-gated:

• Default: mode omitted → behaves like "plan" (no remote write)
• To actually write: set "mode": "apply"

Example (plan):

{ "projectPath": "/absolute/path/to/your/tapcart-project", "labels": ["MyBlock"] }

Example (apply):

{ "projectPath": "/absolute/path/to/your/tapcart-project", "labels": ["MyBlock"], "mode": "apply" }

Available Tools

📘

Discover tools at runtime

tapcart_mcp_capabilities returns a structured, always-current list of every registered tool (name, description, input schema, and which tools are mode-gated). Use it if this reference ever drifts from the installed CLI version.

Project & Auth

Blocks & Components

Layouts

All layout tools operate on local layout files under .tapcart/layouts (read-only unless noted).

Dependencies

Lint, Logs, Docs & Capabilities

Long-running commands (dev server)

For the long-running dev server, tapcart_dev_instructions returns instructions (a command to run) rather than starting a background process — the MCP server itself never keeps a dev server alive.

• Tool: tapcart_dev_instructions
• Input:

{ "projectPath": "/absolute/path/to/your/tapcart-project", "devMode": "block", "target": "MyBlock" }

Omit devMode/target to launch the interactive picker in the browser instead. A single shared dev server handles block, component, and layout previews (default port 4995, override with port).

Run the returned command in a terminal and stop it with Ctrl+C when you're done.

Safety Notes

• Remote writes are gated behind mode: "apply" for tools that mutate remote state:
  • tapcart_blocks_push
  • tapcart_block_versions_set
  • tapcart_components_push
  • tapcart_component_versions_set
  • tapcart_dependencies_pushRemote
  • tapcart_lint (only when fix: true)
• Local filesystem writes happen unconditionally for tools like:
  • tapcart_project_create
  • tapcart_blocks_createLocal / tapcart_components_createLocal
  • tapcart_blocks_pull / tapcart_components_pull
  • tapcart_types_sync
  • All tapcart_layout_* tools except _list, _show, and _validate (which are read-only)
• tapcart_dependencies_addLocal / _removeLocal write to tapcart.config.json only (no remote call).
• tapcart_log_show returns local CLI logs but redacts common secret patterns.

Troubleshooting

Tools don't appear

• Restart the MCP integration in your client
• Verify CLI version:
  • tapcart --version

"Not authenticated"

• Run tapcart_auth_login_instructions and follow the steps
• Re-run tapcart_auth_status

"Missing appId"

• Ensure your Tapcart project contains tapcart.config.json with a valid appId
• See Getting Started instructions for creating your Tapcart project