--- updatedAt: 2026-08-17T04:10:49.000Z agentTools: projectIndex: https://dev.tapcart.com/llms.txt --- # MCP (local CLI server) This MCP server exposes Tapcart CLI capabilities (project setup, blocks, components, layouts, dependencies, auth, logs, lint, docs search, etc.) to MCP-compatible clients like Windsurf/Cursor via a local process. > 📘 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](https://dev.tapcart.com/docs/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` ```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: ```json { "projectPath": "/absolute/path/to/your/tapcart-project" } ``` ### 2) List remote blocks * Tool: `tapcart_blocks_listRemote` * Input: ```json { "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: ```json { "projectPath": "/absolute/path/to/your/tapcart-project", "includeCode": true } ``` ### 3) Pull a block locally * Tool: `tapcart_blocks_pull` * Input: ```json { "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): ```json { "projectPath": "/absolute/path/to/your/tapcart-project", "labels": ["MyBlock"] } ``` Example (apply): ```json { "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 | Tool | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tapcart_project_info` | Return resolved project configuration and environment info for a project path. | | `tapcart_project_create` | Scaffold a new Tapcart custom-blocks project (config, package.json, `blocks/`/`components/` dirs, root `mockData.json`, editor IntelliSense). Requires `appId` and `folderPath`. | | `tapcart_types_sync` | Write/refresh `.tapcart/types/` + `jsconfig.json` for editor IntelliSense. | | `tapcart_auth_status` | Return local Auth0 credential status from `~/.tapcart/auth.json`. | | `tapcart_auth_login_instructions` | Return the command to run to log in via browser. | | `tapcart_auth_logout` | Clear local credentials. | | `tapcart_dev_instructions` | Return the terminal command to start the local hot-reload dev server (`devMode`: `block` \| `component` \| `layout`, plus `target`/`port`/`verbose`). Does not start the server itself. | ### Blocks & Components | Tool | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `tapcart_blocks_createLocal` | Scaffold a new block folder locally. | | `tapcart_blocks_listRemote` | List remote blocks for the configured `appId` (summary by default; `includeCode` for full payloads). | | `tapcart_blocks_pull` | Pull one/all remote blocks into `./blocks` (optionally a specific `version` for a single block). | | `tapcart_blocks_push` | Build and push local blocks to the dashboard. Mode-gated. | | `tapcart_block_versions_list` | List all versions of a block and flag which is local vs. live. | | `tapcart_block_versions_set` | Set the active (live) version of a block. Mode-gated. | | `tapcart_components_createLocal` | Scaffold a new component folder locally. | | `tapcart_components_listRemote` | List remote components for the configured `appId`. | | `tapcart_components_pull` | Pull one/all remote components into `./components` (optionally a specific `version` for a single component). | | `tapcart_components_push` | Build and push local components to the dashboard. Mode-gated. | | `tapcart_component_versions_list` | List all versions of a component and flag which is local vs. live. | | `tapcart_component_versions_set` | Set the active (live) version of a component. Mode-gated. | ### Layouts All layout tools operate on local layout files under `.tapcart/layouts` (read-only unless noted). | Tool | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `tapcart_layout_new` | Create a new local layout (`tabbed` for a tabbed layout). | | `tapcart_layout_add` | Add a local block/component to a layout by folder name. Auto-resolves the layout if omitted and only one exists. | | `tapcart_layout_remove` | Remove a block from a layout by index or `as` handle. | | `tapcart_layout_reorder` | Move a block from one index (`from`) to another (`to`) within a layout. | | `tapcart_layout_set` | Set `manifestConfig` values on a block within a layout (`kv` key=value pairs). | | `tapcart_layout_tab_add` | Add a tab to a tabbed layout. | | `tapcart_layout_tab_remove` | Remove a tab from a tabbed layout. | | `tapcart_layout_tab_rename` | Rename a tab on a tabbed layout. | | `tapcart_layout_list` | List local layouts (read-only). | | `tapcart_layout_show` | Print a local layout file (read-only). | | `tapcart_layout_validate` | Validate one or all local layouts against the schema and available local block folders (read-only). | ### Dependencies | Tool | Description | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `tapcart_dependencies_listLocal` | List dependencies configured in `tapcart.config.json`. | | `tapcart_dependencies_addLocal` | Add a dependency locally (validates against esm.sh unless `validate: false`; use `force: true` to overwrite a conflicting version). | | `tapcart_dependencies_removeLocal` | Remove a dependency locally. | | `tapcart_dependencies_pullRemote` | Pull remote dependencies into `tapcart.config.json`. | | `tapcart_dependencies_pushRemote` | Push the local dependency list to the remote app config. Mode-gated. | ### Lint, Logs, Docs & Capabilities | Tool | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tapcart_lint` | Run ESLint on local blocks/components (`all: true`, or specific `blocks`/`components` arrays). Filesystem writes from `fix: true` only occur when `mode: "apply"`. | | `tapcart_log_show` | Show recent lines from `~/.tapcart/cli.log` (read-only; common secret patterns are redacted). | | `tapcart_docs_search` | Search Tapcart developer docs for conceptual/how-to questions. For API shapes (the `useTapcart()` hook, `BlockProps`, component props), prefer the local `.tapcart/types/*.d.ts` files instead. | | `tapcart_mcp_capabilities` | Return a structured overview of every registered tool, including which are mode-gated. | *** ## 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: ```json { "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](https://dev.tapcart.com/docs/tapcart-cli) instructions for creating your Tapcart project ***