# @shippp/mcp

Pull production-perfect UI code from your Shippp design files straight into your IDE agent (Claude Code, Cursor, …), and keep a repository current over the official receipt-tracked sync.

## Setup

1. Create an API key in your Shippp workspace settings. It's shown once — copy it.
2. Add the server to your IDE's MCP config:

```json
{
  "mcpServers": {
    "shippp": {
      "command": "npx",
      "args": ["-y", "@shippp/mcp"],
      "env": {
        "SHIPPP_API_KEY": "sk_...",
        "SHIPPP_API_URL": "https://app.shippp.ai"
      }
    }
  }
}
```

`SHIPPP_API_URL` is optional (defaults to the Shippp production URL).

## Tools

| Tool | Returns |
|---|---|
| `shippp_list_units` | The file's screens + components (id + name). Call first to discover ids. |
| `shippp_get_component` | One component's Chakra `.tsx`. |
| `shippp_get_tokens` | The design tokens as a Chakra theme. |
| `shippp_get_design_system` | The whole design system as a package. |
| `shippp_get_project` | The whole file as a runnable Next.js project. |
| `shippp_diff` | Your current code vs a fresh generation. |
| `shippp_sync_plan` | Deterministic sync plan for the bound repository — no writes. |
| `shippp_sync_apply` | The full sync run: artifact → plan → apply → checks → receipt. |

The server never modifies your design. The sync tools write ONLY under the
generated root recorded in the repo's own committed `shippp.target.json`
binding (created with `shippp_bind_repository` on the Shippp remote MCP):
hand-modified generated files are structured conflicts and are never
overwritten, a failed check rolls everything back, and the receipt is written
only on full success. A compiler/IR/adapter upgrade needs the user's explicit
approval of the exact delta.

## Repository sync (CLI)

The same deterministic runner ships as a CLI:

```bash
# preview (no writes)
SHIPPP_API_KEY=sk_... npx @shippp/mcp plan --root .

# full sync: apply + checks + receipt, with rollback
SHIPPP_API_KEY=sk_... npx @shippp/mcp sync --root . --check "npm run typecheck"
```

Flags: `--root <repo>` (default: cwd), `--check <cmd>` (repeatable; runs after
apply, before the receipt), `--allow-compiler-upgrade` (explicit consent to a
pending compiler/IR/adapter delta), `--accept-rebound-baseline` (adopt the
previous binding's receipt as baseline after an approved re-bind). In server
mode the repo root comes from `SHIPPP_REPO_ROOT` (or the server's cwd) and the
check command from `SHIPPP_SYNC_CHECKS` — developer configuration, never tool
input. Exit codes: `0` success, `2` structured refusal, `1` error.

## MCP Registry

Published to the official MCP Registry as `ai.shippp/mcp`.