# jupyter-book-writer MCP

Claude Code용 MCP 서버 — 책을 읽고 Jupyter Book 노트북으로 정리하는 Study Note 작업의 반복 워크플로우를 자동화합니다.

## 왜 만들었나

Jupyter Book은 배포(`git push`)해야 렌더링을 볼 수 있습니다. 그 전에 발생하는 3가지 렌더링 실패가 반복되었습니다:

| 실패 패턴 | 원인 | 자동 수정 |
|---|---|---|
| `**text(English)**` 볼드 미적용 | CommonMark right-flanking delimiter rule — `)` 뒤에 `**`가 오고 한국어가 이어지면 닫힘 인식 불가 | `<strong>` 태그로 변환 |
| 수식이 빨간 코드 블록으로 렌더링 | `` `x ≤ 0` `` 형태로 작성 | `$x ≤ 0$` 인라인 math로 변환 |
| 마크다운 미렌더링 | `source`가 per-line list가 아닌 단일 문자열 | per-line list 포맷 강제 |

## 도구

| 툴 | 역할 |
|---|---|
| `add_cell(notebook_path, markdown, position)` | 셀 추가 — 위 3가지 수정 자동 적용 |
| `validate_notebook(notebook_path)` | 배포 전 검증 — 렌더링 이슈 사전 감지 |
| `update_toc(toc_path, chapter_index_file, section_files, parent_file)` | `_toc.yml` 챕터/섹션 추가 |
| `deploy_and_wait(repo_path, commit_msg, wait_for_ci, timeout_seconds)` | git add/commit/push + CI 결과 대기 |

## 설치

```bash
pip install mcp pyyaml
claude mcp add jupyter-book-writer --scope user -- python /path/to/server.py
```

## 개발 (TDD)

테스트를 먼저 작성하고, 서버가 통과할 때까지 구현합니다.

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

새 기능 추가 순서:
1. `tests/` 에 실패하는 테스트 작성
2. `server.py` 수정해서 통과
3. `validate_notebook` 에 해당 체크 추가 (재발 방지)