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 방어 — 모든 경로를 위키 루트 기준으로 검증

Related MCP server: Project RAG wiki

사전 요구사항

• 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를 실제 마크다운 위키 디렉터리의 절대 경로로 변경하세요.

도구

경로 규칙

모든 도구의 path 파라미터는 wiki root 기준 상대 경로입니다.

wiki root는 서버 실행 시 인자로 전달된 디렉터리입니다. 현재 환경 기준 **~/doc/wiki/docs/**입니다.

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