google_image_search

Instructions

Implementation Reference

• src/index.ts:246-281 (handler)

  The core handler function that performs the Google Custom Search API call for images, applies rate limiting, parses the response, and formats the results into a readable text output.

  async function performImageSearch(query: string, count: number = 5, start: number = 1) {
    checkRateLimit();
    
    const url = new URL('https://www.googleapis.com/customsearch/v1');
    url.searchParams.set('key', GOOGLE_API_KEY);
    url.searchParams.set('cx', GOOGLE_CSE_ID);
    url.searchParams.set('q', query);
    url.searchParams.set('num', Math.min(count, 10).toString());
    url.searchParams.set('start', start.toString());
    url.searchParams.set('searchType', 'image');
  
    const response = await fetch(url, {
      headers: {
        'Accept': 'application/json',
      }
    });
  
    if (!response.ok) {
      throw new Error(`Google API error: ${response.status} ${response.statusText}\n${await response.text()}`);
    }
  
    const data = await response.json() as GoogleImageSearchResult;
    
    if (data.error) {
      throw new Error(`Google API error: ${data.error.code} ${data.error.message}`);
    }
  
    if (!data.items || data.items.length === 0) {
      return "No image results found for your query.";
    }
  
    // Format the image results
    return data.items.map((item, index) => 
      `[${index + 1}] Title: ${item.title}\nDescription: ${item.snippet || 'No description'}\nImage URL: ${item.link}\n${item.image?.thumbnailLink ? `Thumbnail: ${item.image.thumbnailLink}` : ''}`
    ).join('\n\n');
  }

• src/index.ts:45-72 (registration)

  Defines and registers the 'google_image_search' tool, including its name, description, and input schema for the MCP server.

  const IMAGE_SEARCH_TOOL: Tool = {
    name: "google_image_search",
    description:
      "Searches for images using Google's Custom Search API. " +
      "Best for finding images related to specific terms, concepts, or objects. " +
      "Returns image URLs, titles, and thumbnails. " +
      "Use this when needing to find relevant images or visual references.",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Image search query"
        },
        count: {
          type: "number",
          description: "Number of results (1-10, default 5)",
          default: 5
        },
        start: {
          type: "number",
          description: "Pagination start index (default 1)",
          default: 1
        },
      },
      required: ["query"]
    }
  };

• src/index.ts:165-184 (schema)

  TypeScript interface defining the structure of the Google Image Search API response.

  interface GoogleImageSearchResult {
    kind: string;
    items?: Array<{
      title: string;
      link: string;
      snippet: string;
      image?: {
        contextLink: string;
        height: number;
        width: number;
        thumbnailLink: string;
        thumbnailHeight: number;
        thumbnailWidth: number;
      };
    }>;
    error?: {
      code: number;
      message: string;
    };
  }

• src/index.ts:195-202 (schema)

  Type guard function for validating input arguments to the google_image_search tool.

  function isGoogleImageSearchArgs(args: unknown): args is { query: string; count?: number; start?: number } {
    return (
      typeof args === "object" &&
      args !== null &&
      "query" in args &&
      typeof (args as { query: string }).query === "string"
    );
  }

• src/index.ts:309-319 (handler)

  Dispatch case in the main CallToolRequestHandler that validates args and calls the performImageSearch handler.

  case "google_image_search": {
    if (!isGoogleImageSearchArgs(args)) {
      throw new Error("Invalid arguments for google_image_search");
    }
    const { query, count = 5, start = 1 } = args;
    const results = await performImageSearch(query, count, start);
    return {
      content: [{ type: "text", text: results }],
      isError: false,
    };
  }