Jupyter Book Writer

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 결과 대기

설치

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

개발 (TDD)

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

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

새 기능 추가 순서:

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