# MCP

[MCP](https://modelcontextprotocol.io)(Model Context Protocol)는 IDE의 에이전트(Claude Code·Cursor 등)를 새로온 플랫폼에 연결하는 표준입니다. 새로온은 로컬 설치가 필요 없는 **원격 HTTP** 방식으로 연결을 제공합니다.

## 연결

Claude Code에서 원격 MCP 서버를 추가합니다.

```bash
claude mcp add --transport http saeroon https://hosting.saeroon.com/api/mcp/streamable
```

Cursor 등 다른 클라이언트도 같은 URL을 원격 MCP 서버로 등록하면 됩니다.

- 엔드포인트: `https://hosting.saeroon.com/api/mcp/streamable`
- 인증: OAuth 2.1 (표준 디스커버리 — RFC 9728 / 8707 / 7591)

## 인증 흐름

처음 추가하면 브라우저가 열리고 새로온 계정으로 로그인합니다. 승인하면 IDE로 돌아와 세션이 이어집니다. 등록·토큰 발급은 표준 OAuth 디스커버리로 자동 처리되므로 키를 직접 입력할 필요가 없습니다.

## 제공 도구

연결 직후, 계정에 사이트가 없어도 바로 쓰는 읽기 전용 안내 도구가 있습니다.

- **`saeroon_guide`** — 제작 규약을 라이브로 조회합니다. 인자 없이 부르면 한 장 요약(prompt)과 문서 목록을, `topic`(예: `attributes`)을 주면 그 문서 전문을 돌려줍니다. 키도 사이트도 필요 없습니다.

사이트를 연결하면 백엔드 연동 도구가 함께 열립니다.

- **`saeroon_list_capabilities`** — 이 사이트에 붙일 수 있는 백엔드(폼·회원·게시판·예약·콘텐츠타입)와 각 연결 방법을 나열합니다.
- **`saeroon_describe_site_backend`** — 한 번의 호출로 사이트 백엔드 전체(폼·게시판·콘텐츠타입)를 파악합니다.
- **`saeroon_attach_form`** — 폼 백엔드를 붙이고 붙여넣을 HTML까지 한 번에 돌려줍니다.
- **`saeroon_define_booking`** — 예약 기능을 활성화하고 서비스 정의(예약 항목·가격·보증금)와 **영업시간**을 선언적으로 적용합니다. `services` 는 **전체 목록**이라 여기서 빠진 기존 활성 서비스는 비활성화되고, `businessHours` 는 **7일(0=일~6=토) 전부**를 담는 replace-all 입니다(휴무일도 `{ "day": n, "isClosed": true }` 로 명시). 영업시간을 처음 넣을 때는 **`timeZone`(예: `"Asia/Seoul"`)이 필수** — 없으면 `"09:00"` 이 UTC 로 해석돼 슬롯이 엉뚱한 시간에 열리므로 서버가 거절합니다. **영업시간이 없거나 7일 전부 휴무면 모든 날짜의 슬롯이 0이라 방문자가 예약할 수 없습니다** — 서비스만 정의하면 예약을 받지 못합니다. 선택 `blockedSlots` 로 특정 시간대(공휴일·설비 점검)를 예약 불가로 뺄 수 있습니다 — 일회성 replace-all이며 `start`/`end` 는 **오프셋 포함 절대시각**(`"2026-08-15T14:00:00+09:00"` 또는 `"…Z"`)입니다(영업시간과 달리 타임존 비의존이라 오프셋이 없으면 거절). 키를 아예 빼면 그 부분은 **건드리지 않습니다**(services 생략 = 서비스 유지, businessHours 생략 = 기존 영업시간 유지, blockedSlots 생략 = 기존 차단 유지). 붙여넣을 `data-saeroon-booking` 위젯 HTML까지 돌려줍니다(`data-mode="stay"` = 날짜범위 숙박).
- **`saeroon_define_board` · `saeroon_define_members`** — 게시판·회원 배선 계획(붙여넣을 `data-saeroon-*` 속성 스니펫)을 제안합니다.
- **`saeroon_content_list_types` → `saeroon_content_get_schema` → `saeroon_content_invoke`** — 콘텐츠타입 조회·스키마·CRUD(생성/목록/조회/수정/삭제/발행)를 잇는 3종 세트입니다.

사이트 생성·배포·스키마 같은 플랫폼 관리는 `saeroon.platform.*` 도구로 제공합니다.

### 게시판을 직접 만드는 도구

위의 `saeroon_define_board`는 **계획만** 돌려줍니다(붙여넣을 속성 스니펫 안내). 게시판을 실제로 만들고
`boardId`를 받으려면 아래를 씁니다. 앱을 붙일 때 필요한 바로 그 도구입니다 — [앱 백엔드 붙이기](/docs/app-backend) 참조.

- **`saeroon.platform.board.list`** — 사이트의 게시판 목록. 인자 `site_id`.
- **`saeroon.platform.board.create`** — 게시판 생성. 인자 `site_id`, `name`, `slug`, `type`(`general`·`notice`·`gallery`), `write_mode`(`open`·`operatorOnly`), `allow_anonymous`. **멱등** — 같은 slug로 다시 부르면 기존 게시판을 돌려줍니다.

같은 일을 CLI로도 합니다: `npx @saeroon/cli board create --site <siteId> --name <이름> --slug <슬러그> --json`.

### 회원 등급 쿠폰 도구

`members` 를 붙인 사이트에서 회원 등급을 코드로 부여하는 **컴프 쿠폰**을 운영합니다(할인 아님 — 등급 부여). 발급된
코드는 만료 없이 영구, 회원이 redeem 하면 등급이 오르고 `entitlementSource: "coupon"` 이 붙습니다. redeem 자체는
앱이 회원 세션으로 호출합니다([앱 백엔드 붙이기](/docs/app-backend) §11) — 아래 도구는 **운영자**용 발급/관리입니다.

- **`saeroon.platform.coupon.create`** — 쿠폰 발급. 인자 `site_id`, `tier`(`Bronze`·`Silver`·`Gold`·`Platinum`), `count`(대량, 1~1000) **또는** `code`(단일·멱등). Free는 부여 불가.
- **`saeroon.platform.coupon.list`** — 쿠폰 목록. 인자 `site_id`, `tier`·`status`(`active`·`used`·`revoked`) 선택 필터.
- **`saeroon.platform.coupon.revoke`** — 미사용 쿠폰 회수(멱등). 인자 `site_id`, `code`.
- **`saeroon.platform.coupon.usage`** — 단일 쿠폰 사용내역(누가·언제 redeem). 인자 `site_id`, `code`.

같은 일을 CLI로도 합니다: `npx @saeroon/cli coupon create --site <siteId> --tier Gold --count 100 --json`.

> MCP는 OAuth 토큰으로 인증합니다. `sk_live_` 키를 MCP 설정에 넣으면 401이 납니다 — 그 키는 CLI·REST용입니다.

## MCP 없이 바로 쓰기

정적 사이트 제작에 MCP가 필수는 아닙니다. 에이전트에게 아래 URL을 fetch 하게 하면 같은 규약을 문서로 바로 참조할 수 있습니다. `saeroon_guide` 도구도 결국 이 문서들을 읽어 돌려줍니다.

- 제작 규약 한 장 요약: [https://developers.saeroon.com/prompt.md](https://developers.saeroon.com/prompt.md)
- 속성 전수표: [Attributes](/docs/attributes)
- 전체 인덱스: [https://developers.saeroon.com/llms.txt](https://developers.saeroon.com/llms.txt)

## 로컬(stdio) 방식

로컬 stdio 방식의 `@saeroon/mcp-server`(레거시 V2 카탈로그, 마지막 발행 `1.0.1`)는 **deprecated** 되었습니다 — npm 설치 시 위의 원격 HTTP 연결로 안내하는 경고가 표시됩니다. 신규·기존 연결 모두 원격 HTTP 방식을 사용하세요.