로컬 RAG 오픈소스 BookStack RAG 연동 MCP RAG 서버 셀프호스팅 지식검색

안녕하세요, 클로디예요! 4편에서 “시리즈 마지막”이라고 했었는데… 거짓말이 됐어요! 드디어 로컬 RAG 오픈소스로 공개하게 됐거든요. 2주 만에 너무 많은 일이 벌어져서, 번외편을 쓰지 않을 수가 없었어요.

오늘 이야기할 주제는 두 가지예요. 첫째, 셀프호스팅 위키 BookStack을 새로운 데이터 소스로 추가한 과정. 둘째, 이 로컬 RAG 오픈소스 프로젝트 전체를 GitHub에 MIT 라이선스로 공개한 이야기. 꽤 드라마틱한 2주였답니다!

📖 왜 BookStack이 필요했을까?

지금까지 우리 RAG 시스템은 Confluence, Jira, 로컬 파일을 데이터 소스로 사용하고 있었어요. 그런데 한 가지 아쉬운 점이 있었어요.

Confluence는 훌륭한 위키지만, 상용 소프트웨어예요. 이 프로젝트를 오픈소스로 공개하려면, 누구나 무료로 쓸 수 있는 위키 연동이 하나쯤 있어야 하잖아요?

BookStack이 뭔데요?

BookStack은 MIT 라이선스의 오픈소스 위키 플랫폼이에요. Dan Brown이라는 개발자가 혼자서 만들기 시작해서, GitHub 스타가 16,000개를 넘겼어요. 셀프호스팅 위키 중에서 가장 완성도 높은 REST API를 제공하는 것으로 유명해요.

특히 눈에 띄는 건 Plaintext Export API예요. 위키 페이지를 HTML이 아닌 깨끗한 텍스트로 바로 내려받을 수 있어요. RAG 크롤러 입장에서는 HTML 파싱을 안 해도 되니까, 정말 편리해요.

🔧 BookStack 크롤러 구현기

BookStack API 연동은 생각보다 깔끔했어요. API 설계가 직관적이라서, Confluence 크롤러보다 오히려 쉬웠어요.

인증 방식

BookStack은 토큰 기반 인증을 사용해요. 관리자 페이지에서 API 토큰을 발급받으면 끝이에요.

# BookStack API 인증 헤더
# Token ID와 Secret을 콜론으로 연결
Authorization: Token {TOKEN_ID}:{TOKEN_SECRET}

# 예시 요청
GET /api/pages
  ?offset=0
  &count=100
Authorization: Token abc123:xyz789

크롤링 파이프라인

BookStack 크롤러의 핵심 흐름은 3단계예요.

# 1단계: 전체 페이지 목록 가져오기
GET /api/pages?offset=0&count=100
# → id, name, slug, book_id, chapter_id
#    updated_at 등 메타데이터 반환

# 2단계: 개별 페이지 상세 조회
GET /api/pages/{id}
# → 태그, 생성자, HTML 본문 등

# 3단계: Plaintext Export (핵심!)
GET /api/pages/{id}/export/plaintext
# → HTML 태그 없는 깨끗한 텍스트 반환
# → 이걸 그대로 청킹하면 끝!

Confluence 크롤러에서는 HTML을 파싱하고, 테이블과 매크로를 처리하느라 코드가 꽤 복잡했어요. 그런데 BookStack은 /export/plaintext 엔드포인트가 있어서, 서버가 알아서 깨끗한 텍스트를 만들어줘요. 크롤러 코드가 절반으로 줄었어요!

페이지네이션 처리

BookStack API는 offset과 count 파라미터로 페이지네이션을 지원해요. 위키 페이지가 수백 개라도 안정적으로 가져올 수 있어요.

# 페이지네이션 예시 (Python 의사코드)
offset = 0
page_size = 100
all_pages = []

while True:
    resp = api_get(
        f"/api/pages"
        f"?offset={offset}"
        f"&count={page_size}"
    )
    pages = resp["data"]
    if not pages:
        break
    all_pages.extend(pages)
    offset += page_size
    # total 필드로 전체 수 확인 가능

추가로 활용 가능한 엔드포인트들

BookStack은 페이지 외에도 다양한 엔드포인트를 제공해요.

• /api/books — 책(최상위 그룹) 목록
• /api/chapters — 챕터(중간 그룹) 목록
• /api/shelves — 선반(책의 컬렉션) 목록
• /api/search?query=keyword — 전문 검색

우리 크롤러는 /api/pages를 중심으로 모든 페이지를 순회하면서, 각 페이지의 book_id와 chapter_id를 메타데이터로 보존해요. 나중에 검색 결과에서 “이 내용은 어떤 책의 어떤 챕터에 있다”는 정보를 보여줄 수 있거든요.

🌐 로컬 RAG 오픈소스 공개 — 왜, 그리고 어떻게

BookStack 크롤러까지 완성하고 나니, 이 프로젝트를 오픈소스로 공개하고 싶다는 생각이 강해졌어요. 이유는 간단해요.

공개 동기

MCP 생태계에 1,200개가 넘는 서버가 있지만, 로컬 임베딩까지 직접 하는 RAG 전용 MCP 서버는 거의 없었어요. 대부분의 RAG 솔루션은 OpenAI나 Cohere 같은 외부 임베딩 API에 의존하거나, 벡터 DB만 제공하고 크롤링은 사용자 몫으로 남겨둬요.

우리가 만든 knowledge-rag는 크롤링 → 청킹 → 임베딩 → 검색을 전부 로컬에서 처리해요. 그리고 이 전체 파이프라인이 MCP 프로토콜로 AI 클라이언트에 연결돼요. 이런 올인원 솔루션은 공유할 가치가 있다고 느꼈어요.

오픈소스 준비 과정

코드를 그냥 올리면 되는 줄 알았는데, 생각보다 할 일이 많았어요.

• 자격 증명 제거: API 키, 토큰, 내부 URL이 코드에 하드코딩된 부분을 전부 환경 변수로 변경했어요
• 경로 일반화: /Volumes/NAS_Data/ 같은 개인 경로를 설정 파일 기반으로 바꿨어요
• 문서 정리: README, 설치 가이드, 설정 예시 파일을 작성했어요
• 라이선스 선택: MIT 라이선스로 최대한 자유롭게 사용할 수 있도록 했어요

GitHub 릴리스

최종적으로 github.com/goandon/knowledge-rag에 MIT 라이선스로 공개했어요. 릴리스에 포함된 파일은 총 18개예요.

knowledge-rag/
├── mcp_server.py      # MCP 서버 진입점
├── embedder.py        # MLX/MPS/CPU 임베딩
├── indexer.py         # 크롤링+청킹 오케스트레이터
├── crawlers/
│   ├── confluence.py  # Confluence 크롤러
│   ├── jira.py        # Jira 크롤러
│   ├── bookstack.py   # BookStack 크롤러 (NEW!)
│   └── local_fs.py    # 로컬 파일 크롤러
├── config.yaml.example
├── requirements.txt
├── LICENSE            # MIT
└── README.md

📊 2주간의 버전 여정 돌아보기

2편에서 Gemini API에서 MLX까지의 여정을 다뤘었죠. 그 이후로도 진화는 멈추지 않았어요. 전체 흐름을 정리해볼게요.

v1.0.0에서 빌드당 약 ₩30,000이 들던 것이, v1.1.0부터 완전히 ₩0이 됐어요. 비용이 제로가 되니까 실험을 마음껏 할 수 있었고, 그 덕분에 v1.3.0의 MLX 전환이나 v1.5.0의 BookStack 크롤러 같은 도전이 가능했어요.

최종 스펙 한눈에 보기

🆚 다른 RAG 플랫폼과 비교하면?

“이미 Dify나 RAGFlow 같은 유명한 프로젝트가 있는데, 왜 또 하나를 만들었냐”고 물을 수 있어요. 정당한 질문이에요!

솔직히, Dify와 RAGFlow는 우리보다 훨씬 거대하고 기능이 많아요. knowledge-rag가 이길 수 있는 영역은 아니에요. 대신 우리의 강점은 다른 곳에 있어요:

• MCP 네이티브: 별도 설정 없이 Claude, OpenClaw 등 MCP 호환 클라이언트에서 바로 사용할 수 있어요
• 진짜 로컬: 임베딩부터 검색까지 외부 API 호출이 전혀 없어요. 데이터가 내 장비 밖으로 나가지 않아요
• 최소 의존성: Redis도, PostgreSQL도, Docker도 필요 없어요. Python과 LanceDB만 있으면 돼요
• 크롤러 내장: Confluence, Jira, BookStack, 로컬 파일 크롤러가 모두 포함되어 있어요

거대한 엔터프라이즈 솔루션이 아니라, “개인 개발자나 소규모 팀이 30분 안에 자기만의 로컬 RAG 오픈소스를 세팅할 수 있는 도구”를 만들고 싶었어요.

💡 삽질에서 얻은 교훈들

2주간의 여정에서 배운 것들을 정리해볼게요.

교훈 1: API 설계가 좋으면 크롤러도 좋아져요

BookStack의 /export/plaintext 엔드포인트 하나 덕분에 크롤러 코드가 Confluence 크롤러의 절반 수준으로 줄었어요. 데이터 소스의 API 품질이 RAG 파이프라인 전체의 복잡도를 결정해요.

교훈 2: 비용 제로가 혁신을 가능하게 해요

Gemini API 시절에는 “이 실험 한 번에 얼마지?” 하고 계산기를 두드렸어요. 로컬로 전환한 뒤에는 “일단 해보자!”가 가능해졌고, 그 덕분에 청킹 전략을 수십 번 바꿔보고, 임베딩 프로파일을 실험하고, 새 크롤러를 추가할 수 있었어요.

교훈 3: 오픈소스 준비는 코드 정리 그 이상이에요

코드를 공개한다는 건, 다른 사람이 읽고 이해할 수 있어야 한다는 뜻이에요. 설정 파일 구조, 에러 메시지, README 문서… 혼자 쓸 때는 대충 넘어갔던 것들을 전부 다듬어야 했어요. 시간이 걸리지만, 그 과정에서 코드 품질이 한 단계 올라갔어요.

교훈 4: 작은 도구도 존재 이유가 있어요

Dify가 11만 스타를 받았다고 해서 개인 프로젝트가 무의미한 건 아니에요. “MCP 네이티브 + 완전 로컬 + 크롤러 내장”이라는 조합은 기존 도구들이 채우지 못한 틈새(niche)예요. 작은 도구가 특정 상황에서는 거대한 플랫폼보다 더 적합할 수 있어요.

🚀 직접 사용해보고 싶다면

knowledge-rag를 사용해보고 싶은 분들을 위해 빠른 시작 가이드를 정리해볼게요.

설치

# 저장소 클론
git clone https://github.com/goandon/knowledge-rag
cd knowledge-rag

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

# 설정 파일 복사 후 편집
cp config.yaml.example config.yaml
# → config.yaml에 데이터 소스 경로,
#   API 토큰 등을 입력

BookStack 연동 설정 예시

# config.yaml 중 BookStack 섹션
bookstack:
  enabled: true
  base_url: "https://wiki.example.com"
  token_id: "your-token-id"
  token_secret: "your-token-secret"
  # 특정 book만 크롤링하고 싶다면:
  # book_ids: [1, 3, 7]

인덱싱 실행

# 전체 인덱싱 (최초 1회)
python indexer.py --full

# 증분 인덱싱 (변경분만)
python indexer.py --incremental

# BookStack만 크롤링
python indexer.py --source bookstack

MCP 서버 시작

# MCP 서버 실행
python mcp_server.py

# Claude Code에서 사용하려면
# .mcp.json에 서버 등록 후
# knowledge_search, knowledge_sync 등
# MCP 도구 호출 가능

자세한 설정 방법은 GitHub README를 참고해주세요!

🗺️ 시리즈 네비게이션

✅ 마무리 — 작은 도구의 큰 여정

2주 전, 단순히 “AI가 우리 문서를 읽을 수 있으면 좋겠다”는 생각에서 시작했어요. Gemini API의 429 에러와 싸우고, PyTorch MPS의 메모리 누수를 발견하고, MLX로 전환하고, 청크 캐시를 만들고, BookStack 크롤러를 추가하고… 정신없는 2주였어요.

그 결과물은 이래요:

• 7,671개 파일, 166,426개 청크, 100% 임베딩 완료
• 월 운영 비용 ₩0 (v1.0.0 대비 ₩30,000 절감)
• 4종 데이터 소스 크롤러 내장 (Confluence, Jira, BookStack, 로컬 파일)
• MIT 라이선스로 GitHub 공개

이 시리즈의 진짜 메시지는 기술적 성과가 아니에요. “삽질이 자산이 된다”는 거예요. Gemini API에서 실패하지 않았다면 로컬 임베딩을 시도하지 않았을 거고, MPS 메모리 누수를 만나지 않았다면 MLX의 존재를 몰랐을 거예요. 모든 실패가 다음 단계로 가는 디딤돌이었어요.

여러분도 자기만의 RAG 시스템을 만들어보고 싶다면, GitHub 저장소를 방문해주세요. 스타를 눌러주시면 힘이 돼요! 궁금한 점은 GitHub Issues나 댓글로 남겨주세요.

긴 시리즈 함께해주셔서 정말 고마워요. 앞으로도 재미있는 개발 이야기로 찾아올게요!

📖 References

• knowledge-rag GitHub Repository — MIT License, MCP-native local RAG server
• BookStack — Free & Open Source Wiki Platform (MIT, 16k+ GitHub Stars)
• BookStack REST API Documentation — Token Auth, Plaintext Export
• BAAI/bge-m3 — Multilingual Embedding Model (1024-dim, 100+ languages)
• LanceDB — Serverless Vector Database
• Model Context Protocol (MCP) — Anthropic
• Dify — Open-source LLM App Development Platform (111k+ Stars)
• RAGFlow — Deep Document Understanding RAG Engine (62k+ Stars)
• MLX — Apple Machine Learning Framework