NPM Context Agent MCP

Instructions

Implementation Reference

• src/index.ts:749-832 (handler)

  The handler function for the 'compare_packages' tool. It fetches full package information and last-month download stats for two packages from the npm registry, extracts latest versions, constructs a comparison output with details like version, description, downloads, maintainers, and keywords, formats a textual comparison, and returns both structured data and formatted text, handling errors appropriately.

  async ({ packageName1, packageName2 }) => {
    try {
      const [pkg1Full, pkg2Full, pkg1Stats, pkg2Stats] = await Promise.all([
        fetchFullPackageInfo(packageName1),
        fetchFullPackageInfo(packageName2),
        fetch(
          `https://api.npmjs.org/downloads/point/last-month/${encodeURIComponent(
            packageName1
          )}`
        ).then((r) => r.json()),
        fetch(
          `https://api.npmjs.org/downloads/point/last-month/${encodeURIComponent(
            packageName2
          )}`
        ).then((r) => r.json()),
      ]);
  
      const pkg1Latest = pkg1Full.versions[pkg1Full["dist-tags"].latest];
      const pkg2Latest = pkg2Full.versions[pkg2Full["dist-tags"].latest];
  
      const output = {
        packages: [
          {
            name: pkg1Latest.name,
            version: pkg1Latest.version,
            description: pkg1Latest.description,
            downloads: pkg1Stats.downloads || 0,
            maintainers: pkg1Latest.maintainers?.map((m: any) => m.name) || [],
            keywords: pkg1Latest.keywords,
          },
          {
            name: pkg2Latest.name,
            version: pkg2Latest.version,
            description: pkg2Latest.description,
            downloads: pkg2Stats.downloads || 0,
            maintainers: pkg2Latest.maintainers?.map((m: any) => m.name) || [],
            keywords: pkg2Latest.keywords,
          },
        ],
      };
  
      const formattedText = `Package Comparison:\n\n${pkg1Latest.name} vs ${
        pkg2Latest.name
      }\n\n${pkg1Latest.name}:\n  Version: ${
        pkg1Latest.version
      }\n  Description: ${
        pkg1Latest.description || "N/A"
      }\n  Downloads (last month): ${(
        pkg1Stats.downloads || 0
      ).toLocaleString()}\n  Maintainers: ${
        output.packages[0].maintainers.join(", ") || "N/A"
      }\n  Keywords: ${pkg1Latest.keywords?.join(", ") || "None"}\n\n${
        pkg2Latest.name
      }:\n  Version: ${pkg2Latest.version}\n  Description: ${
        pkg2Latest.description || "N/A"
      }\n  Downloads (last month): ${(
        pkg2Stats.downloads || 0
      ).toLocaleString()}\n  Maintainers: ${
        output.packages[1].maintainers.join(", ") || "N/A"
      }\n  Keywords: ${pkg2Latest.keywords?.join(", ") || "None"}`;
  
      return {
        content: [
          {
            type: "text",
            text: formattedText,
          },
        ],
        structuredContent: output,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error comparing packages: ${
              error instanceof Error ? error.message : "Unknown error"
            }`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:729-748 (schema)

  Input and output schemas defining the parameters (packageName1, packageName2 as strings) and the structured output (array of package objects with name, version, description, downloads, maintainers, keywords).

  {
    title: "Compare Packages",
    description: "Compare two packages side-by-side",
    inputSchema: {
      packageName1: z.string(),
      packageName2: z.string(),
    },
    outputSchema: {
      packages: z.array(
        z.object({
          name: z.string(),
          version: z.string(),
          description: z.string().optional(),
          downloads: z.number(),
          maintainers: z.array(z.string()),
          keywords: z.array(z.string()).optional(),
        })
      ),
    },
  },

• src/index.ts:727-833 (registration)

  Registration of the 'compare_packages' tool using server.registerTool, including the tool name, schema, and handler function.

  server.registerTool(
    "compare_packages",
    {
      title: "Compare Packages",
      description: "Compare two packages side-by-side",
      inputSchema: {
        packageName1: z.string(),
        packageName2: z.string(),
      },
      outputSchema: {
        packages: z.array(
          z.object({
            name: z.string(),
            version: z.string(),
            description: z.string().optional(),
            downloads: z.number(),
            maintainers: z.array(z.string()),
            keywords: z.array(z.string()).optional(),
          })
        ),
      },
    },
    async ({ packageName1, packageName2 }) => {
      try {
        const [pkg1Full, pkg2Full, pkg1Stats, pkg2Stats] = await Promise.all([
          fetchFullPackageInfo(packageName1),
          fetchFullPackageInfo(packageName2),
          fetch(
            `https://api.npmjs.org/downloads/point/last-month/${encodeURIComponent(
              packageName1
            )}`
          ).then((r) => r.json()),
          fetch(
            `https://api.npmjs.org/downloads/point/last-month/${encodeURIComponent(
              packageName2
            )}`
          ).then((r) => r.json()),
        ]);
  
        const pkg1Latest = pkg1Full.versions[pkg1Full["dist-tags"].latest];
        const pkg2Latest = pkg2Full.versions[pkg2Full["dist-tags"].latest];
  
        const output = {
          packages: [
            {
              name: pkg1Latest.name,
              version: pkg1Latest.version,
              description: pkg1Latest.description,
              downloads: pkg1Stats.downloads || 0,
              maintainers: pkg1Latest.maintainers?.map((m: any) => m.name) || [],
              keywords: pkg1Latest.keywords,
            },
            {
              name: pkg2Latest.name,
              version: pkg2Latest.version,
              description: pkg2Latest.description,
              downloads: pkg2Stats.downloads || 0,
              maintainers: pkg2Latest.maintainers?.map((m: any) => m.name) || [],
              keywords: pkg2Latest.keywords,
            },
          ],
        };
  
        const formattedText = `Package Comparison:\n\n${pkg1Latest.name} vs ${
          pkg2Latest.name
        }\n\n${pkg1Latest.name}:\n  Version: ${
          pkg1Latest.version
        }\n  Description: ${
          pkg1Latest.description || "N/A"
        }\n  Downloads (last month): ${(
          pkg1Stats.downloads || 0
        ).toLocaleString()}\n  Maintainers: ${
          output.packages[0].maintainers.join(", ") || "N/A"
        }\n  Keywords: ${pkg1Latest.keywords?.join(", ") || "None"}\n\n${
          pkg2Latest.name
        }:\n  Version: ${pkg2Latest.version}\n  Description: ${
          pkg2Latest.description || "N/A"
        }\n  Downloads (last month): ${(
          pkg2Stats.downloads || 0
        ).toLocaleString()}\n  Maintainers: ${
          output.packages[1].maintainers.join(", ") || "N/A"
        }\n  Keywords: ${pkg2Latest.keywords?.join(", ") || "None"}`;
  
        return {
          content: [
            {
              type: "text",
              text: formattedText,
            },
          ],
          structuredContent: output,
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error comparing packages: ${
                error instanceof Error ? error.message : "Unknown error"
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );