olostep-mcp

Instructions

Implementation Reference

• src/tools/getGoogleSearch.ts:20-85 (handler)

  The core handler function that constructs a Google search URL, sends a scrape request to the Olostep API using the '@olostep/google-search' parser, parses the JSON response, and returns structured search results or error messages.

  handler: async ({ query, country }: { query: string; country?: string }, apiKey: string, orbitKey?: string) => {
      try {
          const headers = new Headers({
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${apiKey}`
          });
  
          const searchUrl = new URL('https://www.google.com/search');
          searchUrl.searchParams.append('q', query);
          if (country) searchUrl.searchParams.append('gl', country);
  
          const payload = {
              formats: ["parser_extract"],
              parser_extract: { parser_id: "@olostep/google-search" },
              url_to_scrape: searchUrl.toString(),
              wait_before_scraping: 0,
              ...(orbitKey && { force_connection_id: orbitKey })
          };
  
          const response = await fetch(OLOSTEP_SCRAPE_API_URL, {
              method: 'POST',
              headers: headers,
              body: JSON.stringify(payload)
          });
  
          if (!response.ok) {
              const errorDetails = await response.json();
              return {
                  isError: true,
                  content: [{
                      type: "text",
                      text: `Olostep API Error: ${response.status} ${response.statusText}. Details: ${JSON.stringify(errorDetails)}`
                  }]
              };
          }
  
          const data = await response.json() as GoogleSearchResponse;
          
          if (data.result?.json_content) {
              const parsedContent = JSON.parse(data.result.json_content);
              return {
                  content: [{
                      type: "text",
                      text: JSON.stringify(parsedContent, null, 2)
                  }]
              };
          } else {
              return {
                  isError: true,
                  content: [{
                      type: "text",
                      text: "Error: No search results found in Olostep API response."
                  }]
              };
          }
  
      } catch (error: unknown) {
          return {
              isError: true,
              content: [{
                  type: "text",
                  text: `Error: Failed to perform Google search. ${error instanceof Error ? error.message : String(error)}`
              }]
          };
      }
  }

• src/tools/getGoogleSearch.ts:16-19 (schema)

  Input schema using Zod validation: requires 'query' string and optional 'country' string (defaults to 'US').

  schema: {
      query: z.string().describe("The search query to perform"),
      country: z.string().optional().default("US").describe("Country code for localized results (e.g., US, GB)")
  },

• src/index.ts:164-176 (registration)

  MCP server registration of the 'google_search' tool, including API key validation and content type normalization.

  server.tool(
      getGoogleSearch.name,
      getGoogleSearch.description,
      getGoogleSearch.schema,
      async (params) => {
          if (!OLOSTEP_API_KEY) return missingApiKeyError;
          const result = await getGoogleSearch.handler(params, OLOSTEP_API_KEY, ORBIT_KEY);
          return {
              ...result,
              content: result.content.map(item => ({ ...item, type: item.type as "text" }))
          };
      }
  );

• src/tools/getGoogleSearch.ts:7-11 (helper)

  TypeScript interface for typing the response from the Olostep API scrape.

  interface GoogleSearchResponse {
      result?: {
          json_content?: string;
      };
  }

• src/tools/getGoogleSearch.ts:14-14 (registration)

  Tool name definition as 'google_search'.

  name: "google_search",