NPM Context Agent MCP

Instructions

Implementation Reference

• src/index.ts:936-997 (handler)

  The inline anonymous async handler function that implements the core logic of the get_package_quality tool. It fetches quality metrics from the npms.io API, validates the response using QualityMetricsSchema, computes formatted text output, and returns structured content with metrics.

  async ({ packageName }) => {
    try {
      const encodedPackageName = encodeURIComponent(packageName);
      const response = await fetch(
        `https://api.npms.io/v2/package/${encodedPackageName}`
      );
  
      if (!response.ok) {
        throw new Error(
          `Failed to fetch quality metrics: ${response.statusText}`
        );
      }
  
      const rawData = await response.json();
      const parseResult = QualityMetricsSchema.safeParse(rawData.score);
  
      if (!parseResult.success) {
        throw new Error(
          `Invalid quality metrics structure: ${parseResult.error.message}`
        );
      }
  
      const score = parseResult.data;
      const output = {
        name: packageName,
        final: score.final,
        quality: score.detail.quality,
        popularity: score.detail.popularity,
        maintenance: score.detail.maintenance,
      };
  
      const formattedText = `Package: ${packageName}\n\nQuality Metrics:\n  Overall Score: ${(
        score.final * 100
      ).toFixed(1)}%\n  Quality: ${(score.detail.quality * 100).toFixed(
        1
      )}%\n  Popularity: ${(score.detail.popularity * 100).toFixed(
        1
      )}%\n  Maintenance: ${(score.detail.maintenance * 100).toFixed(1)}%`;
  
      return {
        content: [
          {
            type: "text",
            text: formattedText,
          },
        ],
        structuredContent: output,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching quality metrics: ${
              error instanceof Error ? error.message : "Unknown error"
            }`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:920-998 (registration)

  The server.registerTool call that registers the get_package_quality tool, specifying its name, title, description, inputSchema (packageName: string), outputSchema (name, final, quality, popularity, maintenance scores), and references the handler function.

  server.registerTool(
    "get_package_quality",
    {
      title: "Get Package Quality Metrics",
      description: "Get quality metrics from npms.io",
      inputSchema: {
        packageName: z.string(),
      },
      outputSchema: {
        name: z.string(),
        final: z.number(),
        quality: z.number(),
        popularity: z.number(),
        maintenance: z.number(),
      },
    },
    async ({ packageName }) => {
      try {
        const encodedPackageName = encodeURIComponent(packageName);
        const response = await fetch(
          `https://api.npms.io/v2/package/${encodedPackageName}`
        );
  
        if (!response.ok) {
          throw new Error(
            `Failed to fetch quality metrics: ${response.statusText}`
          );
        }
  
        const rawData = await response.json();
        const parseResult = QualityMetricsSchema.safeParse(rawData.score);
  
        if (!parseResult.success) {
          throw new Error(
            `Invalid quality metrics structure: ${parseResult.error.message}`
          );
        }
  
        const score = parseResult.data;
        const output = {
          name: packageName,
          final: score.final,
          quality: score.detail.quality,
          popularity: score.detail.popularity,
          maintenance: score.detail.maintenance,
        };
  
        const formattedText = `Package: ${packageName}\n\nQuality Metrics:\n  Overall Score: ${(
          score.final * 100
        ).toFixed(1)}%\n  Quality: ${(score.detail.quality * 100).toFixed(
          1
        )}%\n  Popularity: ${(score.detail.popularity * 100).toFixed(
          1
        )}%\n  Maintenance: ${(score.detail.maintenance * 100).toFixed(1)}%`;
  
        return {
          content: [
            {
              type: "text",
              text: formattedText,
            },
          ],
          structuredContent: output,
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error fetching quality metrics: ${
                error instanceof Error ? error.message : "Unknown error"
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/index.ts:115-123 (schema)

  Zod schema definition for validating the 'score' object from npms.io API response, used in the handler's safeParse call.

  const QualityMetricsSchema = z.object({
    final: z.number(),
    detail: z.object({
      quality: z.number(),
      popularity: z.number(),
      maintenance: z.number(),
    }),
    analyzedAt: z.string().optional(),
  });