Freesound MCP Server

Instructions

Implementation Reference

• src/index.ts:106-131 (registration)

  Tool registration in the list of tools, including name, description, and input schema definition

  {
    name: "get_similar_sounds",
    description: "Find sounds similar to a given sound",
    inputSchema: {
      type: "object",
      properties: {
        sound_id: {
          type: "number",
          description: "The ID of the sound to find similar sounds for",
        },
        descriptors_filter: {
          type: "string",
          description: "Filter similar sounds by content descriptors",
        },
        page: {
          type: "number",
          description: "Page number (default: 1)",
        },
        page_size: {
          type: "number",
          description: "Number of results per page (default: 15)",
        },
      },
      required: ["sound_id"],
    },
  },

• src/index.ts:262-279 (handler)

  MCP CallToolRequest handler for get_similar_sounds, which delegates to FreesoundClient and returns JSON response

  case "get_similar_sounds": {
    const similar = await freesoundClient.getSimilarSounds(
      args.sound_id as number,
      {
        descriptors_filter: args.descriptors_filter as string | undefined,
        page: args.page as number | undefined,
        page_size: args.page_size as number | undefined,
      }
    );
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(similar, null, 2),
        },
      ],
    };
  }

• src/freesound-client.ts:165-180 (helper)

  Core implementation of getSimilarSounds in FreesoundClient, making API call to Freesound similar sounds endpoint

  async getSimilarSounds(
    soundId: number,
    params?: SimilarSoundsParams
  ): Promise<PaginatedResults<Sound>> {
    const response = await this.axiosInstance.get(
      `/sounds/${soundId}/similar/`,
      {
        params: {
          descriptors_filter: params?.descriptors_filter,
          page: params?.page || 1,
          page_size: params?.page_size || 15,
        },
      }
    );
    return response.data;
  }

• src/freesound-client.ts:17-19 (schema)

  TypeScript interface defining parameters for getSimilarSounds

  export interface SimilarSoundsParams extends PaginationParams {
    descriptors_filter?: string;
  }