NPM Context Agent MCP

Instructions

Implementation Reference

• src/index.ts:213-263 (handler)

  The core handler function for the 'get_readme_data' tool. It fetches package metadata from npm registry, validates with schema, extracts GitHub repository URL, fetches the README.md content, formats the response with text and structured output, and handles errors appropriately.

  async ({ packageName, version }) => {
    try {
      const rawData = await fetchPackageData(packageName, version);
      const parseResult = NpmRegistryResponseSchema.safeParse(rawData);
  
      if (!parseResult.success) {
        throw new Error(
          `Invalid package data structure: ${parseResult.error.message}`
        );
      }
  
      const data = parseResult.data;
      const { url: repositoryUrl } = data.repository;
  
      const readme = await fetchReadmeFromGitHub(repositoryUrl);
  
      const output = {
        package: data.name,
        version: data.version,
        description: data.description || "N/A",
        repository: repositoryUrl,
        readme,
      };
  
      return {
        content: [
          {
            type: "text",
            text: `Package: ${data.name}\nVersion: ${
              data.version
            }\nDescription: ${
              data.description || "N/A"
            }\nRepository: ${repositoryUrl}\n\nREADME:\n${readme}`,
          },
        ],
        structuredContent: output,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error fetching package ${packageName}: ${
              error instanceof Error ? error.message : "Unknown error"
            }`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:196-264 (registration)

  The registration of the 'get_readme_data' tool using server.registerTool, including inline input/output schemas and the handler function.

  server.registerTool(
    "get_readme_data",
    {
      title: "Get Package README",
      description: "Get README file content from a package's GitHub repository",
      inputSchema: {
        packageName: z.string(),
        version: z.string().optional(),
      },
      outputSchema: {
        package: z.string(),
        version: z.string(),
        description: z.string(),
        repository: z.string(),
        readme: z.string(),
      },
    },
    async ({ packageName, version }) => {
      try {
        const rawData = await fetchPackageData(packageName, version);
        const parseResult = NpmRegistryResponseSchema.safeParse(rawData);
  
        if (!parseResult.success) {
          throw new Error(
            `Invalid package data structure: ${parseResult.error.message}`
          );
        }
  
        const data = parseResult.data;
        const { url: repositoryUrl } = data.repository;
  
        const readme = await fetchReadmeFromGitHub(repositoryUrl);
  
        const output = {
          package: data.name,
          version: data.version,
          description: data.description || "N/A",
          repository: repositoryUrl,
          readme,
        };
  
        return {
          content: [
            {
              type: "text",
              text: `Package: ${data.name}\nVersion: ${
                data.version
              }\nDescription: ${
                data.description || "N/A"
              }\nRepository: ${repositoryUrl}\n\nREADME:\n${readme}`,
            },
          ],
          structuredContent: output,
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error fetching package ${packageName}: ${
                error instanceof Error ? error.message : "Unknown error"
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/index.ts:11-19 (schema)

  Zod schema used in the handler to validate the npm registry response data before extracting repository URL.

  const NpmRegistryResponseSchema = z.object({
    name: z.string(),
    version: z.string(),
    description: z.string().optional(),
    repository: z.object({
      type: z.string(),
      url: z.string(),
    }),
  });

• src/index.ts:160-177 (helper)

  Helper function called by the handler to fetch package metadata from npm registry for the specified package and version (or latest).

  async function fetchPackageData(
    packageName: string,
    version?: string
  ): Promise<any> {
    const versionPath = version || "latest";
    const encodedPackageName = encodeURIComponent(packageName);
    const response = await fetch(
      `https://registry.npmjs.org/${encodedPackageName}/${versionPath}`
    );
  
    if (!response.ok) {
      throw new Error(
        `Failed to fetch package ${packageName}: ${response.statusText}`
      );
    }
  
    return await response.json();
  }

• src/index.ts:132-157 (helper)

  Helper function called by the handler to fetch README.md content from the package's GitHub repository, trying main/master branches first then default.

  async function fetchReadmeFromGitHub(repositoryUrl: string): Promise<string> {
    const githubUrl = new URL(repositoryUrl.replace("git+", ""));
    const repositoryPath = githubUrl.pathname.substring(1).replace(".git", "");
  
    // Try branches in order: main, master, default
    const branches = ["main", "master"];
  
    for (const branch of branches) {
      const readmeUrl = `https://raw.githubusercontent.com/${repositoryPath}/refs/heads/${branch}/README.md`;
      const readmeResponse = await fetch(readmeUrl);
  
      if (readmeResponse.ok) {
        return await readmeResponse.text();
      }
    }
  
    // If both branches fail, try without branch specification (will return default branch)
    const defaultReadmeUrl = `https://raw.githubusercontent.com/${repositoryPath}/README.md`;
    const defaultResponse = await fetch(defaultReadmeUrl);
  
    if (defaultResponse.ok) {
      return await defaultResponse.text();
    }
  
    throw new Error("README not found in main, master, or default branch");
  }