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;
  }