# kakao-docs-mcp

카카오 개발자([developers.kakao.com](https://developers.kakao.com)) REST API 문서를 검색하고 읽을 수 있는
**검색 REST API**와 **MCP(Model Context Protocol) 서버**입니다.

카카오는 REST API 문서를 `llms.txt`나 공식 MCP 형태로 제공하지 않습니다. 이 프로젝트는 그 공백을 메우는
**공익 오픈소스 프로젝트**입니다.

- **그냥 검색만 쓰고 싶다** → [1. 호스팅된 공개 서비스 사용하기](#1-호스팅된-공개-서비스-사용하기) (설치 불필요)
- **Claude에서 카카오 문서를 검색하게 하고 싶다** → [2. Claude에 MCP 연결하기](#2-claude에-mcp-연결하기)
- **내 서버/로컬에서 직접 돌리고 싶다** → [3. 직접 실행 / 셀프호스트](#3-직접-실행--셀프호스트)

> 문서 출처: [카카오 개발자](https://developers.kakao.com) — 문서 저작권은 **카카오**에 있습니다.
> 이 프로젝트는 문서 본문을 통째로 복제·재배포하지 않습니다. 자세한 내용은
> [저작권 관련 설계](#저작권-관련-설계)를 참고하세요.

---

## 한눈에 보기

대부분의 사용자는 아무것도 설치할 필요가 없습니다. 공개 엔드포인트에서 **키 1개를 발급**받아 REST API와 MCP를 모두 사용합니다.

```
┌──────────────┐  ① POST /kakao-docs/keys (인증 불필요)
│  나 / 내 앱   │ ───────────────────────────────────→  키 발급 (kd_xxxx)
└──────┬───────┘
       │ ② Authorization: Bearer kd_xxxx
       │
       ├─────────────→  https://api.tan-kim.com/kakao-docs   (REST 검색/조회)
       │
       └─────────────→  https://mcp.tan-kim.com/kakao-docs   (Claude MCP)
```

| 용도 | 엔드포인트 | 인증 |
|------|-----------|------|
| 키 발급(셀프) | `POST https://api.tan-kim.com/kakao-docs/keys` | 불필요 |
| 키워드 검색 | `GET https://api.tan-kim.com/kakao-docs/search?q=...` | `Bearer <키>` |
| 문서 본문 조회 | `GET https://api.tan-kim.com/kakao-docs/page/<경로>` | `Bearer <키>` |
| 카테고리 목록 | `GET https://api.tan-kim.com/kakao-docs/categories` | `Bearer <키>` |
| 헬스체크 | `GET https://api.tan-kim.com/kakao-docs/health` | 불필요 |
| MCP (Claude) | `https://mcp.tan-kim.com/kakao-docs` | `Bearer <키>` |

> ⚠️ `api.tan-kim.com` / `mcp.tan-kim.com`은 이 프로젝트의 레퍼런스 운영 도메인입니다.
> 직접 배포한 경우 자신의 도메인으로 바꿔 읽으세요. (아직 배포 전이라면 [3. 직접 실행](#3-직접-실행--셀프호스트) 또는
> [docs/DEPLOY.md](docs/DEPLOY.md) 참고)

---

## 왜 이 프로젝트가 필요한가

카카오 개발자 문서는:

- `llms.txt` / `llms-full.txt`를 제공하지 않습니다 (`developers.kakao.com/llms.txt` → 404).
- 공식 MCP는 [PlayMCP](https://playmcp.kakao.com)가 있지만, 이는 **톡캘린더/카카오맵/기프트/멜론 등
  실제 서비스 기능**을 MCP 도구로 노출하는 것이지 **REST API 개발 문서 자체**를 위한 것이 아닙니다.

그래서 LLM/에이전트가 카카오 REST API를 정확히 참고하려면 매번 웹 검색 → 페이지 열람 → 파싱을 반복해야 합니다.
이 프로젝트는 그 과정을 검색 + 실시간 조회 툴 2개로 대체합니다.

---

## 1. 호스팅된 공개 서비스 사용하기

### 1-1. API 키 발급 (셀프 발급)

인증 없이 누구나 키를 발급받을 수 있습니다. 발급된 키 1개로 REST와 MCP를 모두 사용합니다.

```bash
curl -X POST https://api.tan-kim.com/kakao-docs/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"내-에이전트"}'
```

응답 (원본 키는 **이때 한 번만** 표시됩니다 — 서버는 해시만 저장하므로 분실 시 재발급):

```json
{
  "id": 12,
  "name": "내-에이전트",
  "rate_per_min": 30,
  "api_key": "kd_a1B2c3D4...",
  "note": "api_key는 지금만 표시됩니다. 안전한 곳에 보관하세요(서버는 해시만 저장)."
}
```

- 셀프 발급 키의 기본 한도는 **분당 30요청**입니다.
- 남용 방지를 위해 **IP당 발급 횟수에 시간당 제한**이 있습니다.

### 1-2. 키워드 검색 — `GET /search`

```bash
curl "https://api.tan-kim.com/kakao-docs/search?q=토큰갱신&limit=5" \
  -H "Authorization: Bearer kd_a1B2c3D4..."
```

| 쿼리 파라미터 | 필수 | 기본값 | 설명 |
|--------------|------|--------|------|
| `q` | ✅ | — | 검색 키워드 |
| `limit` | ❌ | 5 | 결과 수 (최대 20) |
| `category` | ❌ | 전체 | 카테고리 슬러그 필터 (예: `kakaologin`) |

응답 (제목/카테고리/짧은 발췌만 포함 — 본문 전체는 `/page`로 조회):

```json
{
  "results": [
    { "path": "kakaologin/common", "title": "카카오 로그인 > 이해하기", "category": "카카오 로그인", "snippet": "...", "score": 12.4 }
  ],
  "total": 1
}
```

### 1-3. 문서 본문 조회 — `GET /page/<경로>`

검색 결과의 `path`를 그대로 사용합니다. **본문은 매 요청마다 developers.kakao.com에서 실시간으로 가져와
마크다운으로 변환**합니다(카카오 서버 부하를 줄이기 위해 최근 조회분은 짧게 캐시합니다).

```bash
curl "https://api.tan-kim.com/kakao-docs/page/kakaologin/common" \
  -H "Authorization: Bearer kd_a1B2c3D4..."
```

```json
{
  "path": "kakaologin/common",
  "title": "카카오 로그인 > 이해하기",
  "sourceUrl": "https://developers.kakao.com/docs/ko/kakaologin/common",
  "markdown": "> 출처: ...\n\n# 이해하기\n\n...",
  "fetchedAt": "2026-07-17T12:00:00.000Z",
  "found": true
}
```

### 1-4. 카테고리 목록 — `GET /categories`

```bash
curl "https://api.tan-kim.com/kakao-docs/categories" -H "Authorization: Bearer kd_a1B2c3D4..."
```

---

## 2. Claude에 MCP 연결하기

`.mcp.json` 또는 Claude 설정에 발급받은 키를 넣습니다.

```json
{
  "mcpServers": {
    "kakao-docs": {
      "type": "http",
      "url": "https://mcp.tan-kim.com/kakao-docs",
      "headers": { "Authorization": "Bearer <발급받은 API키>" }
    }
  }
}
```

### 제공 툴

| 툴 | 설명 |
|----|------|
| `search_kakao_docs` | 키워드로 카카오 REST API 문서를 검색 (제목/카테고리/짧은 발췌 반환) |
| `get_kakao_doc_page` | 검색 결과의 `path`로 문서 본문 전체를 실시간 조회 (마크다운) |
| `list_kakao_doc_categories` | 카테고리(슬러그, 한글 이름) 목록 조회 |

일반적인 사용 흐름: `search_kakao_docs`로 후보를 찾고 → `get_kakao_doc_page`로 필요한 문서의 본문을 읽습니다.

---

## 3. 직접 실행 / 셀프호스트

### 3-1. 로컬 개발

```powershell
# 의존성 설치
npm install

# 문서 색인 (사이트맵 크롤 → 제목/헤딩/스니펫만 SQLite에 저장, 본문은 저장 안 함)
npm run index

# REST API 서버 (기본: SQLite, API 키 비활성 — 로컬 테스트용)
npm run api

# MCP 서버 (stdio, Claude Code/Desktop이 직접 프로세스로 실행)
npm run mcp
```

`.env.example`을 `.env`로 복사해 필요에 맞게 값을 조정합니다.

### 3-2. Claude Code/Desktop에 로컬 MCP 등록 (stdio)

```json
{
  "mcpServers": {
    "kakao-docs": {
      "command": "npx",
      "args": ["tsx", "/절대경로/kakao-docs-mcp/src/mcp/server.ts"]
    }
  }
}
```

### 3-3. 운영 배포 (Docker + Oracle Cloud)

[docs/DEPLOY.md](docs/DEPLOY.md)를 참고하세요. API 키/사용 로그는 MySQL(RDS)에, 검색 인덱스는
서버의 SQLite 볼륨에 둡니다. `namuwiki-search-mcp`와 동일한 VM에 나란히 배포하도록 설계했습니다
(포트 3002/3012 사용, 3000/3001/3003/3005/3011과 충돌 없음).

---

## 저작권 관련 설계

카카오 개발자 문서의 저작권은 **카카오**에 있습니다. 이 프로젝트는 그 저작권을 존중하기 위해 다음과 같이 설계했습니다.

- **검색 인덱스에는 본문 전체를 저장하지 않습니다.** 제목/헤딩/200자 이내 발췌만 SQLite에 색인합니다.
- **본문은 항상 실시간 조회입니다.** `get_kakao_doc_page` / `GET /page/*` 호출 시마다
  developers.kakao.com에서 그때그때 가져와 반환하며, 디스크에 영속 저장하지 않습니다
  (반복 요청 부하 완화를 위한 짧은 인메모리 캐시만 사용, 기본 15분).
- 응답에는 항상 출처 URL과 저작권 고지를 포함합니다.
- 크롤러는 robots.txt를 준수하고(`/docs/ko/*`는 허용됨), 식별 가능한 User-Agent와
  요청 간 지연을 사용해 카카오 서버에 부담을 주지 않습니다.

---

## 라이선스

이 저장소의 코드는 [MIT License](LICENSE)로 배포됩니다. 카카오 문서 콘텐츠 자체는 카카오의 저작물이며
이 라이선스의 대상이 아닙니다.