get_download_stats
Retrieve npm package download statistics for specific time periods to analyze usage trends and package popularity.
Instructions
Get download statistics from npm
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| packageName | Yes | ||
| period | No |
Implementation Reference
- src/index.ts:537-595 (handler)The main execution logic of the get_download_stats tool: fetches npm download stats API, parses with Zod schema, returns formatted text and structured content or error.async ({ packageName, period = "last-month" }) => { try { const encodedPackageName = encodeURIComponent(packageName); const response = await fetch( `https://api.npmjs.org/downloads/point/${period}/${encodedPackageName}` ); if (!response.ok) { throw new Error( `Failed to fetch download stats: ${response.statusText}` ); } const rawData = await response.json(); const parseResult = DownloadStatsSchema.safeParse(rawData); if (!parseResult.success) { throw new Error( `Invalid download stats structure: ${parseResult.error.message}` ); } const data = parseResult.data; const output = { package: data.package, downloads: data.downloads, period, start: data.start, end: data.end, }; return { content: [ { type: "text", text: `Package: ${ data.package }\nDownloads (${period}): ${data.downloads.toLocaleString()}\nPeriod: ${ data.start } to ${data.end}`, }, ], structuredContent: output, }; } catch (error) { return { content: [ { type: "text", text: `Error fetching download stats: ${ error instanceof Error ? error.message : "Unknown error" }`, }, ], isError: true, }; } } );
- src/index.ts:68-73 (schema)Zod schema used to validate the raw JSON response from npm downloads API.const DownloadStatsSchema = z.object({ downloads: z.number(), start: z.string(), end: z.string(), package: z.string(), });
- src/index.ts:522-536 (schema)Inline inputSchema and outputSchema defined for the tool registration using Zod.{ title: "Get Download Statistics", description: "Get download statistics from npm", inputSchema: { packageName: z.string(), period: z.enum(["last-day", "last-week", "last-month"]).optional(), }, outputSchema: { package: z.string(), downloads: z.number(), period: z.string(), start: z.string(), end: z.string(), }, },
- src/index.ts:520-595 (registration)server.registerTool call that registers the get_download_stats tool with its schema and inline handler function.server.registerTool( "get_download_stats", { title: "Get Download Statistics", description: "Get download statistics from npm", inputSchema: { packageName: z.string(), period: z.enum(["last-day", "last-week", "last-month"]).optional(), }, outputSchema: { package: z.string(), downloads: z.number(), period: z.string(), start: z.string(), end: z.string(), }, }, async ({ packageName, period = "last-month" }) => { try { const encodedPackageName = encodeURIComponent(packageName); const response = await fetch( `https://api.npmjs.org/downloads/point/${period}/${encodedPackageName}` ); if (!response.ok) { throw new Error( `Failed to fetch download stats: ${response.statusText}` ); } const rawData = await response.json(); const parseResult = DownloadStatsSchema.safeParse(rawData); if (!parseResult.success) { throw new Error( `Invalid download stats structure: ${parseResult.error.message}` ); } const data = parseResult.data; const output = { package: data.package, downloads: data.downloads, period, start: data.start, end: data.end, }; return { content: [ { type: "text", text: `Package: ${ data.package }\nDownloads (${period}): ${data.downloads.toLocaleString()}\nPeriod: ${ data.start } to ${data.end}`, }, ], structuredContent: output, }; } catch (error) { return { content: [ { type: "text", text: `Error fetching download stats: ${ error instanceof Error ? error.message : "Unknown error" }`, }, ], isError: true, }; } } );