# Figma + Notion MCP Server

Figma와 Notion API를 MCP(Model Context Protocol)로 노출하는 Python 서버입니다.
Claude Desktop, Cursor 등 MCP 클라이언트에서 Figma 파일·Notion 문서를 직접 조회·편집하고,
자연어로 디자인을 설명하면 **Figma에 자동으로 그려주는** 기능까지 제공합니다.

---

## MCP 엔드포인트

| 경로 | SSE URL | 설명 |
|------|---------|------|
| `/figma` | `http://localhost:8000/figma/sse` | Figma 파일 읽기 (8개 도구) |
| `/notion` | `http://localhost:8000/notion/sse` | Notion 페이지/DB 조회·편집 (7개 도구) |
| `/project` | `http://localhost:8000/project/sse` | Figma + Notion 통합 조회 (3개 도구) |
| `/draw` | `http://localhost:8000/draw/sse` | 자연어 → Figma 디자인 자동 생성 (8개 도구) |

---

## 프로젝트 구조

3-레이어 아키텍처입니다. 의존 방향은 **단방향** (`mcp → services → core`).

```
main.py                     # FastAPI 앱 — 4개 MCP 서버 마운트
src/
├── core/                   # 인프라 레이어
│   ├── config.py           # 환경변수 → Settings 싱글턴 (frozen dataclass + lru_cache)
│   └── http.py             # figma_client / notion_client async 컨텍스트 매니저
├── services/               # 비즈니스 레이어
│   ├── figma.py            # FigmaService — Figma REST API 호출 + 응답 가공
│   ├── notion.py           # NotionService — Notion API 호출 + 응답 가공
│   └── figma_draw.py       # FigmaDrawService — 디자인 명세 → Figma Plugin Script 생성
└── mcp/                    # 인터페이스 레이어
    ├── figma.py            # figma_mcp + @tool 8개
    ├── notion.py           # notion_mcp + @tool 7개
    ├── project.py          # project_mcp + @tool 3개
    └── draw.py             # draw_mcp + @tool 8개
```

---

## 설치 및 실행

### 1. 패키지 설치

```bash
pip install -r requirements.txt
```

### 2. 환경변수 설정

```bash
cp .env.example .env
```

`.env` 파일을 열어 토큰을 입력합니다.

```env
FIGMA_ACCESS_TOKEN=fig_xxxxxxxxxxxxxxxxxxxxxxxx
NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxx
```

#### Figma Personal Access Token 발급

1. [figma.com](https://www.figma.com/)에 로그인합니다.
2. 좌측 상단 프로필 아이콘 클릭 → **Settings**를 선택합니다.
3. **Security** 탭으로 이동합니다.
4. **Personal access tokens** 섹션에서 **Generate new token**을 클릭합니다.
5. 토큰 이름을 입력하고 (예: `mcp-server`), 만료 기간을 선택합니다.
6. **Scopes**는 기본값(File content: Read only)이면 충분합니다.
7. 생성된 `fig_` 로 시작하는 토큰을 복사하여 `.env`의 `FIGMA_ACCESS_TOKEN`에 붙여넣습니다.

> **주의**: 토큰은 생성 직후에만 표시됩니다. 페이지를 벗어나면 다시 확인할 수 없으므로 바로 복사하세요.

#### Notion Integration Secret 발급

1. [notion.so/my-integrations](https://www.notion.so/my-integrations)에 접속합니다.
2. **새 API 통합 만들기** (New integration)를 클릭합니다.
3. 기본 정보를 입력합니다:
   - **이름**: 원하는 이름 (예: `MCP Server`)
   - **연결된 워크스페이스**: API로 접근할 워크스페이스 선택
4. **기능** 설정:
   - 콘텐츠 읽기: 허용
   - 콘텐츠 업데이트: 허용 (페이지 생성·수정 기능을 쓸 경우)
   - 콘텐츠 삽입: 허용
5. **제출**을 클릭하면 `secret_`으로 시작하는 Internal Integration Secret이 표시됩니다.
6. 토큰을 복사하여 `.env`의 `NOTION_API_KEY`에 붙여넣습니다.

> **중요 — 페이지 연결 필수**: Integration을 만들었더라도, 접근할 Notion 페이지/데이터베이스에 직접 연결해야 합니다.
>
> 1. 접근할 Notion 페이지를 엽니다.
> 2. 우측 상단 `···` 메뉴 클릭 → **연결** (Connections)을 선택합니다.
> 3. 방금 만든 Integration 이름을 검색하여 추가합니다.
> 4. 하위 페이지에도 접근 허용할지 확인 후 승인합니다.
>
> 이 단계를 빠뜨리면 API 호출 시 `403 Forbidden` 에러가 발생합니다.

### 3. 서버 실행

```bash
python3 main.py
```

개발 중 자동 재시작:

```bash
uvicorn main:app --reload --port 8000
```

`http://localhost:8000/` 에서 전체 엔드포인트 목록을 확인할 수 있습니다.

---

## 사용자 연동 가이드

MCP 서버가 배포되어 있다면, 아래 설정만으로 바로 사용할 수 있습니다.

> 아래 예시의 `https://your-mcp-server.com`을 실제 배포 URL로 바꿔주세요.

### Claude Code (CLI)

터미널에서 아래 명령을 실행합니다.

```bash
# 필수 (Figma + Notion + 통합)
claude mcp add --transport sse soldoc-figma https://your-mcp-server.com/figma/sse
claude mcp add --transport sse soldoc-notion https://your-mcp-server.com/notion/sse
claude mcp add --transport sse soldoc-project https://your-mcp-server.com/project/sse

# 선택
claude mcp add --transport sse soldoc-draw https://your-mcp-server.com/draw/sse
claude mcp add --transport sse soldoc-asana https://your-mcp-server.com/asana/sse
```

등록 확인:

```bash
claude mcp list
```

Claude Code 실행 후 `/mcp` 명령으로 연결 상태를 확인할 수 있습니다.

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)을 열고 `mcpServers`에 추가합니다.

> **사전 요구**: Node.js 18 이상 (`node -v`로 확인)

```json
{
  "mcpServers": {
    "soldoc-figma": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/figma/sse", "--port", "5011"]
    },
    "soldoc-notion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/notion/sse", "--port", "5012"]
    },
    "soldoc-project": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/project/sse", "--port", "5013"]
    },
    "soldoc-draw": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/draw/sse", "--port", "5014"]
    },
    "soldoc-asana": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/asana/sse", "--port", "5015"]
    }
  }
}
```

저장 후 Claude Desktop을 **완전 종료(Cmd+Q)** 후 재시작합니다.

### 사용 예시

연결 후 Claude에게 이렇게 요청하면 됩니다.

```
# Figma — URL 붙여넣기만 하면 됩니다
"이 Figma 기획 내용 정리해줘: https://www.figma.com/design/abc123/..."

# Notion
"Notion에서 '스프린트' 키워드로 검색해줘"

# 통합 조회
"Figma 파일과 Notion 페이지로 프로젝트 현황 요약해줘"

# Asana
"Asana 프로젝트 목록 보여줘"
"'로그인 버그 수정' 태스크를 만들고 김철수에게 할당해줘"

# 디자인 생성
"로그인 페이지 디자인을 Figma에 그려줘"
```

### 트러블슈팅

| 증상 | 원인 | 해결 |
|------|------|------|
| Server Disconnected | Node.js 16 이하 | Node 18+ 설치, 또는 `npx`를 절대경로로 변경 |
| Server Disconnected | 서버 미실행/접속 불가 | 서버 URL이 올바른지, 서버가 실행 중인지 확인 |
| 포트 충돌 | mcp-remote 포트 겹침 | 각 서버의 `--port` 값을 다르게 지정 |
| 도구가 안 보임 | 설정 미반영 | Claude Desktop 완전 종료(Cmd+Q) 후 재시작 |
| NVM 환경에서 에러 | 잘못된 Node 버전 참조 | `"command": "/opt/homebrew/bin/npx"` 등 절대경로 사용 |

---

## 서버 개발/운영 가이드

아래는 MCP 서버를 직접 실행하거나 개발할 때 참고하는 내용입니다.

### 로컬 실행

```bash
pip install -r requirements.txt
cp .env.example .env   # 토큰 입력
python3 main.py        # http://localhost:8000
```

로컬에서 Claude Code/Desktop에 연결할 때는 URL을 `http://localhost:8000/...`으로 사용합니다.

---

## 도구 목록

### `/figma` — Figma 읽기 (10개)

| 도구 | 설명 |
|------|------|
| `parse_url` | Figma URL에서 file_key, node_id 자동 추출 |
| `get_me` | 내 계정 정보 + 소속 팀 목록 |
| `get_file` | 파일 구조(페이지 목록, 수정일, 썸네일) 조회 |
| `get_file_nodes` | 특정 노드(프레임, 컴포넌트 등) 세부 정보 조회 |
| `get_file_components` | 파일 내 모든 컴포넌트 목록 조회 |
| `get_file_styles` | 색상·텍스트·효과 스타일 목록 조회 |
| `get_image_urls` | 노드 렌더링 이미지 URL 생성 (PNG, SVG, PDF 등) |
| `get_comments` | 파일에 달린 댓글 전체 조회 |
| `get_team_projects` | 팀의 프로젝트 목록 조회 |
| `get_project_files` | 프로젝트 내 파일 목록 조회 |

### `/notion` — Notion 읽기/쓰기 (7개)

| 도구 | 설명 |
|------|------|
| `search_pages` | 워크스페이스에서 페이지/데이터베이스 검색 |
| `get_page` | 페이지 메타데이터(제목, 속성, URL) 조회 |
| `get_page_content` | 페이지 본문 블록 전체 조회 |
| `get_database` | 데이터베이스 스키마(속성 정의) 조회 |
| `query_database` | 필터·정렬 조건으로 데이터베이스 쿼리 |
| `create_page` | 특정 페이지 하위에 새 페이지 생성 |
| `update_page_title` | 페이지 제목 업데이트 |

### `/project` — 통합 허브 (8개)

Figma URL을 직접 넣으면 자동 파싱하며, Figma + Notion을 동시에 조회합니다.

| 도구 | 설명 |
|------|------|
| `parse_figma_url_tool` | Figma URL → file_key, node_id 추출 |
| `get_my_figma_info` | 내 Figma 계정/팀 조회 |
| `search_all` | Figma + Notion 동시 검색 |
| `get_figma_file_from_url` | Figma URL만으로 파일 구조 + 노드 자동 조회 |
| `get_figma_node_from_url` | Figma URL의 특정 노드 세부 조회 |
| `get_project_overview` | Figma + Notion 동시 요약 (URL 직접 입력 가능) |
| `sync_figma_components_to_notion` | Figma 컴포넌트 → Notion DB 동기화 |
| `get_design_doc_status` | Notion DB 작업 상태 집계 + Figma 수정일 |

### `/asana` — Asana 프로젝트 관리 (11개, 선택)

`ASANA_ACCESS_TOKEN` 환경변수가 설정되어 있을 때만 활성화됩니다.

| 도구 | 설명 |
|------|------|
| `get_workspaces` | 워크스페이스 목록 |
| `get_projects` | 프로젝트 목록 |
| `get_project` | 프로젝트 상세 정보 |
| `get_project_sections` | 섹션(보드 컬럼) 목록 |
| `get_tasks` | 태스크 목록 |
| `get_task` | 태스크 상세 정보 |
| `create_task` | 태스크 생성 (섹션 지정 가능) |
| `update_task` | 태스크 수정 (이름, 설명, 마감일, 완료 등) |
| `move_task_to_section` | 태스크 상태(섹션) 변경 |
| `assign_task` | 담당자 지정/변경 |
| `get_users` | 워크스페이스 멤버 목록 |

### `/draw` — Figma 디자인 자동 생성

자연어로 디자인을 설명하면 Claude가 도구를 호출하고, 반환된 `plugin_script`를 Figma 콘솔에 붙여넣으면 자동으로 그려집니다.

| 도구 | 설명 |
|------|------|
| `draw_design` | JSON 명세로 **완전 자유 형식** 디자인 생성 |
| `draw_button` | 버튼 컴포넌트 (primary / secondary / danger / outline) |
| `draw_card` | 카드 컴포넌트 (선택적 이미지 영역 포함) |
| `draw_navbar` | 내비게이션 바 |
| `draw_login_page` | 로그인 페이지 전체 레이아웃 |
| `draw_dashboard_page` | 대시보드 페이지 전체 레이아웃 |
| `draw_profile_page` | 프로필 페이지 전체 레이아웃 |
| `draw_custom_page` | 섹션을 자유롭게 구성하는 커스텀 페이지 |
| `get_draw_guide` | 사용 가이드 및 지원 타입 목록 반환 |

#### Figma 콘솔에서 실행하는 방법

```
1. Figma 데스크탑 앱 실행
2. 상단 메뉴 Plugins → Development → Open Console
3. 도구가 반환한 plugin_script 값을 붙여넣기
4. Enter → 현재 페이지에 디자인 생성 완료
```

---

## 사용 예시

서버와 Claude Desktop을 연결한 뒤 Claude에게 이렇게 요청할 수 있습니다.

```
# Figma 분석
"Figma 파일 abc123의 컴포넌트 목록을 보여줘"
"이 Figma 파일에서 색상 스타일을 전부 뽑아줘"

# Notion 작업
"Notion에서 '스프린트' 키워드로 페이지를 검색해줘"
"이 데이터베이스에서 Status가 '진행 중'인 항목만 뽑아줘"

# 통합 조회
"Figma 파일 abc123과 Notion 페이지 def456으로 프로젝트 현황을 요약해줘"
"Figma 컴포넌트 목록을 Notion DB에 동기화해줘"

# 디자인 자동 생성
"소셜 로그인 버튼이 있는 로그인 페이지를 Figma에 그려줘"
"카드 4개짜리 대시보드를 만들어줘"
"파란색 primary 버튼 하나 만들어줘"
"상단 네비바, 프로필 이미지, 이름, 소개, 편집 버튼이 있는 프로필 페이지 그려줘"
```

---

## 린트 & 타입 체크

```bash
ruff check .          # 린트 검사
ruff check . --fix    # 자동 수정
ruff format .         # 포매팅
mypy src/             # 타입 체크
```

설정: `pyproject.toml` (ruff `line-length=100`, `target-version=py311` / mypy `strict=true`)

---

## 기술 스택

| 패키지 | 역할 |
|--------|------|
| [FastMCP](https://github.com/jlowin/fastmcp) 2.x | MCP 서버 프레임워크 |
| [FastAPI](https://fastapi.tiangolo.com/) | HTTP 서버 및 라우팅 |
| [httpx](https://www.python-httpx.org/) | 비동기 HTTP 클라이언트 |
| [uvicorn](https://www.uvicorn.org/) | ASGI 서버 |
| [python-dotenv](https://pypi.org/project/python-dotenv/) | `.env` 파일 로드 |

---

## 관련 문서

- `CLAUDE.md` — Claude Code용 아키텍처·컨벤션·린트 가이드
- `CONTEXT.md` — 전체 작업 이력, 설계 결정 이유, 미완료 항목 (인수인계용)