NPM Context Agent MCP

Instructions

Implementation Reference

• src/index.ts:620-723 (handler)

  The core handler function for the 'get_package_info' tool. It fetches data from the npm registry, handles both specific version and full package info, uses PackageInfoSchema for validation, extracts and formats key metadata, and returns both text summary and structured content.
  async ({ packageName, version }) => { try { const encodedPackageName = encodeURIComponent(packageName); const response = await fetch( `https://registry.npmjs.org/${encodedPackageName}${ version ? `/${version}` : "" }` ); if (!response.ok) { throw new Error(`Failed to fetch package info: ${response.statusText}`); } const rawData = await response.json(); let formattedInfo = ""; let output: any; if (version) { // Single version info const versionData = rawData.versions?.[version]; if (versionData) { output = { name: versionData.name, version: versionData.version, description: versionData.description, license: versionData.license, keywords: versionData.keywords, repository: versionData.repository?.url, homepage: versionData.homepage, }; formattedInfo = `Package: ${versionData.name}\nVersion: ${ versionData.version }\nDescription: ${versionData.description || "N/A"}\nLicense: ${ versionData.license || "N/A" }\nHomepage: ${versionData.homepage || "N/A"}\n\nKeywords: ${ versionData.keywords?.join(", ") || "None" }\n\nAuthor: ${JSON.stringify( versionData.author || "N/A" )}\n\nRepository: ${versionData.repository?.url || "N/A"}`; } } else { // Full package info const parseResult = PackageInfoSchema.safeParse(rawData); if (!parseResult.success) { throw new Error( `Invalid package info structure: ${parseResult.error.message}` ); } const data = parseResult.data; const latestVersion = data["dist-tags"].latest; const latestData = data.versions[latestVersion]; output = { name: data.name, description: data.description, license: data.license, keywords: latestData.keywords, maintainers: latestData.maintainers?.map((m: any) => m.name) || [], repository: latestData.repository?.url, homepage: latestData.homepage, totalVersions: Object.keys(data.versions).length, distTags: Object.keys(data["dist-tags"]), }; formattedInfo = `Package: ${ data.name }\nLatest Version: ${latestVersion}\nDescription: ${ data.description || "N/A" }\nLicense: ${data.license || "N/A"}\n\nKeywords: ${ latestData.keywords?.join(", ") || "None" }\n\nMaintainers: ${ latestData.maintainers?.map((m: any) => m.name).join(", ") || "N/A" }\n\nTotal Versions: ${ Object.keys(data.versions).length }\nDist Tags: ${Object.keys(data["dist-tags"]).join(", ")}`; } return { content: [ { type: "text", text: formattedInfo, }, ], structuredContent: output, }; } catch (error) { return { content: [ { type: "text", text: `Error fetching package info: ${ error instanceof Error ? error.message : "Unknown error" }`, }, ], isError: true, }; } }
• src/index.ts:75-102 (schema)

  Zod schema used within the handler to validate and parse the full npm package registry response data.
  const PackageInfoSchema = z.object({ name: z.string(), description: z.string().optional(), "dist-tags": z.record(z.string(), z.string()), versions: z.record( z.string(), z.object({ name: z.string(), version: z.string(), description: z.string().optional(), keywords: z.array(z.string()).optional(), license: z.string().optional(), author: z.any().optional(), maintainers: z.array(z.any()).optional(), repository: z .object({ type: z.string(), url: z.string(), }) .optional(), dependencies: z.record(z.string(), z.string()).optional(), homepage: z.string().optional(), }) ), time: z.record(z.string(), z.string()), license: z.string().optional(), readme: z.string().optional(), });
• src/index.ts:600-619 (schema)

  Inline input and output schemas defined for the tool registration, specifying parameters and expected output structure.
  { title: "Get Package Info", description: "Get comprehensive package metadata", inputSchema: { packageName: z.string(), version: z.string().optional(), }, outputSchema: { name: z.string(), version: z.string().optional(), description: z.string().optional(), license: z.string().optional(), keywords: z.array(z.string()).optional(), maintainers: z.array(z.string()).optional(), repository: z.string().optional(), homepage: z.string().optional(), totalVersions: z.number().optional(), distTags: z.array(z.string()).optional(), }, },
• src/index.ts:598-724 (registration)

  The registration of the 'get_package_info' tool using server.registerTool, including schema definitions and inline handler function.
  server.registerTool( "get_package_info", { title: "Get Package Info", description: "Get comprehensive package metadata", inputSchema: { packageName: z.string(), version: z.string().optional(), }, outputSchema: { name: z.string(), version: z.string().optional(), description: z.string().optional(), license: z.string().optional(), keywords: z.array(z.string()).optional(), maintainers: z.array(z.string()).optional(), repository: z.string().optional(), homepage: z.string().optional(), totalVersions: z.number().optional(), distTags: z.array(z.string()).optional(), }, }, async ({ packageName, version }) => { try { const encodedPackageName = encodeURIComponent(packageName); const response = await fetch( `https://registry.npmjs.org/${encodedPackageName}${ version ? `/${version}` : "" }` ); if (!response.ok) { throw new Error(`Failed to fetch package info: ${response.statusText}`); } const rawData = await response.json(); let formattedInfo = ""; let output: any; if (version) { // Single version info const versionData = rawData.versions?.[version]; if (versionData) { output = { name: versionData.name, version: versionData.version, description: versionData.description, license: versionData.license, keywords: versionData.keywords, repository: versionData.repository?.url, homepage: versionData.homepage, }; formattedInfo = `Package: ${versionData.name}\nVersion: ${ versionData.version }\nDescription: ${versionData.description || "N/A"}\nLicense: ${ versionData.license || "N/A" }\nHomepage: ${versionData.homepage || "N/A"}\n\nKeywords: ${ versionData.keywords?.join(", ") || "None" }\n\nAuthor: ${JSON.stringify( versionData.author || "N/A" )}\n\nRepository: ${versionData.repository?.url || "N/A"}`; } } else { // Full package info const parseResult = PackageInfoSchema.safeParse(rawData); if (!parseResult.success) { throw new Error( `Invalid package info structure: ${parseResult.error.message}` ); } const data = parseResult.data; const latestVersion = data["dist-tags"].latest; const latestData = data.versions[latestVersion]; output = { name: data.name, description: data.description, license: data.license, keywords: latestData.keywords, maintainers: latestData.maintainers?.map((m: any) => m.name) || [], repository: latestData.repository?.url, homepage: latestData.homepage, totalVersions: Object.keys(data.versions).length, distTags: Object.keys(data["dist-tags"]), }; formattedInfo = `Package: ${ data.name }\nLatest Version: ${latestVersion}\nDescription: ${ data.description || "N/A" }\nLicense: ${data.license || "N/A"}\n\nKeywords: ${ latestData.keywords?.join(", ") || "None" }\n\nMaintainers: ${ latestData.maintainers?.map((m: any) => m.name).join(", ") || "N/A" }\n\nTotal Versions: ${ Object.keys(data.versions).length }\nDist Tags: ${Object.keys(data["dist-tags"]).join(", ")}`; } return { content: [ { type: "text", text: formattedInfo, }, ], structuredContent: output, }; } catch (error) { return { content: [ { type: "text", text: `Error fetching package info: ${ error instanceof Error ? error.message : "Unknown error" }`, }, ], isError: true, }; } } );