getWatchtowerLinks

Instructions

Implementation Reference

• src/tools/watchtower-tools.js:7-34 (handler)

  Core handler function implementing the getWatchtowerLinks tool logic. Fetches publication data from JW.org API, processes files to extract article links, skipping the ZIP file.

  export async function getWatchtowerLinks(pub = 'w', langwritten = 'E', issue = null, fileformat = 'RTF') {
    try {
      // Use current Watchtower issue (2 months behind) if none provided
      const finalIssue = issue || getCurrentWatchtowerIssue();
      const { files, pubName, formattedDate, language } = await fetchPublicationData(pub, langwritten, finalIssue, fileformat);
      
      // Skip the first item (ZIP file) and return the individual articles
      const articles = files.slice(1).map((file, index) => ({
        title: file.title,
        url: file.file.url,
        filesize: file.filesize,
        track: file.track,
        modifiedDatetime: file.file.modifiedDatetime,
        checksum: file.file.checksum
      }));
  
      return {
        pubName,
        formattedDate,
        issue: finalIssue,
        language,
        articles
      };
  
    } catch (error) {
      throw new Error(`Failed to fetch Watchtower links: ${error.message}`);
    }
  }

• src/tools/watchtower-tools.js:59-103 (registration)

  Registration of Watchtower tools for MCP server, including schema and description for getWatchtowerLinks.

  export const watchtowerTools = [
    {
      name: 'getWatchtowerLinks',
      description: 'STEP 1: Get JW.org Watchtower study articles. When a user asks for current/this week\'s Watchtower content, use this tool FIRST without any parameters - it automatically gets the correct issue for current study articles (Watchtower publications are 2 months ahead, so May 2025 studies come from March 2025 issue). Returns article titles like "Imitate the Faithful Angels (July 14-20)" with their RTF download URLs. Just use defaults for current articles.',
      inputSchema: {
        type: 'object',
        properties: {
          pub: {
            type: 'string',
            description: 'Publication code: "w" for Watchtower (Study edition)',
            default: 'w'
          },
          langwritten: {
            type: 'string', 
            description: 'Language code: "E" for English, "S" for Spanish, etc.',
            default: 'E'
          },
          issue: {
            type: 'string',
            description: 'Issue in YYYYMM00 format. Leave empty for current study articles (server automatically calculates correct issue - Watchtower studies are 2 months ahead of publication)'
          },
          fileformat: {
            type: 'string',
            description: 'File format: "RTF" for Rich Text Format',
            default: 'RTF'
          }
        },
        required: []
      }
    },
    {
      name: 'getWatchtowerContent',
      description: 'STEP 2: Get the actual Watchtower article content after user chooses an article. Use this tool AFTER getWatchtowerLinks when user specifies which article they want (e.g., "Imitate the Faithful Angels" or "Look to Jehovah for Comfort"). Takes the RTF URL from Step 1 results, downloads the RTF file, parses it to clean plain text, and returns the formatted article content with proper structure and line breaks.',
      inputSchema: {
        type: 'object',
        properties: {
          url: {
            type: 'string',
            description: 'The RTF file URL from getWatchtowerLinks results (e.g., "https://cfp2.jw-cdn.org/a/...")'
          }
        },
        required: ['url']
      }
    }
  ];

• src/tools/watchtower-tools.js:107-132 (handler)

  MCP-specific handler dispatch block within handleWatchtowerTools that calls the core getWatchtowerLinks function based on tool name.

  // Handle getWatchtowerLinks tool
  if (request.params.name === 'getWatchtowerLinks') {
    try {
      const { pub, langwritten, issue, fileformat } = request.params.arguments || {};
      const result = await getWatchtowerLinks(pub, langwritten, issue, fileformat);
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/rtf-utils.js:20-27 (helper)

  Helper function to compute the current Watchtower study issue (2 months behind publication date). Used by getWatchtowerLinks when no issue provided.

  export function getCurrentWatchtowerIssue() {
    const now = new Date();
    // Subtract 2 months to get the correct Watchtower issue
    const targetDate = new Date(now.getFullYear(), now.getMonth() - 2, 1);
    const year = targetDate.getFullYear();
    const month = String(targetDate.getMonth() + 1).padStart(2, '0');
    return `${year}${month}00`;
  }

• src/tools/rtf-utils.js:57-91 (helper)

  Helper function that calls JW.org pub-media API to fetch publication files data, used by getWatchtowerLinks to get the links.

  export async function fetchPublicationData(pub, langwritten = 'E', issue = null, fileformat = 'RTF') {
    try {
      // Use current issue if none provided
      const finalIssue = issue || getCurrentIssue();
      
      const apiUrl = `https://b.jw-cdn.org/apis/pub-media/GETPUBMEDIALINKS?pub=${pub}&langwritten=${langwritten}&issue=${finalIssue}&fileformat=${fileformat}&output=json`;
      
      const response = await fetch(apiUrl);
      
      if (!response.ok) {
        throw new Error(`API request failed: ${response.statusText}`);
      }
  
      const data = await response.json();
      
      // Extract files for the specified language and format
      const files = data.files?.[langwritten]?.[fileformat];
      
      if (!files || files.length === 0) {
        throw new Error(`No ${fileformat} files found for ${pub} in ${langwritten}`);
      }
  
      return {
        data,
        files,
        pubName: data.pubName,
        formattedDate: data.formattedDate,
        issue: data.issue,
        language: data.languages[langwritten].name
      };
  
    } catch (error) {
      throw new Error(`Failed to fetch publication data: ${error.message}`);
    }
  }