JW MCP Server

Instructions

Implementation Reference

• src/tools/scripture-tools.js:211-300 (handler)

  Primary handler function that validates inputs, fetches data from scraper, assembles response with selected fields, and returns JSON.
  export async function getVerseWithStudyImplementation(book, chapter, verse, fields = ['verses', 'study_notes'], limit = 5, fetch = false) { try { // Validate inputs const validation = validateReference(book, chapter, verse); if (!validation.valid) { return { content: [{ type: 'text', text: `Validation error: ${validation.error}` }], isError: true }; } // Validate fields const validFields = ['verses', 'study_notes', 'study_articles', 'cross_references', 'chapter_level', 'combined_text']; const invalidFields = fields.filter(f => !validFields.includes(f)); if (invalidFields.length > 0) { return { content: [{ type: 'text', text: `Invalid fields: ${invalidFields.join(', ')}. Valid fields are: ${validFields.join(', ')}` }], isError: true }; } // Fetch verse with study content const studyData = await scraper.getVerseWithStudy(book, chapter, verse, { fields: fields, limit: limit }); // Format reference const reference = formatReference(book, chapter, studyData.verse_range); // Build response const response = { reference: reference, book_number: studyData.book_num, book_name: studyData.book_name, chapter: studyData.chapter, verse_range: studyData.verse_range }; // Add requested fields if (studyData.verses) { response.verses = studyData.verses; } if (studyData.combined_text) { response.combined_text = studyData.combined_text; } if (studyData.study_notes) { response.study_notes = studyData.study_notes; response.study_notes_count = Object.keys(studyData.study_notes).length; } if (studyData.study_articles) { response.study_articles = studyData.study_articles; response.study_articles_count = studyData.study_articles.length; } if (studyData.cross_references) { response.cross_references = studyData.cross_references; response.cross_references_count = studyData.cross_references.length; } if (studyData.chapter_level) { response.chapter_level = studyData.chapter_level; } return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] }; } catch (error) { return { content: [{ type: 'text', text: `Error fetching verse with study content: ${error.message}` }], isError: true }; } }
• src/tools/scripture-tools.js:169-209 (schema)

  Tool definition including name, description, and detailed inputSchema for validation.
  export const getVerseWithStudyTool = { name: 'get_verse_with_study', description: 'Get Bible verse(s) with comprehensive study content from wol.jw.org. Supports single verses or ranges (e.g., "14-16"). Returns verse text, study notes, cross-references, research articles from the Research Guide, and chapter outlines. Field selection allows you to customize what content is returned.', inputSchema: { type: 'object', properties: { book: { type: 'number', description: 'Bible book number (1-66). Use search_bible_books to find book numbers.' }, chapter: { type: 'number', description: 'Chapter number within the book' }, verse: { type: 'string', description: 'Single verse number (e.g., "14") or verse range (e.g., "14-16")' }, fields: { type: 'array', items: { type: 'string', enum: ['verses', 'study_notes', 'study_articles', 'cross_references', 'chapter_level', 'combined_text'] }, description: 'Content fields to include. Options: "verses" (verse text), "study_notes" (verse-specific notes), "study_articles" (research guide articles), "cross_references" (related scriptures), "chapter_level" (outline and chapter content), "combined_text" (all verses as single text). Default: ["verses", "study_notes"]', default: ['verses', 'study_notes'] }, limit: { type: 'number', description: 'Maximum number of study articles to return. Default: 5 for articles, unlimited for other fields.', default: 5 }, fetch: { type: 'boolean', description: 'Force fresh data from wol.jw.org (useful when content appears to be missing). Default: false', default: false } }, required: ['book', 'chapter', 'verse'] } };
• src/index.js:33-40 (registration)

  Registration of the tool in the allTools array used by the MCP server's ListToolsRequestHandler.
  const allTools = [ captionsTool, ...workbookTools, ...watchtowerTools, searchBibleBooksTool, getBibleVerseTool, getVerseWithStudyTool, getBibleVerseURLTool
• src/http-server.js:32-39 (registration)

  Registration of the tool in the allTools array for the HTTP MCP server.
  const allTools = [ captionsTool, ...workbookTools, ...watchtowerTools, searchBibleBooksTool, getBibleVerseTool, getVerseWithStudyTool, getBibleVerseURLTool
• src/tools/wol-scraper.js:402-475 (helper)

  Core helper method in WOLScraper that scrapes wol.jw.org, extracts verse/study content using Cheerio, and returns structured data used by the handler.
  async getVerseWithStudy(bookNum, chapterNum, verseInput, options = {}) { const { fields = ['verses', 'study_notes'], limit = null } = options; // Parse verse input (single number or range) let verseStart, verseEnd; if (typeof verseInput === 'string' && verseInput.includes('-')) { const parts = verseInput.split('-'); verseStart = parseInt(parts[0]); verseEnd = parseInt(parts[1]); } else { verseStart = verseEnd = parseInt(verseInput); } // Fetch chapter content const content = await this.extractChapterContent(bookNum, chapterNum); // Build result object based on requested fields const result = { book_num: bookNum, book_name: getBookName(bookNum), chapter: chapterNum, verse_range: verseStart === verseEnd ? `${verseStart}` : `${verseStart}-${verseEnd}` }; // Filter verses in range const versesInRange = content.verses.filter( v => v.verse_num >= verseStart && v.verse_num <= verseEnd ); // Add requested fields if (fields.includes('verses')) { result.verses = versesInRange; } if (fields.includes('combined_text')) { result.combined_text = versesInRange .map(v => `${v.verse_num}. ${v.verse_text}`) .join(' '); } if (fields.includes('study_notes')) { result.study_notes = {}; for (let v = verseStart; v <= verseEnd; v++) { if (content.verse_study_notes[v]) { result.study_notes[v] = content.verse_study_notes[v]; } } } if (fields.includes('study_articles') && content.chapter_study_data) { let articles = content.chapter_study_data.study_articles; if (limit && articles.length > limit) { articles = articles.slice(0, limit); } result.study_articles = articles; } if (fields.includes('cross_references') && content.chapter_study_data) { result.cross_references = content.chapter_study_data.cross_references; } if (fields.includes('chapter_level') && content.chapter_study_data) { result.chapter_level = { outline: content.chapter_study_data.outline, study_articles: content.chapter_study_data.study_articles, cross_references: content.chapter_study_data.cross_references }; } return result; }