get_download_stats
Retrieve npm package download statistics for specific time periods to analyze usage trends and 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-594 (handler)The handler function for the 'get_download_stats' tool. It fetches download statistics from the npm API for a given package and period, validates the response using DownloadStatsSchema, formats the output, and returns structured content with text summary.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 within the handler to validate the raw JSON response from the 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)Input and output schemas defined in the tool registration, using Zod for validation of tool arguments and expected output.{ 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)The server.registerTool call that registers the 'get_download_stats' tool with its schema and 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, }; } } );