NPM Package Docs MCP

Instructions

Implementation Reference

• src/server.ts:116-185 (handler)

  Inline asynchronous handler function for the 'get_docs_for_npm_package' tool. Fetches latest package info from npm registry, attempts to retrieve README.md from GitHub repository using common branch names, falls back to downloading and extracting the package tarball to locate README files, and returns markdown content or an error message.
  async ({ packageName }) => { try { console.error(`Processing request for package: ${packageName}`); const npmPackage = await fetch(`https://registry.npmjs.org/${packageName}/latest`).then( res => res.json() as Promise<NpmRegistryResponse>); const tarball = npmPackage.dist.tarball; const repoUrl = npmPackage.repository?.url; let docTxt = ''; // First, try to get docs from GitHub repository if available if (repoUrl) { const repoPath = extractGitHubRepoPath(repoUrl); if (repoPath) { console.error("repoPath", repoPath); // Try multiple branch names to find the README const branches = ['master', 'main', 'develop']; for (const branch of branches) { try { const response = await fetch(`https://raw.githubusercontent.com/${repoPath}/refs/heads/${branch}/README.md`); if (response.ok) { docTxt = await response.text(); break; } } catch (error) { console.error(`Failed to fetch README from ${branch} branch:`, error); continue; } } } } // If no docs found from GitHub, try tarball fallback if (!docTxt) { try { docTxt = await extractTarballAndGetReadme(tarball, packageName); } catch (error) { console.error('Failed to extract tarball:', error); } } // Return the result if (docTxt) { return { content: [{ type: "text", text: docTxt }] }; } else { return { content: [{ type: "text", text: "No documentation found in any common branches or package tarball" }] }; } } catch (error) { console.error('Error in tool execution:', error); return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } }
• src/server.ts:109-115 (schema)

  Tool metadata including title, description, and Zod-based input schema defining the required 'packageName' string parameter.
  { title: 'Get docs for an npm package', description: 'Get the docs for an npm package', inputSchema: { packageName: z.string().describe("Name of the npm package") } },
• src/server.ts:107-186 (registration)

  Registration of the 'get_docs_for_npm_package' tool with the MCP server, specifying name, schema/metadata, and handler function.
  server.registerTool( 'get_docs_for_npm_package', { title: 'Get docs for an npm package', description: 'Get the docs for an npm package', inputSchema: { packageName: z.string().describe("Name of the npm package") } }, async ({ packageName }) => { try { console.error(`Processing request for package: ${packageName}`); const npmPackage = await fetch(`https://registry.npmjs.org/${packageName}/latest`).then( res => res.json() as Promise<NpmRegistryResponse>); const tarball = npmPackage.dist.tarball; const repoUrl = npmPackage.repository?.url; let docTxt = ''; // First, try to get docs from GitHub repository if available if (repoUrl) { const repoPath = extractGitHubRepoPath(repoUrl); if (repoPath) { console.error("repoPath", repoPath); // Try multiple branch names to find the README const branches = ['master', 'main', 'develop']; for (const branch of branches) { try { const response = await fetch(`https://raw.githubusercontent.com/${repoPath}/refs/heads/${branch}/README.md`); if (response.ok) { docTxt = await response.text(); break; } } catch (error) { console.error(`Failed to fetch README from ${branch} branch:`, error); continue; } } } } // If no docs found from GitHub, try tarball fallback if (!docTxt) { try { docTxt = await extractTarballAndGetReadme(tarball, packageName); } catch (error) { console.error('Failed to extract tarball:', error); } } // Return the result if (docTxt) { return { content: [{ type: "text", text: docTxt }] }; } else { return { content: [{ type: "text", text: "No documentation found in any common branches or package tarball" }] }; } } catch (error) { console.error('Error in tool execution:', error); return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } } );
• src/server.ts:36-98 (helper)

  Helper function to download npm package tarball, extract it to temp dir, locate the package folder, search for various README file variants, read and return content if found, with cleanup.
  export async function extractTarballAndGetReadme(tarballUrl: string, packageName: string): Promise<string> { try { // Create a temporary directory for extraction const tempDir = path.join(os.tmpdir(), `npm-docs-${packageName}-${Date.now()}`); await fs.ensureDir(tempDir); // Download the tarball const response = await fetch(tarballUrl); if (!response.ok) { throw new Error(`Failed to download tarball: ${response.statusText}`); } const tarballBuffer = await response.arrayBuffer(); // Extract filename from tarball URL const urlParts = tarballUrl.split('/'); const tarballFilename = urlParts[urlParts.length - 1]; if (!tarballFilename) { throw new Error('Could not extract filename from tarball URL'); } const tarballPath = path.join(tempDir, tarballFilename); // Write tarball to file await fs.writeFile(tarballPath, Buffer.from(tarballBuffer)); // Extract the tarball await tar.extract({ file: tarballPath, cwd: tempDir }); // Find the package directory (usually named package-version) const extractedDirs = await fs.readdir(tempDir); const packageDir = extractedDirs.find(dir => dir.startsWith('package')); if (!packageDir) { throw new Error('Could not find package directory in tarball'); } const packagePath = path.join(tempDir, packageDir); // Look for README files (case insensitive) const readmeFiles = ['README.md', 'readme.md', 'README.txt', 'readme.txt', 'README']; let readmeContent = ''; for (const readmeFile of readmeFiles) { const readmePath = path.join(packagePath, readmeFile); if (await fs.pathExists(readmePath)) { readmeContent = await fs.readFile(readmePath, 'utf-8'); break; } } // Clean up temporary files await fs.remove(tempDir); return readmeContent || 'No README file found in package'; } catch (error) { console.error('Error extracting tarball:', error); throw error; } }
• src/server.ts:11-33 (helper)

  Helper function to normalize and extract 'owner/repo' path from GitHub repository URLs, handling git+ protocol and .git suffix.
  function extractGitHubRepoPath(githubUrl: string): string | null { try { // Handle git+https:// URLs const cleanUrl = githubUrl.replace(/^git\+/, ''); // Parse the URL const url = new URL(cleanUrl); // Check if it's a GitHub URL if (url.hostname === 'github.com') { // Extract the pathname and remove leading slash const path = url.pathname.substring(1); // Remove .git extension if present return path.replace(/\.git$/, ''); } return null; } catch (error) { console.error('Error parsing GitHub URL:', error); return null; } }