# K-POP Wiki

K-POP 아티스트·앨범·용어 정보를 다루는 **LLM 기반 지식베이스 통합 프로젝트**입니다.
하네스(`AGENTS.md`)가 정의한 규칙에 따라 AI 에이전트(Claude Code)가 `raw/`의 원본 자료를
`wiki/`의 마크다운 지식베이스로 정리하고, 이 위키를 **MCP 서버**(`server.py`)와
**Gradio 웹 UI**(`app.py`)가 함께 노출합니다.

---

## 프로젝트 소개

이 저장소는 다음 4가지 요소가 하나로 통합된 시스템입니다.

| 구성 요소 | 파일 | 역할 |
|-----------|------|------|
| **하네스** | `AGENTS.md` | AI 에이전트가 이 저장소에서 작업하는 방식(규칙·절차·금지사항)을 정의. 매 세션 시작 시 에이전트가 가장 먼저 읽어야 하는 "운영 매뉴얼" |
| **LLM Wiki** | `raw/` → `wiki/` | `raw/`에 들어온 원본 소스(PDF 등)를 에이전트가 읽고 핵심 정보를 추출해 `wiki/` 마크다운 페이지로 변환·축적 |
| **MCP 서버** | `server.py` | `wiki/` 폴더를 5개의 MCP Tool(`wiki_search`, `wiki_get`, `wiki_create`, `wiki_update`, `wiki_list`)로 노출. Claude 등 MCP 클라이언트가 위키를 검색·조회·생성·수정할 수 있음 |
| **Gradio 뷰어** | `app.py` | `server.py`의 함수를 직접 import하여 같은 `wiki/` 데이터를 브라우저에서 조회·검색·새 페이지 작성할 수 있는 웹 UI 제공 |

즉, **에이전트가 지식을 축적**하고 → **MCP로 도구화**되며 → **사람은 웹 UI로 결과를 확인**하는
순환 구조입니다. `server.py`와 `app.py`는 동일한 `wiki/` 폴더를 데이터 소스로 공유하므로,
한쪽에서 추가한 페이지는 다른 쪽에서도 즉시 확인할 수 있습니다.

---

## 설치 방법

### 요구 사항
- Python **3.11 이상**
- pip

### 설치 절차

```bash
# 1. 저장소 클론
git clone <repo-url>
cd kpop-wiki-final

# 2. 의존성 설치
pip install -r requirements.txt
```

`requirements.txt`에는 다음 패키지가 포함되어 있습니다.

```
fastmcp
gradio
```

---

## MCP Tool 목록과 동작

`server.py`에서 FastMCP 인스턴스(`mcp = FastMCP("K-POP Wiki", ...)`)에 다음 5개 Tool이
`@mcp.tool()`로 등록되어 있습니다. 모든 경로는 `WIKI_DIR = <프로젝트 루트>/wiki` 기준입니다.

### 1. `wiki_search(query: str) -> list[dict]`
`wiki/` 폴더 전체를 순회하며 파일명 또는 본문에 `query`가 포함된 마크다운 문서를 찾습니다.
각 결과는 `page_id`, `title`, `snippet`(본문 앞 300자)을 담은 딕셔너리로 반환됩니다.

```python
wiki_search("해찬")
# → [{"page_id": "artists/nct-haechan", "title": "NCT 해찬", "snippet": "..."}]
```

### 2. `wiki_get(page_id: str) -> str`
`page_id`에 해당하는 마크다운 파일의 전체 내용을 문자열로 반환합니다. 파일이 없으면
`"페이지를 찾을 수 없습니다: {page_id}"`를 반환합니다.

```python
wiki_get("artists/flare-u")
# → wiki/artists/flare-u.md 파일 전체 내용
```

### 3. `wiki_create(title: str, content: str, category: str = "general") -> str`
`title`로부터 slug(파일명)를 자동 생성해 `wiki/{category}/{slug}.md`에 새 문서를 만듭니다.
같은 이름의 페이지가 이미 있으면 생성하지 않고 안내 메시지를 반환합니다(기존 문서 보호).

```python
wiki_create("아이브", "## 소개\n스타쉽엔터테인먼트 소속 그룹...", category="artists")
# → "페이지 생성 완료: artists/아이브"
```

### 4. `wiki_update(page_id: str, section: str, content: str) -> str`
기존 마크다운 파일의 맨 끝에 `## {section}` 형태의 새 섹션을 추가합니다. 기존 내용은
삭제되지 않고 그대로 유지됩니다. 파일이 없으면 `"페이지를 찾을 수 없습니다: {page_id}"`를
반환합니다.

```python
wiki_update("artists/nct-haechan", "최근 활동", "2026년 솔로 앨범 발매...")
# → "섹션 추가 완료: [artists/nct-haechan] ## 최근 활동"
```

### 5. `wiki_list(category: str = "") -> list[dict]`
`wiki/` 폴더의 문서 목록을 반환합니다. `category`를 지정하면 해당 하위 폴더의 문서만,
비워두면 전체 문서를 `page_id`, `title`, `category`와 함께 반환합니다.

```python
wiki_list()
# → [{"page_id": "artists/flare-u", "title": "FLARE U", "category": "artists"}, ...]

wiki_list("glossary")
# → glossary/ 폴더의 문서만 반환
```

---

## 사용법 (처음 보는 사람 기준 30분 가이드)

### 1. 저장소 clone

```bash
git clone <repo-url>
cd kpop-wiki-final
```

### 2. 의존성 설치

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

### 3. `raw/` 폴더에 자료 넣기

K-POP 관련 자료(텍스트 `.txt` 또는 마크다운 `.md` 파일)를 `raw/` 폴더에 넣습니다.
파일명에 `processed_` 접두어가 없는 파일은 "아직 wiki에 반영되지 않은 미처리 원본"으로
취급됩니다.

```
raw/
└── 새로운아이돌_정보.md   ← 이렇게 추가
```

### 4. Claude Code 실행 → AGENTS.md 읽고 ingest 파이프라인 실행 지시

프로젝트 루트에서 Claude Code를 실행합니다.

```bash
claude
```

그리고 다음과 같이 요청합니다.

```
AGENTS.md를 읽고, raw/ 폴더의 미처리 파일을 wiki/ 폴더의 마크다운 페이지로 변환해줘.
```

에이전트는 `AGENTS.md`의 규칙과 `scripts/ingest.md`의 절차에 따라 다음을 수행합니다.

1. `raw/`에서 `processed_` 접두어가 없는 파일 탐색
2. 파일을 읽고 핵심 개념·정의·예시 추출
3. `wiki/` 폴더에 새 마크다운 페이지 작성
4. `wiki/index.md`에 새 페이지 링크 추가
5. 처리된 `raw/` 파일명 앞에 `processed_` 접두어 추가
6. `journal.md`에 처리 기록 한 줄 append

### 5. `python app.py` 실행 → `127.0.0.1:7860` 접속

```bash
python app.py
```

브라우저에서 [http://127.0.0.1:7860](http://127.0.0.1:7860)에 접속합니다.

> 참고: AI 에이전트가 MCP Tool로 위키에 접근하게 하려면 별도 터미널에서
> `python server.py`를 실행하세요. (`127.0.0.1:8000`, streamable-http)

### 6. `wiki/`에 생성된 페이지 확인

Gradio UI 왼쪽 패널에서 "새로고침"을 누르면 4단계에서 새로 생성된 페이지가 목록에 나타납니다.
페이지를 클릭하면 본문이 우측에 표시되고, "검색" 기능으로 키워드 검색도 가능합니다.

---

## 검증 방법

### 1. `wiki_list()` 호출로 페이지 목록 확인

```bash
python -c "from server import wiki_list; print(wiki_list())"
```

`wiki/` 폴더의 모든 문서가 `page_id`, `title`, `category`와 함께 출력되면 정상입니다.
새로 추가한 페이지가 목록에 포함되어 있는지 확인하세요.

### 2. 브라우저에서 페이지 조회

1. `python app.py` 실행 후 [http://127.0.0.1:7860](http://127.0.0.1:7860) 접속
2. 좌측 "새로고침" 클릭 → 페이지 목록에 새 문서가 보이는지 확인
3. 페이지 클릭 → 우측에 본문 마크다운이 정상적으로 렌더링되는지 확인
4. 검색창에 키워드 입력 → 관련 문서가 검색 결과에 나타나는지 확인

---

## 디렉토리 구조

```
kpop-wiki-final/
├── AGENTS.md              # 하네스 — 에이전트 작업 규칙 (ingest 파이프라인, 쿼리 처리, 금지사항)
├── README.md              # 이 문서
├── PRD.md                 # 프로젝트 요구사항 정의서
├── TASK.md                # 현재 작업 Contract (Status / Goal / Done when / Log)
├── journal.md             # 작업 기록 (append-only, 수정·삭제 금지)
├── domain.md              # K-POP을 지식 도메인으로 선정한 이유 등 도메인 정의
├── requirements.txt       # 의존성 (fastmcp, gradio)
├── server.py              # MCP 서버 — wiki_search/get/create/update/list 정의
├── app.py                 # Gradio 웹 UI (server.py 함수 직접 import)
├── scripts/
│   └── ingest.md          # raw → wiki 변환 절차를 정의한 Skill 파일
├── raw/                    # 원본 소스 입력 폴더
│   └── processed_*.pdf    # 처리 완료된 원본 (접두어 processed_)
├── wiki/                   # 정리된 마크다운 지식베이스
│   ├── index.md           # 위키 인덱스 (전체 페이지 목록)
│   ├── artists/
│   │   ├── flare-u.md     # FLARE U (FNC엔터테인먼트, 2026년 5월 데뷔)
│   │   └── nct-haechan.md # NCT 해찬 (SM엔터테인먼트)
│   └── glossary/
│       └── kpop-terms.md  # K-POP 용어 사전 (컴백, 직캠, 팬덤 등)
└── demo/
    └── MVP GUI.png         # MVP 화면 스크린샷
```

---

## 위키 페이지 추가/수정 방법 (요약)

- **새 페이지 추가**: `wiki_create(title, content, category)` 호출 또는 Gradio UI의
  "새 페이지 추가" 폼 사용
- **기존 페이지에 내용 추가**: `wiki_update(page_id, section, content)` 호출 시 해당
  문서 끝에 `## section` 섹션이 추가됩니다 (기존 내용은 유지)
- 페이지 삭제 기능은 제공하지 않습니다