wiki-mcp

English · 한국어

MCP (Model Context Protocol) 기반 개인 마크다운 위키 관리 서버입니다. 검색, 탐색, 읽기, 쓰기, 삭제, 이동 도구를 제공하며, AGENTS.md 규칙에 따라 index.md를 자동으로 관리합니다.

OpenCode 및 모든 MCP 호환 클라이언트에서 사용 가능합니다.

기능

• 검색 — 제목, 헤딩, 본문 전체 텍스트 검색
• 탐색 — 디렉터리 목록 보기, 전체 문서 트리 표시
• 읽기 — 모든 마크다운 문서 열기
• 쓰기 — 새 문서 생성 시 index.md에 자동 등록
• 수정 — 문서 편집; 제목 변경 시 index.md 자동 갱신
• 삭제 — 문서 삭제 시 index.md 항목 및 빈 섹션 자동 정리
• 이동 — 문서 이동 시 원본/대상 index.md 모두 갱신
• 디렉터리 생성 — 새 디렉터리와 기본 index.md 생성
• Path traversal 방어 — 모든 경로를 위키 루트 기준으로 검증

사전 요구사항

• Python 3.11+
• mcp>=1.0.0 (자동 설치됨)

설치

방법 A: 클론 + editable install (개발/수정 필요 시 권장)

git clone https://github.com/icarus-inte01/wiki-mcp.git
cd wiki-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

방법 B: pip 직접 설치 (읽기 전용)

pip install git+https://github.com/icarus-inte01/wiki-mcp.git

설정

OpenCode의 ~/.config/opencode/opencode.jsonc에 MCP 서버를 등록합니다:

{
  "mcp": {
    "wiki": {
      "type": "local",
      "command": ["/path/to/wiki-mcp/.venv/bin/python", "-m", "wiki_mcp", "/path/to/wiki/docs"],
      "enabled": true
    }
  }
}

/path/to/wiki/docs를 실제 마크다운 위키 디렉터리의 절대 경로로 변경하세요.

도구

도구	설명
wiki_search	키워드로 문서 검색 (제목/헤딩/본문 범위 지정 가능)
wiki_list	디렉터리의 마크다운 문서 목록 표시
wiki_read	문서 전체 내용 읽기
wiki_tree	디렉터리별 전체 문서 트리 표시
wiki_write	새 문서 생성 (index.md에 자동 추가)
wiki_update	문서 내용 업데이트 (제목 변경 시 index.md 갱신)
wiki_delete	문서 삭제 (index.md에서 자동 제거)
wiki_move	문서 이동/이름 변경 (원본/대상 index.md 모두 갱신)
wiki_create_dir	새 디렉터리와 기본 index.md 생성

index.md 관리 규칙

서버는 AGENTS.md 규칙을 자동으로 따릅니다:

• 새 파일 생성 → 같은 디렉터리의 index.md에 항목 추가
• 제목 변경 → index.md 항목 갱신
• 파일 삭제 → index.md에서 항목 제거; 빈 섹션도 함께 정리
• 파일 이동 → 원본 index.md에서 제거, 대상 index.md에 추가
• index.md 자체는 자기 자신의 목록에 포함되지 않음

프로젝트 구조

wiki-mcp/
├── wiki_mcp/
│   ├── __init__.py
│   ├── __main__.py      # CLI 진입점: python -m wiki_mcp <wiki_root>
│   └── server.py        # MCP 서버 (9개 도구)
├── pyproject.toml
├── .gitignore
└── README.md

라이선스

MIT