ani-mcp 0.1.0

package/dist/engine/mood.js

@@ -0,0 +1,165 @@
+/** Maps freeform mood strings to genre/tag boost and penalize rules */
+// === Mood Keyword Rules ===
+// Base mood rules keyed by canonical keyword
+const BASE_MOOD_RULES = {
+    dark: {
+        boost: ["Psychological", "Thriller", "Horror", "Tragedy", "Drama"],
+        penalize: ["Comedy", "Slice of Life"],
+    },
+    chill: {
+        boost: ["Slice of Life", "Iyashikei", "Music", "Cgdct"],
+        penalize: ["Horror", "Action", "Thriller"],
+    },
+    hype: {
+        boost: ["Action", "Shounen", "Sports", "Mecha", "Super Power"],
+        penalize: ["Slice of Life", "Drama"],
+    },
+    action: {
+        boost: ["Action", "Shounen", "Martial Arts", "Super Power", "Mecha"],
+        penalize: ["Slice of Life", "Iyashikei"],
+    },
+    romantic: {
+        boost: ["Romance", "Drama", "Love Triangle", "Couples"],
+        penalize: ["Horror", "Gore"],
+    },
+    funny: {
+        boost: ["Comedy", "Parody", "Gag Humor", "Slapstick"],
+        penalize: ["Tragedy", "Horror"],
+    },
+    brainy: {
+        boost: ["Psychological", "Sci-Fi", "Mystery", "Philosophy", "Mind Games"],
+        penalize: ["Ecchi", "Gag Humor"],
+    },
+    sad: {
+        boost: ["Drama", "Tragedy", "Romance", "Coming of Age", "Emotional"],
+        penalize: ["Comedy", "Parody"],
+    },
+    scary: {
+        boost: ["Horror", "Thriller", "Psychological", "Survival"],
+        penalize: ["Comedy", "Slice of Life", "Romance"],
+    },
+    epic: {
+        boost: ["Fantasy", "Adventure", "Action", "Shounen", "War"],
+        penalize: ["Slice of Life", "Cgdct"],
+    },
+    wholesome: {
+        boost: ["Slice of Life", "Comedy", "Iyashikei", "Family Life", "Cgdct"],
+        penalize: ["Horror", "Gore", "Tragedy"],
+    },
+    intense: {
+        boost: ["Thriller", "Action", "Psychological", "Survival", "Battle Royale"],
+        penalize: ["Slice of Life", "Iyashikei"],
+    },
+    mystery: {
+        boost: ["Mystery", "Thriller", "Psychological", "Detective"],
+        penalize: ["Slice of Life", "Sports"],
+    },
+    fantasy: {
+        boost: ["Fantasy", "Adventure", "Magic", "Isekai"],
+        penalize: [],
+    },
+    scifi: {
+        boost: ["Sci-Fi", "Mecha", "Space", "Cyberpunk", "Time Travel"],
+        penalize: [],
+    },
+    trippy: {
+        boost: ["Psychological", "Avant Garde", "Surreal", "Experimental"],
+        penalize: ["Shounen", "Sports"],
+    },
+};
+// Synonyms that resolve to a base keyword's rules
+const MOOD_SYNONYMS = {
+    // dark
+    grim: "dark",
+    moody: "dark",
+    bleak: "dark",
+    // chill
+    relaxing: "chill",
+    peaceful: "chill",
+    cozy: "chill",
+    mellow: "chill",
+    // hype
+    exciting: "hype",
+    thrilling: "hype",
+    // romantic
+    romance: "romantic",
+    love: "romantic",
+    sweet: "romantic",
+    // funny
+    comedy: "funny",
+    silly: "funny",
+    witty: "funny",
+    hilarious: "funny",
+    // brainy
+    smart: "brainy",
+    cerebral: "brainy",
+    intellectual: "brainy",
+    complex: "brainy",
+    // sad
+    emotional: "sad",
+    depressing: "sad",
+    melancholic: "sad",
+    bittersweet: "sad",
+    // scary
+    creepy: "scary",
+    spooky: "scary",
+    eerie: "scary",
+    // epic
+    grand: "epic",
+    ambitious: "epic",
+    // wholesome
+    comforting: "wholesome",
+    heartwarming: "wholesome",
+    uplifting: "wholesome",
+    // intense
+    tense: "intense",
+    gripping: "intense",
+    // trippy
+    surreal: "trippy",
+    experimental: "trippy",
+};
+// Merge base rules and synonyms into a single lookup
+const MOOD_RULES = { ...BASE_MOOD_RULES };
+for (const [synonym, base] of Object.entries(MOOD_SYNONYMS)) {
+    MOOD_RULES[synonym] = BASE_MOOD_RULES[base];
+}
+// === Mood Parser ===
+/** Parse a freeform mood string into genre/tag boost and penalize sets */
+export function parseMood(mood) {
+    // Strip punctuation and split into lowercase tokens for keyword matching
+    const words = mood
+        .toLowerCase()
+        .replace(/[^a-z\s]/g, "")
+        .split(/\s+/);
+    const boostGenres = new Set();
+    const boostTags = new Set();
+    const penalizeGenres = new Set();
+    const penalizeTags = new Set();
+    for (const word of words) {
+        const rule = MOOD_RULES[word];
+        if (!rule)
+            continue;
+        // Add to both genre and tag sets since we can't distinguish at parse time
+        for (const name of rule.boost) {
+            boostGenres.add(name);
+            boostTags.add(name);
+        }
+        for (const name of rule.penalize) {
+            penalizeGenres.add(name);
+            penalizeTags.add(name);
+        }
+    }
+    return { boostGenres, boostTags, penalizeGenres, penalizeTags };
+}
+/** Check whether a mood string matches any known keywords */
+export function hasMoodMatch(mood) {
+    const words = mood
+        .toLowerCase()
+        .replace(/[^a-z\s]/g, "")
+        .split(/\s+/);
+    return words.some((w) => w in MOOD_RULES);
+}
+/** List all recognized mood keywords */
+export function getMoodKeywords() {
+    return Object.keys(MOOD_RULES);
+}

package/dist/engine/taste.d.ts

@@ -0,0 +1,30 @@
+/** Builds a weighted taste profile from a user's scored anime/manga list */
+import type { AniListMediaListEntry } from "../types.js";
+export interface WeightedItem {
+    name: string;
+    weight: number;
+    count: number;
+}
+export interface ScoringPattern {
+    meanScore: number;
+    median: number;
+    totalScored: number;
+    distribution: Record<number, number>;
+    tendency: "generous" | "harsh" | "average";
+}
+export interface FormatBreakdown {
+    format: string;
+    count: number;
+    percent: number;
+}
+export interface TasteProfile {
+    genres: WeightedItem[];
+    tags: WeightedItem[];
+    scoring: ScoringPattern;
+    formats: FormatBreakdown[];
+    totalCompleted: number;
+}
+/** Build a taste profile from scored list entries */
+export declare function buildTasteProfile(entries: AniListMediaListEntry[]): TasteProfile;
+/** Summarize a taste profile as natural language */
+export declare function describeTasteProfile(profile: TasteProfile, username: string): string;

package/dist/engine/taste.js

@@ -0,0 +1,202 @@
+/** Builds a weighted taste profile from a user's scored anime/manga list */
+// === Constants ===
+// AniList community mean hovers around 7.0-7.2
+const SITE_MEAN = 7.0;
+// Minimum entries to produce a meaningful profile
+const MIN_ENTRIES = 5;
+// Entries scored 0 are unscored on AniList (not a real 0/10)
+const UNSCORED = 0;
+// Cap the number of tags returned to keep output focused
+const MAX_TAGS = 20;
+// Recency decay: entries from HALF_LIFE years ago get ~50% weight
+const DECAY_HALF_LIFE_YEARS = 3;
+const DECAY_LAMBDA = Math.LN2 / DECAY_HALF_LIFE_YEARS;
+// Bayesian smoothing: pull sparse observations toward a neutral prior
+const BAYESIAN_PRIOR_WEIGHT = 0.5;
+const BAYESIAN_PRIOR_COUNT = 3;
+// === Profile Builder ===
+/** Build a taste profile from scored list entries */
+export function buildTasteProfile(entries) {
+    // Filter out unscored entries (score 0 means the user didn't rate it)
+    const scored = entries.filter((e) => e.score !== UNSCORED);
+    if (scored.length < MIN_ENTRIES) {
+        return emptyProfile(entries.length);
+    }
+    const genres = computeGenreWeights(scored);
+    const tags = computeTagWeights(scored);
+    const scoring = computeScoringPattern(scored);
+    // Format breakdown uses all entries, not just scored ones
+    const formats = computeFormatBreakdown(entries);
+    return {
+        genres,
+        tags,
+        scoring,
+        formats,
+        totalCompleted: entries.length,
+    };
+}
+/** Summarize a taste profile as natural language */
+export function describeTasteProfile(profile, username) {
+    if (profile.genres.length === 0) {
+        return (`${username} has completed ${profile.totalCompleted} titles, ` +
+            `but not enough have scores to build a taste profile. ` +
+            `Score more titles on AniList for a detailed breakdown.`);
+    }
+    const lines = [];
+    // Top genres
+    const topGenres = profile.genres
+        .slice(0, 5)
+        .map((g) => g.name)
+        .join(", ");
+    lines.push(`Top genres: ${topGenres}.`);
+    // Top tags (themes)
+    if (profile.tags.length > 0) {
+        const topTags = profile.tags
+            .slice(0, 5)
+            .map((t) => t.name)
+            .join(", ");
+        lines.push(`Strongest themes: ${topTags}.`);
+    }
+    // Scoring tendency
+    const { scoring } = profile;
+    const tendencyDesc = scoring.tendency === "generous"
+        ? `Scores generously (avg ${scoring.meanScore.toFixed(1)} vs site avg ${SITE_MEAN})`
+        : scoring.tendency === "harsh"
+            ? `Scores harshly (avg ${scoring.meanScore.toFixed(1)} vs site avg ${SITE_MEAN})`
+            : `Scores close to average (avg ${scoring.meanScore.toFixed(1)})`;
+    lines.push(`${tendencyDesc} across ${scoring.totalScored} rated titles.`);
+    // Format preferences
+    if (profile.formats.length > 0) {
+        const fmtParts = profile.formats
+            .slice(0, 3)
+            .map((f) => `${f.format} ${f.percent}%`);
+        lines.push(`Format split: ${fmtParts.join(", ")}.`);
+    }
+    lines.push(`Total completed: ${profile.totalCompleted}.`);
+    return lines.join("\n");
+}
+// === Weighting Algorithms ===
+/** Weight genres by how much the user liked shows in that genre */
+function computeGenreWeights(entries) {
+    const genreMap = new Map();
+    for (const entry of entries) {
+        // Higher-scored and more recent shows contribute more
+        const scoreWeight = (entry.score / 10) * computeDecay(entry);
+        for (const genre of entry.media.genres) {
+            const existing = genreMap.get(genre) ?? { weight: 0, count: 0 };
+            existing.weight += scoreWeight;
+            existing.count += 1;
+            genreMap.set(genre, existing);
+        }
+    }
+    return mapToSortedItems(genreMap);
+}
+/** Weight tags by user score multiplied by tag relevance */
+function computeTagWeights(entries) {
+    const tagMap = new Map();
+    for (const entry of entries) {
+        const scoreWeight = (entry.score / 10) * computeDecay(entry);
+        for (const tag of entry.media.tags) {
+            if (tag.isMediaSpoiler)
+                continue;
+            // Tag rank (0-100) indicates how relevant the tag is to this media
+            const relevance = tag.rank / 100;
+            const existing = tagMap.get(tag.name) ?? { weight: 0, count: 0 };
+            existing.weight += scoreWeight * relevance;
+            existing.count += 1;
+            tagMap.set(tag.name, existing);
+        }
+    }
+    return mapToSortedItems(tagMap).slice(0, MAX_TAGS);
+}
+/** Score distribution and tendency classification */
+function computeScoringPattern(entries) {
+    const scores = entries.map((e) => e.score);
+    const sorted = [...scores].sort((a, b) => a - b);
+    const mean = scores.reduce((sum, s) => sum + s, 0) / scores.length;
+    // Middle value of sorted scores (average of two middle values if even count)
+    const median = sorted.length % 2 === 0
+        ? (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2
+        : sorted[Math.floor(sorted.length / 2)];
+    // Build histogram: count of each score value (1-10)
+    const distribution = {};
+    for (const s of scores) {
+        distribution[s] = (distribution[s] ?? 0) + 1;
+    }
+    // Classify based on distance from site average (7.0)
+    const tendency = mean >= SITE_MEAN + 0.5
+        ? "generous"
+        : mean <= SITE_MEAN - 0.5
+            ? "harsh"
+            : "average";
+    return {
+        meanScore: mean,
+        median,
+        totalScored: scores.length,
+        distribution,
+        tendency,
+    };
+}
+/** Format preferences as percentages */
+function computeFormatBreakdown(entries) {
+    const counts = new Map();
+    // Count entries per format (TV, MOVIE, OVA, etc.)
+    for (const entry of entries) {
+        const format = entry.media.format ?? "UNKNOWN";
+        counts.set(format, (counts.get(format) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([format, count]) => ({
+        format,
+        count,
+        percent: Math.round((count / entries.length) * 100),
+    }))
+        .sort((a, b) => b.count - a.count);
+}
+// === Helpers ===
+/** Convert a name->weight Map into a Bayesian-smoothed sorted array */
+function mapToSortedItems(map) {
+    return [...map.entries()]
+        .map(([name, { weight, count }]) => ({
+        name,
+        // Pull sparse observations toward a neutral prior
+        weight: (weight + BAYESIAN_PRIOR_WEIGHT * BAYESIAN_PRIOR_COUNT) /
+            (count + BAYESIAN_PRIOR_COUNT),
+        count,
+    }))
+        .sort((a, b) => b.weight - a.weight);
+}
+/** Recency multiplier (0-1) - recent entries weigh more than old ones */
+function computeDecay(entry) {
+    const now = Date.now() / 1000;
+    const completedEpoch = dateToEpoch(entry.completedAt);
+    const epoch = completedEpoch ?? entry.updatedAt;
+    if (!epoch)
+        return 1;
+    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 {
+        genres: [],
+        tags: [],
+        scoring: {
+            meanScore: 0,
+            median: 0,
+            totalScored: 0,
+            distribution: {},
+            tendency: "average",
+        },
+        formats: [],
+        totalCompleted,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** ani-mcp - AniList MCP Server */
+import "dotenv/config";

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/** ani-mcp - AniList MCP Server */
+import "dotenv/config";
+import { FastMCP } from "fastmcp";
+import { registerSearchTools } from "./tools/search.js";
+import { registerListTools } from "./tools/lists.js";
+import { registerRecommendTools } from "./tools/recommend.js";
+import { registerDiscoverTools } from "./tools/discover.js";
+import { registerInfoTools } from "./tools/info.js";
+// Both vars are optional - warn on missing so operators know what's available
+if (!process.env.ANILIST_USERNAME) {
+    console.warn("ANILIST_USERNAME not set - tools will require a username argument.");
+}
+if (!process.env.ANILIST_TOKEN) {
+    console.warn("ANILIST_TOKEN not set - authenticated features unavailable.");
+}
+const server = new FastMCP({
+    name: "ani-mcp",
+    version: "0.1.0",
+});
+registerSearchTools(server);
+registerListTools(server);
+registerRecommendTools(server);
+registerDiscoverTools(server);
+registerInfoTools(server);
+server.start({ transportType: "stdio" });

package/dist/intelligence/matcher.d.ts

@@ -0,0 +1,12 @@
+/** Scores candidate media against a taste profile with natural-language explanations */
+import type { AniListMedia } from "../types.js";
+import type { TasteProfile } from "./taste.js";
+import type { MoodModifiers } from "./mood.js";
+export interface MatchResult {
+    media: AniListMedia;
+    score: number;
+    reasons: string[];
+    moodFit: string | null;
+}
+/** Score and rank candidates against a user's taste profile */
+export declare function matchCandidates(candidates: AniListMedia[], profile: TasteProfile, mood?: MoodModifiers): MatchResult[];

package/dist/intelligence/matcher.js

@@ -0,0 +1,134 @@
+/** Scores candidate media against a taste profile with natural-language explanations */
+// === Constants ===
+// How much each signal contributes to the final score
+const GENRE_WEIGHT = 0.5;
+const TAG_WEIGHT = 0.3;
+const COMMUNITY_WEIGHT = 0.2;
+// Mood boost/penalty as a multiplier on the final score
+const MOOD_BOOST = 1.3;
+const MOOD_PENALTY = 0.6;
+// Minimum community score (out of 100) to avoid recommending poorly-rated titles
+const MIN_COMMUNITY_SCORE = 50;
+// === Matcher ===
+/** Score and rank candidates against a user's taste profile */
+export function matchCandidates(candidates, profile, mood) {
+    // Build lookup maps for O(1) access during scoring
+    const genreWeights = toWeightMap(profile.genres);
+    const tagWeights = toWeightMap(profile.tags);
+    // Find max weights for normalization
+    const maxGenreWeight = profile.genres[0]?.weight ?? 1;
+    const maxTagWeight = profile.tags[0]?.weight ?? 1;
+    const results = [];
+    for (const media of candidates) {
+        // Skip titles with very low community scores
+        if (media.meanScore !== null && media.meanScore < MIN_COMMUNITY_SCORE) {
+            continue;
+        }
+        const reasons = [];
+        // Genre affinity: sum of user's genre weights for this title's genres
+        const genreScore = computeGenreAffinity(media, genreWeights, maxGenreWeight, reasons);
+        // Tag affinity: sum of user's tag weights for this title's tags
+        const tagScore = computeTagAffinity(media, tagWeights, maxTagWeight, reasons);
+        // Fall back to 70 for unrated titles so they aren't penalized or boosted
+        const communityScore = (media.meanScore ?? 70) / 100;
+        // Weighted combination
+        let finalScore = genreScore * GENRE_WEIGHT +
+            tagScore * TAG_WEIGHT +
+            communityScore * COMMUNITY_WEIGHT;
+        // Apply mood modifiers
+        const moodFit = mood ? applyMood(media, mood, reasons) : null;
+        if (moodFit === "boost")
+            finalScore *= MOOD_BOOST;
+        if (moodFit === "penalty")
+            finalScore *= MOOD_PENALTY;
+        results.push({
+            media,
+            score: finalScore,
+            reasons,
+            moodFit: moodFit
+                ? moodFit === "boost"
+                    ? "Strong mood match"
+                    : "Weak mood fit"
+                : null,
+        });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}
+// === Scoring Components ===
+/** How well a title's genres align with the user's genre preferences */
+function computeGenreAffinity(media, genreWeights, maxWeight, reasons) {
+    if (media.genres.length === 0)
+        return 0;
+    let total = 0;
+    const matchedGenres = [];
+    // Accumulate user's preference weight for each matching genre
+    for (const genre of media.genres) {
+        const weight = genreWeights.get(genre);
+        if (weight !== undefined) {
+            total += weight;
+            matchedGenres.push(genre);
+        }
+    }
+    // Cap divisor at 3 so titles with many genres aren't unfairly diluted
+    const normalized = total / (maxWeight * Math.min(media.genres.length, 3));
+    if (matchedGenres.length > 0) {
+        reasons.push(`Matches your taste in ${matchedGenres.join(", ")}`);
+    }
+    return Math.min(1, normalized);
+}
+/** How well a title's tags align with the user's tag preferences */
+function computeTagAffinity(media, tagWeights, maxWeight, reasons) {
+    const nonSpoilerTags = media.tags.filter((t) => !t.isMediaSpoiler);
+    if (nonSpoilerTags.length === 0)
+        return 0;
+    let total = 0;
+    const matchedTags = [];
+    for (const tag of nonSpoilerTags) {
+        const weight = tagWeights.get(tag.name);
+        if (weight !== undefined) {
+            // Scale by tag relevance
+            total += weight * (tag.rank / 100);
+            matchedTags.push(tag.name);
+        }
+    }
+    // Cap divisor so titles with many tags aren't unfairly diluted
+    const normalized = total / (maxWeight * Math.min(nonSpoilerTags.length, 5));
+    if (matchedTags.length >= 2) {
+        reasons.push(`Themes you enjoy: ${matchedTags.slice(0, 3).join(", ")}`);
+    }
+    return Math.min(1, normalized);
+}
+/** Apply mood boost/penalty based on genre and tag overlap */
+function applyMood(media, mood, reasons) {
+    let boostCount = 0;
+    let penaltyCount = 0;
+    // Count mood matches across genres and tags
+    for (const genre of media.genres) {
+        if (mood.boostGenres.has(genre))
+            boostCount++;
+        if (mood.penalizeGenres.has(genre))
+            penaltyCount++;
+    }
+    for (const tag of media.tags) {
+        if (tag.isMediaSpoiler)
+            continue;
+        if (mood.boostTags.has(tag.name))
+            boostCount++;
+        if (mood.penalizeTags.has(tag.name))
+            penaltyCount++;
+    }
+    // Boost wins if it has more matches, penalty if it dominates
+    if (boostCount >= 2 && boostCount > penaltyCount) {
+        reasons.push("Fits the mood you described");
+        return "boost";
+    }
+    if (penaltyCount >= 2 && penaltyCount > boostCount) {
+        return "penalty";
+    }
+    return null;
+}
+// === Helpers ===
+/** Convert WeightedItem[] to a Map for fast lookup */
+function toWeightMap(items) {
+    return new Map(items.map((i) => [i.name, i.weight]));
+}

package/dist/intelligence/mood.d.ts

@@ -0,0 +1,17 @@
+/** Maps freeform mood strings to genre/tag boost and penalize rules */
+export interface MoodRule {
+    boost: string[];
+    penalize: string[];
+}
+export interface MoodModifiers {
+    boostGenres: Set<string>;
+    boostTags: Set<string>;
+    penalizeGenres: Set<string>;
+    penalizeTags: Set<string>;
+}
+/** Parse a freeform mood string into genre/tag boost and penalize sets */
+export declare function parseMood(mood: string): MoodModifiers;
+/** Check whether a mood string matches any known keywords */
+export declare function hasMoodMatch(mood: string): boolean;
+/** List all recognized mood keywords */
+export declare function getMoodKeywords(): string[];