# 연결 안내 — 웹·REST API·MCP

## 한눈에 보기

| 방법 | 주소 | 키 없이 | 키가 있으면 |
|---|---|---|---|
| 웹사이트 | `https://docs.dawoon.link/` | 공개 문서 | 오른쪽 위 **키로 로그인** → 등급에 맞는 문서 |
| REST API | `https://docs.dawoon.link/api/v1` | 공개 문서 | `Authorization: Bearer <키>` 헤더 |
| Swagger | `https://docs.dawoon.link/swagger/` | 공개 문서로 시험 | **Authorize** 버튼에 키 입력 |
| MCP | `https://docs.dawoon.link/mcp` | 공개 문서 | 연결 설정에 같은 헤더 추가 |
| OpenAPI 명세 | `https://docs.dawoon.link/api/v1/openapi.json` | — | — |
| AI 안내 목록 | `https://docs.dawoon.link/llms.txt` | 공개 문서 목록 | — |

세 방법 모두 **같은 원본 문서**를 읽습니다. 웹에서 본 내용과 API·MCP 로 받은 내용은 항상 같습니다.

## 접근 키

- 공개(`public`) 문서는 키 없이 읽습니다.
- 협력(`partner`)·사내(`internal`) 문서는 다운 담당자가 발급한 **접근 키**가 있어야 보입니다. 형식은 `dwd_` 로 시작하는 53자 문자열입니다.
- 키는 사람·업체·용도마다 따로 받습니다. 한 키를 여럿이 나눠 쓰지 않습니다.
- 키는 비밀번호처럼 다룹니다 — 소스 코드·커밋·이슈·채팅·스크린샷에 남기지 않고 환경변수나 비밀 저장소에 둡니다.
- 키가 새었거나 더 필요 없으면 담당자에게 알려 **폐기**합니다. 폐기된 키는 바로 막힙니다.

> 왜 — 키마다 이름과 등급이 붙어 있고 조회 기록이 남습니다. 키를 나눠 쓰면 누가 무엇을 봤는지 알 수 없고, 한 사람이 빠질 때 모두의 키를 바꿔야 합니다.

## 웹사이트

1. `https://docs.dawoon.link/` 에 들어갑니다.
2. 오른쪽 위 **키로 로그인**을 누르고 키를 붙여 넣습니다.
3. 로그인은 이 브라우저에만 유지되고 8시간이 지나면 다시 로그인합니다.

규약 목록 표의 머리글(제목·공개범위·버전·수정일)을 누르면 정렬됩니다.

## REST API

모든 응답은 JSON(UTF-8)입니다. 볼 권한이 없는 문서는 `404` 로 답합니다.

| 메서드·경로 | 하는 일 |
|---|---|
| `GET /api/v1/whoami` | 내 키 이름과 등급 확인 |
| `GET /api/v1/categories` | 분류와 볼 수 있는 문서 수 |
| `GET /api/v1/docs?category=dev` | 문서 목록 (본문 제외). `tag`, `sort`(title·updated·version·category), `order`(asc·desc) |
| `GET /api/v1/docs/{분류}/{문서}` | 문서 한 편 (메타 + markdown + html) |
| `GET /api/v1/docs/{분류}/{문서}?format=markdown` | 원본 마크다운만 |
| `GET /api/v1/search?q=커밋` | 검색 (공백으로 나눈 단어를 모두 포함) |

```bash
# 키 없이 — 공개 문서
curl -s https://docs.dawoon.link/api/v1/docs?category=dev

# 키와 함께 — 등급에 맞는 문서
curl -s -H "Authorization: Bearer $DAWOON_DOCS_KEY" https://docs.dawoon.link/api/v1/whoami
curl -s -H "Authorization: Bearer $DAWOON_DOCS_KEY" "https://docs.dawoon.link/api/v1/docs/work/request-reply-process?format=markdown"
```

| 응답 코드 | 뜻 |
|---|---|
| `200` | 성공 |
| `401` | 키가 틀렸거나 만료·폐기됨 (키를 보냈을 때만. 키를 빼면 공개 등급으로 답한다) |
| `404` | 없는 문서이거나 지금 등급으로 볼 수 없는 문서 |
| `429` | 요청이 너무 많음 — 잠시 뒤 다시 시도 |

요청 제한: 키 없이 분당 120회(IP 기준), 키가 있으면 분당 240회(키 기준).

## Swagger

`https://docs.dawoon.link/swagger/` 에서 위 API 를 브라우저로 바로 시험합니다. 협력·사내 문서를 시험하려면 **Authorize** 를 눌러 `bearerAuth` 에 키를 넣습니다. Swagger 는 키를 브라우저에 저장하지 않으므로 창을 닫으면 다시 넣습니다.

## MCP (AI 에이전트)

MCP 는 Claude Code 같은 AI 에이전트가 도구로 문서를 찾아 읽게 하는 표준입니다. 이 서버는 **Streamable HTTP(상태 없음)** 방식이며 `POST /mcp` 만 받습니다.

### 연결

```bash
# Claude Code — 공개 문서만
claude mcp add --transport http dawoon-docs https://docs.dawoon.link/mcp

# Claude Code — 키와 함께
claude mcp add --transport http dawoon-docs https://docs.dawoon.link/mcp \
  --header "Authorization: Bearer $DAWOON_DOCS_KEY"
```

다른 MCP 클라이언트는 설정 파일에 같은 주소와 헤더를 적습니다.

```json
{
  "mcpServers": {
    "dawoon-docs": {
      "type": "http",
      "url": "https://docs.dawoon.link/mcp",
      "headers": { "Authorization": "Bearer ${DAWOON_DOCS_KEY}" }
    }
  }
}
```

### 도구

| 도구 | 입력 | 하는 일 |
|---|---|---|
| `list_categories` | — | 분류와 볼 수 있는 문서 수, 내 등급 |
| `list_docs` | `category?`, `tag?` | 문서 id·제목·요약·버전 목록 |
| `search_docs` | `query`, `limit?` | 관련도 순 검색 — 결과의 `id` 를 `get_doc` 에 넘긴다 |
| `get_doc` | `id` (예: `dev/commit-message`) | 문서 전문(마크다운) |

### 에이전트에게 맡길 때

프로젝트의 에이전트 지침(CLAUDE.md·AGENTS.md 등)에 이렇게 적어 두면 작업 전에 규약을 확인합니다.

```markdown
## 다운 규약
커밋·버전·인코딩·UI·협업 절차가 걸린 작업은 시작 전에 MCP `dawoon-docs` 의
search_docs 로 해당 규약을 찾고 get_doc 으로 전문을 읽은 뒤 그 기준을 따른다.
```

## 문의

문서 내용이 실제와 다르거나 키가 필요하면 각 문서의 담당(`owner`) 팀에 알려 주세요.