ani-mcp 0.6.2 → 0.7.0

package/dist/engine/analytics.d.ts

@@ -0,0 +1,46 @@
+/** Analytics engine: scoring calibration, drop patterns, and genre evolution. */
+import type { AniListMediaListEntry } from "../types.js";
+export interface GenreCalibration {
+    genre: string;
+    userMean: number;
+    communityMean: number;
+    delta: number;
+    count: number;
+}
+export interface CalibrationResult {
+    overallDelta: number;
+    tendency: "generous" | "harsh" | "average";
+    genreCalibrations: GenreCalibration[];
+    totalScored: number;
+}
+export interface DropCluster {
+    label: string;
+    type: "genre" | "tag";
+    dropCount: number;
+    totalCount: number;
+    dropRate: number;
+    medianDropPoint: number;
+}
+export interface DropAnalysis {
+    totalDropped: number;
+    clusters: DropCluster[];
+    earlyDrops: number;
+    avgDropProgress: number;
+}
+export interface GenreEra {
+    period: string;
+    startYear: number;
+    endYear: number;
+    topGenres: string[];
+    count: number;
+}
+export interface EvolutionResult {
+    eras: GenreEra[];
+    shifts: string[];
+}
+/** Per-genre scoring bias relative to community consensus */
+export declare function computeCalibration(entries: AniListMediaListEntry[]): CalibrationResult;
+/** Genre and tag clusters in a user's dropped titles */
+export declare function analyzeDrops(droppedEntries: AniListMediaListEntry[], allEntries: AniListMediaListEntry[]): DropAnalysis;
+/** How genre preferences shifted across time windows */
+export declare function computeGenreEvolution(entries: AniListMediaListEntry[], windowYears?: number): EvolutionResult;

package/dist/engine/analytics.js

@@ -0,0 +1,264 @@
+/** Analytics engine: scoring calibration, drop patterns, and genre evolution. */
+// === Constants ===
+// Min entries per genre for meaningful calibration
+const MIN_GENRE_ENTRIES = 3;
+// Min drops in a cluster to report
+const MIN_CLUSTER_DROPS = 3;
+// Max tag clusters to report
+const MAX_TAG_CLUSTERS = 10;
+// === Score Calibration ===
+/** Per-genre scoring bias relative to community consensus */
+export function computeCalibration(entries) {
+    // Filter to scored entries with community scores
+    const scored = entries.filter((e) => e.score > 0 && e.media.meanScore != null && e.media.meanScore > 0);
+    if (scored.length === 0) {
+        return {
+            overallDelta: 0,
+            tendency: "average",
+            genreCalibrations: [],
+            totalScored: 0,
+        };
+    }
+    // Overall delta: user mean - community mean (on 1-10 scale)
+    let userSum = 0;
+    let communitySum = 0;
+    for (const e of scored) {
+        userSum += e.score;
+        communitySum += (e.media.meanScore ?? 0) / 10;
+    }
+    const overallDelta = userSum / scored.length - communitySum / scored.length;
+    // Per-genre calibration
+    const genreMap = new Map();
+    for (const e of scored) {
+        const community = (e.media.meanScore ?? 0) / 10;
+        for (const genre of e.media.genres) {
+            let bucket = genreMap.get(genre);
+            if (!bucket) {
+                bucket = { userScores: [], communityScores: [] };
+                genreMap.set(genre, bucket);
+            }
+            bucket.userScores.push(e.score);
+            bucket.communityScores.push(community);
+        }
+    }
+    const genreCalibrations = [];
+    for (const [genre, bucket] of genreMap) {
+        if (bucket.userScores.length < MIN_GENRE_ENTRIES)
+            continue;
+        const userMean = mean(bucket.userScores);
+        const communityMean = mean(bucket.communityScores);
+        genreCalibrations.push({
+            genre,
+            userMean,
+            communityMean,
+            delta: userMean - communityMean,
+            count: bucket.userScores.length,
+        });
+    }
+    // Sort by absolute delta descending
+    genreCalibrations.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+    const tendency = overallDelta >= 0.5
+        ? "generous"
+        : overallDelta <= -0.5
+            ? "harsh"
+            : "average";
+    return {
+        overallDelta,
+        tendency,
+        genreCalibrations,
+        totalScored: scored.length,
+    };
+}
+// === Drop Pattern Analysis ===
+/** Genre and tag clusters in a user's dropped titles */
+export function analyzeDrops(droppedEntries, allEntries) {
+    if (droppedEntries.length === 0) {
+        return { totalDropped: 0, clusters: [], earlyDrops: 0, avgDropProgress: 0 };
+    }
+    // Count total entries per genre/tag across all statuses
+    const genreTotals = new Map();
+    const tagTotals = new Map();
+    for (const e of allEntries) {
+        for (const g of e.media.genres) {
+            genreTotals.set(g, (genreTotals.get(g) ?? 0) + 1);
+        }
+        for (const t of e.media.tags) {
+            if (!t.isMediaSpoiler) {
+                tagTotals.set(t.name, (tagTotals.get(t.name) ?? 0) + 1);
+            }
+        }
+    }
+    // Genre drop counts and progress at drop
+    const genreDrops = new Map();
+    const tagDrops = new Map();
+    let earlyDrops = 0;
+    let totalProgress = 0;
+    let progressCount = 0;
+    for (const e of droppedEntries) {
+        const total = e.media.episodes ?? e.media.chapters ?? 0;
+        const progressPct = total > 0 ? e.progress / total : 0;
+        if (total > 0 && progressPct < 0.25)
+            earlyDrops++;
+        if (total > 0) {
+            totalProgress += progressPct;
+            progressCount++;
+        }
+        for (const g of e.media.genres) {
+            let arr = genreDrops.get(g);
+            if (!arr) {
+                arr = [];
+                genreDrops.set(g, arr);
+            }
+            if (total > 0)
+                arr.push(progressPct);
+            else
+                arr.push(-1); // unknown progress
+        }
+        for (const t of e.media.tags) {
+            if (t.isMediaSpoiler)
+                continue;
+            let arr = tagDrops.get(t.name);
+            if (!arr) {
+                arr = [];
+                tagDrops.set(t.name, arr);
+            }
+            if (total > 0)
+                arr.push(progressPct);
+            else
+                arr.push(-1);
+        }
+    }
+    const clusters = [];
+    // Genre clusters
+    for (const [genre, progresses] of genreDrops) {
+        if (progresses.length < MIN_CLUSTER_DROPS)
+            continue;
+        const total = genreTotals.get(genre) ?? progresses.length;
+        const known = progresses.filter((p) => p >= 0);
+        clusters.push({
+            label: genre,
+            type: "genre",
+            dropCount: progresses.length,
+            totalCount: total,
+            dropRate: progresses.length / total,
+            medianDropPoint: known.length > 0 ? median(known) : 0,
+        });
+    }
+    // Tag clusters
+    for (const [tag, progresses] of tagDrops) {
+        if (progresses.length < MIN_CLUSTER_DROPS)
+            continue;
+        const total = tagTotals.get(tag) ?? progresses.length;
+        const known = progresses.filter((p) => p >= 0);
+        clusters.push({
+            label: tag,
+            type: "tag",
+            dropCount: progresses.length,
+            totalCount: total,
+            dropRate: progresses.length / total,
+            medianDropPoint: known.length > 0 ? median(known) : 0,
+        });
+    }
+    // Sort by drop rate descending, cap tag clusters
+    clusters.sort((a, b) => b.dropRate - a.dropRate);
+    // Keep all genre clusters, cap tags
+    const genreClusters = clusters.filter((c) => c.type === "genre");
+    const tagClusters = clusters
+        .filter((c) => c.type === "tag")
+        .slice(0, MAX_TAG_CLUSTERS);
+    const merged = [...genreClusters, ...tagClusters].sort((a, b) => b.dropRate - a.dropRate);
+    return {
+        totalDropped: droppedEntries.length,
+        clusters: merged,
+        earlyDrops,
+        avgDropProgress: progressCount > 0 ? totalProgress / progressCount : 0,
+    };
+}
+// === Genre Evolution ===
+/** How genre preferences shifted across time windows */
+export function computeGenreEvolution(entries, windowYears = 2) {
+    // Filter to entries with valid completion dates
+    const dated = entries.filter((e) => e.completedAt.year != null);
+    if (dated.length === 0) {
+        return { eras: [], shifts: [] };
+    }
+    // Find date range
+    const years = dated.map((e) => e.completedAt.year);
+    const minYear = Math.min(...years);
+    const maxYear = Math.max(...years);
+    const span = maxYear - minYear + 1;
+    // Use 1-year windows if span is narrow
+    const winSize = span < 4 ? 1 : windowYears;
+    // Build windows
+    const windows = [];
+    let start = minYear;
+    while (start <= maxYear) {
+        const end = Math.min(start + winSize - 1, maxYear);
+        windows.push({ start, end });
+        start = end + 1;
+    }
+    const eras = [];
+    for (const win of windows) {
+        const windowEntries = dated.filter((e) => {
+            const y = e.completedAt.year;
+            return y >= win.start && y <= win.end;
+        });
+        if (windowEntries.length === 0)
+            continue;
+        // Count genres
+        const genreCounts = new Map();
+        for (const e of windowEntries) {
+            for (const g of e.media.genres) {
+                genreCounts.set(g, (genreCounts.get(g) ?? 0) + 1);
+            }
+        }
+        // Top 5 genres by count
+        const topGenres = [...genreCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5)
+            .map(([g]) => g);
+        const period = win.start === win.end ? `${win.start}` : `${win.start}-${win.end}`;
+        eras.push({
+            period,
+            startYear: win.start,
+            endYear: win.end,
+            topGenres,
+            count: windowEntries.length,
+        });
+    }
+    // Generate shift descriptions
+    const shifts = [];
+    for (let i = 1; i < eras.length; i++) {
+        const prev = eras[i - 1];
+        const curr = eras[i];
+        // Genres that appeared in current top 5 but not previous
+        const risen = curr.topGenres.filter((g) => !prev.topGenres.includes(g));
+        const dropped = prev.topGenres.filter((g) => !curr.topGenres.includes(g));
+        if (risen.length > 0) {
+            shifts.push(`${curr.period}: ${risen.join(", ")} rose into top genres`);
+        }
+        if (dropped.length > 0) {
+            shifts.push(`${curr.period}: ${dropped.join(", ")} dropped out of top genres`);
+        }
+    }
+    return { eras, shifts };
+}
+// === Helpers ===
+function mean(values) {
+    if (values.length === 0)
+        return 0;
+    let sum = 0;
+    for (const v of values)
+        sum += v;
+    return sum / values.length;
+}
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+        return (sorted[mid - 1] + sorted[mid]) / 2;
+    }
+    return sorted[mid];
+}

package/dist/engine/taste.js

@@ -1,4 +1,5 @@
 /** Builds a weighted taste profile from a user's scored anime/manga list */
+import { dateToEpoch } from "../utils.js";
 // === Constants ===
 // AniList community mean hovers around 7.0-7.2
 const SITE_MEAN = 7.0;
@@ -176,14 +177,6 @@ function computeDecay(entry) {
     const yearsSince = (now - epoch) / (365.25 * 24 * 3600);
     return Math.exp(-DECAY_LAMBDA * Math.max(0, yearsSince));
 }
-/** Convert an AniListDate to Unix epoch, or null if incomplete */
-function dateToEpoch(date) {
-    if (date.year == null)
-        return null;
-    const month = date.month ?? 1;
-    const day = date.day ?? 1;
-    return new Date(date.year, month - 1, day).getTime() / 1000;
-}
 /** Empty profile for users with too few scored entries */
 function emptyProfile(totalCompleted) {
     return {

package/dist/index.js

@@ -9,6 +9,7 @@ import { registerDiscoverTools } from "./tools/discover.js";
 import { registerInfoTools } from "./tools/info.js";
 import { registerWriteTools } from "./tools/write.js";
 import { registerSocialTools } from "./tools/social.js";
+import { registerAnalyticsTools } from "./tools/analytics.js";
 import { registerResources } from "./resources.js";
 import { registerPrompts } from "./prompts.js";
 // Both vars are optional - warn on missing so operators know what's available
@@ -20,7 +21,7 @@ if (!process.env.ANILIST_TOKEN) {
 }
 const server = new FastMCP({
     name: "ani-mcp",
-    version: "0.6.2",
+    version: "0.7.0",
 });
 registerSearchTools(server);
 registerListTools(server);
@@ -29,6 +30,7 @@ registerDiscoverTools(server);
 registerInfoTools(server);
 registerWriteTools(server);
 registerSocialTools(server);
+registerAnalyticsTools(server);
 registerResources(server);
 registerPrompts(server);
 // === Transport ===

package/dist/schemas.d.ts

@@ -363,3 +363,63 @@ export declare const ReviewsInputSchema: z.ZodObject<{
     page: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type ReviewsInput = z.infer<typeof ReviewsInputSchema>;
+/** Input for score calibration analysis */
+export declare const CalibrationInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    type: z.ZodDefault<z.ZodEnum<{
+        ANIME: "ANIME";
+        MANGA: "MANGA";
+    }>>;
+}, z.core.$strip>;
+export type CalibrationInput = z.infer<typeof CalibrationInputSchema>;
+/** Input for drop pattern analysis */
+export declare const DropPatternInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    type: z.ZodDefault<z.ZodEnum<{
+        ANIME: "ANIME";
+        MANGA: "MANGA";
+    }>>;
+}, z.core.$strip>;
+export type DropPatternInput = z.infer<typeof DropPatternInputSchema>;
+/** Input for genre evolution over time */
+export declare const EvolutionInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    type: z.ZodDefault<z.ZodEnum<{
+        ANIME: "ANIME";
+        MANGA: "MANGA";
+    }>>;
+}, z.core.$strip>;
+export type EvolutionInput = z.infer<typeof EvolutionInputSchema>;
+/** Input for franchise completion tracking */
+export declare const CompletionistInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    type: z.ZodDefault<z.ZodEnum<{
+        ANIME: "ANIME";
+        MANGA: "MANGA";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type CompletionistInput = z.infer<typeof CompletionistInputSchema>;
+/** Input for seasonal pick-up and completion rates */
+export declare const SeasonalHitRateInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    season: z.ZodOptional<z.ZodEnum<{
+        WINTER: "WINTER";
+        SPRING: "SPRING";
+        SUMMER: "SUMMER";
+        FALL: "FALL";
+    }>>;
+    year: z.ZodOptional<z.ZodNumber>;
+    history: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SeasonalHitRateInput = z.infer<typeof SeasonalHitRateInputSchema>;
+/** Input for pace estimation */
+export declare const PaceInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    mediaId: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodDefault<z.ZodEnum<{
+        ANIME: "ANIME";
+        MANGA: "MANGA";
+    }>>;
+}, z.core.$strip>;
+export type PaceInput = z.infer<typeof PaceInputSchema>;

package/dist/schemas.js

@@ -616,3 +616,91 @@ export const ReviewsInputSchema = z
     .refine((data) => data.id !== undefined || data.title !== undefined, {
     message: "Provide either an id or a title.",
 });
+// === 0.7.0 Analytics & Insight ===
+/** Input for score calibration analysis */
+export const CalibrationInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Analyze anime or manga scores"),
+});
+/** Input for drop pattern analysis */
+export const DropPatternInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Analyze anime or manga drops"),
+});
+/** Input for genre evolution over time */
+export const EvolutionInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Track anime or manga taste evolution"),
+});
+/** Input for franchise completion tracking */
+export const CompletionistInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Check anime or manga franchise completion"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .default(10)
+        .describe("Number of franchise groups to show (default 10, max 20)"),
+});
+/** Input for seasonal pick-up and completion rates */
+export const SeasonalHitRateInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    season: z
+        .enum(["WINTER", "SPRING", "SUMMER", "FALL"])
+        .optional()
+        .describe("Season to analyze. Defaults to last completed season."),
+    year: z
+        .number()
+        .int()
+        .min(2000)
+        .max(MAX_YEAR)
+        .optional()
+        .describe("Year to analyze. Defaults to current year."),
+    history: z
+        .number()
+        .int()
+        .min(1)
+        .max(8)
+        .default(4)
+        .describe("Number of past seasons to show (default 4, max 8)"),
+});
+/** Input for pace estimation */
+export const PaceInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    mediaId: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("AniList media ID to estimate pace for. Omit for all current titles."),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Estimate pace for anime or manga"),
+});

package/dist/tools/analytics.d.ts

@@ -0,0 +1,4 @@
+/** Analytics tools: scoring calibration, drop patterns, genre evolution, and more. */
+import type { FastMCP } from "fastmcp";
+/** Register all analytics tools */
+export declare function registerAnalyticsTools(server: FastMCP): void;

package/dist/tools/analytics.js

@@ -0,0 +1,455 @@
+/** Analytics tools: scoring calibration, drop patterns, genre evolution, and more. */
+import { anilistClient } from "../api/client.js";
+import { BATCH_RELATIONS_QUERY } from "../api/queries.js";
+import { computeCalibration, analyzeDrops, computeGenreEvolution, } from "../engine/analytics.js";
+import { CalibrationInputSchema, DropPatternInputSchema, EvolutionInputSchema, CompletionistInputSchema, SeasonalHitRateInputSchema, PaceInputSchema, } from "../schemas.js";
+import { getDefaultUsername, getTitle, resolveSeasonYear, throwToolError, dateToEpoch, } from "../utils.js";
+// Season order for iteration
+const SEASON_ORDER = ["WINTER", "SPRING", "SUMMER", "FALL"];
+/** Register all analytics tools */
+export function registerAnalyticsTools(server) {
+    // === Score Calibration ===
+    server.addTool({
+        name: "anilist_calibration",
+        description: "Score calibration analysis showing how a user rates compared to community consensus. " +
+            "Use when the user asks if they score too high or low, which genres they're harshest " +
+            "or most generous on, or how their taste compares to mainstream. " +
+            "Returns overall bias, per-genre deviation, and scoring tendency.",
+        parameters: CalibrationInputSchema,
+        annotations: {
+            title: "Score Calibration",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const username = getDefaultUsername(args.username);
+                const entries = await anilistClient.fetchList(username, args.type, "COMPLETED");
+                const result = computeCalibration(entries);
+                if (result.totalScored === 0) {
+                    return `${username} has no scored ${args.type.toLowerCase()} entries to calibrate.`;
+                }
+                const lines = [
+                    `# Score Calibration: ${username} (${args.type.toLowerCase()})`,
+                    "",
+                    `Based on ${result.totalScored} scored titles.`,
+                    "",
+                ];
+                // Overall tendency
+                const sign = result.overallDelta >= 0 ? "+" : "";
+                lines.push(`Overall: ${sign}${result.overallDelta.toFixed(2)} vs community (${result.tendency} scorer)`);
+                // Per-genre breakdown
+                if (result.genreCalibrations.length > 0) {
+                    lines.push("", "Per-genre bias (biggest deviations first):");
+                    for (const g of result.genreCalibrations.slice(0, 10)) {
+                        const gSign = g.delta >= 0 ? "+" : "";
+                        const direction = g.delta >= 0 ? "higher" : "lower";
+                        lines.push(`  ${g.genre}: ${gSign}${g.delta.toFixed(2)} (you rate ${Math.abs(g.delta).toFixed(1)} ${direction} than average, ${g.count} titles)`);
+                    }
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "computing score calibration");
+            }
+        },
+    });
+    // === Drop Pattern Analysis ===
+    server.addTool({
+        name: "anilist_drops",
+        description: "Drop pattern analysis from a user's dropped list. " +
+            "Use when the user asks why they drop shows, what patterns their drops follow, " +
+            "or which genres they abandon most. " +
+            "Returns drop rate by genre/tag, median episode at drop, and early drop percentage.",
+        parameters: DropPatternInputSchema,
+        annotations: {
+            title: "Drop Patterns",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const username = getDefaultUsername(args.username);
+                // Fetch dropped and all entries in parallel
+                const [dropped, all] = await Promise.all([
+                    anilistClient.fetchList(username, args.type, "DROPPED"),
+                    anilistClient.fetchList(username, args.type),
+                ]);
+                if (dropped.length === 0) {
+                    return `${username} hasn't dropped any ${args.type.toLowerCase()} titles.`;
+                }
+                const result = analyzeDrops(dropped, all);
+                const lines = [
+                    `# Drop Patterns: ${username} (${args.type.toLowerCase()})`,
+                    "",
+                    `${result.totalDropped} titles dropped.`,
+                ];
+                // Early drop stats
+                if (result.totalDropped > 0) {
+                    const earlyPct = ((result.earlyDrops / result.totalDropped) *
+                        100).toFixed(0);
+                    lines.push(`${result.earlyDrops} early drops (${earlyPct}% dropped before 25% progress)`);
+                    if (result.avgDropProgress > 0) {
+                        lines.push(`Average drop point: ${(result.avgDropProgress * 100).toFixed(0)}% through`);
+                    }
+                }
+                // Genre clusters
+                const genreClusters = result.clusters.filter((c) => c.type === "genre");
+                if (genreClusters.length > 0) {
+                    lines.push("", "Drop rate by genre:");
+                    for (const c of genreClusters) {
+                        const pct = (c.dropRate * 100).toFixed(0);
+                        const dropEp = c.medianDropPoint > 0
+                            ? ` (median drop at ${(c.medianDropPoint * 100).toFixed(0)}%)`
+                            : "";
+                        lines.push(`  ${c.label}: ${pct}% drop rate (${c.dropCount}/${c.totalCount})${dropEp}`);
+                    }
+                }
+                // Tag clusters
+                const tagClusters = result.clusters.filter((c) => c.type === "tag");
+                if (tagClusters.length > 0) {
+                    lines.push("", "Drop rate by theme:");
+                    for (const c of tagClusters) {
+                        const pct = (c.dropRate * 100).toFixed(0);
+                        lines.push(`  ${c.label}: ${pct}% drop rate (${c.dropCount}/${c.totalCount})`);
+                    }
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "analyzing drop patterns");
+            }
+        },
+    });
+    // === Genre Evolution ===
+    server.addTool({
+        name: "anilist_evolution",
+        description: "Genre evolution analysis showing how taste has shifted over time. " +
+            "Use when the user asks how their taste has changed, what they used to watch vs now, " +
+            "or wants a timeline of their preferences. " +
+            "Returns era-by-era genre rankings and shift descriptions.",
+        parameters: EvolutionInputSchema,
+        annotations: {
+            title: "Genre Evolution",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const username = getDefaultUsername(args.username);
+                const entries = await anilistClient.fetchList(username, args.type, "COMPLETED");
+                const result = computeGenreEvolution(entries);
+                if (result.eras.length === 0) {
+                    return `${username} has no dated completed ${args.type.toLowerCase()} entries to analyze.`;
+                }
+                const lines = [
+                    `# Genre Evolution: ${username} (${args.type.toLowerCase()})`,
+                    "",
+                ];
+                for (const era of result.eras) {
+                    lines.push(`${era.period} (${era.count} titles): ${era.topGenres.join(", ")}`);
+                }
+                if (result.shifts.length > 0) {
+                    lines.push("", "Key shifts:");
+                    for (const s of result.shifts) {
+                        lines.push(`  ${s}`);
+                    }
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "analyzing genre evolution");
+            }
+        },
+    });
+    // === Completionist Stats ===
+    server.addTool({
+        name: "anilist_completionist",
+        description: "Franchise completion tracker showing progress through series with sequels. " +
+            "Use when the user asks what franchises they've started but not finished, " +
+            "their completion rate, or what's left to watch in a series. " +
+            "Returns franchise groups with completed/total counts.",
+        parameters: CompletionistInputSchema,
+        annotations: {
+            title: "Franchise Completion",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const username = getDefaultUsername(args.username);
+                // Get all entries to know which IDs the user has interacted with
+                const allEntries = await anilistClient.fetchList(username, args.type);
+                if (allEntries.length === 0) {
+                    return `${username} has no ${args.type.toLowerCase()} entries.`;
+                }
+                const completedIds = new Set(allEntries
+                    .filter((e) => e.status === "COMPLETED")
+                    .map((e) => e.media.id));
+                const allIds = new Set(allEntries.map((e) => e.media.id));
+                // Batch-fetch relations for all media the user has
+                const relationsMap = new Map();
+                let frontier = [...allIds];
+                const maxRounds = 3;
+                for (let round = 0; round < maxRounds && frontier.length > 0; round++) {
+                    // Process in chunks of 50
+                    for (let i = 0; i < frontier.length; i += 50) {
+                        const chunk = frontier.slice(i, i + 50);
+                        const data = await anilistClient.query(BATCH_RELATIONS_QUERY, { ids: chunk }, { cache: "media" });
+                        for (const media of data.Page.media) {
+                            if (!relationsMap.has(media.id)) {
+                                relationsMap.set(media.id, media);
+                            }
+                        }
+                    }
+                    // Discover new IDs from relations
+                    const nextFrontier = [];
+                    for (const node of relationsMap.values()) {
+                        for (const edge of node.relations.edges) {
+                            if (!relationsMap.has(edge.node.id) &&
+                                (edge.relationType === "SEQUEL" ||
+                                    edge.relationType === "PREQUEL") &&
+                                edge.node.type === args.type) {
+                                nextFrontier.push(edge.node.id);
+                            }
+                        }
+                    }
+                    frontier = nextFrontier;
+                }
+                // Group by franchise root (follow PREQUEL edges backward)
+                const franchises = new Map();
+                const assigned = new Set();
+                for (const id of allIds) {
+                    if (assigned.has(id))
+                        continue;
+                    // Find root by following prequel edges
+                    let rootId = id;
+                    const visited = new Set();
+                    while (true) {
+                        visited.add(rootId);
+                        const node = relationsMap.get(rootId);
+                        if (!node)
+                            break;
+                        const prequel = node.relations.edges.find((e) => e.relationType === "PREQUEL" && !visited.has(e.node.id));
+                        if (!prequel)
+                            break;
+                        rootId = prequel.node.id;
+                    }
+                    // Collect all franchise members via sequel/prequel edges
+                    const members = new Set();
+                    const queue = [rootId];
+                    while (queue.length > 0) {
+                        const current = queue.shift();
+                        if (current === undefined || members.has(current))
+                            continue;
+                        members.add(current);
+                        const node = relationsMap.get(current);
+                        if (!node)
+                            continue;
+                        for (const edge of node.relations.edges) {
+                            if ((edge.relationType === "SEQUEL" ||
+                                edge.relationType === "PREQUEL") &&
+                                edge.node.type === args.type &&
+                                !members.has(edge.node.id)) {
+                                queue.push(edge.node.id);
+                            }
+                        }
+                    }
+                    // Only track franchises with 2+ entries
+                    if (members.size < 2)
+                        continue;
+                    // Find a good title for the franchise
+                    const rootNode = relationsMap.get(rootId);
+                    const title = rootNode
+                        ? (rootNode.title.english ?? rootNode.title.romaji ?? "Unknown")
+                        : "Unknown";
+                    const memberArr = [...members];
+                    const completed = memberArr.filter((m) => completedIds.has(m)).length;
+                    for (const m of members)
+                        assigned.add(m);
+                    franchises.set(rootId, {
+                        title,
+                        members: memberArr,
+                        completed,
+                    });
+                }
+                // Sort by largest completion gap (most to finish first)
+                const sorted = [...franchises.values()]
+                    .filter((f) => f.completed > 0 && f.completed < f.members.length)
+                    .sort((a, b) => b.members.length - b.completed - (a.members.length - a.completed));
+                if (sorted.length === 0) {
+                    return `${username} has no partially completed franchises.`;
+                }
+                const lines = [
+                    `# Franchise Completion: ${username} (${args.type.toLowerCase()})`,
+                    "",
+                ];
+                for (const f of sorted.slice(0, args.limit)) {
+                    const remaining = f.members.length - f.completed;
+                    const pct = ((f.completed / f.members.length) * 100).toFixed(0);
+                    lines.push(`${f.title}: ${f.completed}/${f.members.length} (${pct}%) - ${remaining} remaining`);
+                }
+                if (sorted.length > args.limit) {
+                    lines.push("", `${sorted.length - args.limit} more franchises not shown.`);
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "computing franchise completion");
+            }
+        },
+    });
+    // === Seasonal Hit Rate ===
+    server.addTool({
+        name: "anilist_seasonal_stats",
+        description: "Seasonal pick-up and completion rates. " +
+            "Use when the user asks about their seasonal watching habits, how many shows " +
+            "they finish vs drop each season, or their hit rate. " +
+            "Returns per-season breakdown of picked, finished, dropped, and ongoing counts.",
+        parameters: SeasonalHitRateInputSchema,
+        annotations: {
+            title: "Seasonal Hit Rate",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const username = getDefaultUsername(args.username);
+                // Fetch all entries (all statuses)
+                const entries = await anilistClient.fetchList(username, "ANIME");
+                if (entries.length === 0) {
+                    return `${username} has no anime entries.`;
+                }
+                // Determine target seasons to show
+                const { season: currentSeason, year: currentYear } = resolveSeasonYear(args.season, args.year);
+                // Build list of seasons to analyze (going backward)
+                const seasons = [];
+                let s = SEASON_ORDER.indexOf(currentSeason);
+                let y = currentYear;
+                for (let i = 0; i < args.history; i++) {
+                    seasons.push({ season: SEASON_ORDER[s], year: y });
+                    s--;
+                    if (s < 0) {
+                        s = 3;
+                        y--;
+                    }
+                }
+                seasons.reverse();
+                const lines = [`# Seasonal Hit Rate: ${username}`, ""];
+                for (const target of seasons) {
+                    // Match entries by the media's season/year
+                    const matching = entries.filter((e) => e.media.season === target.season &&
+                        e.media.seasonYear === target.year);
+                    if (matching.length === 0)
+                        continue;
+                    const finished = matching.filter((e) => e.status === "COMPLETED").length;
+                    const dropped = matching.filter((e) => e.status === "DROPPED").length;
+                    const current = matching.filter((e) => e.status === "CURRENT").length;
+                    const paused = matching.filter((e) => e.status === "PAUSED").length;
+                    const hitRate = ((finished / matching.length) * 100).toFixed(0);
+                    const parts = [];
+                    parts.push(`${finished} finished`);
+                    if (dropped > 0)
+                        parts.push(`${dropped} dropped`);
+                    if (current > 0)
+                        parts.push(`${current} watching`);
+                    if (paused > 0)
+                        parts.push(`${paused} paused`);
+                    lines.push(`${target.season} ${target.year}: ${matching.length} picked up - ${parts.join(", ")} (${hitRate}% hit rate)`);
+                }
+                if (lines.length <= 2) {
+                    return `No seasonal data found for ${username} in the requested range.`;
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "computing seasonal hit rate");
+            }
+        },
+    });
+    // === Pace Estimate ===
+    server.addTool({
+        name: "anilist_pace",
+        description: "Pace estimate for currently watching or reading titles. " +
+            "Use when the user asks how long it'll take to finish something, " +
+            "their watch rate, or wants a progress summary. " +
+            "Returns estimated completion date based on historical pace.",
+        parameters: PaceInputSchema,
+        annotations: {
+            title: "Pace Estimate",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const username = getDefaultUsername(args.username);
+                let entries = await anilistClient.fetchList(username, args.type, "CURRENT");
+                if (entries.length === 0) {
+                    return `${username} has no current ${args.type.toLowerCase()} entries.`;
+                }
+                // Filter to specific media if requested
+                if (args.mediaId) {
+                    entries = entries.filter((e) => e.media.id === args.mediaId);
+                    if (entries.length === 0) {
+                        return `Media ID ${args.mediaId} is not on ${username}'s current list.`;
+                    }
+                }
+                const now = Date.now() / 1000;
+                const unit = args.type === "ANIME" ? "ep" : "ch";
+                const lines = [
+                    `# Pace Estimate: ${username} (${args.type.toLowerCase()})`,
+                    "",
+                ];
+                for (const entry of entries) {
+                    const title = getTitle(entry.media.title);
+                    const total = entry.media.episodes ?? entry.media.chapters ?? 0;
+                    const remaining = total > 0 ? total - entry.progress : 0;
+                    // Compute pace from startedAt
+                    const startEpoch = dateToEpoch(entry.startedAt);
+                    const weeksSinceStart = startEpoch
+                        ? (now - startEpoch) / (7 * 24 * 3600)
+                        : 0;
+                    let rateLine = "";
+                    let estimateLine = "";
+                    if (weeksSinceStart >= 1 && entry.progress > 0) {
+                        const perWeek = entry.progress / weeksSinceStart;
+                        rateLine = `${perWeek.toFixed(1)} ${unit}/week`;
+                        if (remaining > 0 && perWeek > 0) {
+                            const weeksLeft = remaining / perWeek;
+                            const finishEpoch = now + weeksLeft * 7 * 24 * 3600;
+                            const finishDate = new Date(finishEpoch * 1000);
+                            const dateStr = finishDate.toISOString().split("T")[0];
+                            estimateLine = `~${Math.ceil(weeksLeft)} weeks (est. ${dateStr})`;
+                        }
+                    }
+                    // Progress string
+                    const progressStr = total > 0
+                        ? `${entry.progress}/${total} ${unit}`
+                        : `${entry.progress} ${unit}`;
+                    const parts = [progressStr];
+                    if (rateLine)
+                        parts.push(rateLine);
+                    if (estimateLine)
+                        parts.push(estimateLine);
+                    lines.push(`${title}: ${parts.join(" - ")}`);
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "estimating pace");
+            }
+        },
+    });
+}

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 /** Formatting and resolution helpers. */
-import type { AniListMedia, ScoreFormat } from "./types.js";
+import type { AniListDate, 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) */
@@ -23,5 +23,7 @@ export declare function resolveSeasonYear(season?: string, year?: number): {
     season: string;
     year: number;
 };
+/** Convert an AniListDate to Unix epoch seconds, or null if year is missing */
+export declare function dateToEpoch(date: AniListDate): number | null;
 /** 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

@@ -153,6 +153,14 @@ export function resolveSeasonYear(season, year) {
                 : "FALL";
     return { season: currentSeason, year: currentYear };
 }
+/** Convert an AniListDate to Unix epoch seconds, or null if year is missing */
+export function dateToEpoch(date) {
+    if (date.year == null)
+        return null;
+    const month = date.month ?? 1;
+    const day = date.day ?? 1;
+    return new Date(date.year, month - 1, day).getTime() / 1000;
+}
 /** Display a normalized 0-10 score in the user's preferred format */
 export function formatScore(score10, format) {
     if (score10 <= 0)

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.3",
   "name": "ani-mcp",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "display_name": "AniList MCP",
   "description": "A smart MCP server for AniList that gets your anime/manga taste - not just API calls.",
   "author": {
@@ -146,6 +146,24 @@
     },
     {
       "name": "anilist_delete_from_list"
+    },
+    {
+      "name": "anilist_calibration"
+    },
+    {
+      "name": "anilist_drops"
+    },
+    {
+      "name": "anilist_evolution"
+    },
+    {
+      "name": "anilist_completionist"
+    },
+    {
+      "name": "anilist_seasonal_stats"
+    },
+    {
+      "name": "anilist_pace"
     }
   ]
 }

package/package.json

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

package/server.json

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