# Figma MCP Server

MCP Server để lấy cấu trúc JSON từ Figma, dùng cho các AI Coding Agent hỗ trợ giao thức Model Context Protocol (Continue extension, Claude Desktop, Cursor, v.v.).

## Yêu cầu

- Node.js >= 18
- Figma Personal Access Token

## Cài đặt

### 1. Clone repository

```bash
git clone <repository-url>
cd figma-mcp
```

### 2. Cài dependencies

```bash
npm install
```

### 3. Lấy Figma Token

Vào [Figma Settings > Personal Access Tokens](https://www.figma.com/settings) tạo token mới với scope `file_read`.

## Sử dụng

### Khởi động server (stdio)

Set biến môi trường rồi chạy:

```bash
export FIGMA_ACCESS_TOKEN="your-figma-token"
node index.js
```

Server chạy im lặng qua stdio, chờ nhận request từ MCP client.

## API (MCP Tools)

### `get_figma_from_url`

Lấy cấu trúc JSON của file Figma hoặc một node cụ thể.

**Parameters:**

| Parameter | Type   | Required | Mô tả                                                         |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `url`     | string | ✅       | URL file Figma (hỗ trợ cả URL có `node-id`)                   |
| `depth`   | number | ❌       | Giới hạn độ sâu cây (2 hoặc 3 để lấy plan; bỏ trống lấy full) |

**Ví dụ URL:**

- File: https://www.figma.com/file/ABC123/design-name
- Node: https://www.figma.com/file/ABC123/design-name?node-id=123-456

**Response:** JSON string chứa cấu trúc Figma.

## Cấu hình cho Continue Extension (VS Code)

Thêm vào file `~/.continue/config.json` (hoặc Continue > Configuration):

```json
{
  "experimental": {
    "mcpServers": {
      "figma": {
        "command": "/usr/bin/node",
        "args": ["/path/to/figma-mcp/index.js"],
        "env": {
          "FIGMA_ACCESS_TOKEN": "your-figma-token"
        }
      }
    }
  }
}
```

> **Lưu ý:** Thay `/path/to/figma-mcp/index.js` bằng đường dẫn tuyệt đối tới file index.js trong repo. Nếu dùng Windows, thay `/usr/bin/node` bằng đường dẫn tới node.exe.

## Caching

- Cache lưu trong thư mục `.figma_cache` tại thư mục chạy server
- Thời gian sống: 1 giờ
- Cache key: MD5 hash của endpoint

## Sử dụng Prompts với Continue Extension (Bộ 3 bước Figma -> Block)

Thư mục `prompts/examples/continue-extensions/` chứa 3 file prompt giúp tự động hoá việc quét Figma, phân tích và sinh code HTML/Tailwind + JSON.

### Cài đặt Prompts

Copy 3 file `.prompt.md` vào thư mục prompts của Continue:

```bash
cp prompts/examples/continue-extensions/*.prompt.md ~/.continue/prompts/
```

Nếu muốn dùng thư mục khác, thêm cấu hình trong `~/.continue/config.json`:

```json
{
  "experimental": {
    "mcpServers": {
      "figma": { ... }
    }
  },
  "prompts": {
    "include": [
      "/path/to/figma-mcp/prompts/examples/continue-extensions"
    ]
  }
}
```

### Luồng thực thi 3 bước

#### Bước 1: Quét Page Figma → Master Plan

Gọi lệnh trong Continue Chat:

```
/figma-page https://www.figma.com/file/ABC123/design-name
```

Kết quả: Tạo file `plans/page-master.md` chứa danh sách các Section và lệnh copy-paste.

#### Bước 2: Phân tích Section → Plan chi tiết

Từ danh sách ở Bước 1, copy từng lệnh và chạy:

```
/figma-section https://www.figma.com/file/ABC123/design-name?node-id=123-456 -> src/blocks/hero
```

Kết quả: Tạo file `src/blocks/hero/plan.md` chứa DOM Tree, JSON Schema, responsive strategy.

#### Bước 3: Build HTML/Tailwind + JSON từ Plan

Gọi lệnh:

```
/figma-build src/blocks/hero
```

Kết quả: Sinh file `src/blocks/hero/index.html` và `src/blocks/hero/data.json`.

> **Lưu ý:** Bước 3 yêu cầu tool `save_component_data` do Node.js MCP server cung cấp (cần implement riêng nếu chưa có).

## License

ISC