Get Download Statistics

Instructions

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,
        };
      }
    }
  );