ani-mcp 0.8.0 → 0.8.2

package/dist/api/client.d.ts

@@ -12,6 +12,8 @@ export declare const CACHE_TTLS: {
     readonly list: number;
     readonly seasonal: number;
     readonly stats: number;
+    readonly trending: number;
+    readonly schedule: number;
 };
 export type CacheCategory = keyof typeof CACHE_TTLS;
 /** API error with HTTP status and retry eligibility */
@@ -37,6 +39,8 @@ declare class AniListClient {
     fetchList(username: string, type: string, status?: string, sort?: string[]): Promise<AniListMediaListEntry[]>;
     /** Invalidate the entire query cache */
     clearCache(): void;
+    /** Evict cache entries related to a specific user (lists and stats) */
+    invalidateUser(username: string): void;
     /** Retries with exponential backoff via p-retry */
     private executeWithRetry;
     /** Send a single GraphQL POST request and parse the response */

package/dist/api/client.js

@@ -34,6 +34,8 @@ export const CACHE_TTLS = {
     list: 5 * 60 * 1000, // 5m
     seasonal: 30 * 60 * 1000, // 30m
     stats: 10 * 60 * 1000, // 10m
+    trending: 30 * 60 * 1000, // 30m
+    schedule: 30 * 60 * 1000, // 30m
 };
 // 85 req/60s, excess calls queue automatically
 const rateLimit = pThrottle({
@@ -46,6 +48,14 @@ const queryCache = new LRUCache({
     max: 500,
     allowStale: false,
 });
+/** Stable JSON serialization with sorted keys */
+function stableStringify(obj) {
+    const keys = Object.keys(obj).sort();
+    const sorted = {};
+    for (const k of keys)
+        sorted[k] = obj[k];
+    return JSON.stringify(sorted);
+}
 // === Error Types ===
 /** API error with HTTP status and retry eligibility */
 export class AniListApiError extends Error {
@@ -71,7 +81,7 @@ class AniListClient {
         const name = queryName(query);
         // Cache-through: return cached result or fetch, store, and return
         if (cacheCategory) {
-            const cacheKey = `${query}::${JSON.stringify(variables)}`;
+            const cacheKey = `${query}::${stableStringify(variables)}`;
             const cached = queryCache.get(cacheKey);
             if (cached !== undefined) {
                 log("cache-hit", name);
@@ -111,6 +121,17 @@ class AniListClient {
     clearCache() {
         queryCache.clear();
     }
+    /** Evict cache entries related to a specific user (lists and stats) */
+    invalidateUser(username) {
+        const needle = `"${username}"`;
+        for (const key of queryCache.keys()) {
+            // Variable portion is after "::"
+            const varPart = key.slice(key.indexOf("::") + 2);
+            if (varPart.includes(needle)) {
+                queryCache.delete(key);
+            }
+        }
+    }
     /** Retries with exponential backoff via p-retry */
     async executeWithRetry(query, variables) {
         const name = queryName(query);

package/dist/engine/compare.js

@@ -35,18 +35,21 @@ export function computeGenreDivergences(p1, p2, name1 = "User 1", name2 = "User
     const genres2 = new Map(p2.genres.map((g) => [g.name, g]));
     const allGenres = new Set([...genres1.keys(), ...genres2.keys()]);
     const divergences = [];
+    // Pre-compute rank maps for O(1) lookup
+    const rankOf1 = new Map([...genres1.keys()].map((g, i) => [g, i]));
+    const rankOf2 = new Map([...genres2.keys()].map((g, i) => [g, i]));
     // Flag genres in one user's top 5 but not the other's top 10
     for (const genre of allGenres) {
-        const rank1 = [...genres1.keys()].indexOf(genre);
-        const rank2 = [...genres2.keys()].indexOf(genre);
-        if (rank1 >= 0 && rank1 < 5 && (rank2 < 0 || rank2 > 10)) {
+        const rank1 = rankOf1.get(genre) ?? -1;
+        const rank2 = rankOf2.get(genre) ?? -1;
+        if (rank1 >= 0 && rank1 < 5 && (rank2 === -1 || rank2 > 10)) {
             divergences.push({
                 genre,
                 diff: 10,
                 desc: `${name1} loves ${genre}, ${name2} doesn't`,
             });
         }
-        else if (rank2 >= 0 && rank2 < 5 && (rank1 < 0 || rank1 > 10)) {
+        else if (rank2 >= 0 && rank2 < 5 && (rank1 === -1 || rank1 > 10)) {
             divergences.push({
                 genre,
                 diff: 10,

package/dist/index.js

@@ -21,7 +21,7 @@ if (!process.env.ANILIST_TOKEN) {
 }
 const server = new FastMCP({
     name: "ani-mcp",
-    version: "0.8.0",
+    version: "0.8.2",
 });
 registerSearchTools(server);
 registerListTools(server);

package/dist/resources.js

@@ -1,10 +1,10 @@
 /** MCP Resources: expose user context without tool calls */
 import { anilistClient } from "./api/client.js";
-import { USER_PROFILE_QUERY, USER_STATS_QUERY } from "./api/queries.js";
+import { USER_PROFILE_QUERY } from "./api/queries.js";
 import { buildTasteProfile, describeTasteProfile, } from "./engine/taste.js";
 import { formatProfile } from "./tools/social.js";
 import { formatListEntry } from "./tools/lists.js";
-import { getDefaultUsername, detectScoreFormat } from "./utils.js";
+import { getDefaultUsername, getScoreFormat } from "./utils.js";
 /** Register MCP resources on the server */
 export function registerResources(server) {
     // === User Profile ===
@@ -73,10 +73,7 @@ export function registerResources(server) {
                 const mediaType = String(type).toUpperCase();
                 const [entries, scoreFormat] = await Promise.all([
                     anilistClient.fetchList(username, mediaType, "CURRENT"),
-                    detectScoreFormat(async () => {
-                        const data = await anilistClient.query(USER_STATS_QUERY, { name: username }, { cache: "stats" });
-                        return data.User.mediaListOptions.scoreFormat;
-                    }),
+                    getScoreFormat(username),
                 ]);
                 if (!entries.length) {
                     return {

package/dist/schemas.d.ts

@@ -278,11 +278,13 @@ export declare const RateInputSchema: z.ZodObject<{
 export type RateInput = z.infer<typeof RateInputSchema>;
 /** Input for removing a title from the list */
 export declare const DeleteFromListInputSchema: z.ZodObject<{
-    entryId: z.ZodNumber;
+    entryId: z.ZodOptional<z.ZodNumber>;
+    mediaId: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 /** Input for scoring a title against a user's taste profile */
 export declare const ExplainInputSchema: z.ZodObject<{
-    mediaId: z.ZodNumber;
+    mediaId: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodOptional<z.ZodString>;
     username: z.ZodOptional<z.ZodString>;
     type: z.ZodDefault<z.ZodEnum<{
         ANIME: "ANIME";
@@ -294,7 +296,8 @@ export declare const ExplainInputSchema: z.ZodObject<{
 export type ExplainInput = z.infer<typeof ExplainInputSchema>;
 /** Input for finding titles similar to a specific anime or manga */
 export declare const SimilarInputSchema: z.ZodObject<{
-    mediaId: z.ZodNumber;
+    mediaId: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type SimilarInput = z.infer<typeof SimilarInputSchema>;

package/dist/schemas.js

@@ -7,12 +7,12 @@ const pageParam = z
     .min(1)
     .default(1)
     .describe("Page number for pagination (default 1)");
-// AniList usernames: 2-20 chars, alphanumeric + underscores
+// AniList usernames: 2-20 chars, alphanumeric + underscores + hyphens
 const usernameSchema = z
     .string()
     .min(2)
     .max(20)
-    .regex(/^[a-zA-Z0-9_]+$/, "Letters, numbers, and underscores only");
+    .regex(/^[a-zA-Z0-9_-]+$/, "Letters, numbers, underscores, and hyphens only");
 /** Input for searching anime or manga by title and filters */
 export const SearchInputSchema = z.object({
     query: z
@@ -471,21 +471,37 @@ export const RateInputSchema = z.object({
         .describe("Score on a 0-10 scale. Use 0 to remove a score."),
 });
 /** Input for removing a title from the list */
-export const DeleteFromListInputSchema = z.object({
+export const DeleteFromListInputSchema = z
+    .object({
     entryId: z
         .number()
         .int()
         .positive()
-        .describe("List entry ID to delete. This is the id field on a list entry, not the media ID. " +
-        "Use anilist_list to find entry IDs."),
+        .optional()
+        .describe("List entry ID to delete (from anilist_list)"),
+    mediaId: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("AniList media ID to remove from your list"),
+})
+    .refine((data) => data.entryId !== undefined || data.mediaId !== undefined, {
+    message: "Provide either an entryId or a mediaId.",
 });
 /** Input for scoring a title against a user's taste profile */
-export const ExplainInputSchema = z.object({
+export const ExplainInputSchema = z
+    .object({
     mediaId: z
         .number()
         .int()
         .positive()
+        .optional()
         .describe("AniList media ID to evaluate against your taste profile"),
+    title: z
+        .string()
+        .optional()
+        .describe("Search by title if no ID is known"),
     username: usernameSchema
         .optional()
         .describe("AniList username. Falls back to configured default if not provided."),
@@ -497,14 +513,23 @@ export const ExplainInputSchema = z.object({
         .string()
         .optional()
         .describe('Optional mood context, e.g. "dark and brainy"'),
+})
+    .refine((data) => data.mediaId !== undefined || data.title !== undefined, {
+    message: "Provide either a mediaId or a title.",
 });
 /** Input for finding titles similar to a specific anime or manga */
-export const SimilarInputSchema = z.object({
+export const SimilarInputSchema = z
+    .object({
     mediaId: z
         .number()
         .int()
         .positive()
+        .optional()
         .describe("AniList media ID to find similar titles for"),
+    title: z
+        .string()
+        .optional()
+        .describe("Search by title if no ID is known"),
     limit: z
         .number()
         .int()
@@ -512,6 +537,9 @@ export const SimilarInputSchema = z.object({
         .max(25)
         .default(10)
         .describe("Number of similar titles to return (default 10, max 25)"),
+})
+    .refine((data) => data.mediaId !== undefined || data.title !== undefined, {
+    message: "Provide either a mediaId or a title.",
 });
 /** Input for searching staff/people by name */
 export const StaffSearchInputSchema = z.object({

package/dist/tools/discover.js

@@ -2,7 +2,7 @@
 import { anilistClient } from "../api/client.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";
+import { formatMediaSummary, throwToolError, paginationFooter, BROWSE_SORT_MAP, } from "../utils.js";
 /** Register discovery tools on the MCP server */
 export function registerDiscoverTools(server) {
     // === Trending ===
@@ -25,7 +25,7 @@ export function registerDiscoverTools(server) {
                     isAdult: args.isAdult ? undefined : false,
                     page: args.page,
                     perPage: args.limit,
-                }, { cache: "search" });
+                }, { cache: "trending" });
                 const results = data.Page.media;
                 if (!results.length) {
                     return `No trending ${args.type.toLowerCase()} found.`;
@@ -61,15 +61,10 @@ export function registerDiscoverTools(server) {
         },
         execute: async (args) => {
             try {
-                const sortMap = {
-                    SCORE: ["SCORE_DESC"],
-                    POPULARITY: ["POPULARITY_DESC"],
-                    TRENDING: ["TRENDING_DESC"],
-                };
                 const variables = {
                     type: args.type,
                     genre_in: [args.genre],
-                    sort: sortMap[args.sort] ?? sortMap.SCORE,
+                    sort: BROWSE_SORT_MAP[args.sort] ?? BROWSE_SORT_MAP.SCORE,
                     isAdult: args.isAdult ? undefined : false,
                     page: args.page,
                     perPage: args.limit,

package/dist/tools/info.js

@@ -154,7 +154,7 @@ export function registerInfoTools(server) {
                     variables.id = args.id;
                 if (args.title)
                     variables.search = args.title;
-                const data = await anilistClient.query(AIRING_SCHEDULE_QUERY, variables, { cache: "search" });
+                const data = await anilistClient.query(AIRING_SCHEDULE_QUERY, variables, { cache: "schedule" });
                 const m = data.Media;
                 const lines = [
                     `# Schedule: ${getTitle(m.title)}`,

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, formatScore, detectScoreFormat, } from "../utils.js";
+import { getTitle, getDefaultUsername, throwToolError, paginationFooter, formatScore, getScoreFormat, } from "../utils.js";
 // Map user-friendly sort names to AniList's internal enum values
 const SORT_MAP = {
     SCORE: ["SCORE_DESC"],
@@ -38,10 +38,7 @@ export function registerListTools(server) {
                 const status = args.status !== "ALL" ? args.status : undefined;
                 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;
-                    }),
+                    getScoreFormat(username),
                 ]);
                 if (!allEntries.length) {
                     if (args.status === "ALL") {
@@ -141,11 +138,7 @@ async function handleCustomLists(username, args, sort) {
         return `${username}'s ${listLabel} have no entries.`;
     }
     sortEntries(allEntries, args.sort);
-    // Detect score format
-    const scoreFormat = await detectScoreFormat(async () => {
-        const data = await anilistClient.query(USER_STATS_QUERY, { name: username }, { cache: "stats" });
-        return data.User.mediaListOptions.scoreFormat;
-    });
+    const scoreFormat = await getScoreFormat(username);
     const totalCount = allEntries.length;
     const offset = (args.page - 1) * args.limit;
     const limited = allEntries.slice(offset, offset + args.limit);

package/dist/tools/recommend.js

@@ -2,7 +2,8 @@
 import { anilistClient } from "../api/client.js";
 import { BATCH_RELATIONS_QUERY, DISCOVER_MEDIA_QUERY, MEDIA_DETAILS_QUERY, RECOMMENDATIONS_QUERY, SEASONAL_MEDIA_QUERY, } from "../api/queries.js";
 import { TasteInputSchema, PickInputSchema, SessionInputSchema, SequelAlertInputSchema, WatchOrderInputSchema, CompareInputSchema, WrappedInputSchema, ExplainInputSchema, SimilarInputSchema, } from "../schemas.js";
-import { getTitle, getDefaultUsername, throwToolError, isNsfwEnabled, resolveSeasonYear, } from "../utils.js";
+import { getTitle, getDefaultUsername, throwToolError, isNsfwEnabled, resolveSeasonYear, resolveAlias, } from "../utils.js";
+import { SEARCH_MEDIA_QUERY } from "../api/queries.js";
 import { buildTasteProfile, describeTasteProfile, } from "../engine/taste.js";
 import { matchCandidates, explainMatch } from "../engine/matcher.js";
 import { parseMood, hasMoodMatch, seasonalMoodSuggestions, } from "../engine/mood.js";
@@ -146,15 +147,19 @@ export function registerRecommendTools(server) {
                     const { season, year } = resolveSeasonYear(args.season, args.year);
                     sourceLabel = `${season} ${year} seasonal anime`;
                     candidatePromise = (async () => {
-                        const data = await anilistClient.query(SEASONAL_MEDIA_QUERY, {
+                        const vars = {
                             season,
                             seasonYear: year,
                             type: "ANIME",
                             sort: ["POPULARITY_DESC"],
                             perPage: 50,
-                            page: 1,
-                        }, { cache: "seasonal" });
-                        return data.Page.media;
+                        };
+                        // Fetch pages 1 and 2 in parallel to cover 100 titles
+                        const [p1, p2] = await Promise.all([
+                            anilistClient.query(SEASONAL_MEDIA_QUERY, { ...vars, page: 1 }, { cache: "seasonal" }),
+                            anilistClient.query(SEASONAL_MEDIA_QUERY, { ...vars, page: 2 }, { cache: "seasonal" }),
+                        ]);
+                        return [...p1.Page.media, ...p2.Page.media];
                     })();
                 }
                 else if (source === "DISCOVER") {
@@ -783,11 +788,19 @@ export function registerRecommendTools(server) {
         execute: async (args) => {
             try {
                 const username = getDefaultUsername(args.username);
+                // Resolve title to media ID if needed
+                let mediaId = args.mediaId;
+                if (!mediaId && args.title) {
+                    const search = resolveAlias(args.title);
+                    const searchData = await anilistClient.query(SEARCH_MEDIA_QUERY, { search, type: "ANIME", page: 1, perPage: 1 }, { cache: "search" });
+                    if (!searchData.Page.media.length) {
+                        return `No results found for "${args.title}".`;
+                    }
+                    mediaId = searchData.Page.media[0].id;
+                }
                 // Fetch media details and taste profile in parallel
                 const [mediaData, { profile, entries }] = await Promise.all([
-                    anilistClient.query(MEDIA_DETAILS_QUERY, {
-                        id: args.mediaId,
-                    }, { cache: "media" }),
+                    anilistClient.query(MEDIA_DETAILS_QUERY, { id: mediaId }, { cache: "media" }),
                     profileForUser(username, args.type),
                 ]);
                 const media = mediaData.Media;
@@ -874,15 +887,20 @@ export function registerRecommendTools(server) {
         },
         execute: async (args) => {
             try {
+                // Resolve title to media ID if needed
+                let mediaId = args.mediaId;
+                if (!mediaId && args.title) {
+                    const search = resolveAlias(args.title);
+                    const searchData = await anilistClient.query(SEARCH_MEDIA_QUERY, { search, type: "ANIME", page: 1, perPage: 1 }, { cache: "search" });
+                    if (!searchData.Page.media.length) {
+                        return `No results found for "${args.title}".`;
+                    }
+                    mediaId = searchData.Page.media[0].id;
+                }
                 // Fetch source details and recommendations in parallel
                 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" }),
+                    anilistClient.query(MEDIA_DETAILS_QUERY, { id: mediaId }, { cache: "media" }),
+                    anilistClient.query(RECOMMENDATIONS_QUERY, { id: mediaId, perPage: 25 }, { cache: "media" }),
                 ]);
                 const source = detailsData.Media;
                 const sourceTitle = getTitle(source.title);

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, isNsfwEnabled, resolveAlias, resolveSeasonYear, } from "../utils.js";
+import { getTitle, truncateDescription, throwToolError, formatMediaSummary, paginationFooter, isNsfwEnabled, resolveAlias, resolveSeasonYear, BROWSE_SORT_MAP, } from "../utils.js";
 // Default to popularity for broad queries
 const SEARCH_SORT = ["POPULARITY_DESC"];
 // === Tool Registration ===
@@ -171,17 +171,12 @@ export function registerSearchTools(server) {
         execute: async (args) => {
             try {
                 const { season, year } = resolveSeasonYear(args.season, args.year);
-                const sortMap = {
-                    POPULARITY: ["POPULARITY_DESC"],
-                    SCORE: ["SCORE_DESC"],
-                    TRENDING: ["TRENDING_DESC"],
-                };
                 const data = await anilistClient.query(SEASONAL_MEDIA_QUERY, {
                     season,
                     seasonYear: year,
                     type: "ANIME",
                     isAdult: args.isAdult ? undefined : false,
-                    sort: sortMap[args.sort] ?? sortMap.POPULARITY,
+                    sort: BROWSE_SORT_MAP[args.sort] ?? BROWSE_SORT_MAP.POPULARITY,
                     page: args.page,
                     perPage: args.limit,
                 }, { cache: "seasonal" });

package/dist/tools/write.js

@@ -4,7 +4,7 @@ import { SAVE_MEDIA_LIST_ENTRY_MUTATION, DELETE_MEDIA_LIST_ENTRY_MUTATION, TOGGL
 import { pushUndo, popUndo } from "../engine/undo.js";
 import { invalidateUserProfiles } from "../engine/profile-cache.js";
 import { UpdateProgressInputSchema, AddToListInputSchema, RateInputSchema, DeleteFromListInputSchema, FavouriteInputSchema, PostActivityInputSchema, UndoInputSchema, UnscoredInputSchema, BatchUpdateInputSchema, } from "../schemas.js";
-import { throwToolError, formatScore, detectScoreFormat, getTitle, getDefaultUsername, } from "../utils.js";
+import { throwToolError, formatScore, getScoreFormat, getTitle, getDefaultUsername, } from "../utils.js";
 // === Auth Guard ===
 /** Guard against unauthenticated write attempts */
 function requireAuth() {
@@ -69,8 +69,9 @@ export function registerWriteTools(server) {
                     status: args.status ?? "CURRENT",
                 };
                 const data = await anilistClient.query(SAVE_MEDIA_LIST_ENTRY_MUTATION, variables, { cache: null });
-                anilistClient.clearCache();
-                invalidateUserProfiles(await getViewerName());
+                const viewerName = await getViewerName();
+                anilistClient.invalidateUser(viewerName);
+                invalidateUserProfiles(viewerName);
                 const entry = data.SaveMediaListEntry;
                 // Track for undo
                 pushUndo({
@@ -122,13 +123,11 @@ export function registerWriteTools(server) {
                     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;
-                    }),
+                    getScoreFormat(),
                 ]);
-                anilistClient.clearCache();
-                invalidateUserProfiles(await getViewerName());
+                const viewerName = await getViewerName();
+                anilistClient.invalidateUser(viewerName);
+                invalidateUserProfiles(viewerName);
                 const entry = data.SaveMediaListEntry;
                 // Track for undo
                 pushUndo({
@@ -175,13 +174,11 @@ export function registerWriteTools(server) {
                 const before = await snapshotByMediaId(args.mediaId);
                 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;
-                    }),
+                    getScoreFormat(),
                 ]);
-                anilistClient.clearCache();
-                invalidateUserProfiles(await getViewerName());
+                const viewerName = await getViewerName();
+                anilistClient.invalidateUser(viewerName);
+                invalidateUserProfiles(viewerName);
                 const entry = data.SaveMediaListEntry;
                 // Track for undo
                 if (before) {
@@ -209,7 +206,7 @@ export function registerWriteTools(server) {
     server.addTool({
         name: "anilist_delete_from_list",
         description: "Remove an entry from your anime or manga list. " +
-            "Requires the list entry ID (not the media ID) - use anilist_list to find it. " +
+            "Pass either a list entry ID or a media ID. " +
             "Requires ANILIST_TOKEN.",
         parameters: DeleteFromListInputSchema,
         annotations: {
@@ -222,13 +219,26 @@ export function registerWriteTools(server) {
         execute: async (args) => {
             try {
                 requireAuth();
+                // Resolve mediaId to entryId if needed
+                let entryId = args.entryId;
+                if (!entryId && args.mediaId) {
+                    const snapshot = await snapshotByMediaId(args.mediaId);
+                    if (!snapshot) {
+                        return `Media ${args.mediaId} is not on your list.`;
+                    }
+                    entryId = snapshot.id;
+                }
+                if (!entryId) {
+                    return "Provide either an entryId or a mediaId.";
+                }
                 // Snapshot before deletion
-                const before = await snapshotByEntryId(args.entryId);
-                const data = await anilistClient.query(DELETE_MEDIA_LIST_ENTRY_MUTATION, { id: args.entryId }, { cache: null });
-                anilistClient.clearCache();
-                invalidateUserProfiles(await getViewerName());
+                const before = await snapshotByEntryId(entryId);
+                const data = await anilistClient.query(DELETE_MEDIA_LIST_ENTRY_MUTATION, { id: entryId }, { cache: null });
+                const viewerName = await getViewerName();
+                anilistClient.invalidateUser(viewerName);
+                invalidateUserProfiles(viewerName);
                 if (!data.DeleteMediaListEntry.deleted) {
-                    return `Entry ${args.entryId} was not found or already removed.`;
+                    return `Entry ${entryId} was not found or already removed.`;
                 }
                 // Track for undo
                 if (before) {
@@ -236,13 +246,13 @@ export function registerWriteTools(server) {
                         operation: { type: "delete", before },
                         toolName: "anilist_delete_from_list",
                         timestamp: Date.now(),
-                        description: `Deleted entry ${args.entryId} (media ${before.mediaId})`,
+                        description: `Deleted entry ${entryId} (media ${before.mediaId})`,
                     });
                 }
                 const hint = before
                     ? `\n(Deleted ${before.status} entry - say "undo" to restore)`
                     : "";
-                return `Entry ${args.entryId} deleted from your list.${hint}`;
+                return `Entry ${entryId} deleted from your list.${hint}`;
             }
             catch (error) {
                 return throwToolError(error, "deleting from list");
@@ -278,15 +288,17 @@ export function registerWriteTools(server) {
                         scoreRaw: op.before.score * 10,
                         progress: op.before.progress,
                     }, { cache: null });
-                    anilistClient.clearCache();
-                    invalidateUserProfiles(await getViewerName());
+                    const viewerName = await getViewerName();
+                    anilistClient.invalidateUser(viewerName);
+                    invalidateUserProfiles(viewerName);
                     return `Undone: restored media ${op.before.mediaId} to ${op.before.status}, progress ${op.before.progress}, score ${op.before.score}.`;
                 }
                 if (op.type === "create") {
                     // Delete the newly created entry
                     await anilistClient.query(DELETE_MEDIA_LIST_ENTRY_MUTATION, { id: op.entryId }, { cache: null });
-                    anilistClient.clearCache();
-                    invalidateUserProfiles(await getViewerName());
+                    const viewerName = await getViewerName();
+                    anilistClient.invalidateUser(viewerName);
+                    invalidateUserProfiles(viewerName);
                     return `Undone: removed media ${op.mediaId} from your list.`;
                 }
                 if (op.type === "delete") {
@@ -297,8 +309,9 @@ export function registerWriteTools(server) {
                         scoreRaw: op.before.score * 10,
                         progress: op.before.progress,
                     }, { cache: null });
-                    anilistClient.clearCache();
-                    invalidateUserProfiles(await getViewerName());
+                    const viewerName = await getViewerName();
+                    anilistClient.invalidateUser(viewerName);
+                    invalidateUserProfiles(viewerName);
                     return `Undone: restored media ${op.before.mediaId} to ${op.before.status}, progress ${op.before.progress}.`;
                 }
                 if (op.type === "batch") {
@@ -318,8 +331,9 @@ export function registerWriteTools(server) {
                             // Continue on individual failures
                         }
                     }
-                    anilistClient.clearCache();
-                    invalidateUserProfiles(await getViewerName());
+                    const viewerName = await getViewerName();
+                    anilistClient.invalidateUser(viewerName);
+                    invalidateUserProfiles(viewerName);
                     return `Undone: restored ${restored}/${op.entries.length} entries to their previous state.`;
                 }
                 return "Unknown undo operation type.";
@@ -364,7 +378,7 @@ export function registerWriteTools(server) {
                 requireAuth();
                 const variables = { [FAVOURITE_VAR_MAP[args.type]]: args.id };
                 const data = await anilistClient.query(TOGGLE_FAVOURITE_MUTATION, variables, { cache: null });
-                anilistClient.clearCache();
+                anilistClient.invalidateUser(await getViewerName());
                 // Check if entity is now in favourites (added) or absent (removed)
                 const field = FAVOURITE_FIELD_MAP[args.type];
                 const isFavourited = data.ToggleFavourite[field].nodes.some((n) => n.id === args.id);
@@ -396,7 +410,7 @@ export function registerWriteTools(server) {
             try {
                 requireAuth();
                 const data = await anilistClient.query(SAVE_TEXT_ACTIVITY_MUTATION, { text: args.text }, { cache: null });
-                anilistClient.clearCache();
+                anilistClient.invalidateUser(await getViewerName());
                 const activity = data.SaveTextActivity;
                 const dateStr = new Date(activity.createdAt * 1000).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
                 return [
@@ -562,8 +576,9 @@ export function registerWriteTools(server) {
                         failures++;
                     }
                 }
-                anilistClient.clearCache();
-                invalidateUserProfiles(await getViewerName());
+                const viewerName = await getViewerName();
+                anilistClient.invalidateUser(viewerName);
+                invalidateUserProfiles(viewerName);
                 // Track batch for undo
                 if (snapshots.length > 0) {
                     pushUndo({

package/dist/utils.d.ts

@@ -18,6 +18,10 @@ export declare function paginationFooter(page: number, limit: number, total: num
 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>;
+/** Fetch score format for a user (by username) or the authenticated viewer */
+export declare function getScoreFormat(username?: string): Promise<ScoreFormat>;
+/** Sort direction map for browse/seasonal tools */
+export declare const BROWSE_SORT_MAP: Record<string, string[]>;
 /** Resolve season and year, defaulting to current if not provided */
 export declare function resolveSeasonYear(season?: string, year?: number): {
     season: string;

package/dist/utils.js

@@ -1,5 +1,7 @@
 /** Formatting and resolution helpers. */
 import { UserError } from "fastmcp";
+import { anilistClient } from "./api/client.js";
+import { USER_STATS_QUERY, VIEWER_QUERY } from "./api/queries.js";
 /** Best available title, respecting ANILIST_TITLE_LANGUAGE preference */
 export function getTitle(title) {
     const pref = process.env.ANILIST_TITLE_LANGUAGE?.toLowerCase();
@@ -136,6 +138,23 @@ export async function detectScoreFormat(fetchFormat) {
         return "POINT_10";
     }
 }
+/** Fetch score format for a user (by username) or the authenticated viewer */
+export async function getScoreFormat(username) {
+    return detectScoreFormat(async () => {
+        if (username) {
+            const data = await anilistClient.query(USER_STATS_QUERY, { name: username }, { cache: "stats" });
+            return data.User.mediaListOptions.scoreFormat;
+        }
+        const data = await anilistClient.query(VIEWER_QUERY, {}, { cache: "stats" });
+        return data.Viewer.mediaListOptions.scoreFormat;
+    });
+}
+/** Sort direction map for browse/seasonal tools */
+export const BROWSE_SORT_MAP = {
+    SCORE: ["SCORE_DESC"],
+    POPULARITY: ["POPULARITY_DESC"],
+    TRENDING: ["TRENDING_DESC"],
+};
 /** Resolve season and year, defaulting to current if not provided */
 export function resolveSeasonYear(season, year) {
     const now = new Date();

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.3",
   "name": "ani-mcp",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "display_name": "AniList MCP",
   "description": "A smart MCP server for AniList that gets your anime/manga taste - not just API calls.",
   "author": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ani-mcp",
   "mcpName": "io.github.gavxm/ani-mcp",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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",

package/server.json

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