get-chapter

Instructions

Implementation Reference

• src/index.ts:30-54 (registration)

  Tool registration with name 'get-chapter' and input schema definition (book, chapter, version)

  {
    name: "get-chapter",
    description: "Get all verses from a specific chapter of the Korean Bible",
    inputSchema: {
      type: "object",
      properties: {
        book: {
          type: "string",
          description: "Book name (English or Korean) or code (e.g., 'Genesis', '창세기', 'gen')",
        },
        chapter: {
          type: "number",
          description: "Chapter number",
          minimum: 1,
        },
        version: {
          type: "string",
          description: "Bible translation version (default: GAE)",
          enum: ["GAE", "GAE1", "NIR", "KOR", "CEV"],
          default: "GAE",
        },
      },
      required: ["book", "chapter"],
    },
  },

• src/index.ts:174-200 (handler)

  Handler logic for 'get-chapter': validates input via Zod schema, resolves book code, fetches chapter data via API, formats verses as markdown text, and returns result

  case "get-chapter": {
    const validated = validateInput(getChapterSchema, args, 'get-chapter');
    const bookCode = findBookCode(validated.book);
    if (!bookCode) {
      return {
        content: [
          {
            type: "text",
            text: `Error: Book '${validated.book}' not found. Use list-books to see available books.`,
          },
        ],
      };
    }
  
    const chapterData = await fetchChapter(bookCode, validated.chapter, validated.version || "GAE");
  
    let result = `# ${chapterData.book} (${chapterData.bookKorean}) ${chapterData.chapter}\n`;
    result += `**Translation:** ${chapterData.versionName}\n\n`;
  
    for (const verse of chapterData.verses) {
      result += `**${verse.number}.** ${verse.text}\n\n`;
    }
  
    return {
      content: [{ type: "text", text: result }],
    };
  }

• src/validation.ts:3-7 (schema)

  Zod validation schema for 'get-chapter' input: required book (string), required chapter (positive int), optional version (one of 5 translations)

  export const getChapterSchema = z.object({
    book: z.string().min(1),
    chapter: z.number().positive().int(),
    version: z.enum(['GAE', 'GAE1', 'NIR', 'KOR', 'CEV']).optional(),
  });

• src/bible.ts:183-274 (helper)

  Core helper function that fetches chapter data from the Bible API with caching, retry logic, timeout, and HTML parsing (cheerio) to extract verses from span elements

  export async function fetchChapter(
    bookCode: string,
    chapter: number,
    version: string = "GAE"
  ): Promise<Chapter> {
    const cacheKey = `${version}:${bookCode}:${chapter}`;
    const cached = verseCache.get(cacheKey);
    if (cached) {
      return cached;
    }
  
    const url = `${CONFIG.API.BASE_URL}?version=${version}&book=${bookCode}&chap=${chapter}`;
  
    for (let attempt = 0; attempt <= CONFIG.API.RETRY.MAX_RETRIES; attempt++) {
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), CONFIG.API.TIMEOUT);
      try {
        const response = await fetch(url, { signal: controller.signal });
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
  
        const html = await response.text();
        const $ = cheerio.load(html);
  
        const verses: Verse[] = [];
        const seenVerses = new Set<number>();
  
        // Parse verses from span elements
        // The website uses span elements where verse text starts with verse number
        $("span").each((i, elem) => {
          const text = $(elem).text().trim();
  
          // Look for pattern: number followed by spaces and text
          const match = text.match(/^(\d+)\s+(.+)$/s);
          if (match) {
            const verseNum = parseInt(match[1]);
            let verseText = match[2];
  
            // Remove footnote markers (like 1), 2), etc.)
            verseText = verseText.replace(/\d+\)/g, "").trim();
  
            // Remove explanatory text that comes after line breaks (like "또는 ...")
            const lines = verseText.split("\n");
            verseText = lines[0].trim();
  
            // Avoid duplicate verses (website has multiple spans per verse)
            if (!seenVerses.has(verseNum)) {
              seenVerses.add(verseNum);
              verses.push({
                number: verseNum,
                text: verseText,
              });
            }
          }
        });
  
        // Empty-verse guard
        if (verses.length === 0) {
          console.error(`Warning: No verses parsed for ${bookCode} chapter ${chapter} (version: ${version})`);
        }
  
        const bookInfo = getBookInfo(bookCode);
  
        const chapterData: Chapter = {
          book: bookInfo?.name || bookCode,
          bookKorean: bookInfo?.korean || "",
          chapter,
          version,
          versionName: TRANSLATIONS[version] || version,
          verses,
        };
  
        verseCache.set(cacheKey, chapterData);
        return chapterData;
      } catch (error: unknown) {
        if (attempt === CONFIG.API.RETRY.MAX_RETRIES) {
          throw new Error(`Failed to fetch chapter ${bookCode} ${chapter}: ${error}`);
        }
        const delay = Math.min(
          CONFIG.API.RETRY.INITIAL_DELAY_MS * Math.pow(CONFIG.API.RETRY.BACKOFF_FACTOR, attempt),
          CONFIG.API.RETRY.MAX_DELAY_MS
        );
        await new Promise(r => setTimeout(r, delay));
      } finally {
        clearTimeout(timeoutId);
      }
    }
  
    // Unreachable, but TypeScript needs it
    throw new Error(`Failed to fetch chapter ${bookCode} ${chapter} after retries`);
  }

• src/bible.ts:148-170 (helper)

  Helper function to resolve book name (English, Korean, or code) to a normalized book code used by the API

  export function findBookCode(bookName: string): string | null {
    const normalized = bookName.toLowerCase().trim();
    if (!normalized) return null;
  
    // Try direct match
    for (const [name, info] of Object.entries(BIBLE_BOOKS)) {
      if (name.toLowerCase() === normalized ||
          info.korean === bookName ||
          info.code === normalized) {
        return info.code;
      }
    }
  
    // Try partial match
    for (const [name, info] of Object.entries(BIBLE_BOOKS)) {
      if (name.toLowerCase().includes(normalized) ||
          info.korean.includes(bookName)) {
        return info.code;
      }
    }
  
    return null;
  }