get_readme_data
Extract README file content from GitHub repositories for npm packages to understand functionality and usage details.
Instructions
Get README file content from a package's GitHub repository
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| packageName | Yes | ||
| version | No |
Implementation Reference
- src/index.ts:213-263 (handler)The core handler function for the 'get_readme_data' tool. It fetches package metadata from npm registry, validates with schema, extracts GitHub repository URL, fetches the README.md content, formats the response with text and structured output, and handles errors appropriately.async ({ packageName, version }) => { try { const rawData = await fetchPackageData(packageName, version); const parseResult = NpmRegistryResponseSchema.safeParse(rawData); if (!parseResult.success) { throw new Error( `Invalid package data structure: ${parseResult.error.message}` ); } const data = parseResult.data; const { url: repositoryUrl } = data.repository; const readme = await fetchReadmeFromGitHub(repositoryUrl); const output = { package: data.name, version: data.version, description: data.description || "N/A", repository: repositoryUrl, readme, }; return { content: [ { type: "text", text: `Package: ${data.name}\nVersion: ${ data.version }\nDescription: ${ data.description || "N/A" }\nRepository: ${repositoryUrl}\n\nREADME:\n${readme}`, }, ], structuredContent: output, }; } catch (error) { return { content: [ { type: "text", text: `Error fetching package ${packageName}: ${ error instanceof Error ? error.message : "Unknown error" }`, }, ], isError: true, }; } }
- src/index.ts:196-264 (registration)The registration of the 'get_readme_data' tool using server.registerTool, including inline input/output schemas and the handler function.server.registerTool( "get_readme_data", { title: "Get Package README", description: "Get README file content from a package's GitHub repository", inputSchema: { packageName: z.string(), version: z.string().optional(), }, outputSchema: { package: z.string(), version: z.string(), description: z.string(), repository: z.string(), readme: z.string(), }, }, async ({ packageName, version }) => { try { const rawData = await fetchPackageData(packageName, version); const parseResult = NpmRegistryResponseSchema.safeParse(rawData); if (!parseResult.success) { throw new Error( `Invalid package data structure: ${parseResult.error.message}` ); } const data = parseResult.data; const { url: repositoryUrl } = data.repository; const readme = await fetchReadmeFromGitHub(repositoryUrl); const output = { package: data.name, version: data.version, description: data.description || "N/A", repository: repositoryUrl, readme, }; return { content: [ { type: "text", text: `Package: ${data.name}\nVersion: ${ data.version }\nDescription: ${ data.description || "N/A" }\nRepository: ${repositoryUrl}\n\nREADME:\n${readme}`, }, ], structuredContent: output, }; } catch (error) { return { content: [ { type: "text", text: `Error fetching package ${packageName}: ${ error instanceof Error ? error.message : "Unknown error" }`, }, ], isError: true, }; } } );
- src/index.ts:11-19 (schema)Zod schema used in the handler to validate the npm registry response data before extracting repository URL.const NpmRegistryResponseSchema = z.object({ name: z.string(), version: z.string(), description: z.string().optional(), repository: z.object({ type: z.string(), url: z.string(), }), });
- src/index.ts:160-177 (helper)Helper function called by the handler to fetch package metadata from npm registry for the specified package and version (or latest).async function fetchPackageData( packageName: string, version?: string ): Promise<any> { const versionPath = version || "latest"; const encodedPackageName = encodeURIComponent(packageName); const response = await fetch( `https://registry.npmjs.org/${encodedPackageName}/${versionPath}` ); if (!response.ok) { throw new Error( `Failed to fetch package ${packageName}: ${response.statusText}` ); } return await response.json(); }
- src/index.ts:132-157 (helper)Helper function called by the handler to fetch README.md content from the package's GitHub repository, trying main/master branches first then default.async function fetchReadmeFromGitHub(repositoryUrl: string): Promise<string> { const githubUrl = new URL(repositoryUrl.replace("git+", "")); const repositoryPath = githubUrl.pathname.substring(1).replace(".git", ""); // Try branches in order: main, master, default const branches = ["main", "master"]; for (const branch of branches) { const readmeUrl = `https://raw.githubusercontent.com/${repositoryPath}/refs/heads/${branch}/README.md`; const readmeResponse = await fetch(readmeUrl); if (readmeResponse.ok) { return await readmeResponse.text(); } } // If both branches fail, try without branch specification (will return default branch) const defaultReadmeUrl = `https://raw.githubusercontent.com/${repositoryPath}/README.md`; const defaultResponse = await fetch(defaultReadmeUrl); if (defaultResponse.ok) { return await defaultResponse.text(); } throw new Error("README not found in main, master, or default branch"); }