PubNub MCP Server

Instructions

Implementation Reference

• index.js:113-200 (handler)

  Main execution handler for read_pubnub_sdk_docs tool. Handles parameters language and apiReference, loads from cache or fetches SDK docs from PubNub site, combines with additional resources, and returns markdown content.

  toolHandlers['read_pubnub_sdk_docs'] = async ({ language, apiReference }) => {
      const apiRefKey = apiReference === 'App Context' ? 'objects' : apiReference;
      // Early return for PubNub Functions documentation
      if (apiRefKey === 'functions') {
        try {
          const functionsDoc = fs.readFileSync(
            pathJoin(__dirname, 'resources', 'pubnub_functions.md'),
            'utf8'
          );
          return { content: [ { type: 'text', text: functionsDoc } ] };
        } catch (err) {
          return {
            content: [ { type: 'text', text: `Error loading functions documentation: ${err}` } ],
            isError: true
          };
        }
      }
  
      // Special case for rest-api - load only the three specific files
      if (language === 'rest-api') {
        const restApiFiles = [
          'rest-api_publish-message-to-channel.md',
          'rest-api_subscribe-v-2.md',
          'rest-api_get-message-history.md'
        ];
        
        let combinedRestApiContent = '';
        
        for (const filename of restApiFiles) {
          try {
            const filePath = pathJoin(__dirname, 'resources', 'sdk_docs', filename);
            const content = fs.readFileSync(filePath, 'utf8');
            combinedRestApiContent += content + '\n\n';
          } catch (err) {
            //console.error(`Error loading ${filename}: ${err}`);
            combinedRestApiContent += `Error loading ${filename}: ${err.message}\n\n`;
          }
        }
        
        return {
          content: [
            {
              type: 'text',
              text: combinedRestApiContent + getPubNubInitSDKInstructions(),
            },
          ],
        };
      }
  
      // Regular processing for other languages
      // Try to load from cached files first (with version checking), fallback to API calls if not available or outdated
      let sdkResponse = loadCachedSDKDoc(language, 'overview');
      if (!sdkResponse) {
        const sdkURL = `https://www.pubnub.com/docs/sdks/${language}`;
        sdkResponse = await loadArticle(sdkURL);
      }
  
      let apiRefResponse = loadCachedSDKDoc(language, apiRefKey);
      if (!apiRefResponse) {
        const apiRefURL = `https://www.pubnub.com/docs/sdks/${language}/api-reference/${apiRefKey}`;
        apiRefResponse = await loadArticle(apiRefURL);
  
        // Apply "(old)" section removal logic for dynamically loaded content
        if (apiRefResponse && !apiRefResponse.startsWith('Error fetching')) {
          const lines = apiRefResponse.split('\n');
          const oldIndex = lines.findIndex((line) => /^##\s.*\(old\)/i.test(line));
          if (oldIndex !== -1) {
            apiRefResponse = lines.slice(0, oldIndex).join('\n');
          }
        }
      }
  
      const context7Response = loadLanguageFile(language);
      const presenceBestPracticesResponse = loadPresenceBestPracticesFile(language);
  
      // Combine the content of both responses
      const combinedContent = [sdkResponse, apiRefResponse, context7Response, presenceBestPracticesResponse].join('\n\n');
  
      // Return the combined content
      return {
        content: [
          {
            type: 'text',
            text: combinedContent + getPubNubInitSDKInstructions(),
          },
        ],
      };
  };

• index.js:103-110 (schema)

  Zod schema and metadata definition for the read_pubnub_sdk_docs tool, including name, description, and input parameters (language enum and optional apiReference).

  toolDefinitions['read_pubnub_sdk_docs'] = {
    name: 'read_pubnub_sdk_docs',
    description: 'Retrieves official PubNub SDK documentation for a given programming language and API reference section. Call this tool for low-level API details, code examples, and usage patterns. Returns documentation in markdown format. For conceptual guides, best practices, and how-tos, also call the read_pubnub_resources tool.',
    parameters: {
      language: z.enum(languages).describe('Programming language of the PubNub SDK to retrieve documentation for (e.g. javascript, python)'),
      apiReference: z.enum(apiReferences).optional().default('configuration').describe('API reference section to retrieve (e.g. configuration, publish-and-subscribe, objects (App Context); defaults to configuration)'),
    }
  };

• index.js:1363-1394 (registration)

  Registration function that adds the read_pubnub_sdk_docs tool to the MCP server using server.tool(). Excludes it when chatSdkMode is true. Called for main server and HTTP session servers.

  function registerAllTools(serverInstance, chatSdkMode = false) {
    // Tools to exclude when in chat SDK mode
    const chatSdkExcludedTools = [
      'read_pubnub_sdk_docs',
      'write_pubnub_app', 
      'read_pubnub_resources',
      'manage_pubnub_account'
    ];
  
    for (const toolName in toolDefinitions) {
      if (toolHandlers[toolName]) {
        // Skip excluded tools when in chat SDK mode
        if (chatSdkMode && chatSdkExcludedTools.includes(toolName)) {
          continue;
        }
  
        // Special handling for chat SDK docs tool
        if (toolName === 'read_pubnub_chat_sdk_docs' && 
            (chatSdkLanguages.length === 0 || chatSdkTopics.length === 0)) {
          continue; // Skip this tool if chat SDK data isn't loaded
        }
        
        const toolDef = toolDefinitions[toolName];
        serverInstance.tool(
          toolDef.name,
          toolDef.description,
          toolDef.parameters,
          wrapToolHandler(toolHandlers[toolName], toolName)
        );
      }
    }
  }

• index.js:238-274 (helper)

  Helper function to load cached SDK documentation from resources/sdk_docs directory, with version checking to determine if fresh fetch is needed.

  function loadCachedSDKDoc(language, type, forceRefresh = false) {
    try {
      const filename = `${sanitizeFilename(language)}_${sanitizeFilename(type)}.md`;
      const filePath = pathJoin(__dirname, 'resources', 'sdk_docs', filename);
      
      // Check if file exists
      if (!fs.existsSync(filePath)) {
        return null;
      }
      
      const content = fs.readFileSync(filePath, 'utf8');
      
      // Skip version checking if force refresh is requested or for REST API
      if (forceRefresh || language === 'rest-api') {
        return content;
      }
      
      // Extract version from cached content
      const cachedVersion = extractVersionFromCachedDoc(content);
      const currentVersion = sdkVersions[language];
      
      // If we have both versions and they match, return cached content
      if (cachedVersion && currentVersion && isVersionMatch(cachedVersion, currentVersion)) {
        return content;
      }
      
      // If versions don't match or we can't determine versions, return null to trigger fresh fetch
      if (cachedVersion && currentVersion && !isVersionMatch(cachedVersion, currentVersion)) {
        //console.log(`Version mismatch for ${language}: cached=${cachedVersion}, current=${currentVersion}. Will fetch fresh content.`);
      }
      
      return null;
    } catch (err) {
      //console.error(`Error loading cached SDK doc ${language}_${type}: ${err}`);
      return null;
    }
  }