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