MCP Server Giphy

Instructions

Implementation Reference

• src/service.ts:5-39 (handler)

  The core handler function that implements the search_gifs tool logic: constructs API parameters, calls Giphy search endpoint, formats response GIFs, and handles errors.

  export async function searchGifs(params: {
    query: string;
    limit?: number;
    offset?: number;
    rating?: "g" | "pg" | "pg-13" | "r";
    lang?: string;
  }) {
    const { query, limit = 10, offset = 0, rating = "g", lang = "en" } = params;
  
    const searchParams = {
      q: query,
      limit,
      offset,
      rating,
      lang,
    };
  
    const url = buildUrl("search", searchParams);
  
    try {
      const response = await axios.get(url);
      const responseData = response.data as GiphyResponse;
      return formatGifs(responseData.data);
    } catch (error) {
      let errorMsg = "Giphy API error";
  
      if (axios.isAxiosError(error) && error.response) {
        errorMsg = `${errorMsg}: ${error.response.status} ${error.response.statusText}`;
      } else if (error instanceof Error) {
        errorMsg = `${errorMsg}: ${error.message}`;
      }
  
      throw new Error(errorMsg);
    }
  }

• src/tools.ts:4-26 (schema)

  Defines the input schema and metadata for the search_gifs tool, used for validation in MCP.

  export const searchGifsTool: Tool = {
    name: "search_gifs",
    description: "Search for GIFs on Giphy with a query string",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query term or phrase" },
        limit: {
          type: "number",
          description:
            "Maximum number of objects to return (default: 10, max: 50)",
        },
        offset: { type: "number", description: "Results offset (default: 0)" },
        rating: {
          type: "string",
          enum: ["g", "pg", "pg-13", "r"],
          description: "Content rating (g, pg, pg-13, r)",
        },
        lang: { type: "string", description: "Language code (default: en)" },
      },
      required: ["query"],
    },
  };

• src/server.ts:107-111 (registration)

  Registers searchGifsTool in the MCP server's listTools handler, making it discoverable.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [searchGifsTool, getRandomGifTool, getTrendingGifsTool],
    };
  });

• src/server.ts:32-50 (registration)

  Handles incoming callTool requests for search_gifs by invoking the searchGifs handler and formatting the MCP response.

  case "search_gifs": {
    const searchParams = args as {
      query: string;
      limit?: number;
      offset?: number;
      rating?: "g" | "pg" | "pg-13" | "r";
      lang?: string;
    };
    const gifs = await searchGifs(searchParams);
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ gifs }),
        },
      ],
    };
  }

• src/service.ts:130-132 (helper)

  Helper function to format multiple GIFs from Giphy response, used by searchGifs.

  function formatGifs(gifs: GiphyGif[]) {
    return gifs.map(formatGif);
  }