# wiki-mcp

> [**English**](README.en.md) · **한국어**

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

[OpenCode](https://opencode.ai) 및 모든 MCP 호환 클라이언트에서 사용 가능합니다.

## 기능

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

## 사전 요구사항

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

## 설치

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

```bash
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 직접 설치 (읽기 전용)

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

## 설정

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

```jsonc
{
  "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` 생성 |
| `wiki_add` | 외부 `.md` 파일을 위키로 복사 (`source`로 파일 경로 지정) |

## 경로 규칙

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

| 규칙 | 예시 | 결과 |
|------|------|------|
| wiki root 기준 상대 경로 | `dev/mcp.md` | ✅ 정상 동작 |
| `.md` 확장자 생략 가능 | `dev/mcp` | ✅ 자동으로 `.md` 붙여줌 |
| 절대 경로 | `/home/user/doc/wiki/docs/dev/mcp.md` | ❌ 거부됨 |
| wiki root 이탈 시도 | `../../etc/passwd` | ❌ Path traversal 방어로 차단 |
| 존재하지 않는 디렉터리 | `new-dir/foo.md` | ❌ `wiki_create_dir()`로 먼저 생성 필요 |

> 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