LottieFiles MCP Server

Instructions

Implementation Reference

• src/handlers/ToolHandler.ts:124-143 (handler)

  Executes the 'get_popular_animations' MCP tool by calling the API client to fetch popular animations and returning a formatted JSON response.

  case "get_popular_animations":
    const popular = await this.apiClient.getPopularAnimations(
      args?.page as number,
      args?.limit as number
    );
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              count: popular.length,
              popular: popular,
            },
            null,
            2
          ),
        },
      ],
    };

• src/api/LottieApiClient.ts:79-98 (helper)

  Performs the actual HTTP API call to the LottieFiles endpoint to retrieve popular animations data.

  async getPopularAnimations(page: number = 1, limit: number = 20) {
    try {
      const response = await this.axiosInstance.get(
        `${this.baseUrl}/iconscout/popular-animations-weekly?api=%26sort%3Dpopular`,
        {
          params: {
            page,
            limit,
          },
        }
      );
  
      return response.data.popularWeeklyData.data;
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Failed to get popular animations: ${error.message}`);
      }
      throw new Error("Failed to get popular animations: Unknown error");
    }
  }

• src/handlers/ToolHandler.ts:57-78 (registration)

  Registers the 'get_popular_animations' tool in the MCP listTools method, defining its name, description, and input JSON schema.

  {
    name: "get_popular_animations",
    description: "Get a list of currently popular Lottie animations.",
    inputSchema: {
      type: "object",
      properties: {
        page: {
          type: "integer",
          description: "Page number, starting from 1",
          minimum: 1,
          default: 1,
        },
        limit: {
          type: "integer",
          description: "Number of items per page",
          minimum: 1,
          maximum: 100,
          default: 20,
        },
      },
    },
  },

• src/types.ts:22-25 (schema)

  TypeScript interface defining the input parameters for getPopularAnimations.

  export interface GetPopularAnimationsParams {
    page?: number;
    limit?: number;
  }

• src/types.ts:34-39 (schema)

  TypeScript interface defining the response structure for getPopularAnimations.

  export interface GetPopularAnimationsResponse {
    animations: LottieAnimation[];
    total: number;
    page: number;
    limit: number;
  }