Context7 MCP

Instructions

Implementation Reference

• src/index.ts:89-129 (handler)

  The main handler function implementing the 'resolve-library-id' tool. It searches for libraries using searchLibraries, handles errors, formats results, and returns structured content.

      async ({ libraryName }) => {
        const searchResponse: SearchResponse = await searchLibraries(libraryName);
  
        if (!searchResponse.results || searchResponse.results.length === 0) {
          return {
            content: [
              {
                type: "text",
                text: searchResponse.error
                  ? searchResponse.error
                  : "Failed to retrieve library documentation data from Context7",
              },
            ],
          };
        }
  
        const resultsText = formatSearchResults(searchResponse);
  
        return {
          content: [
            {
              type: "text",
              text: `Available Libraries (top matches):
  
  Each result includes:
  - Library ID: Context7-compatible identifier (format: /org/project)
  - Name: Library or package name
  - Description: Short summary
  - Code Snippets: Number of available code examples
  - Trust Score: Authority indicator
  - Versions: List of versions if available. Use one of those versions if and only if the user explicitly provides a version in their query.
  
  For best results, select libraries based on name match, trust score, snippet coverage, and relevance to your use case.
  
  ----------
  
  ${resultsText}`,
            },
          ],
        };
      }

• src/index.ts:84-88 (schema)

  Zod input schema defining the 'libraryName' parameter for the tool.

  {
    libraryName: z
      .string()
      .describe("Library name to search for and retrieve a Context7-compatible library ID."),
  },

• src/index.ts:64-130 (registration)

  Registration of the 'resolve-library-id' tool using McpServer.tool() including description, schema, and handler.

      "resolve-library-id",
      `Resolves a package/product name to a Context7-compatible library ID and returns a list of matching libraries.
  
  You MUST call this function before 'get-library-docs' to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.
  
  Selection Process:
  1. Analyze the query to understand what library/package the user is looking for
  2. Return the most relevant match based on:
  - Name similarity to the query (exact matches prioritized)
  - Description relevance to the query's intent
  - Documentation coverage (prioritize libraries with higher Code Snippet counts)
  - Trust score (consider libraries with scores of 7-10 more authoritative)
  
  Response Format:
  - Return the selected library ID in a clearly marked section
  - Provide a brief explanation for why this library was chosen
  - If multiple good matches exist, acknowledge this but proceed with the most relevant one
  - If no good matches exist, clearly state this and suggest query refinements
  
  For ambiguous queries, request clarification before proceeding with a best-guess match.`,
      {
        libraryName: z
          .string()
          .describe("Library name to search for and retrieve a Context7-compatible library ID."),
      },
      async ({ libraryName }) => {
        const searchResponse: SearchResponse = await searchLibraries(libraryName);
  
        if (!searchResponse.results || searchResponse.results.length === 0) {
          return {
            content: [
              {
                type: "text",
                text: searchResponse.error
                  ? searchResponse.error
                  : "Failed to retrieve library documentation data from Context7",
              },
            ],
          };
        }
  
        const resultsText = formatSearchResults(searchResponse);
  
        return {
          content: [
            {
              type: "text",
              text: `Available Libraries (top matches):
  
  Each result includes:
  - Library ID: Context7-compatible identifier (format: /org/project)
  - Name: Library or package name
  - Description: Short summary
  - Code Snippets: Number of available code examples
  - Trust Score: Authority indicator
  - Versions: List of versions if available. Use one of those versions if and only if the user explicitly provides a version in their query.
  
  For best results, select libraries based on name match, trust score, snippet coverage, and relevance to your use case.
  
  ----------
  
  ${resultsText}`,
            },
          ],
        };
      }
    );

• src/lib/api.ts:11-36 (helper)

  Helper function searchLibraries that performs the API call to Context7 search endpoint, called by the tool handler.

  export async function searchLibraries(query: string): Promise<SearchResponse> {
    try {
      const url = new URL(`${CONTEXT7_API_BASE_URL}/v1/search`);
      url.searchParams.set("query", query);
      const response = await fetch(url);
      if (!response.ok) {
        const errorCode = response.status;
        if (errorCode === 429) {
          console.error(`Rate limited due to too many requests. Please try again later.`);
          return {
            results: [],
            error: `Rate limited due to too many requests. Please try again later.`,
          } as SearchResponse;
        }
        console.error(`Failed to search libraries. Please try again later. Error code: ${errorCode}`);
        return {
          results: [],
          error: `Failed to search libraries. Please try again later. Error code: ${errorCode}`,
        } as SearchResponse;
      }
      return await response.json();
    } catch (error) {
      console.error("Error searching libraries:", error);
      return { results: [], error: `Error searching libraries: ${error}` } as SearchResponse;
    }
  }

• src/lib/utils.ts:44-51 (helper)

  Helper function formatSearchResults that formats the search results into readable text, used in the tool handler.

  export function formatSearchResults(searchResponse: SearchResponse): string {
    if (!searchResponse.results || searchResponse.results.length === 0) {
      return "No documentation libraries found matching your query.";
    }
  
    const formattedResults = searchResponse.results.map(formatSearchResult);
    return formattedResults.join("\n----------\n");
  }