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

설치 절차

# 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자)을 담은 딕셔너리로 반환됩니다.

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

2. wiki_get(page_id: str) -> str

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

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에 새 문서를 만듭니다. 같은 이름의 페이지가 이미 있으면 생성하지 않고 안내 메시지를 반환합니다(기존 문서 보호).

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

4. wiki_update(page_id: str, section: str, content: str) -> str

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

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

5. wiki_list(category: str = "") -> list[dict]

wiki/ 폴더의 문서 목록을 반환합니다. category를 지정하면 해당 하위 폴더의 문서만, 비워두면 전체 문서를 page_id, title, category와 함께 반환합니다.

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

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

---

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

1. 저장소 clone

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

2. 의존성 설치

pip install -r requirements.txt

3. raw/ 폴더에 자료 넣기

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

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

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

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

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 접속

python app.py

브라우저에서 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() 호출로 페이지 목록 확인

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 접속
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 섹션이 추가됩니다 (기존 내용은 유지)
• 페이지 삭제 기능은 제공하지 않습니다