MCP

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)

Configure MCP Server

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

Cursor: $HOME/.cursor/mcp.json

{
  "mcpServers": {
    "tapcart-cli": {
      "command": "npx",
      "args": ["-y", "@tapcart/[email protected]", "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.

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" }

Long-running commands (block dev / component dev / layout dev)

For long-running dev servers, the MCP tools return instructions (commands to run) rather than starting a background process.

Use:

• tapcart_blocks_dev_instructions
• tapcart_components_dev_instructions
• tapcart_layout_dev_instructions

Then 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.
• Local filesystem writes happen for tools like:
  • tapcart_blocks_createLocal
  • tapcart_components_createLocal
  • tapcart_blocks_pull
  • tapcart_components_pull
• 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