anilist-mcp

Instructions

Implementation Reference

• tools/lists.ts:28-51 (handler)

  The handler function for the add_list_entry tool. It authenticates using the AniList token, calls anilist.lists.addEntry with the provided id and options, and returns the JSON-stringified result or an error response.

    async ({ id, options }) => {
      try {
        const auth = requireAuth(config.anilistToken);
        if (!auth.isAuthorized) {
          return auth.errorResponse;
        }
  
        const result = await anilist.lists.addEntry(id, options);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (error: any) {
        return {
          content: [{ type: "text", text: `Error: ${error.message}` }],
          isError: true,
        };
      }
    },
  );

• utils/schemas.ts:206-245 (schema)

  Zod schema defining the 'options' input for the add_list_entry tool, including fields for status, progress, scores, dates, and more for updating/adding list entries.

  export const UpdateEntryOptionsSchema = z
    .object({
      id: z.number().describe("The ID of the list entry"),
      mediaId: z.number().describe("The ID of the media to add"),
      status: EntryStatusSchema.describe("The status of the media on the list"),
      score: z.number().describe("The score given to the media"),
      scoreRaw: z.number().describe("The raw score in 100 point format"),
      progress: z.number().describe("The amount of episodes/chapters consumed"),
      progressVolumes: z
        .number()
        .describe("The amount of volumes read (manga only)"),
      repeat: z.number().describe("Amount of times the media has been repeated"),
      priority: z.number().describe("Priority level of the media"),
      private: z.boolean().describe("Whether the entry should be private"),
      notes: z.string().describe("Text notes about the media"),
      hiddenFromStatusLists: z
        .boolean()
        .describe("Whether the entry should be hidden from non-custom lists"),
      customLists: z
        .array(z.string())
        .describe("Array of custom list names for the media"),
      advancedScores: z
        .array(z.number())
        .describe("Advanced scores as an object"),
      startedAt: z
        .object({
          year: z.number(),
          month: z.number(),
          day: z.number(),
        })
        .describe("When the user started the media"),
      completedAt: z
        .object({
          year: z.number(),
          month: z.number(),
          day: z.number(),
        })
        .describe("When the user completed the media"),
    })
    .describe("Values to save with the entry");

• tools/lists.ts:15-51 (registration)

  Registers the add_list_entry tool on the MCP server within the registerListsTools function, specifying name, description, input schema (id and options), tool properties, and handler.

    "add_list_entry",
    "[Requires Login] Add an entry to the authorized user's list",
    {
      id: z.number().describe("The AniList ID of the media entry to add"),
      options: UpdateEntryOptionsSchema,
    },
    {
      title: "Add List Entry",
      readOnlyHint: false,
      destructiveHint: true,
      idempotentHint: true,
      openWorldHint: true,
    },
    async ({ id, options }) => {
      try {
        const auth = requireAuth(config.anilistToken);
        if (!auth.isAuthorized) {
          return auth.errorResponse;
        }
  
        const result = await anilist.lists.addEntry(id, options);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (error: any) {
        return {
          content: [{ type: "text", text: `Error: ${error.message}` }],
          isError: true,
        };
      }
    },
  );

• tools/index.ts:33-33 (registration)

  Top-level call to registerListsTools in registerAllTools, which includes the add_list_entry tool registration.

  registerListsTools(server, anilist, config);