# F_MCP - Claude Code x Figma MCP Bridge

Claude Code에서 Figma를 직접 제어하는 MCP(Model Context Protocol) 브릿지입니다.
[grab/cursor-talk-to-figma-mcp](https://github.com/grab/cursor-talk-to-figma-mcp)를 포크하여 **이미지 삽입, 레지스트리 패턴, Claude Code 스킬** 등을 추가한 확장 버전입니다.

## Architecture

```
Claude Code
    |
    |--- MCP (stdio) ---> mcp-server      (도구 등록 + WebSocket 중계)
    |                         |
    |--- MCP (stdio) ---> mcp-ws-image    (이미지 fetch + base64 변환)
    |                         |
    +---- WebSocket (port 3055) ----------> Figma Plugin (code.ts)
                                                |
                                            Figma API
```

### 3-Layer 구조

| Layer | 경로 | 역할 |
|-------|------|------|
| **MCP Server** | `mcp-server/` | Claude Code와 Figma 중계. registry 패턴으로 도구 자동 등록 |
| **Image MCP Server** | `mcp-ws-image/` | 이미지 URL fetch -> base64 변환 -> WebSocket 전달 (별도 MCP) |
| **Figma Plugin** | `figma-plugin/` | Figma 내부 API 실행. base64 이미지 디코딩 + 적용 |

## Why Custom?

공식 `cursor-talk-to-figma-mcp`에는 **이미지 삽입 기능이 없습니다.**

Figma 플러그인 샌드박스는 외부 CDN에 직접 접근할 수 없기 때문에:

1. **MCP 서버**에서 이미지를 fetch
2. **base64**로 인코딩하여 WebSocket으로 전달
3. **플러그인**에서 디코딩 후 `figma.createImage()` 호출

이 우회 경로를 구현한 것이 이 프로젝트의 핵심입니다.

## Quick Start

### 1. 의존성 설치

```bash
# MCP Server
cd mcp-server && npm install && npm run build

# Image MCP Server
cd mcp-ws-image && npm install && npm run build

# Figma Plugin
cd figma-plugin && npm install && npm run build
```

### 2. Figma Plugin 등록

Figma Desktop App에서:
1. Menu > Plugins > Development > Import plugin from manifest
2. `figma-plugin/manifest.json` 선택
3. 플러그인 실행 후 **Connect** 클릭 -> 채널명 확인 (예: `c32c7nbc`)

### 3. MCP 서버 등록

프로젝트 루트의 `.mcp.json`:

```json
{
  "mcpServers": {
    "set_node_image_fill": {
      "command": "node",
      "args": ["./mcp-ws-image/dist/index.js"]
    }
  }
}
```

> **Note:** `TalkToFigma` MCP는 별도로 npm 글로벌 설치하거나, `mcp-server/dist/index.js`를 등록합니다.

### 4. Claude Code에서 사용

```
# 채널 연결
> join_channel("c32c7nbc")

# 프레임 생성
> create_frame(x=0, y=0, width=1080, height=1080, name="Banner")

# 이미지 적용
> set_node_image_fill(channel="c32c7nbc", nodeId="44:56", imageUrl="https://...")
```

## Project Structure

```
F_MCP/
├── mcp-server/                 # MCP Server (도구 중계)
│   └── src/
│       ├── index.ts            # 서버 엔트리포인트
│       ├── registry.ts         # 커맨드 레지스트리 (Single Source of Truth)
│       ├── tools/index.ts      # registry -> MCP 도구 자동 등록
│       ├── types/commands.ts   # 타입 자동 추출
│       ├── http/server.ts      # HTTP 서버
│       └── queue/              # 커맨드 큐
│
├── mcp-ws-image/               # Image MCP Server (이미지 전용)
│   └── src/
│       └── index.ts            # fetch -> base64 -> WebSocket
│
├── figma-plugin/               # Figma Plugin
│   ├── manifest.json           # 플러그인 메타 + 네트워크 허용 도메인
│   └── src/
│       ├── code.ts             # Figma API 핸들러 (set_image_fill 포함)
│       └── ui.ts               # WebSocket UI
│
├── .claude/
│   └── skills/                 # Claude Code Skills
│       ├── channel-specs/      # 마케팅 채널별 이미지 사이즈 규격표
│       └── add-figma-command/  # 새 커맨드 추가 가이드
│
├── .mcp.json                   # MCP 서버 등록 설정
└── .gitignore
```

## Adding New Commands

`registry.ts` + `code.ts` **2개 파일만** 수정하면 됩니다.

### Step 1: `mcp-server/src/registry.ts`에 커맨드 추가

```typescript
export const commandRegistry = {
  // ... 기존 커맨드들
  my_new_command: {
    description: 'Description for Claude Code',
    schema: z.object({
      nodeId: z.string().describe('Figma node ID'),
      // ... 파라미터
    })
  }
};
```

### Step 2: `figma-plugin/src/code.ts`에 핸들러 추가

```typescript
case 'my_new_command': {
  const node = figma.getNodeById(msg.nodeId);
  // Figma API 호출
  figma.ui.postMessage({
    type: 'result', success: true,
    nodeId: msg.nodeId, commandId: msg.commandId
  });
  break;
}
```

### Step 3: 빌드

```bash
cd mcp-server && npm run build
cd figma-plugin && npm run build
```

도구 자동 등록(`tools/index.ts`)이 처리하므로 다른 파일 수정은 불필요합니다.

## Claude Code Skills

이 프로젝트에는 Claude Code에서 자동 인식되는 스킬이 포함되어 있습니다.

| Skill | 용도 | 호출 |
|-------|------|------|
| `channel-specs` | 마케팅 채널별 이미지 사이즈 규격 (구글, 네이버, 무신사, Meta 등) | `/channel-specs` |
| `add-figma-command` | 새 Figma 커맨드 추가 가이드 | `/add-figma-command` |

Clone 후 Claude Code로 열면 자동으로 사용 가능합니다.

## Registered MCP Tools

### mcp-server (TalkToFigma)

| Tool | Description |
|------|-------------|
| `create_rect` | 사각형 생성 |
| `create_text` | 텍스트 생성 |
| `create_frame` | 프레임(컨테이너) 생성 |
| `create_image` | URL 이미지로 새 프레임 생성 |
| `set_fill` | 노드 채우기 색상 변경 |
| `set_image_fill` | 기존 노드에 이미지 URL 적용 |
| `move_node` | 노드 위치 이동 |
| `delete_node` | 노드 삭제 |

### mcp-ws-image (Image Fill)

| Tool | Description |
|------|-------------|
| `set_node_image_fill` | URL에서 이미지 fetch -> base64 변환 -> Figma 노드에 적용 |

## Image Flow Detail

```
1. Claude Code: set_node_image_fill(channel, nodeId, imageUrl)
2. mcp-ws-image: fetch(imageUrl) -> arrayBuffer -> base64
3. WebSocket:    { command: "set_image_fill", params: { nodeId, imageBase64, scaleMode } }
4. Figma Plugin: base64 decode -> Uint8Array -> figma.createImage(bytes)
5. Figma:        node.fills = [{ type: 'IMAGE', imageHash, scaleMode: 'FILL' }]
```

> Figma 플러그인 샌드박스에는 `atob()`이 없으므로 커스텀 base64 디코더를 사용합니다.

## Network Access

`figma-plugin/manifest.json`의 `networkAccess.allowedDomains`에 허용된 도메인:

- `ws://localhost:3055` (WebSocket 서버)
- `https://static-resource-mall.fnf.co.kr`
- `https://static-resource.mlb-korea.com`

새 도메인의 이미지를 사용하려면 이 목록에 추가 후 플러그인을 다시 빌드하세요.

## Credits

- Original: [grab/cursor-talk-to-figma-mcp](https://github.com/grab/cursor-talk-to-figma-mcp)
- License: MIT