anilist-mcp

Instructions

Implementation Reference

• tools/search.ts:106-128 (handler)

  The core handler function for the 'search_anime' tool. It takes term, filter, page, and amount as input, calls anilist.searchEntry.anime(), formats the results as JSON text content, or returns an error if the API call fails.
  async ({ term, filter, page, amount }) => { try { const results = await anilist.searchEntry.anime( term, filter, page, amount, ); return { content: [ { type: "text", text: JSON.stringify(results, null, 2), }, ], }; } catch (error: any) { return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true, }; } },
• tools/search.ts:70-100 (schema)

  Input schema for the 'search_anime' tool, defined using Zod. Includes optional query term, MediaFilterTypesSchema for filters, page (default 1), and amount (default 5, max 25).
  { term: z .string() .optional() .describe( `Query term for finding anime (leave it as undefined when no query term specified.) Query term is used for searching with specific word or title in mind. You SHOULD not include things that can be found in the filter object, such as genre or tag. Those things should be included in the filter object instead. To check whether a user requested term should be considered as a query term or a filter term. It is recommended to use tools like 'get_genres' and 'get_media_tags' first.`, ), filter: MediaFilterTypesSchema.optional().describe( `Filter object for searching anime. You MUST NOT include "{ "type": "ANIME" }" in the filter object. As it is already included in the API call. When no sorting method or any filter is specified, you SHOULD use the site default: "{ "sort": ["SEARCH_MATCH"] }". Otherwise, request is likely to fail or return no results.`, ), page: z .number() .optional() .default(1) .describe("Page number for results"), amount: z .number() .optional() .default(5) .describe("Results per page (max 25)"), },
• tools/search.ts:68-129 (registration)

  Registration of the 'search_anime' tool on the MCP server using server.tool(). Includes name, description, input schema, metadata, and inline handler function.
  "search_anime", "Search for anime with query term and filters", { term: z .string() .optional() .describe( `Query term for finding anime (leave it as undefined when no query term specified.) Query term is used for searching with specific word or title in mind. You SHOULD not include things that can be found in the filter object, such as genre or tag. Those things should be included in the filter object instead. To check whether a user requested term should be considered as a query term or a filter term. It is recommended to use tools like 'get_genres' and 'get_media_tags' first.`, ), filter: MediaFilterTypesSchema.optional().describe( `Filter object for searching anime. You MUST NOT include "{ "type": "ANIME" }" in the filter object. As it is already included in the API call. When no sorting method or any filter is specified, you SHOULD use the site default: "{ "sort": ["SEARCH_MATCH"] }". Otherwise, request is likely to fail or return no results.`, ), page: z .number() .optional() .default(1) .describe("Page number for results"), amount: z .number() .optional() .default(5) .describe("Results per page (max 25)"), }, { title: "AniList Anime Search", readOnlyHint: true, openWorldHint: true, }, async ({ term, filter, page, amount }) => { try { const results = await anilist.searchEntry.anime( term, filter, page, amount, ); return { content: [ { type: "text", text: JSON.stringify(results, null, 2), }, ], }; } catch (error: any) { return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true, }; } }, );
• utils/schemas.ts:347-569 (helper)

  MediaFilterTypesSchema: Zod schema defining comprehensive filter options for media searches (used in search_anime filter param). Includes fields for ID, dates, season, type, format, status, genres, tags, sorting, etc.
  export const MediaFilterTypesSchema = z.object({ id: z.number().optional().describe("The AniList ID"), idMal: z.number().optional().describe("The MyAnimeList ID"), startDate: FuzzyDateSchema.optional().describe("The start date of the media"), endDate: FuzzyDateSchema.optional().describe("The end date of the media"), season: MediaSeasonSchema.optional().describe("The season the media aired"), seasonYear: z.number().optional().describe("The year of the season"), type: MediaTypeSchema.optional().describe( "The type of the media (ANIME or MANGA)", ), format: MediaFormatSchema.optional().describe("The format of the media"), status: MediaStatusSchema.optional().describe( "The current status of the media", ), episodes: z .number() .optional() .describe("The number of episodes in the media"), duration: z .number() .optional() .describe("The duration of episodes in minutes"), chapters: z .number() .optional() .describe("The number of chapters in the media"), volumes: z.number().optional().describe("The number of volumes in the media"), isAdult: z .boolean() .optional() .describe("If the media is intended for adult audiences"), genre: z.string().optional().describe("Filter by a specific genre"), tag: z.string().optional().describe("Filter by a specific tag"), minimumTagRank: z .number() .optional() .describe("The minimum tag rank to filter by"), tagCategory: z.string().optional().describe("Filter by tag category"), onList: z .boolean() .optional() .describe( "[Requires Login] Filter by if the media is on the authenticated user's list", ), licensedBy: z .string() .optional() .describe("Filter by media licensed by a specific company"), averageScore: z .number() .optional() .describe("Filter by the media's average score"), popularity: z .number() .optional() .describe("Filter by the media's popularity"), source: MediaFormatSchema.optional().describe( "Filter by the media's source type", ), countryOfOrigin: z .number() .optional() .describe( "Filter by the country where the media was created (ISO 3166-1 alpha-2 country code)", ), search: z.string().optional().describe("Filter by search query"), id_not: z .number() .optional() .describe("Filter by media ID not equal to value"), id_in: z.array(z.number()).optional().describe("Filter by media ID in array"), id_not_in: z .array(z.number()) .optional() .describe("Filter by media ID not in array"), idMal_not: z .number() .optional() .describe("Filter by MyAnimeList ID not equal to value"), idMal_in: z .array(z.number()) .optional() .describe("Filter by MyAnimeList ID in array"), idMal_not_in: z .array(z.number()) .optional() .describe("Filter by MyAnimeList ID not in array"), startDate_greater: z .number() .optional() .describe("Filter by start date greater than value (FuzzyDateInt format)"), startDate_lesser: z .number() .optional() .describe("Filter by start date less than value (FuzzyDateInt format)"), startDate_like: z .string() .optional() .describe("Filter by start date that matches pattern"), endDate_greater: z .number() .optional() .describe("Filter by end date greater than value (FuzzyDateInt format)"), endDate_lesser: z .number() .optional() .describe("Filter by end date less than value (FuzzyDateInt format)"), endDate_like: z .string() .optional() .describe("Filter by end date that matches pattern"), format_in: z .array(MediaFormatSchema) .optional() .describe("Filter by media format in array"), format_not: MediaFormatSchema.optional().describe( "Filter by media format not equal to value", ), format_not_in: z .array(MediaFormatSchema) .optional() .describe("Filter by media format not in array"), status_in: z .array(MediaStatusSchema) .optional() .describe("Filter by media status in array"), status_not: MediaStatusSchema.optional().describe( "Filter by media status not equal to value", ), status_not_in: z .array(MediaStatusSchema) .optional() .describe("Filter by media status not in array"), episodes_greater: z .number() .optional() .describe("Filter by episode count greater than value"), episodes_lesser: z .number() .optional() .describe("Filter by episode count less than value"), duration_greater: z .number() .optional() .describe("Filter by episode duration greater than value"), duration_lesser: z .number() .optional() .describe("Filter by episode duration less than value"), chapters_greater: z .number() .optional() .describe("Filter by chapter count greater than value"), chapters_lesser: z .number() .optional() .describe("Filter by chapter count less than value"), volumes_greater: z .number() .optional() .describe("Filter by volume count greater than value"), volumes_lesser: z .number() .optional() .describe("Filter by volume count less than value"), genre_in: z .array(z.string()) .optional() .describe("Filter by genres in array"), genre_not_in: z .array(z.string()) .optional() .describe("Filter by genres not in array"), tag_in: z.array(z.string()).optional().describe("Filter by tags in array"), tag_not_in: z .array(z.string()) .optional() .describe("Filter by tags not in array"), tagCategory_in: z .array(z.string()) .optional() .describe("Filter by tag categories in array"), tagCategory_not_in: z .array(z.string()) .optional() .describe("Filter by tag categories not in array"), licensedBy_in: z .array(z.string()) .optional() .describe("Filter by media licensed by companies in array"), averageScore_not: z .number() .optional() .describe("Filter by average score not equal to value"), averageScore_greater: z .number() .optional() .describe("Filter by average score greater than value"), averageScore_lesser: z .number() .optional() .describe("Filter by average score less than value"), popularity_not: z .number() .optional() .describe("Filter by popularity not equal to value"), popularity_greater: z .number() .optional() .describe("Filter by popularity greater than value"), popularity_lesser: z .number() .optional() .describe("Filter by popularity less than value"), source_in: z .array(MediaSourceSchema) .optional() .describe("Filter by source types in array"), sort: z .array(MediaSortSchema) .optional() .describe("Sort the results by the provided sort options"), });
• tools/index.ts:37-37 (registration)

  Invocation of registerSearchTools within registerAllTools, which registers the search_anime tool (and others) on the MCP server.
  registerSearchTools(server, anilist);