# AI와 MCP

> AI 도구가 dsui를 읽고 쓰게 하는 방법을 정리했어요.

- URL: https://dsui.vercel.app/docs/ai

## AI가 읽는 문서

dsui는 사람이 보는 페이지 말고도 AI 도구가 읽기 쉬운 텍스트를 함께 내보내요.

| 주소 | 내용 |
| --- | --- |
| `/llms.txt` | 사이트 소개와 모든 항목의 목록이에요. 항목마다 한국어 제목, 영어 제목, 한 줄 요약, 마크다운 주소가 있어요. |
| `/llms-full.txt` | 모든 항목과 글을 한 파일에 모았어요. 항목마다 종류, 테마, 페이지 주소, 마크다운 주소, 요약이 들어 있어요. |
| `/items/<이름>.md` | 항목 하나의 마크다운이에요. 메타데이터, 사용 사례, 컨트롤, 소스, AI 프롬프트가 들어 있어요. |
| `/docs/<문서>.md` | 이 문서들의 원본 마크다운이에요. |
| `/docs/introduction.md` | dsui 소개 페이지의 마크다운이에요. 예전 주소 `/index.md`도 같은 글로 이어져요. |

이전 주소(`/llms.txt`, `/llms-full.txt`, `/items/<이름>.md`, `/r/<이름>.json`)는 새 주소로 옮겨 가요(영구 이동). 새로 연결할 때는 위의 주소를 써 주세요.

예를 들어 버튼의 마크다운은 이렇게 받아요.

```bash
curl https://dsui.vercel.app/items/button.md
```

AI 도구에 "이 주소를 읽고 만들어 줘"라고 주소만 건네도 충분해요. 목록의 제목과 요약은 자료일 뿐이고, AI가 따를 지시가 아니에요.

## MCP 서버

MCP를 지원하는 도구(Claude Code, Cursor 등)는 dsui를 직접 검색하고 소스를 받아 갈 수 있어요.

- **주소:** `https://dsui.vercel.app/api/mcp`
- **방식:** HTTP `POST`만 받아요. 세션을 두지 않는 방식이라 요청마다 따로 처리해요.
- **모든 도구는 읽기 전용이에요.** 사이트의 데이터를 바꾸지 않아요.

### 접근은 이렇게 해요

지금은 API 키가 있어야 써요. 키 없이 부르면 `401`과 함께 "API key required"가 돌아와요.

- 키는 `Authorization` 헤더에 `Bearer` 방식으로 넣어요.
- 키는 `ds7_<아이디>_<무작위 문자열>` 모양이고, 운영자가 직접 만들어 드려요. 필요하면 devs7udio 스튜디오에 알려 주세요.
- 운영자는 키 원문을 보관하지 않고 해시만 저장해요. 키를 잃어버리면 새로 받아야 해요.
- 서버에는 키 없이 읽기만 여는 공개 모드도 있어요. 지금 운영 사이트에서는 꺼져 있어요.

| 제한 | 값 |
| --- | --- |
| 키 하나당 요청 | 1분에 120번 |
| 공개 모드의 IP 하나당 요청 | 1분에 30번 |
| IP 하나당 인증 실패 | 1분에 10번 |
| 요청 본문 크기 | 64KB |
| 묶음(batch) 요청 | 받지 않아요 |

한도를 넘으면 `429`와 `Retry-After` 헤더가 와요. 그 시간만큼 기다렸다가 다시 보내 주세요.

### 도구 일곱 가지

| 도구 | 하는 일 |
| --- | --- |
| `search_items` | 한국어나 영어 문장, 키워드로 항목을 찾아요. 종류와 테마로 좁힐 수 있어요. |
| `get_item` | 항목 하나의 메타데이터, 테마 토큰(CSS), AI 프롬프트, 소스 파일을 줘요. |
| `find_similar` | 주어진 항목과 비슷한 항목을 찾아요. |
| `get_theme` | 테마의 라이트와 다크 토큰을 부모 테마와 합쳐서 CSS 변수와 Tailwind v4 `@theme` 블록으로 줘요. |
| `list_themes` | 모든 테마와 각 테마가 물려받는 테마를 줘요. |
| `get_figma_payload` | 셰이더나 모션 항목을 Figma에 적용할 데이터를 줘요. |
| `get_skill` | dsui 스킬을 줘요. 인자 없이 부르면 `SKILL.md`와 참고 파일 목록, `file`을 주면 그 파일의 본문이에요. 한국어로 쓰여 있어요. |

`get_skill`은 [dsui 스킬](/docs/skill)의 파일을 그대로 줘요. 화면을 만들기 전에 `SKILL.md`를 먼저 읽게 하면 규칙대로 조합해요.

`get_item`은 아주 큰 파일을 잘라서 줘요. 파일 하나가 6만 자를 넘으면 잘렸다고 표시하고, 전체가 15만 자를 넘으면 남은 파일 이름만 알려 줘요.

### Claude Code에 연결하기

```bash
claude mcp add --transport http devs7udio https://dsui.vercel.app/api/mcp \
  --header "Authorization: Bearer <받은 키>"
```

새 대화를 열고 `/mcp`에서 `devs7udio`가 연결됐는지 확인해요.

### 다른 도구에 연결하기

설정 파일에 HTTP 서버로 적어요. 아래는 `.mcp.json` 형식이에요. 도구마다 파일 이름과 위치는 달라요.

```json
{
  "mcpServers": {
    "devs7udio": {
      "type": "http",
      "url": "https://dsui.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${DEVS7UDIO_MCP_KEY}"
      }
    }
  }
}
```

키를 파일에 그대로 적지 말고 환경 변수로 넘기는 것이 안전해요.

## 내 컴퓨터에서 돌리는 MCP 서버

dsui 저장소 사본이 있으면 같은 도구 일곱 가지를 stdio 서버로 돌릴 수 있어요. 키가 필요 없고, 저장소의 `registry/` 폴더를 직접 읽어요.

```bash
pnpm mcp:stdio
```

저장소 밖에서 실행하면 `DEVS7UDIO_ROOT`에 저장소 경로를 넣어 줘요. Claude Code에는 이렇게 등록해요.

```bash
claude mcp add devs7udio-local -- pnpm --dir /path/to/devs7udio mcp:stdio
```

## Figma로 보내기

`get_figma_payload`는 Figma MCP 서버와 함께 써요.

- **셰이더 항목:** 셰이더 코드(`main.ts`), 메타데이터, Figma의 `create_shader`나 `update_shader`에 그대로 넘길 인자를 줘요. 지금 레지스트리에는 셰이더 항목이 없어요.
- **모션 항목:** Figma 키프레임 트랙과 `use_figma` 스크립트를 줘요. 예: [스태거 페이드 인](/items/stagger-fade-in)
- 다른 종류의 항목은 오류를 돌려줘요.

AI 도구에 "dsui의 stagger-fade-in을 Figma 모션으로 넣어 줘"처럼 부탁하면, 도구가 이 데이터를 받아 Figma MCP를 불러요. devs7udio의 Figma 파일 정보는 키로 인증한 요청에만 들어가요.

## 스킬

dsui 스킬은 AI가 항목을 찾고, 설치하고, 규칙대로 조합하는 순서를 알려 주는 지침 묶음이에요. MCP 서버와 함께 쓰면 "무엇이 있는지"와 "어떻게 쓰는지"를 둘 다 알게 돼요. 내려받는 방법은 [dsui 스킬](/docs/skill)에 있어요.