# MCP server setup

## 1. Figma remote MCP

Used for: Reading FA 1.0 designs, extracting component context, getting design
properties for reference when building components.

### Setup

```bash
# Add the Figma remote MCP to Claude Code
claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp

# Restart Claude Code, then authenticate:
# Run /mcp → select figma-remote-mcp → Authenticate
# This opens a browser for Figma OAuth
```

### Verify connection

```bash
# In Claude Code:
/mcp
# Should show: figma-remote-mcp (connected)
```

### Usage

The Figma MCP is link-based. To use it:
1. Open your FA 1.0 Figma file
2. Select a frame or component
3. Copy the link (right-click → Copy link to selection, or copy from browser URL bar)
4. Paste the link in your Claude Code prompt

Example prompts:
- "Get the design context for this button: [figma-link]"
- "What colours and spacing does this card use? [figma-link]"
- "Extract the component structure of this form: [figma-link]"

### Rate limits

With a Figma Professional plan, you get per-minute rate limits (Tier 1 REST API
equivalent). This is sufficient for component-by-component extraction.

---

## 2. Storybook MCP

Used for: Querying the component library during composition — finding available
components, checking props, getting usage examples.

### Prerequisites

Storybook must be running locally before the MCP can connect.

```bash
# Start Storybook
npm run storybook
# This runs on http://localhost:6006 by default
```

### Setup — Standalone Storybook MCP

```bash
# Add the Storybook MCP server to Claude Code
claude mcp add storybook --transport http http://localhost:6006/mcp
```

Or add to `.mcp.json` in the project root:
```json
{
  "mcpServers": {
    "storybook": {
      "url": "http://localhost:6006/mcp",
      "type": "http"
    }
  }
}
```

**Note:** Storybook must be running before the MCP server can connect.

### Verify connection

```bash
# In Claude Code (with Storybook running):
/mcp
# Should show: storybook (connected)
```

### Usage

The Storybook MCP exposes tools for querying your component library:
- List all available components
- Get component props and their types
- Find components by keyword
- Get usage examples from stories

This is primarily used by the layout-composer agent (for later phases) to
discover and correctly use components when building page layouts.

---

## 3. Penpot MCP (for later — layout phase)

Setup instructions will be added when you reach the layout composition phase.
The Penpot MCP requires either the official Penpot MCP plugin running locally,
or the Docker-based server alongside a self-hosted Penpot instance.

---

## Troubleshooting

### Figma MCP not connecting
- Restart Claude Code completely (MCP connections initialise at startup)
- Re-authenticate: `/mcp` → select figma-remote-mcp → Authenticate
- Check you're on a Figma Professional plan (Starter has 6 calls/month)

### Storybook MCP not connecting
- Ensure Storybook is running (`npm run storybook`)
- Check the port: default is 6006, but it may use 6007+ if 6006 is occupied
- Restart Claude Code after starting Storybook

### General MCP issues
- Run `/mcp` to see status of all servers
- Check for error messages in the MCP status output
- Try removing and re-adding: `claude mcp remove <name>` then re-add