jw-mcp

JW.org 공개 자료(성경·파수대·집회 워크북·영상 자막·교과)를 Claude 에서 대화로 쓰기 위한 원격 MCP 서버. 자체 OAuth 2.1 인증(다중 사용자)을 갖추고 hosub 홈서버에서 독립 프로세스로 돈다.

상류 advenimus/jw-mcp 의 도구 구현을 이어받되, Smithery 호스팅 전제를 걷어내고 자체 호스팅 + 인증 + 운영 관측을 붙였다.

특징

• 도구 11종 — 성경 구절·연구 노트, 파수대, 집회 워크북, 영상 자막, 교과
• 자체 OAuth 2.1 — hosub 의 인증과 코드·DB·issuer 를 전혀 공유하지 않는다
• 다중 사용자 — 가입 → 관리자 승인 → 커넥터 연결. 계정을 끄면 토큰이 즉시 죽는다
• 경로 분리 배치 — hosub.duckdns.org/jw 하나로 기존 서비스와 도메인을 공유
• 대시보드 API — hosub 대시보드가 그대로 그릴 수 있는 형태로 지표를 내보낸다
• 이중 진입점 — 원격(HTTP+OAuth)과 로컬(stdio, 인증 없음)을 같은 도구 목록으로

도구

도구	설명
search_bible_books	성경 책 이름 검색 (한/영)
get_bible_verse	구절 본문 조회
get_verse_with_study	구절 + 연구 노트 + 상호 참조
get_bible_verse_url	jw.org finder 링크 생성
getWatchtowerLinks	연구용 파수대 기사 목록 (현재 호 자동 계산)
getWatchtowerContent	파수대 기사 본문 (RTF → 평문)
getWorkbookLinks	집회 워크북 주차 목록
getWorkbookContent	워크북 주차 본문 (RTF → 평문)
get_lesson_list	교과 과 목록
get_lesson_content	교과 본문
get_jw_captions	영상 자막 (ID 또는 URL)

성경 책 번호는 1–39(구약) / 40–66(신약). 파수대는 현재 월 −2개월이 연구용 호다 (2026년 7월 → 2026년 5월호). 언어는 langwritten 으로 바꾼다(E 기본, K 한국어).

아키텍처

[claude.ai / 모바일 앱]
      │ Custom Connector (OAuth 2.1 + PKCE)
      ▼
[Caddy · hosub.duckdns.org]
      ├─ /jw/*                          ──▶ jw-mcp  127.0.0.1:8604   ← 이 저장소
      ├─ /.well-known/oauth-*/jw...     ──▶ jw-mcp  127.0.0.1:8604
      ├─ / · /api/* · /static/*         ──▶ hosub 대시보드 :8701
      └─ (그 외)                         ──▶ hosub MCP :8700

[hosub 대시보드 :8701] ──▶ http://127.0.0.1:8604/api/dash/*   (Caddy 미라우팅 = 비공개)

jw-mcp 는 hosub 과 호스트만 공유한다. 프로세스·저장소·DB·OAuth issuer·실행 계정이 전부 분리되어 있어, 한쪽을 배포하거나 껐다 켜도 다른 쪽 세션이 끊기지 않는다.

인증 경계

경계	자격증명	쓰이는 곳
MCP 도구 호출	OAuth 2.1 Bearer (사용자 계정에 바인딩)	POST /jw/mcp
브라우저 로그인	서명 세션 쿠키 (Path=/jw)	계정·관리자 화면
대시보드 조회	X-Internal-Token + 루프백 전용	/api/dash/*

셋은 서로를 대신하지 못한다. 특히 세션 쿠키로는 /jw/mcp 에 접근할 수 없다.

다중 사용자 정책

가입 → status=pending → 관리자 승인 → active → 커넥터 연결 가능

• 최초 가입자는 자동으로 관리자 겸 활성 사용자가 된다(그러지 않으면 아무도 아무를 승인할 수 없다). JW_ADMIN_EMAILS 로 추가 관리자를 지정할 수 있다.
• JW_INVITE_CODE 를 설정하면 코드를 아는 사람은 승인 없이 바로 쓴다.
• 계정을 disabled 로 바꾸면 이미 발급된 토큰이 그 즉시 전부 무효가 된다 (Bearer 검증이 매 요청 계정 상태를 확인한다). 리프레시로도 되살아나지 않는다.
• 마지막 활성 관리자는 비활성화할 수 없다 — 자기 자신을 잠그는 사고 방지.

설치

서버 설치 절차는 docs/SETUP.md 를 따른다. 요약:

sudo git clone https://github.com/teenfo/JW-MCP.git /opt/jw-mcp
sudo bash /opt/jw-mcp/deploy/bootstrap.sh     # 유저·의존성·.env·systemd 자동 준비
# 출력되는 안내대로 Caddy 스니펫 반영 → /jw/signup 에서 첫 계정 생성

main 에 머지하면 jw-mcp-update.timer 가 5분 내 자동 배포한다(pull 기반).

로컬 개발

npm install
npm test                 # 도구 레지스트리 단위 테스트 (네트워크 불필요)
npm run test:oauth       # OAuth 전 구간 통합 테스트 (서버를 직접 띄운다)

JW_SESSION_SECRET=$(openssl rand -hex 32) \
JW_INTERNAL_TOKEN=$(openssl rand -hex 32) \
JW_SECURE_COOKIES=false \
npm run start:http       # http://127.0.0.1:8604/jw/signup

로컬 Claude Desktop 은 인증 없이 stdio 로 붙일 수 있다:

{ "mcpServers": { "jw": { "command": "node", "args": ["/path/to/JW-MCP/src/index.js"] } } }

도구를 추가할 때

src/tools/registry.js 한 곳만 고치면 stdio·HTTP 양쪽에 동시에 반영된다. 상류처럼 진입점마다 배열을 따로 들고 있지 않으므로 한쪽만 고쳐 누락되는 일이 없다.

1. src/tools/<이름>.js 에 도구 정의 + 구현 + 핸들러(자기 도구가 아니면 null 반환)
2. src/tools/registry.js 의 allTools 와 toolHandlers 에 추가
3. tests/registry.test.js 의 도구 개수 갱신

문서

• docs/SETUP.md — 서버 설치·Caddy 반영·대시보드 연동 런북
• docs/DASHBOARD-API.md — 대시보드 연동 API 스펙 (소비자 구현용 계약)
• docs/UPSTREAM-README.md — 상류 저장소 원문 (도구 상세)
• CLAUDE.md — Claude Code 용 저장소 안내

라이선스

MIT. JW.org 공개 자료를 조회할 뿐이며 어떤 콘텐츠도 재배포하지 않는다. 이 저장소는 Watch Tower Bible and Tract Society 와 무관한 비공식 프로젝트다.