NPM Package Docs MCP

Instructions

Implementation Reference

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

  The core handler function for the 'get_docs_for_npm_package' tool. It fetches the latest package metadata from the npm registry, attempts to retrieve the README.md from the GitHub repository (trying common branches: master, main, develop), and falls back to downloading and extracting the package tarball to locate README files if GitHub fails.
  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 schema definition including title, description, and Zod-validated input schema requiring a 'packageName' string.
  { 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, including name, schema, and inline handler.
  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 the npm package tarball, extract it to a temp directory, locate the package folder, find and read README files (various names/cases), and clean up.
  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 parse GitHub repository URL (handling git+ prefix and .git suffix) and extract the owner/repo path for raw.githubusercontent.com access.
  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; } }
• src/types/index.ts:1-10 (schema)

  TypeScript interface defining the structure of the npm registry response used in the handler for accessing repository URL and tarball.
  export interface NpmRegistryResponse{ name: string repository?:{ type?: "git" url: string } dist:{ tarball: string } }