Docusaurus와 MCP로 나만의 FAQ 만들기
몇 분 만에 전문적인 문서 사이트를 만들고, Claude AI가 Model Context Protocol(MCP)을 통해 콘텐츠를 작성하고 관리하도록 하세요.
만들게 될 것
이 가이드를 마치면 다음을 갖게 됩니다:
- Yundera 서버에서 실행되는 Docusaurus 문서 사이트
- Claude가 문서를 읽고, 쓰고, 검색하고, 빌드할 수 있는 Docusaurus MCP 연결
- 발행되어 라이브로 동작하는 첫 번째 FAQ 페이지
전제 조건
- Yundera 개인 클라우드 서버(PCS)
- Claude 또는 Claude Code CLI 접근 권한
1단계: Yundera에 Docusaurus 설치
- Yundera 대시보드를 엽니다
- App Store로 이동
- Docusaurus를 찾아 설치 클릭
- 초기화가 완료될 때까지 대기. 클래식 템플릿으로 Docusaurus 프로젝트가 생성됩니다.
문서 사이트가 https://docusaurus-<your-domain>에서 라이브로 동작합니다.
첫 설치는 npx create-docusaurus를 실행하고 사이트를 빌드하므로 1분 정도 걸립니다. 이후 재시작은 빠릅니다.
2단계: Docusaurus MCP 연결
Docusaurus MCP는 Docusaurus 앱에 자동으로 포함됩니다. Model Context Protocol을 통해 docs 폴더를 Claude에 노출합니다.
옵션 A: Claude.ai (Beacon)
서버에 Beacon이 설정되어 있으면 Docusaurus MCP가 자동 발견됩니다. Claude.ai를 열면 사용 가능한 도구에 나타납니다.
옵션 B: Claude Code CLI
MCP 서버를 수동으로 추가:
claude mcp add docusaurus-mcp \
--transport http \
"https://beacon-<your-server>.nsl.sh/mcp?hash=<your-hash>"
새 Claude Code 세션을 시작하고 /mcp로 확인합니다. docusaurus-mcp가 나와야 합니다.
3단계: 5가지 MCP 도구
Docusaurus MCP는 Claude가 사용할 수 있는 5가지 도구를 제공합니다:
| 도구 | 기능 |
|---|---|
list_docs | docs 폴더의 모든 .md, .mdx 파일을 경로, 크기, 수정일과 함께 목록 |
read_doc | 특정 문서 파일의 전체 내용 읽기 |
write_doc | 문서 파일 생성 또는 덮어쓰기 (상위 디렉토리 자동 생성) |
search_docs | 모든 문서에서 대소문자 무시 전문 검색 |
rebuild | npm run build 실행 후 웹 서버로 출력 복사. 변경사항이 즉시 반영 |
모든 경로는 docs/ 디렉토리 기준 상대 경로입니다. 예: guides/my-guide.md는 Docusaurus 프로젝트의 docs/guides/my-guide.md를 가리킵니다.
4단계: 첫 FAQ 작성
Claude에게 첫 FAQ 페이지를 만들어달라고 요청하세요:
"내 프로젝트의 FAQ 페이지를 만들어줘. 시작하기, 요금, 문제 해결에 대한 질문을 포함해."
Claude가 write_doc으로 파일을 생성하고, rebuild로 발행합니다.
예시: 수동 접근
구체적으로 지정하려면:
"docusaurus-mcp를 사용해서 faq/general.md에 다음 내용으로 파일을 작성하고, 사이트를 리빌드해줘."
Claude가:
write_doc("faq/general.md", "...")을 호출하여 파일 생성rebuild()를 호출하여 빌드 및 배포
5단계: SEO 모범 사례
모든 문서 페이지에 검색 엔진 최적화를 위한 frontmatter를 포함해야 합니다:
---
title: "페이지 제목"
description: "Google 검색 결과용 150-160자 설명"
keywords:
- 키워드1
- 키워드2
image: /img/yundera-social-card.png
---
Claude에게 "내 모든 문서를 검토하고 SEO frontmatter가 빠진 페이지에 추가해줘"라고 요청할 수 있습니다.
6단계: 문서 구성
Docusaurus는 docs/ 내부의 폴더 구조를 사이드바 네비게이션으로 사용합니다.
사이드바 순서
frontmatter에서 sidebar_position으로 순서를 제어합니다. 숫자가 작을수록 먼저 나타납니다.
다음은?
FAQ 사이트가 실행되고 MCP가 연결되었으니:
- 콘텐츠 추가: Claude에게 작성할 내용을 말하면 됩니다
- 테마 커스터마이즈:
src/css/custom.css에서 CSS 편집 - 커스텀 도메인 설정: 커스텀 도메인 가이드 참조
- 문서 검색: Claude에게 특정 콘텐츠 찾아달라고 요청
Docusaurus MCP로 문서는 대화 하나면 됩니다. 페이지 업데이트가 필요하면 요청만 하세요. 새 섹션을 추가하고 싶으면 설명하고 Claude가 나머지를 처리합니다.