ani-mcp 0.12.0 → 0.13.0

package/README.md

@@ -114,6 +114,7 @@ Works with any MCP-compatible client.
 | `anilist_watch_order` | Viewing order for a franchise |
 | `anilist_session` | Plan a viewing session within a time budget |
 | `anilist_mal_import` | Import a MyAnimeList user's list and generate recommendations |
+| `anilist_kitsu_import` | Import a Kitsu user's list and generate recommendations |
 
 ### Cards
 

package/dist/api/client.d.ts

@@ -39,6 +39,11 @@ declare class AniListClient {
     fetchList(username: string, type: string, status?: string, sort?: string[]): Promise<AniListMediaListEntry[]>;
     /** Invalidate the entire query cache */
     clearCache(): void;
+    /** Cache size and capacity for health checks */
+    cacheStats(): {
+        size: number;
+        maxSize: number;
+    };
     /** Evict cache entries related to a specific user (lists and stats) */
     invalidateUser(username: string): void;
     /** Retries with exponential backoff via p-retry */

package/dist/api/client.js

@@ -121,6 +121,10 @@ class AniListClient {
     clearCache() {
         queryCache.clear();
     }
+    /** Cache size and capacity for health checks */
+    cacheStats() {
+        return { size: queryCache.size, maxSize: 500 };
+    }
     /** Evict cache entries related to a specific user (lists and stats) */
     invalidateUser(username) {
         const needle = `"${username}"`;

package/dist/api/kitsu-client.d.ts

@@ -0,0 +1,39 @@
+/** Kitsu API client for read-only list import */
+export interface KitsuLibraryEntry {
+    id: string;
+    attributes: {
+        status: string;
+        ratingTwenty: number | null;
+        progress: number;
+    };
+    relationships: {
+        anime: {
+            data: {
+                type: string;
+                id: string;
+            } | null;
+        };
+    };
+}
+export interface KitsuAnime {
+    id: string;
+    attributes: {
+        canonicalTitle: string;
+        episodeCount: number | null;
+        averageRating: string | null;
+        subtype: string;
+    };
+}
+export interface KitsuCategory {
+    id: string;
+    attributes: {
+        title: string;
+    };
+}
+/** Map Kitsu subtype to AniList format */
+export declare function mapKitsuFormat(subtype: string): string;
+/** Fetch a Kitsu user's completed anime library */
+export declare function fetchKitsuList(username: string, maxPages?: number): Promise<{
+    entries: KitsuLibraryEntry[];
+    anime: Map<string, KitsuAnime>;
+}>;

package/dist/api/kitsu-client.js

@@ -0,0 +1,87 @@
+/** Kitsu API client for read-only list import */
+import pThrottle from "p-throttle";
+import pRetry, { AbortError } from "p-retry";
+const KITSU_BASE = process.env.KITSU_API_URL || "https://kitsu.io/api/edge";
+const FETCH_TIMEOUT_MS = 15_000;
+const PAGE_LIMIT = 20;
+// Kitsu has no documented rate limit; be conservative
+const throttle = pThrottle({
+    limit: process.env.VITEST ? 10_000 : 5,
+    interval: 1_000,
+});
+const throttled = throttle(() => { });
+// === Format Mapping ===
+const KITSU_TO_ANILIST_FORMAT = {
+    TV: "TV",
+    movie: "MOVIE",
+    OVA: "OVA",
+    ONA: "ONA",
+    special: "SPECIAL",
+    music: "MUSIC",
+};
+/** Map Kitsu subtype to AniList format */
+export function mapKitsuFormat(subtype) {
+    return KITSU_TO_ANILIST_FORMAT[subtype] ?? "TV";
+}
+// === Client ===
+/** Resolve a Kitsu username to a user ID */
+async function resolveUserId(username) {
+    return pRetry(async () => {
+        await throttled();
+        const url = `${KITSU_BASE}/users?filter[name]=${encodeURIComponent(username)}&fields[users]=id,name&page[limit]=1`;
+        const response = await fetch(url, {
+            headers: { Accept: "application/vnd.api+json" },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            throw new Error(`Kitsu API error (HTTP ${response.status})`);
+        }
+        const json = (await response.json());
+        if (!json.data.length) {
+            throw new AbortError(`Kitsu user "${username}" not found.`);
+        }
+        return json.data[0].id;
+    }, { retries: 3 });
+}
+/** Fetch a Kitsu user's completed anime library */
+export async function fetchKitsuList(username, maxPages = 10) {
+    const userId = await resolveUserId(username);
+    const entries = [];
+    const animeMap = new Map();
+    let url = `${KITSU_BASE}/library-entries?filter[userId]=${userId}` +
+        `&filter[status]=completed&filter[kind]=anime` +
+        `&page[limit]=${PAGE_LIMIT}` +
+        `&include=anime` +
+        `&fields[libraryEntries]=status,ratingTwenty,progress,anime` +
+        `&fields[anime]=canonicalTitle,episodeCount,averageRating,subtype`;
+    for (let page = 0; page < maxPages && url; page++) {
+        const data = await fetchPage(url);
+        entries.push(...data.data);
+        // Index included anime
+        if (data.included) {
+            for (const inc of data.included) {
+                if (inc.id && "canonicalTitle" in (inc.attributes ?? {})) {
+                    animeMap.set(inc.id, inc);
+                }
+            }
+        }
+        url = data.links?.next ?? null;
+    }
+    return { entries, anime: animeMap };
+}
+async function fetchPage(url) {
+    return pRetry(async () => {
+        await throttled();
+        const response = await fetch(url, {
+            headers: { Accept: "application/vnd.api+json" },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            if (response.status === 404) {
+                throw new AbortError("Kitsu user not found.");
+            }
+            throw new Error(`Kitsu API error (HTTP ${response.status})`);
+        }
+        return (await response.json());
+    }, { retries: 3 });
+}

package/dist/index.js

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

package/dist/resources.js

@@ -91,6 +91,37 @@ export function registerResources(server) {
             }
         },
     });
+    // === Health Check ===
+    server.addResource({
+        uri: "anilist://status",
+        name: "Server Status",
+        description: "Health check showing API connectivity, auth status, cache state, and server version.",
+        mimeType: "text/plain",
+        async load() {
+            const lines = ["# ani-mcp Status", ""];
+            // Server version
+            lines.push(`Version: 0.13.0`);
+            // Auth status
+            const hasToken = Boolean(process.env.ANILIST_TOKEN);
+            const hasUsername = Boolean(process.env.ANILIST_USERNAME);
+            lines.push(`Auth: ${hasToken ? "token configured" : "no token (read-only mode)"}`);
+            lines.push(`Username: ${hasUsername ? process.env.ANILIST_USERNAME : "not configured"}`);
+            // API connectivity
+            try {
+                const start = Date.now();
+                await anilistClient.query("query Ping { Viewer { id } }", {}, { cache: null });
+                const latency = Date.now() - start;
+                lines.push(`API: connected (${latency}ms)`);
+            }
+            catch {
+                lines.push("API: unreachable");
+            }
+            // Cache stats
+            const cacheStats = anilistClient.cacheStats();
+            lines.push(`Cache: ${cacheStats.size}/${cacheStats.maxSize} entries`);
+            return { text: lines.join("\n") };
+        },
+    });
 }
 // === Formatting Helpers ===
 /** Format a taste profile with detailed breakdowns */

package/dist/schemas.d.ts

@@ -260,6 +260,12 @@ export declare const MalImportInputSchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type MalImportInput = z.infer<typeof MalImportInputSchema>;
+/** Input for importing a Kitsu user's completed list */
+export declare const KitsuImportInputSchema: z.ZodObject<{
+    kitsuUsername: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type KitsuImportInput = z.infer<typeof KitsuImportInputSchema>;
 /** Input for character search */
 export declare const CharacterSearchInputSchema: z.ZodObject<{
     query: z.ZodString;

package/dist/schemas.js

@@ -449,6 +449,21 @@ export const MalImportInputSchema = z.object({
         .default(5)
         .describe("Number of recommendations to return (default 5, max 15)"),
 });
+/** Input for importing a Kitsu user's completed list */
+export const KitsuImportInputSchema = z.object({
+    kitsuUsername: z
+        .string()
+        .min(2)
+        .max(30)
+        .describe("Kitsu username to import"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(15)
+        .default(5)
+        .describe("Number of recommendations to return (default 5, max 15)"),
+});
 /** Input for character search */
 export const CharacterSearchInputSchema = z.object({
     query: z

package/dist/tools/import.js

@@ -1,8 +1,9 @@
 /** Import tools: cross-platform list import for recommendations */
 import { fetchMalList, mapMalGenre, mapMalFormat, } from "../api/mal-client.js";
+import { fetchKitsuList, mapKitsuFormat, } from "../api/kitsu-client.js";
 import { anilistClient } from "../api/client.js";
 import { DISCOVER_MEDIA_QUERY } from "../api/queries.js";
-import { MalImportInputSchema } from "../schemas.js";
+import { MalImportInputSchema, KitsuImportInputSchema } from "../schemas.js";
 import { throwToolError, formatMediaSummary } from "../utils.js";
 import { buildTasteProfile, describeTasteProfile, formatTasteProfileText, } from "../engine/taste.js";
 import { matchCandidates } from "../engine/matcher.js";
@@ -72,8 +73,120 @@ export function registerImportTools(server) {
             }
         },
     });
+    // === Kitsu Import ===
+    server.addTool({
+        name: "anilist_kitsu_import",
+        description: "Import a Kitsu user's completed anime list and generate " +
+            "personalized recommendations based on their taste. No auth needed. " +
+            "Use when the user mentions their Kitsu account or wants recs from Kitsu history. " +
+            "Returns a taste profile summary and recommended titles from AniList.",
+        parameters: KitsuImportInputSchema,
+        annotations: {
+            title: "Kitsu Import",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const { entries, anime } = await fetchKitsuList(args.kitsuUsername);
+                if (entries.length === 0) {
+                    return `No completed anime found for Kitsu user "${args.kitsuUsername}".`;
+                }
+                // Convert to AniList format for taste engine
+                const converted = kitsuEntriesToAniList(entries, anime);
+                const profile = buildTasteProfile(converted);
+                const lines = [
+                    `# Kitsu Import: ${args.kitsuUsername}`,
+                    `Imported ${entries.length} completed anime from Kitsu.`,
+                    "",
+                    "## Taste Profile",
+                    describeTasteProfile(profile, args.kitsuUsername),
+                    ...formatTasteProfileText(profile),
+                ];
+                // Fetch AniList candidates using top genres
+                const topGenres = profile.genres.slice(0, 3).map((g) => g.name);
+                if (topGenres.length > 0) {
+                    const candidates = await fetchDiscoverCandidates(topGenres);
+                    // Filter out titles already on Kitsu list
+                    const kitsuTitles = new Set(Array.from(anime.values()).map((a) => a.attributes.canonicalTitle.toLowerCase()));
+                    const filtered = candidates.filter((m) => !kitsuTitles.has((m.title.english ?? m.title.romaji ?? "").toLowerCase()));
+                    const ranked = matchCandidates(filtered, profile).slice(0, args.limit);
+                    lines.push("", "## Recommendations", "");
+                    if (ranked.length === 0) {
+                        lines.push("No new recommendations found.");
+                    }
+                    else {
+                        for (let i = 0; i < ranked.length; i++) {
+                            const r = ranked[i];
+                            lines.push(`${i + 1}. ${formatMediaSummary(r.media)}`);
+                            if (r.reasons.length > 0) {
+                                lines.push(`  Why: ${r.reasons.slice(0, 3).join(", ")}`);
+                            }
+                            lines.push("");
+                        }
+                    }
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "importing Kitsu list");
+            }
+        },
+    });
 }
 // === Helpers ===
+// Convert Kitsu entries to AniList format for the taste engine
+function kitsuEntriesToAniList(entries, animeMap) {
+    return entries
+        .filter((e) => e.attributes.ratingTwenty !== null && e.attributes.ratingTwenty > 0)
+        .map((e) => {
+        const animeId = e.relationships.anime.data?.id ?? "0";
+        const anime = animeMap.get(animeId);
+        const title = anime?.attributes.canonicalTitle ?? "Unknown";
+        // ratingTwenty is 2-20 scale; convert to 1-10
+        const score = Math.round((e.attributes.ratingTwenty ?? 0) / 2);
+        const avgRating = anime?.attributes.averageRating;
+        return {
+            id: parseInt(animeId, 10),
+            score,
+            progress: e.attributes.progress,
+            progressVolumes: 0,
+            status: "COMPLETED",
+            updatedAt: 0,
+            startedAt: { year: null, month: null, day: null },
+            completedAt: { year: null, month: null, day: null },
+            notes: null,
+            media: {
+                id: parseInt(animeId, 10),
+                type: "ANIME",
+                title: { romaji: title, english: title, native: null },
+                format: mapKitsuFormat(anime?.attributes.subtype ?? "TV"),
+                status: "FINISHED",
+                episodes: anime?.attributes.episodeCount ?? null,
+                duration: null,
+                chapters: null,
+                volumes: null,
+                meanScore: avgRating ? Math.round(parseFloat(avgRating)) : null,
+                averageScore: null,
+                popularity: null,
+                genres: [],
+                tags: [],
+                season: null,
+                seasonYear: null,
+                startDate: { year: null, month: null, day: null },
+                endDate: { year: null, month: null, day: null },
+                studios: { nodes: [] },
+                source: null,
+                isAdult: false,
+                coverImage: { large: null, extraLarge: null },
+                trailer: null,
+                siteUrl: `https://kitsu.io/anime/${animeId}`,
+                description: null,
+            },
+        };
+    });
+}
 // Convert MAL entries to AniList format for the taste engine
 function malEntriesToAniList(entries) {
     return entries

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.3",
   "name": "ani-mcp",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "display_name": "AniList MCP",
   "description": "A smart MCP server for AniList that gets your anime/manga taste - not just API calls.",
   "author": {
@@ -179,6 +179,30 @@
     },
     {
       "name": "anilist_compat_card"
+    },
+    {
+      "name": "anilist_mal_import"
+    },
+    {
+      "name": "anilist_kitsu_import"
+    },
+    {
+      "name": "anilist_lookup"
+    },
+    {
+      "name": "anilist_airing"
+    },
+    {
+      "name": "anilist_group_pick"
+    },
+    {
+      "name": "anilist_shared_planning"
+    },
+    {
+      "name": "anilist_follow_suggestions"
+    },
+    {
+      "name": "anilist_react"
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ani-mcp",
   "mcpName": "io.github.gavxm/ani-mcp",
-  "version": "0.12.0",
+  "version": "0.13.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.12.0",
+  "version": "0.13.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ani-mcp",
-      "version": "0.12.0",
+      "version": "0.13.0",
       "transport": {
         "type": "stdio"
       },