bible-ko-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP (Model Context Protocol) server that provides Korean Bible data from bskorea.or.kr to Claude Desktop. Implements 6 tools for Bible verse retrieval, search, and translation comparison.

Key Technologies: TypeScript, MCP SDK, cheerio (HTML parsing), node-fetch, Zod (validation)

Data Source: https://www.bskorea.or.kr/bible/korbibReadpage.php

Development Commands

npm run build     # Build (must do before testing changes)
npm test          # Run vitest suite (106 tests, 4 files)
npm run watch     # Watch mode (auto-rebuild)
npm start         # Start MCP server (after building)

Before Committing

npm test          # Must pass all 106 tests
npm run build     # Must compile without errors

Architecture

Module Structure

src/
├── bible.ts       # Domain logic: data, cache, fetch, parse, search
├── index.ts       # MCP server: tool definitions + handlers
├── config.ts      # Configuration constants
├── validation.ts  # Zod schemas for tool inputs
└── tests/
    ├── bible-study.test.ts  # Integration tests
    ├── fetch-retry.test.ts  # Retry/backoff tests
    ├── unit.test.ts         # Unit tests
    ├── validation.test.ts   # Zod schema validation tests
    └── helpers.ts           # Re-exports from bible.ts + getVerses()

• src/bible.ts — All Bible domain logic (BIBLE_BOOKS, TRANSLATIONS, SimpleCache, findBookCode, getBookInfo, fetchChapter, searchVerses). Importable without starting the MCP server.
• src/index.ts — MCP server setup, 6 tool definitions, tool handler switch statement. Imports everything from bible.ts.
• src/config.ts — API URL, timeout, retry settings (3 retries, exponential backoff), cache settings (30-min TTL, 2000 max entries), search limits.
• src/validation.ts — Zod schemas for all tool inputs.

HTML Parsing Strategy

The website uses <span> elements with verse text starting with verse numbers:

<span>1   태초에 하나님이 천지를 창조하시니라</span>