anilist_add_to_list

Instructions

Implementation Reference

• src/tools/write.ts:183-250 (handler)

  The 'anilist_add_to_list' tool handler: executes the tool logic by calling SAVE_MEDIA_LIST_ENTRY_MUTATION with mediaId, status, and optional score (converted to scoreRaw). Snapshots the entry before mutation for undo support, invalidates caches, and returns the result with status, optional formatted score, entry ID, and undo hint.

  server.addTool({
    name: "anilist_add_to_list",
    description:
      "Add an anime or manga to your list with a status. " +
      "Use when the user wants to start watching, plan to watch, " +
      "or mark a title as completed. Requires ANILIST_TOKEN. " +
      "Returns status, optional score, and entry ID.",
    parameters: AddToListInputSchema,
    annotations: {
      title: "Add to List",
      readOnlyHint: false,
      destructiveHint: true,
      idempotentHint: true,
      openWorldHint: true,
    },
    execute: async (args) => {
      try {
        requireAuth();
  
        // Snapshot before mutation
        const before = await snapshotByMediaId(args.mediaId);
  
        const variables: Record<string, unknown> = {
          mediaId: args.mediaId,
          status: args.status,
        };
        if (args.score !== undefined)
          variables.scoreRaw = Math.round(args.score * 10);
  
        const [data, scoreFmt] = await Promise.all([
          anilistClient.query<SaveMediaListEntryResponse>(
            SAVE_MEDIA_LIST_ENTRY_MUTATION,
            variables,
            { cache: null },
          ),
          getScoreFormat(),
        ]);
  
        const viewerName = await getViewerName();
        anilistClient.invalidateUser(viewerName);
        invalidateUserProfiles(viewerName);
  
        const entry = data.SaveMediaListEntry;
  
        // Track for undo
        pushUndo({
          operation: before
            ? { type: "update", before }
            : { type: "create", entryId: entry.id, mediaId: args.mediaId },
          toolName: "anilist_add_to_list",
          timestamp: Date.now(),
          description: `Set status to ${args.status} on media ${args.mediaId}`,
        });
  
        const scoreStr =
          entry.score > 0
            ? ` | Score: ${formatScore(entry.score, scoreFmt)}`
            : "";
        return [
          `Added to list.`,
          `Status: ${entry.status}${scoreStr}`,
          `Entry ID: ${entry.id}`,
          undoHint(before),
        ].join("\n");
      } catch (error) {
        return throwToolError(error, "adding to list");
      }
    },

• src/tools/write.ts:183-251 (registration)

  Registration of the 'anilist_add_to_list' tool on the FastMCP server via server.addTool() inside registerWriteTools(). Also sets annotations (non-readOnly, destructive, idempotent, openWorld).

  server.addTool({
    name: "anilist_add_to_list",
    description:
      "Add an anime or manga to your list with a status. " +
      "Use when the user wants to start watching, plan to watch, " +
      "or mark a title as completed. Requires ANILIST_TOKEN. " +
      "Returns status, optional score, and entry ID.",
    parameters: AddToListInputSchema,
    annotations: {
      title: "Add to List",
      readOnlyHint: false,
      destructiveHint: true,
      idempotentHint: true,
      openWorldHint: true,
    },
    execute: async (args) => {
      try {
        requireAuth();
  
        // Snapshot before mutation
        const before = await snapshotByMediaId(args.mediaId);
  
        const variables: Record<string, unknown> = {
          mediaId: args.mediaId,
          status: args.status,
        };
        if (args.score !== undefined)
          variables.scoreRaw = Math.round(args.score * 10);
  
        const [data, scoreFmt] = await Promise.all([
          anilistClient.query<SaveMediaListEntryResponse>(
            SAVE_MEDIA_LIST_ENTRY_MUTATION,
            variables,
            { cache: null },
          ),
          getScoreFormat(),
        ]);
  
        const viewerName = await getViewerName();
        anilistClient.invalidateUser(viewerName);
        invalidateUserProfiles(viewerName);
  
        const entry = data.SaveMediaListEntry;
  
        // Track for undo
        pushUndo({
          operation: before
            ? { type: "update", before }
            : { type: "create", entryId: entry.id, mediaId: args.mediaId },
          toolName: "anilist_add_to_list",
          timestamp: Date.now(),
          description: `Set status to ${args.status} on media ${args.mediaId}`,
        });
  
        const scoreStr =
          entry.score > 0
            ? ` | Score: ${formatScore(entry.score, scoreFmt)}`
            : "";
        return [
          `Added to list.`,
          `Status: ${entry.status}${scoreStr}`,
          `Entry ID: ${entry.id}`,
          undoHint(before),
        ].join("\n");
      } catch (error) {
        return throwToolError(error, "adding to list");
      }
    },
  });

• src/schemas.ts:638-662 (schema)

  The AddToListInputSchema Zod schema defining the three input fields: mediaId (positive int), status (enum: CURRENT/PLANNING/COMPLETED/DROPPED/PAUSED/REPEATING), and score (0-10, optional).

  export const AddToListInputSchema = z.object({
    mediaId: z
      .number()
      .int()
      .positive()
      .describe("AniList media ID to add to the list"),
    status: z
      .enum([
        "CURRENT",
        "PLANNING",
        "COMPLETED",
        "DROPPED",
        "PAUSED",
        "REPEATING",
      ])
      .describe("List status to set"),
    score: z
      .number()
      .min(0)
      .max(10)
      .optional()
      .describe("Score on a 0-10 scale (e.g. 8.5). Omit to leave unscored."),
  });
  
  export type AddToListInput = z.infer<typeof AddToListInputSchema>;

• src/index.ts:12-52 (helper)

  Import of registerWriteTools from ./tools/write.js, called at line 60 to register all write tools including anilist_add_to_list on the MCP server.

  import { registerWriteTools } from "./tools/write.js";
  import { registerSocialTools } from "./tools/social.js";
  import { registerAnalyticsTools } from "./tools/analytics.js";
  import { registerImportTools } from "./tools/import.js";
  import { registerCardTools } from "./tools/cards.js";
  import { registerResources } from "./resources.js";
  import { registerPrompts } from "./prompts.js";
  
  // Sanitize env vars: clear unresolved templates, placeholders, or invalid values
  for (const key of ["ANILIST_USERNAME", "ANILIST_TOKEN"] as const) {
    const val = process.env[key] ?? "";
    if (!val || val.startsWith("${") || val === "undefined" || val === "null") {
      process.env[key] = "";
    }
  }
  // AniList tokens are long JWT-like strings (100+ chars)
  if (process.env.ANILIST_TOKEN && process.env.ANILIST_TOKEN.length < 30) {
    console.warn("[ani-mcp] ANILIST_TOKEN looks invalid (too short), ignoring.");
    process.env.ANILIST_TOKEN = "";
  }
  
  // Both vars are optional - warn on missing so operators know what's available
  if (!process.env.ANILIST_USERNAME) {
    console.warn(
      "ANILIST_USERNAME not set - tools will require a username argument.",
    );
  }
  if (!process.env.ANILIST_TOKEN) {
    console.warn("ANILIST_TOKEN not set - authenticated features unavailable.");
  }
  
  const server = new FastMCP({
    name: "ani-mcp",
    version: "0.15.4",
    instructions:
      "ani-mcp is a local MCP server for AniList. " +
      "Read-only tools work without authentication. " +
      "Write tools require ANILIST_TOKEN set in the server's environment config. " +
      "If a tool says the token is not set, tell the user to add ANILIST_TOKEN " +
      "to their MCP server config and restart. " +
      "There is no in-app AniList integration or settings page to connect.",