Cloudwiki/설정/MCP서버
# 개요
Cloudwiki는 외부 AI 에이전트가 별도의 브라우저 조작 없이 MCP 서버 도구 호출을 통해 정제된 텍스트 응답을 받아 위키 문서에 쉽게 접근할 수 있는 기능을 지원합니다.
MCP 서버 기능은 선택에 따라 활성화/비활성화 설정이 가능합니다.
이 문서에서는 MCP 서버의 활성화 설정 및 외부 AI 서비스와의 연동 방법을 안내합니다.
---
읽기 도구 목록
* search_title
위키 문서를 제목 키워드로 검색합니다. 찾으려는 문서의 이름을 알고 있을 때 가장 빠르게 접근할 수 있습니다.
* search_fts
위키 문서 본문 전체를 대상으로 전문 검색(Full-Text Search)합니다. 검색 결과에는 일치하는 문서 제목, 하이라이트된 본문 발췌, 해당 내용이 속한 목차명이 함께 반환됩니다.
* get_toc
문서 전체를 읽지 않고 목차(섹션 구조)만 추출합니다. 계층적 번호(예: `1.`, `1.1`, `1.1.1`)로 구성된 목차를 먼저 파악한 뒤, `read_section`으로 필요한 부분만 읽는 방식을 권장합니다. `raw=true` 옵션으로 편집용 원본 번호 체계를 사용할 수 있습니다.
* read_document
문서의 전체 본문을 읽어옵니다. 문서가 짧거나 전체 맥락이 필요한 경우에 사용하세요. 긴 문서는 `get_toc` → `read_section` 조합을 먼저 고려하세요.
* read_section
`get_toc`가 반환한 목차 번호를 지정해 문서의 특정 섹션만 읽어옵니다.
* read_document_batch
여러 문서를 한 번에 최대 10개까지 읽어옵니다. `titles` 배열로 슬러그를 직접 지정하거나, `parent_title`로 하위 문서를 일괄 읽을 수 있습니다. 결과에 읽은/읽지 않은 문서를 나타내는 트리가 포함됩니다.
* get_toc_batch
여러 문서의 목차를 한 번에 최대 10개까지 불러와 하나의 트리로 반환합니다.
* get_tree
지정한 문서를 루트로 한 하위 문서 계층 구조를 트리 형태로 반환합니다.
* search_category
카테고리 이름(부분 문자열)으로 카테고리를 검색합니다.
* get_category_info
특정 카테고리에 속한 문서 목록과 카테고리 설명을 반환합니다.
* get_document_category
특정 문서가 어느 카테고리에 속하는지 목록을 반환합니다.
* get_backlinks
특정 문서를 위키링크(`[[...]]`) 또는 틀 트랜스클루전(`{{...}}`)으로 참조하는 다른 문서 목록을 반환합니다.
* get_recent_changes
위키 전체에서 최근 수정된 문서 목록을 반환합니다. 최대 100개까지 조회 가능하며, 작성자·카테고리·날짜 필터를 지원합니다.
* list_discussions
특정 문서에 달린 토론 스레드 목록을 반환합니다.
* read_discussion
`list_discussions`에서 얻은 ID로 특정 토론 스레드의 전체 내용을 읽어옵니다.
* view_image
위키에 업로드된 이미지를 파일명으로 조회하여 이미지 데이터로 반환합니다.
* list_blog_posts
블로그(/blog) 포스트 목록을 최신순으로 반환합니다. 페이지당 최대 20개이며 페이지네이션을 지원합니다.
* read_blog_post
블로그 포스트의 전체 본문을 읽어옵니다. `id`는 정수 식별자를 사용합니다.
* get_blog_toc
블로그 포스트의 목차만 불러옵니다.
* read_blog_section
블로그 포스트의 특정 섹션만 읽어옵니다.
일반 유저 권한 추가 도구
`wiki:edit` 권한을 가진 일반 유저 계정으로 발급한 토큰에 위 읽기 도구와 함께 추가로 노출됩니다. 인증 없는 게스트 호출이나 권한이 박탈된 토큰(차단 등)에는 노출되지 않습니다.
**보조 읽기**
* read_revision — 특정 리비전의 본문 조회
* list_drafts — 본인의 진행 중 draft 목록 조회
* read_draft — 본인 draft의 현재 본문 확인
**편집 도구 (draft 모델)**
편집 도구는 즉시 저장하지 않고 본인 명의의 `draft`에 누적합니다. 편집이 끝나면 `commit_edit`를 호출해 하나의 리비전으로 저장합니다. draft는 마지막 활동 이후 12시간이 지나면 자동 삭제됩니다. 모든 commit은 리비전 summary에 `[MCP]` 접두가 자동으로 붙어 사람의 직접 편집과 구분됩니다.
* create_or_update_page — 문서 전체 본문을 새로 만들거나 통째로 교체
* patch_page — 문서의 특정 텍스트를 찾아 교체 (Claude Code Edit 방식)
* edit_section — 특정 섹션 본문 교체
* commit_edit — draft 커밋 (리비전 생성)
* discard_edit — draft 폐기
**즉시 적용 (draft 미사용)**
* revert_page — 특정 리비전으로 되돌리기
관리자 권한 추가 도구
`admin:access` 권한을 가진 관리자 계정으로 발급한 토큰에만 위 도구들과 함께 추가로 노출됩니다.
또한 관리자 계정의 MCP 연결에서는 관리자용 비공개 문서 열람 및 편집 잠금 문서 편집이 허용됩니다.
**읽기 전용**
* list_deleted_pages — 소프트 삭제된 문서 목록 조회
**즉시 적용 (draft 미사용)**
* delete_page — 문서 소프트 삭제 (복원 가능). `hard=true`로 영구 삭제 시 super_admin 권한 필요.
* restore_page — 소프트 삭제된 문서 복원
* move_page — 문서 슬러그 변경 (백링크 자동 갱신)
* set_page_status — 본문은 수정하지 않고 카테고리만 변경합니다. 본문을 읽거나 새 리비전을 만들지 않으며, 변경 내역은 `admin_log` 에만 기록됩니다. 비공개 설정·편집 잠금/관리자 전용 ACL은 별도 API 또는 권한 관리 모달에서 설정합니다.
# 설정 방법
## MCP 서버 설정 변경
GitHub 또는 에디터에서 `wrangler.toml` 파일을 찾아 열고, `MCP_MODE = "disabled"` 를 찾습니다.
`"disabled"` 값을 `"enabled"` 등 `disabled`가 아닌 값으로 변경 후 파일을 저장합니다.
## 변경사항 배포 및 적용
Github와 Cloudflare Workers가 연동된 경우, 파일이 저장되었을때 자동으로 배포됩니다.
로컬에서 작업한 경우, 프로젝트 폴더의 루트 경로에서 터미널을 열고 `npx wrangler deploy` 를 입력해 배포합니다.
배포는 보통 1~2분 이내에 완료됩니다.
## 적용 상태 확인 및 MCP 서버 URL 확인
배포 완료 후 관리자 콘솔에 접속 시 MCP 서버의 URL을 확인할 수 있습니다.
## MCP 서버 연결 및 사용
### 인증 (하이브리드 OAuth 2.1)
MCP 서버는 **하이브리드 인증** 모드로 동작하며, 호출자의 권한에 따라 노출되는 도구가 다음 3계층으로 결정됩니다.
* **인증 없음 / 권한 박탈된 토큰 (banned 등)** — 위의 읽기 도구만 사용 가능합니다. 별도 OAuth 흐름 없이 곧바로 위키 탐색이 가능합니다. 토큰이 유효하더라도 사용자 계정이 차단되었거나 `wiki:read`/`admin:access` 권한이 모두 박탈된 경우 자동으로 이 계층으로 강등됩니다.
* **일반 유저 (`wiki:edit`)** — 읽기 도구 + draft 편집 도구 + `revert_page` + 보조 읽기(`read_revision`/draft 조회) 까지 사용할 수 있습니다.
* **관리자 (`admin:access`)** — 위 항목 + 관리자 전용 도구(`delete_page`/`restore_page`/`move_page`/`set_page_status`/`list_deleted_pages`) 까지 모든 도구를 사용할 수 있습니다.
Claude 등 MCP 클라이언트에서 URL을 입력하면, 편집 권한이 필요한 시점에 자동으로 OAuth 인증 흐름(`/oauth/authorize`)이 시작되어 액세스 토큰이 Bearer 헤더로 사용됩니다. 단순히 위키 내용을 읽기만 한다면 인증 없이도 사용할 수 있습니다.
토큰이 만료/폐기되었거나 형식이 잘못된 경우는 `401 + WWW-Authenticate` 응답으로 클라이언트의 재인증을 유도합니다.
> `WIKI_VISIBILITY = "closed"` 환경에서는 비인증 호출도 401로 차단되어 OAuth 흐름이 강제됩니다 (비공개 위키 정책 일관성).
연결이 완료되면 AI가 직접 위키를 탐색할 수 있습니다.
# 참고
MCP 서버 도구를 통해 문서를 읽는 경우, `{color:#FFFF00}` 등 AI의 맥락 파악에 불필요한 단순 꾸미기 문법이 제거된 내용이 반환됩니다.
MCP 서버를 통해 발생한 수정 내역은 `[MCP]` 가 표시됩니다.