ani-mcp 0.2.4 → 0.3.0

package/README.md

@@ -4,6 +4,11 @@
 
 # ani-mcp
 
+[![npm version](https://img.shields.io/npm/v/ani-mcp)](https://www.npmjs.com/package/ani-mcp)
+[![CI](https://github.com/gavxm/ani-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/gavxm/ani-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/node/v/ani-mcp)](https://nodejs.org)
+
 A smart [MCP](https://modelcontextprotocol.io) server for [AniList](https://anilist.co) that understands your anime and manga taste - not just raw API calls.
 
 ## What makes this different
@@ -43,6 +48,9 @@ Works with any MCP-compatible client.
 | --- | --- | --- |
 | `ANILIST_USERNAME` | No | Default username for list and stats tools. Can also pass per-call. |
 | `ANILIST_TOKEN` | No | AniList OAuth token. Required for write operations and private lists. |
+| `ANILIST_TITLE_LANGUAGE` | No | Title preference: `english` (default), `romaji`, or `native`. |
+| `ANILIST_SCORE_FORMAT` | No | Override score display: `POINT_100`, `POINT_10_DECIMAL`, `POINT_10`, `POINT_5`, `POINT_3`. |
+| `ANILIST_NSFW` | No | Set to `true` to include adult content in results. Default: `false`. |
 | `DEBUG` | No | Set to `true` for debug logging to stderr. |
 | `MCP_TRANSPORT` | No | Set to `http` for HTTP Stream transport. Default: stdio. |
 | `MCP_PORT` | No | Port for HTTP transport. Default: `3000`. |
@@ -59,6 +67,7 @@ Works with any MCP-compatible client.
 | `anilist_seasonal` | Browse a season's anime lineup |
 | `anilist_trending` | What's trending on AniList right now |
 | `anilist_genres` | Browse top titles in a genre with optional filters |
+| `anilist_genre_list` | List all valid genres and content tags |
 | `anilist_recommendations` | Community recommendations for a specific title |
 
 ### Lists & Stats
@@ -88,6 +97,7 @@ Works with any MCP-compatible client.
 | `anilist_studio_search` | Search for a studio and see their productions |
 | `anilist_schedule` | Airing schedule and next episode countdown |
 | `anilist_characters` | Search characters by name with appearances and VAs |
+| `anilist_whoami` | Check authentication status and score format |
 
 ### Write (requires `ANILIST_TOKEN`)
 

package/dist/api/client.js

@@ -143,25 +143,29 @@ class AniListClient {
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
             log("network-error", msg);
-            throw new AniListApiError(`Network error connecting to AniList: ${msg}`, undefined, true);
+            const isTimeout = msg.includes("abort") || msg.includes("timeout");
+            throw new AniListApiError(isTimeout
+                ? "Could not reach AniList (request timed out). Try again."
+                : `Network error connecting to AniList: ${msg}`, undefined, true);
         }
         // Map HTTP errors to retryable/non-retryable
         if (!response.ok) {
             // Read error body for context
             const body = await response.text().catch(() => "");
             if (response.status === 429) {
-                log("rate-limit", `429 from AniList`);
                 const retryAfter = response.headers.get("Retry-After");
-                if (retryAfter) {
-                    const delaySec = parseInt(retryAfter, 10);
-                    if (delaySec > 0) {
-                        await new Promise((r) => setTimeout(r, delaySec * 1000));
-                    }
+                const delaySec = retryAfter ? parseInt(retryAfter, 10) : 0;
+                log("rate-limit", `429 from AniList (retry-after: ${delaySec || "none"})`);
+                if (delaySec > 0) {
+                    await new Promise((r) => setTimeout(r, delaySec * 1000));
                 }
-                throw new AniListApiError("AniList rate limit hit. The server will retry automatically.", 429, true);
+                throw new AniListApiError(`AniList rate limit exceeded. Try again in ${delaySec > 0 ? `${delaySec} seconds` : "30-60 seconds"}.`, 429, true);
+            }
+            if (response.status === 401) {
+                throw new AbortError(new AniListApiError("Authentication failed. Check that ANILIST_TOKEN is valid and not expired.", 401, false));
             }
             if (response.status === 404) {
-                throw new AbortError(new AniListApiError("Resource not found on AniList. Check that the ID or username is correct.", 404, false));
+                throw new AbortError(new AniListApiError("Not found on AniList. Check that the ID or username is correct.", 404, false));
             }
             // Only server errors (5xx) are worth retrying
             if (response.status >= 500) {

package/dist/api/queries.d.ts

@@ -13,7 +13,7 @@ export declare const DISCOVER_MEDIA_QUERY = "\n  query DiscoverMedia(\n    $type
 /** Browse anime by season and year */
 export declare const SEASONAL_MEDIA_QUERY = "\n  query SeasonalMedia(\n    $season: MediaSeason\n    $seasonYear: Int\n    $type: MediaType\n    $isAdult: Boolean\n    $sort: [MediaSort]\n    $page: Int\n    $perPage: Int\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total currentPage lastPage hasNextPage }\n      media(\n        season: $season\n        seasonYear: $seasonYear\n        type: $type\n        isAdult: $isAdult\n        sort: $sort\n      ) {\n        ...MediaFields\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** User profile statistics - watching/reading stats, genre/tag/score breakdowns */
-export declare const USER_STATS_QUERY = "\n  query UserStats($name: String!) {\n    User(name: $name) {\n      id\n      name\n      statistics {\n        anime {\n          count\n          meanScore\n          minutesWatched\n          episodesWatched\n          genres(sort: COUNT_DESC, limit: 10) {\n            genre\n            count\n            meanScore\n            minutesWatched\n          }\n          scores(sort: MEAN_SCORE_DESC) {\n            score\n            count\n          }\n          formats(sort: COUNT_DESC) {\n            format\n            count\n          }\n        }\n        manga {\n          count\n          meanScore\n          chaptersRead\n          volumesRead\n          genres(sort: COUNT_DESC, limit: 10) {\n            genre\n            count\n            meanScore\n            chaptersRead\n          }\n          scores(sort: MEAN_SCORE_DESC) {\n            score\n            count\n          }\n          formats(sort: COUNT_DESC) {\n            format\n            count\n          }\n        }\n      }\n    }\n  }\n";
+export declare const USER_STATS_QUERY = "\n  query UserStats($name: String!) {\n    User(name: $name) {\n      id\n      name\n      mediaListOptions {\n        scoreFormat\n      }\n      statistics {\n        anime {\n          count\n          meanScore\n          minutesWatched\n          episodesWatched\n          genres(sort: COUNT_DESC, limit: 10) {\n            genre\n            count\n            meanScore\n            minutesWatched\n          }\n          scores(sort: MEAN_SCORE_DESC) {\n            score\n            count\n          }\n          formats(sort: COUNT_DESC) {\n            format\n            count\n          }\n        }\n        manga {\n          count\n          meanScore\n          chaptersRead\n          volumesRead\n          genres(sort: COUNT_DESC, limit: 10) {\n            genre\n            count\n            meanScore\n            chaptersRead\n          }\n          scores(sort: MEAN_SCORE_DESC) {\n            score\n            count\n          }\n          formats(sort: COUNT_DESC) {\n            format\n            count\n          }\n        }\n      }\n    }\n  }\n";
 /** Media recommendations for a given title */
 export declare const RECOMMENDATIONS_QUERY = "\n  query MediaRecommendations($id: Int, $search: String, $perPage: Int) {\n    Media(id: $id, search: $search) {\n      id\n      title { romaji english native }\n      recommendations(sort: RATING_DESC, perPage: $perPage) {\n        nodes {\n          rating\n          mediaRecommendation {\n            ...MediaFields\n          }\n        }\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** Trending anime or manga right now */
@@ -27,12 +27,16 @@ export declare const AIRING_SCHEDULE_QUERY = "\n  query AiringSchedule($id: Int,
 /** Search for characters by name */
 export declare const CHARACTER_SEARCH_QUERY = "\n  query CharacterSearch($search: String!, $page: Int, $perPage: Int) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      characters(search: $search, sort: FAVOURITES_DESC) {\n        id\n        name { full native alternative }\n        image { medium }\n        favourites\n        siteUrl\n        media(sort: POPULARITY_DESC, perPage: 5) {\n          edges {\n            characterRole\n            node {\n              id\n              title { romaji english }\n              format\n              type\n              siteUrl\n            }\n            voiceActors(language: JAPANESE) {\n              id\n              name { full }\n              siteUrl\n            }\n          }\n        }\n      }\n    }\n  }\n";
 /** Create or update a list entry */
-export declare const SAVE_MEDIA_LIST_ENTRY_MUTATION = "\n  mutation SaveMediaListEntry(\n    $mediaId: Int\n    $status: MediaListStatus\n    $score: Float\n    $progress: Int\n    $notes: String\n    $private: Boolean\n  ) {\n    SaveMediaListEntry(\n      mediaId: $mediaId\n      status: $status\n      score: $score\n      progress: $progress\n      notes: $notes\n      private: $private\n    ) {\n      id\n      mediaId\n      status\n      score(format: POINT_10)\n      progress\n    }\n  }\n";
+export declare const SAVE_MEDIA_LIST_ENTRY_MUTATION = "\n  mutation SaveMediaListEntry(\n    $mediaId: Int\n    $status: MediaListStatus\n    $scoreRaw: Int\n    $progress: Int\n    $notes: String\n    $private: Boolean\n  ) {\n    SaveMediaListEntry(\n      mediaId: $mediaId\n      status: $status\n      scoreRaw: $scoreRaw\n      progress: $progress\n      notes: $notes\n      private: $private\n    ) {\n      id\n      mediaId\n      status\n      score(format: POINT_10)\n      progress\n    }\n  }\n";
 /** Remove a list entry */
 export declare const DELETE_MEDIA_LIST_ENTRY_MUTATION = "\n  mutation DeleteMediaListEntry($id: Int!) {\n    DeleteMediaListEntry(id: $id) {\n      deleted\n    }\n  }\n";
 /** User's anime/manga list, grouped by status. Omit $status to get all lists. */
 export declare const USER_LIST_QUERY = "\n  query UserMediaList(\n    $userName: String!\n    $type: MediaType\n    $status: MediaListStatus\n    $sort: [MediaListSort]\n  ) {\n    MediaListCollection(\n      userName: $userName\n      type: $type\n      status: $status\n      sort: $sort\n    ) {\n      lists {\n        name\n        status\n        entries {\n          id\n          score(format: POINT_10)  # normalize to 1-10 scale regardless of user's profile setting\n          progress\n          status\n          updatedAt\n          startedAt { year month day }\n          completedAt { year month day }\n          notes\n          media {\n            ...MediaFields\n          }\n        }\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** Search for staff by name with their top works */
 export declare const STAFF_SEARCH_QUERY = "\n  query StaffSearch($search: String!, $page: Int, $perPage: Int, $mediaPerPage: Int) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      staff(search: $search, sort: SEARCH_MATCH) {\n        id\n        name { full native }\n        primaryOccupations\n        siteUrl\n        staffMedia(sort: POPULARITY_DESC, perPage: $mediaPerPage) {\n          edges {\n            staffRole\n            node {\n              id\n              title { romaji english }\n              format\n              type\n              meanScore\n              siteUrl\n            }\n          }\n        }\n      }\n    }\n  }\n";
+/** Authenticated user info */
+export declare const VIEWER_QUERY = "\n  query Viewer {\n    Viewer {\n      id\n      name\n      avatar { medium }\n      siteUrl\n      mediaListOptions {\n        scoreFormat\n      }\n    }\n  }\n";
+/** All valid genres and media tags */
+export declare const GENRE_TAG_COLLECTION_QUERY = "\n  query GenreTagCollection {\n    GenreCollection\n    MediaTagCollection {\n      name\n      description\n      category\n      isAdult\n    }\n  }\n";
 /** Search for a studio by name with their productions */
 export declare const STUDIO_SEARCH_QUERY = "\n  query StudioSearch($search: String!, $perPage: Int) {\n    Studio(search: $search, sort: SEARCH_MATCH) {\n      id\n      name\n      isAnimationStudio\n      siteUrl\n      media(sort: POPULARITY_DESC, perPage: $perPage) {\n        edges {\n          isMainStudio\n          node {\n            id\n            title { romaji english }\n            format\n            type\n            status\n            meanScore\n            siteUrl\n          }\n        }\n      }\n    }\n  }\n";

package/dist/api/queries.js

@@ -161,6 +161,9 @@ export const USER_STATS_QUERY = `
     User(name: $name) {
       id
       name
+      mediaListOptions {
+        scoreFormat
+      }
       statistics {
         anime {
           count
@@ -369,7 +372,7 @@ export const SAVE_MEDIA_LIST_ENTRY_MUTATION = `
   mutation SaveMediaListEntry(
     $mediaId: Int
     $status: MediaListStatus
-    $score: Float
+    $scoreRaw: Int
     $progress: Int
     $notes: String
     $private: Boolean
@@ -377,7 +380,7 @@ export const SAVE_MEDIA_LIST_ENTRY_MUTATION = `
     SaveMediaListEntry(
       mediaId: $mediaId
       status: $status
-      score: $score
+      scoreRaw: $scoreRaw
       progress: $progress
       notes: $notes
       private: $private
@@ -460,6 +463,32 @@ export const STAFF_SEARCH_QUERY = `
     }
   }
 `;
+/** Authenticated user info */
+export const VIEWER_QUERY = `
+  query Viewer {
+    Viewer {
+      id
+      name
+      avatar { medium }
+      siteUrl
+      mediaListOptions {
+        scoreFormat
+      }
+    }
+  }
+`;
+/** All valid genres and media tags */
+export const GENRE_TAG_COLLECTION_QUERY = `
+  query GenreTagCollection {
+    GenreCollection
+    MediaTagCollection {
+      name
+      description
+      category
+      isAdult
+    }
+  }
+`;
 /** Search for a studio by name with their productions */
 export const STUDIO_SEARCH_QUERY = `
   query StudioSearch($search: String!, $perPage: Int) {

package/dist/schemas.d.ts

@@ -257,6 +257,11 @@ export declare const StaffSearchInputSchema: z.ZodObject<{
     page: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type StaffSearchInput = z.infer<typeof StaffSearchInputSchema>;
+/** Input for listing all valid genres and tags */
+export declare const GenreListInputSchema: z.ZodObject<{
+    includeAdultTags: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GenreListInput = z.infer<typeof GenreListInputSchema>;
 /** Input for searching studios by name */
 export declare const StudioSearchInputSchema: z.ZodObject<{
     query: z.ZodString;

package/dist/schemas.js

@@ -442,6 +442,13 @@ export const StaffSearchInputSchema = z.object({
         .describe("Works per person to show (default 10, max 25)"),
     page: pageParam,
 });
+/** Input for listing all valid genres and tags */
+export const GenreListInputSchema = z.object({
+    includeAdultTags: z
+        .boolean()
+        .default(false)
+        .describe("Include adult/NSFW tags in the list"),
+});
 /** Input for searching studios by name */
 export const StudioSearchInputSchema = z.object({
     query: z

package/dist/tools/discover.js

@@ -1,8 +1,8 @@
 /** Discovery tools: trending and genre browsing without search terms. */
 import { anilistClient } from "../api/client.js";
-import { TRENDING_MEDIA_QUERY, GENRE_BROWSE_QUERY } from "../api/queries.js";
-import { TrendingInputSchema, GenreBrowseInputSchema } from "../schemas.js";
-import { formatMediaSummary, throwToolError, paginationFooter } from "../utils.js";
+import { TRENDING_MEDIA_QUERY, GENRE_BROWSE_QUERY, GENRE_TAG_COLLECTION_QUERY, } from "../api/queries.js";
+import { TrendingInputSchema, GenreBrowseInputSchema, GenreListInputSchema, } from "../schemas.js";
+import { formatMediaSummary, throwToolError, paginationFooter, } from "../utils.js";
 /** Register discovery tools on the MCP server */
 export function registerDiscoverTools(server) {
     // === Trending ===
@@ -38,7 +38,7 @@ export function registerDiscoverTools(server) {
                 ].join("\n");
                 const formatted = results.map((m, i) => `${offset + i + 1}. ${formatMediaSummary(m)}`);
                 const footer = paginationFooter(args.page, args.limit, pageInfo.total, pageInfo.hasNextPage);
-                return header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : "");
+                return (header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : ""));
             }
             catch (error) {
                 return throwToolError(error, "fetching trending");
@@ -102,11 +102,62 @@ export function registerDiscoverTools(server) {
                 ].join("\n");
                 const formatted = results.map((m, i) => `${offset + i + 1}. ${formatMediaSummary(m)}`);
                 const footer = paginationFooter(args.page, args.limit, pageInfo.total, pageInfo.hasNextPage);
-                return header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : "");
+                return (header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : ""));
             }
             catch (error) {
                 return throwToolError(error, "browsing genres");
             }
         },
     });
+    // === Genre/Tag List ===
+    server.addTool({
+        name: "anilist_genre_list",
+        description: "List all valid AniList genres and content tags. " +
+            "Use when the user asks what genres exist, wants to see available tags, " +
+            "or needs valid genre names for filtering other tools.",
+        parameters: GenreListInputSchema,
+        annotations: {
+            title: "List Genres & Tags",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const data = await anilistClient.query(GENRE_TAG_COLLECTION_QUERY, {}, { cache: "media" });
+                const lines = [
+                    "# AniList Genres",
+                    "",
+                    data.GenreCollection.join(", "),
+                ];
+                // Group tags by category
+                let tags = data.MediaTagCollection;
+                if (!args.includeAdultTags) {
+                    tags = tags.filter((t) => !t.isAdult);
+                }
+                const categories = new Map();
+                for (const tag of tags) {
+                    const cat = tag.category || "Other";
+                    const list = categories.get(cat);
+                    if (list) {
+                        list.push(tag);
+                    }
+                    else {
+                        categories.set(cat, [tag]);
+                    }
+                }
+                lines.push("", "# Content Tags");
+                for (const [category, catTags] of categories) {
+                    lines.push("", `## ${category}`);
+                    for (const tag of catTags) {
+                        lines.push(`  ${tag.name} - ${tag.description}`);
+                    }
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "fetching genre list");
+            }
+        },
+    });
 }

package/dist/tools/info.d.ts

@@ -1,4 +1,4 @@
-/** Info tools: staff credits, airing schedule, and character search. */
+/** Info tools: staff credits, airing schedule, character search, and auth check. */
 import type { FastMCP } from "fastmcp";
 /** Register info tools on the MCP server */
 export declare function registerInfoTools(server: FastMCP): void;

package/dist/tools/info.js

@@ -1,6 +1,7 @@
-/** Info tools: staff credits, airing schedule, and character search. */
+/** Info tools: staff credits, airing schedule, character search, and auth check. */
+import { z } from "zod";
 import { anilistClient } from "../api/client.js";
-import { STAFF_QUERY, AIRING_SCHEDULE_QUERY, CHARACTER_SEARCH_QUERY, STAFF_SEARCH_QUERY, STUDIO_SEARCH_QUERY, } from "../api/queries.js";
+import { STAFF_QUERY, AIRING_SCHEDULE_QUERY, CHARACTER_SEARCH_QUERY, STAFF_SEARCH_QUERY, STUDIO_SEARCH_QUERY, VIEWER_QUERY, } from "../api/queries.js";
 import { StaffInputSchema, ScheduleInputSchema, CharacterSearchInputSchema, StaffSearchInputSchema, StudioSearchInputSchema, } from "../schemas.js";
 import { getTitle, throwToolError, paginationFooter } from "../utils.js";
 // === Helpers ===
@@ -18,6 +19,61 @@ function formatTimeUntil(seconds) {
 // === Tool Registration ===
 /** Register info tools on the MCP server */
 export function registerInfoTools(server) {
+    // === Who Am I ===
+    server.addTool({
+        name: "anilist_whoami",
+        description: "Check which AniList account is authenticated and verify the token works. " +
+            "Use when the user wants to confirm their setup or debug auth issues.",
+        parameters: z.object({}),
+        annotations: {
+            title: "Who Am I",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        execute: async () => {
+            if (!process.env.ANILIST_TOKEN) {
+                const lines = [
+                    "ANILIST_TOKEN is not set.",
+                    "Set it to enable authenticated features (write operations, score format detection).",
+                    "Get a token at: https://anilist.co/settings/developer",
+                ];
+                const envUser = process.env.ANILIST_USERNAME;
+                if (envUser) {
+                    lines.push("", `ANILIST_USERNAME is set to "${envUser}" (read-only mode).`);
+                }
+                return lines.join("\n");
+            }
+            try {
+                const data = await anilistClient.query(VIEWER_QUERY, {}, { cache: "stats" });
+                if (!data.Viewer) {
+                    return throwToolError(new Error("No viewer data returned"), "checking authentication");
+                }
+                const v = data.Viewer;
+                const lines = [
+                    `Authenticated as: ${v.name}`,
+                    `AniList ID: ${v.id}`,
+                    `Score format: ${v.mediaListOptions.scoreFormat}`,
+                    `Profile: ${v.siteUrl}`,
+                ];
+                // Check if Anilist username matches
+                const envUser = process.env.ANILIST_USERNAME;
+                if (envUser) {
+                    const match = envUser.toLowerCase() === v.name.toLowerCase();
+                    lines.push("", match
+                        ? `ANILIST_USERNAME "${envUser}" matches authenticated user.`
+                        : `ANILIST_USERNAME "${envUser}" does not match authenticated user "${v.name}".`);
+                }
+                else {
+                    lines.push("", "ANILIST_USERNAME is not set. Tools will require a username argument.");
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "checking authentication");
+            }
+        },
+    });
     // === Staff Credits ===
     server.addTool({
         name: "anilist_staff",
@@ -205,7 +261,12 @@ export function registerInfoTools(server) {
         },
         execute: async (args) => {
             try {
-                const data = await anilistClient.query(STAFF_SEARCH_QUERY, { search: args.query, page: args.page, perPage: args.limit, mediaPerPage: args.mediaLimit }, { cache: "search" });
+                const data = await anilistClient.query(STAFF_SEARCH_QUERY, {
+                    search: args.query,
+                    page: args.page,
+                    perPage: args.limit,
+                    mediaPerPage: args.mediaLimit,
+                }, { cache: "search" });
                 const results = data.Page.staff;
                 if (!results.length) {
                     return `No staff found matching "${args.query}".`;
@@ -278,10 +339,7 @@ export function registerInfoTools(server) {
                 const data = await anilistClient.query(STUDIO_SEARCH_QUERY, { search: args.query, perPage: args.limit }, { cache: "search" });
                 const studio = data.Studio;
                 const tag = studio.isAnimationStudio ? "Animation Studio" : "Studio";
-                const lines = [
-                    `# ${studio.name} (${tag})`,
-                    "",
-                ];
+                const lines = [`# ${studio.name} (${tag})`, ""];
                 // Main productions first, then supporting
                 const main = studio.media.edges.filter((e) => e.isMainStudio);
                 const supporting = studio.media.edges.filter((e) => !e.isMainStudio);

package/dist/tools/lists.js

@@ -2,7 +2,7 @@
 import { anilistClient } from "../api/client.js";
 import { USER_STATS_QUERY } from "../api/queries.js";
 import { ListInputSchema, StatsInputSchema } from "../schemas.js";
-import { getTitle, getDefaultUsername, throwToolError, paginationFooter } from "../utils.js";
+import { getTitle, getDefaultUsername, throwToolError, paginationFooter, formatScore, detectScoreFormat, } from "../utils.js";
 // Map user-friendly sort names to AniList's internal enum values
 const SORT_MAP = {
     SCORE: ["SCORE_DESC"],
@@ -28,9 +28,16 @@ export function registerListTools(server) {
         execute: async (args) => {
             try {
                 const username = getDefaultUsername(args.username);
+                // Fetch list and score format in parallel
                 const sort = SORT_MAP[args.sort] ?? SORT_MAP.UPDATED;
                 const status = args.status !== "ALL" ? args.status : undefined;
-                const allEntries = await anilistClient.fetchList(username, args.type, status, sort);
+                const [allEntries, scoreFormat] = await Promise.all([
+                    anilistClient.fetchList(username, args.type, status, sort),
+                    detectScoreFormat(async () => {
+                        const data = await anilistClient.query(USER_STATS_QUERY, { name: username }, { cache: "stats" });
+                        return data.User.mediaListOptions.scoreFormat;
+                    }),
+                ]);
                 if (!allEntries.length) {
                     if (args.status === "ALL") {
                         return `${username}'s ${args.type.toLowerCase()} list is empty.`;
@@ -50,9 +57,9 @@ export function registerListTools(server) {
                         (totalCount > limited.length ? `, showing ${limited.length}` : ""),
                     "",
                 ].join("\n");
-                const formatted = limited.map((entry, i) => formatListEntry(entry, offset + i + 1));
+                const formatted = limited.map((entry, i) => formatListEntry(entry, offset + i + 1, scoreFormat));
                 const footer = paginationFooter(args.page, args.limit, totalCount, hasNextPage);
-                return header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : "");
+                return (header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : ""));
             }
             catch (error) {
                 return throwToolError(error, "fetching list");
@@ -148,7 +155,7 @@ function formatTypeStats(stats, label) {
     return lines;
 }
 /** Format a single list entry with title, progress, score, and update date */
-function formatListEntry(entry, index) {
+function formatListEntry(entry, index, scoreFmt) {
     const media = entry.media;
     const title = getTitle(media.title);
     const format = media.format ?? "?";
@@ -156,7 +163,7 @@ function formatListEntry(entry, index) {
     const total = media.episodes ?? media.chapters ?? "?";
     const unit = media.episodes !== null ? "ep" : "ch";
     const progress = `${entry.progress}/${total} ${unit}`;
-    const score = entry.score > 0 ? `★ ${entry.score}/10` : "Unscored";
+    const score = formatScore(entry.score, scoreFmt);
     const updated = entry.updatedAt
         ? new Date(entry.updatedAt * 1000).toLocaleDateString("en-US", {
             // AniList uses Unix seconds

package/dist/tools/recommend.js

@@ -2,7 +2,7 @@
 import { anilistClient } from "../api/client.js";
 import { DISCOVER_MEDIA_QUERY, MEDIA_DETAILS_QUERY, RECOMMENDATIONS_QUERY, } from "../api/queries.js";
 import { TasteInputSchema, PickInputSchema, CompareInputSchema, WrappedInputSchema, ExplainInputSchema, SimilarInputSchema, } from "../schemas.js";
-import { getTitle, getDefaultUsername, throwToolError } from "../utils.js";
+import { getTitle, getDefaultUsername, throwToolError, isNsfwEnabled, } from "../utils.js";
 import { buildTasteProfile, describeTasteProfile, } from "../engine/taste.js";
 import { matchCandidates, explainMatch } from "../engine/matcher.js";
 import { parseMood, hasMoodMatch, seasonalMoodSuggestions, } from "../engine/mood.js";
@@ -18,11 +18,13 @@ async function discoverByTaste(profile, type, completedIds) {
     const topGenres = profile.genres.slice(0, 3).map((g) => g.name);
     if (topGenres.length === 0)
         return [];
+    const nsfw = isNsfwEnabled();
     const data = await anilistClient.query(DISCOVER_MEDIA_QUERY, {
         type,
         genre_in: topGenres,
         perPage: 30,
         sort: ["SCORE_DESC"],
+        ...(nsfw ? {} : { isAdult: false }),
     }, { cache: "search" });
     return data.Page.media.filter((m) => !completedIds.has(m.id));
 }
@@ -134,6 +136,10 @@ export function registerRecommendTools(server) {
                 else {
                     candidates = planning.map((e) => e.media);
                 }
+                // Filter adult content unless enabled
+                if (!isNsfwEnabled()) {
+                    candidates = candidates.filter((m) => !m.isAdult);
+                }
                 // Optionally filter by episode count
                 const maxEps = args.maxEpisodes;
                 if (maxEps) {
@@ -452,7 +458,7 @@ export function registerRecommendTools(server) {
                 const [mediaData, { profile, entries }] = await Promise.all([
                     anilistClient.query(MEDIA_DETAILS_QUERY, {
                         id: args.mediaId,
-                    }),
+                    }, { cache: "media" }),
                     profileForUser(username, args.type),
                 ]);
                 const media = mediaData.Media;
@@ -542,20 +548,23 @@ export function registerRecommendTools(server) {
                 const [detailsData, recsData] = await Promise.all([
                     anilistClient.query(MEDIA_DETAILS_QUERY, {
                         id: args.mediaId,
-                    }),
+                    }, { cache: "media" }),
                     anilistClient.query(RECOMMENDATIONS_QUERY, {
                         id: args.mediaId,
                         perPage: 25,
-                    }),
+                    }, { cache: "media" }),
                 ]);
                 const source = detailsData.Media;
                 const sourceTitle = getTitle(source.title);
                 // Build candidate list and rec rating map
+                const nsfw = isNsfwEnabled();
                 const candidates = [];
                 const recRatings = new Map();
                 for (const node of recsData.Media.recommendations.nodes) {
                     if (!node.mediaRecommendation)
                         continue;
+                    if (!nsfw && node.mediaRecommendation.isAdult)
+                        continue;
                     candidates.push(node.mediaRecommendation);
                     if (node.rating > 0) {
                         recRatings.set(node.mediaRecommendation.id, node.rating);

package/dist/tools/search.js

@@ -2,7 +2,7 @@
 import { anilistClient } from "../api/client.js";
 import { SEARCH_MEDIA_QUERY, MEDIA_DETAILS_QUERY, SEASONAL_MEDIA_QUERY, RECOMMENDATIONS_QUERY, } from "../api/queries.js";
 import { SearchInputSchema, DetailsInputSchema, SeasonalInputSchema, RecommendationsInputSchema, } from "../schemas.js";
-import { getTitle, truncateDescription, throwToolError, formatMediaSummary, paginationFooter, } from "../utils.js";
+import { getTitle, truncateDescription, throwToolError, formatMediaSummary, paginationFooter, isNsfwEnabled, resolveAlias, } from "../utils.js";
 // Default to popularity for broad queries
 const SEARCH_SORT = ["POPULARITY_DESC"];
 // === Tool Registration ===
@@ -23,8 +23,9 @@ export function registerSearchTools(server) {
         },
         execute: async (args) => {
             try {
+                const query = resolveAlias(args.query);
                 const variables = {
-                    search: args.query,
+                    search: query,
                     type: args.type,
                     page: args.page,
                     perPage: args.limit,
@@ -53,7 +54,7 @@ export function registerSearchTools(server) {
                 ].join("\n");
                 const formatted = results.map((m, i) => `${offset + i + 1}. ${formatMediaSummary(m)}`);
                 const footer = paginationFooter(args.page, args.limit, pageInfo.total, pageInfo.hasNextPage);
-                return header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : "");
+                return (header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : ""));
             }
             catch (error) {
                 return throwToolError(error, "searching");
@@ -65,7 +66,8 @@ export function registerSearchTools(server) {
         description: "Get full details about a specific anime or manga. " +
             "Use when the user asks about a specific title and wants synopsis, score, " +
             "episodes, studios, related works, and recommendations. " +
-            "Provide either an AniList ID (faster, exact) or a title (fuzzy match).",
+            "Provide either an AniList ID (faster, exact) or a title (fuzzy match). " +
+            "Title search works with English, romaji, native names, and common abbreviations (e.g. 'aot', 'jjk').",
         parameters: DetailsInputSchema,
         annotations: {
             title: "Get Title Details",
@@ -75,12 +77,11 @@ export function registerSearchTools(server) {
         },
         execute: async (args) => {
             try {
-                // AniList uses "search" as the GraphQL variable name for title lookups
                 const variables = {};
                 if (args.id)
                     variables.id = args.id;
                 if (args.title)
-                    variables.search = args.title;
+                    variables.search = resolveAlias(args.title);
                 const data = await anilistClient.query(MEDIA_DETAILS_QUERY, variables, { cache: "media" });
                 const m = data.Media;
                 const title = getTitle(m.title);
@@ -195,7 +196,7 @@ export function registerSearchTools(server) {
                 ].join("\n");
                 const formatted = results.map((m, i) => `${offset + i + 1}. ${formatMediaSummary(m)}`);
                 const footer = paginationFooter(args.page, args.limit, pageInfo.total, pageInfo.hasNextPage);
-                return header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : "");
+                return (header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : ""));
             }
             catch (error) {
                 return throwToolError(error, "browsing seasonal anime");
@@ -228,7 +229,10 @@ export function registerSearchTools(server) {
                 const data = await anilistClient.query(RECOMMENDATIONS_QUERY, variables, { cache: "media" });
                 const source = data.Media;
                 const sourceTitle = getTitle(source.title);
-                const recs = source.recommendations.nodes.filter((n) => n.mediaRecommendation && n.rating > 0);
+                const nsfw = isNsfwEnabled();
+                const recs = source.recommendations.nodes.filter((n) => n.mediaRecommendation &&
+                    n.rating > 0 &&
+                    (nsfw || !n.mediaRecommendation.isAdult));
                 if (!recs.length) {
                     return `No community recommendations found for "${sourceTitle}".`;
                 }

package/dist/tools/write.js

@@ -1,8 +1,8 @@
 /** Write tools: update progress, add to list, rate, and delete entries. */
 import { anilistClient } from "../api/client.js";
-import { SAVE_MEDIA_LIST_ENTRY_MUTATION, DELETE_MEDIA_LIST_ENTRY_MUTATION, } from "../api/queries.js";
+import { SAVE_MEDIA_LIST_ENTRY_MUTATION, DELETE_MEDIA_LIST_ENTRY_MUTATION, VIEWER_QUERY, } from "../api/queries.js";
 import { UpdateProgressInputSchema, AddToListInputSchema, RateInputSchema, DeleteFromListInputSchema, } from "../schemas.js";
-import { throwToolError } from "../utils.js";
+import { throwToolError, formatScore, detectScoreFormat } from "../utils.js";
 // === Auth Guard ===
 /** Guard against unauthenticated write attempts */
 function requireAuth() {
@@ -23,7 +23,7 @@ export function registerWriteTools(server) {
         annotations: {
             title: "Update Progress",
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: true,
         },
@@ -60,7 +60,7 @@ export function registerWriteTools(server) {
         annotations: {
             title: "Add to List",
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: true,
         },
@@ -72,11 +72,19 @@ export function registerWriteTools(server) {
                     status: args.status,
                 };
                 if (args.score !== undefined)
-                    variables.score = args.score;
-                const data = await anilistClient.query(SAVE_MEDIA_LIST_ENTRY_MUTATION, variables, { cache: null });
+                    variables.scoreRaw = Math.round(args.score * 10);
+                const [data, scoreFmt] = await Promise.all([
+                    anilistClient.query(SAVE_MEDIA_LIST_ENTRY_MUTATION, variables, { cache: null }),
+                    detectScoreFormat(async () => {
+                        const data = await anilistClient.query(VIEWER_QUERY, {}, { cache: "stats" });
+                        return data.Viewer.mediaListOptions.scoreFormat;
+                    }),
+                ]);
                 anilistClient.clearCache();
                 const entry = data.SaveMediaListEntry;
-                const scoreStr = entry.score > 0 ? ` | Score: ${entry.score}/10` : "";
+                const scoreStr = entry.score > 0
+                    ? ` | Score: ${formatScore(entry.score, scoreFmt)}`
+                    : "";
                 return [
                     `Added to list.`,
                     `Status: ${entry.status}${scoreStr}`,
@@ -98,19 +106,25 @@ export function registerWriteTools(server) {
         annotations: {
             title: "Rate Title",
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: true,
         },
         execute: async (args) => {
             try {
                 requireAuth();
-                const data = await anilistClient.query(SAVE_MEDIA_LIST_ENTRY_MUTATION, { mediaId: args.mediaId, score: args.score }, { cache: null });
+                const [data, scoreFmt] = await Promise.all([
+                    anilistClient.query(SAVE_MEDIA_LIST_ENTRY_MUTATION, { mediaId: args.mediaId, scoreRaw: Math.round(args.score * 10) }, { cache: null }),
+                    detectScoreFormat(async () => {
+                        const data = await anilistClient.query(VIEWER_QUERY, {}, { cache: "stats" });
+                        return data.Viewer.mediaListOptions.scoreFormat;
+                    }),
+                ]);
                 anilistClient.clearCache();
                 const entry = data.SaveMediaListEntry;
                 const scoreDisplay = args.score === 0
                     ? "Score removed."
-                    : `Score set to ${entry.score}/10.`;
+                    : `Score set to ${formatScore(entry.score, scoreFmt)}.`;
                 return [scoreDisplay, `Entry ID: ${entry.id}`].join("\n");
             }
             catch (error) {

package/dist/types.d.ts

@@ -102,6 +102,9 @@ export interface UserStatsResponse {
     User: {
         id: number;
         name: string;
+        mediaListOptions: {
+            scoreFormat: ScoreFormat;
+        };
         statistics: {
             anime: MediaTypeStats;
             manga: MediaTypeStats;
@@ -350,6 +353,32 @@ export interface StaffSearchResponse {
         }>;
     };
 }
+/** AniList score format options */
+export type ScoreFormat = "POINT_100" | "POINT_10_DECIMAL" | "POINT_10" | "POINT_5" | "POINT_3";
+/** Authenticated user info from Viewer query */
+export interface ViewerResponse {
+    Viewer: {
+        id: number;
+        name: string;
+        avatar: {
+            medium: string | null;
+        };
+        siteUrl: string;
+        mediaListOptions: {
+            scoreFormat: ScoreFormat;
+        };
+    };
+}
+/** All valid genres and media tags */
+export interface GenreTagCollectionResponse {
+    GenreCollection: string[];
+    MediaTagCollection: Array<{
+        name: string;
+        description: string;
+        category: string;
+        isAdult: boolean;
+    }>;
+}
 /** Single studio with production history */
 export interface StudioSearchResponse {
     Studio: {

package/dist/utils.d.ts

@@ -1,7 +1,11 @@
 /** Formatting and resolution helpers. */
-import type { AniListMedia } from "./types.js";
-/** Best available title: English -> Romaji -> Native */
+import type { AniListMedia, ScoreFormat } from "./types.js";
+/** Best available title, respecting ANILIST_TITLE_LANGUAGE preference */
 export declare function getTitle(title: AniListMedia["title"]): string;
+/** Whether NSFW/adult content is enabled via env var (default: false) */
+export declare function isNsfwEnabled(): boolean;
+/** Resolve common abbreviations to full titles */
+export declare function resolveAlias(query: string): string;
 /** Truncate to max length, breaking at word boundary. Strips residual HTML. */
 export declare function truncateDescription(text: string | null, maxLength?: number): string;
 /** Resolve username from the provided arg or the configured default */
@@ -12,3 +16,7 @@ export declare function throwToolError(error: unknown, action: string): never;
 export declare function paginationFooter(page: number, limit: number, total: number, hasNextPage: boolean): string;
 /** Format a media entry as a compact multi-line summary */
 export declare function formatMediaSummary(media: AniListMedia): string;
+/** Detect score format from env override or API fallback */
+export declare function detectScoreFormat(fetchFormat: () => Promise<ScoreFormat>): Promise<ScoreFormat>;
+/** Display a normalized 0-10 score in the user's preferred format */
+export declare function formatScore(score10: number, format: ScoreFormat): string;

package/dist/utils.js

@@ -1,9 +1,58 @@
 /** Formatting and resolution helpers. */
 import { UserError } from "fastmcp";
-/** Best available title: English -> Romaji -> Native */
+/** Best available title, respecting ANILIST_TITLE_LANGUAGE preference */
 export function getTitle(title) {
+    const pref = process.env.ANILIST_TITLE_LANGUAGE?.toLowerCase();
+    if (pref === "romaji")
+        return title.romaji || title.english || title.native || "Unknown Title";
+    if (pref === "native")
+        return title.native || title.romaji || title.english || "Unknown Title";
+    // Default: english first
     return title.english || title.romaji || title.native || "Unknown Title";
 }
+/** Whether NSFW/adult content is enabled via env var (default: false) */
+export function isNsfwEnabled() {
+    const val = process.env.ANILIST_NSFW?.toLowerCase();
+    return val === "true" || val === "1";
+}
+// Common abbreviations to full AniList titles
+const ALIAS_MAP = {
+    aot: "Attack on Titan",
+    snk: "Shingeki no Kyojin",
+    jjk: "Jujutsu Kaisen",
+    csm: "Chainsaw Man",
+    mha: "My Hero Academia",
+    bnha: "Boku no Hero Academia",
+    hxh: "Hunter x Hunter",
+    fmab: "Fullmetal Alchemist Brotherhood",
+    fma: "Fullmetal Alchemist",
+    opm: "One Punch Man",
+    sao: "Sword Art Online",
+    re0: "Re:Zero",
+    rezero: "Re:Zero",
+    konosuba: "Kono Subarashii Sekai ni Shukufuku wo!",
+    danmachi: "Is It Wrong to Try to Pick Up Girls in a Dungeon?",
+    oregairu: "My Teen Romantic Comedy SNAFU",
+    toradora: "Toradora!",
+    nge: "Neon Genesis Evangelion",
+    eva: "Neon Genesis Evangelion",
+    ttgl: "Tengen Toppa Gurren Lagann",
+    klk: "Kill la Kill",
+    jojo: "JoJo's Bizarre Adventure",
+    dbz: "Dragon Ball Z",
+    dbs: "Dragon Ball Super",
+    op: "One Piece",
+    bc: "Black Clover",
+    ds: "Demon Slayer",
+    kny: "Demon Slayer",
+    aob: "Blue Exorcist",
+    mob: "Mob Psycho 100",
+    yyh: "Yu Yu Hakusho",
+};
+/** Resolve common abbreviations to full titles */
+export function resolveAlias(query) {
+    return ALIAS_MAP[query.toLowerCase()] ?? query;
+}
 /** Truncate to max length, breaking at word boundary. Strips residual HTML. */
 export function truncateDescription(text, maxLength = 500) {
     if (!text)
@@ -75,3 +124,41 @@ export function formatMediaSummary(media) {
     lines.push(`  URL: ${media.siteUrl}`);
     return lines.join("\n");
 }
+/** Detect score format from env override or API fallback */
+export async function detectScoreFormat(fetchFormat) {
+    const override = process.env.ANILIST_SCORE_FORMAT;
+    if (override)
+        return override;
+    try {
+        return await fetchFormat();
+    }
+    catch {
+        return "POINT_10";
+    }
+}
+/** Display a normalized 0-10 score in the user's preferred format */
+export function formatScore(score10, format) {
+    if (score10 <= 0)
+        return "Unscored";
+    switch (format) {
+        case "POINT_100":
+            return `${Math.round(score10 * 10)}/100`;
+        case "POINT_10_DECIMAL":
+            return `${score10.toFixed(1)}/10`;
+        case "POINT_10":
+            return `${Math.round(score10)}/10`;
+        case "POINT_5": {
+            const stars = Math.round(score10 / 2);
+            return "★".repeat(stars) + "☆".repeat(5 - stars);
+        }
+        case "POINT_3": {
+            if (score10 >= 7)
+                return "🙂";
+            if (score10 >= 4)
+                return "😐";
+            return "🙁";
+        }
+        default:
+            return `${score10}/10`;
+    }
+}

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.3",
   "name": "ani-mcp",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "display_name": "AniList MCP",
   "description": "A smart MCP server for AniList that gets your anime/manga taste - not just API calls.",
   "author": {
@@ -105,6 +105,12 @@
     {
       "name": "anilist_characters"
     },
+    {
+      "name": "anilist_whoami"
+    },
+    {
+      "name": "anilist_genre_list"
+    },
     {
       "name": "anilist_update_progress"
     },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ani-mcp",
   "mcpName": "io.github.gavxm/ani-mcp",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "A smart [MCP](https://modelcontextprotocol.io) server for [AniList](https://anilist.co) that gets your anime/manga taste - not just API calls.",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "pack": "npx @anthropic-ai/mcpb pack",
-    "release": "git tag v$(node -p \"require('./package.json').version\") && git push origin v$(node -p \"require('./package.json').version\")"
+    "release": "./scripts/release.sh"
   },
   "keywords": [
     "mcp",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/gavxm/ani-mcp",
     "source": "github"
   },
-  "version": "0.2.4",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ani-mcp",
-      "version": "0.2.4",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       },