NPM Context Agent MCP

Instructions

Implementation Reference

• src/index.ts:376-438 (handler)

  The handler function for the 'get_package_versions' tool. It fetches package data from the npm registry, validates it using PackageVersionSchema, extracts versions and dist-tags, formats the output as text and structured content.

  async ({ packageName }) => {
    try {
      const response = await fetch(
        `https://registry.npmjs.org/${encodeURIComponent(packageName)}`
      );
  
      if (!response.ok) {
        throw new Error(
          `Failed to fetch package versions: ${response.statusText}`
        );
      }
  
      const rawData = await response.json();
      const parseResult = PackageVersionSchema.safeParse(rawData);
  
      if (!parseResult.success) {
        throw new Error(
          `Invalid package versions structure: ${parseResult.error.message}`
        );
      }
  
      const data = parseResult.data;
      const versions = Object.keys(data.versions);
      const latest = data["dist-tags"].latest;
      const tags = Object.entries(data["dist-tags"])
        .map(([tag, version]) => `${tag}: ${version}`)
        .join("\n");
  
      const output = {
        name: data.name,
        latest,
        distTags: data["dist-tags"],
        versions,
        versionCount: versions.length,
      };
  
      return {
        content: [
          {
            type: "text",
            text: `Package: ${
              data.name
            }\n\nLatest version: ${latest}\n\nDist tags:\n${tags}\n\nAll versions (${
              versions.length
            }):\n${versions.join(", ")}`,
          },
        ],
        structuredContent: output,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching package versions: ${
              error instanceof Error ? error.message : "Unknown error"
            }`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:48-58 (schema)

  Zod schema for validating the npm registry response containing package versions, versions object, and dist-tags.

  const PackageVersionSchema = z.object({
    name: z.string(),
    versions: z.record(
      z.string(),
      z.object({
        version: z.string(),
        publish_time: z.string().optional(),
      })
    ),
    "dist-tags": z.record(z.string(), z.string()),
  });

• src/index.ts:360-439 (registration)

  MCP server registration of the 'get_package_versions' tool, defining title, description, input/output schemas, and attaching the handler function.

  server.registerTool(
    "get_package_versions",
    {
      title: "Get Package Versions",
      description: "Get all available versions of a package",
      inputSchema: {
        packageName: z.string(),
      },
      outputSchema: {
        name: z.string(),
        latest: z.string(),
        distTags: z.record(z.string(), z.string()),
        versions: z.array(z.string()),
        versionCount: z.number(),
      },
    },
    async ({ packageName }) => {
      try {
        const response = await fetch(
          `https://registry.npmjs.org/${encodeURIComponent(packageName)}`
        );
  
        if (!response.ok) {
          throw new Error(
            `Failed to fetch package versions: ${response.statusText}`
          );
        }
  
        const rawData = await response.json();
        const parseResult = PackageVersionSchema.safeParse(rawData);
  
        if (!parseResult.success) {
          throw new Error(
            `Invalid package versions structure: ${parseResult.error.message}`
          );
        }
  
        const data = parseResult.data;
        const versions = Object.keys(data.versions);
        const latest = data["dist-tags"].latest;
        const tags = Object.entries(data["dist-tags"])
          .map(([tag, version]) => `${tag}: ${version}`)
          .join("\n");
  
        const output = {
          name: data.name,
          latest,
          distTags: data["dist-tags"],
          versions,
          versionCount: versions.length,
        };
  
        return {
          content: [
            {
              type: "text",
              text: `Package: ${
                data.name
              }\n\nLatest version: ${latest}\n\nDist tags:\n${tags}\n\nAll versions (${
                versions.length
              }):\n${versions.join(", ")}`,
            },
          ],
          structuredContent: output,
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error fetching package versions: ${
                error instanceof Error ? error.message : "Unknown error"
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );