ani-mcp 0.1.0

package/dist/schemas.js

@@ -0,0 +1,316 @@
+/** Zod input schemas for MCP tool validation. */
+import { z } from "zod";
+// AniList usernames: 2-20 chars, alphanumeric + underscores
+const usernameSchema = z
+    .string()
+    .min(2)
+    .max(20)
+    .regex(/^[a-zA-Z0-9_]+$/, "Letters, numbers, and underscores only");
+/** Input for searching anime or manga by title and filters */
+export const SearchInputSchema = z.object({
+    query: z
+        .string()
+        .min(1, "Search query cannot be empty")
+        .describe('Search term, e.g. "steins gate", "one piece", "chainsaw man"'),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Search for anime or manga"),
+    genre: z
+        .string()
+        .optional()
+        .describe('Filter by genre, e.g. "Action", "Romance", "Thriller"'),
+    year: z
+        .number()
+        .int()
+        .min(1940)
+        .max(2030)
+        .optional()
+        .describe("Filter by release year"),
+    format: z
+        .enum([
+        "TV",
+        "MOVIE",
+        "OVA",
+        "ONA",
+        "SPECIAL",
+        "MANGA",
+        "NOVEL",
+        "ONE_SHOT",
+    ])
+        .optional()
+        .describe("Filter by format (TV, MOVIE, etc.)"),
+    isAdult: z
+        .boolean()
+        .default(false)
+        .describe("Include adult (18+) content in results"),
+    // Capped at 25. Sending 100 results to an LLM wastes context window.
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(25)
+        .default(10)
+        .describe("Number of results to return (default 10, max 25)"),
+});
+/** Input for looking up a single anime or manga by ID or title */
+export const DetailsInputSchema = z
+    .object({
+    id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("AniList media ID (e.g. 1 for Cowboy Bebop). Use this if you know the exact ID."),
+    title: z
+        .string()
+        .optional()
+        .describe('Search by title if no ID is known (e.g. "Attack on Titan"). Finds the best match.'),
+})
+    .refine((data) => data.id !== undefined || data.title !== undefined, {
+    message: "Provide either an id or a title to look up.",
+});
+/** Input for fetching a user's anime or manga list */
+export const ListInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Get anime or manga list"),
+    status: z
+        .enum(["CURRENT", "COMPLETED", "PLANNING", "DROPPED", "PAUSED", "ALL"])
+        .default("ALL")
+        .describe("Filter by list status. CURRENT = watching/reading now."),
+    sort: z
+        .enum(["SCORE", "TITLE", "UPDATED", "PROGRESS"])
+        .default("UPDATED")
+        .describe("How to sort results"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(25)
+        .describe("Maximum entries to return (default 25, max 100)"),
+});
+/** Input for generating a taste profile summary */
+export const TasteInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    type: z
+        .enum(["ANIME", "MANGA", "BOTH"])
+        .default("BOTH")
+        .describe("Analyze anime list, manga list, or both"),
+});
+/** Input for personalized recommendations from the user's planning list */
+export const PickInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Recommend from anime or manga planning list"),
+    mood: z
+        .string()
+        .optional()
+        .describe('Freeform mood or vibe, e.g. "something dark", "chill and wholesome", "hype action"'),
+    maxEpisodes: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Filter out series longer than this episode count"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(15)
+        .default(5)
+        .describe("Number of recommendations to return (default 5, max 15)"),
+});
+/** Input for comparing taste profiles between two users */
+export const CompareInputSchema = z.object({
+    user1: usernameSchema.describe("First AniList username"),
+    user2: usernameSchema.describe("Second AniList username"),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Compare anime or manga taste"),
+});
+const MAX_YEAR = new Date().getFullYear() + 2;
+/** Input for browsing anime by season */
+export const SeasonalInputSchema = z.object({
+    season: z
+        .enum(["WINTER", "SPRING", "SUMMER", "FALL"])
+        .optional()
+        .describe("Season to browse. Defaults to the current season."),
+    year: z
+        .number()
+        .int()
+        .min(1940)
+        .max(MAX_YEAR)
+        .optional()
+        .describe("Year to browse. Defaults to the current year."),
+    sort: z
+        .enum(["POPULARITY", "SCORE", "TRENDING"])
+        .default("POPULARITY")
+        .describe("How to rank results"),
+    isAdult: z
+        .boolean()
+        .default(false)
+        .describe("Include adult (18+) content in results"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .default(15)
+        .describe("Number of results to return (default 15, max 50)"),
+});
+/** Input for fetching user statistics */
+export const StatsInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+});
+/** Input for year-in-review summary */
+export const WrappedInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    year: z
+        .number()
+        .int()
+        .min(2000)
+        .max(MAX_YEAR)
+        .optional()
+        .describe("Year to summarize. Defaults to the current year."),
+    type: z
+        .enum(["ANIME", "MANGA", "BOTH"])
+        .default("BOTH")
+        .describe("Summarize anime, manga, or both"),
+});
+/** Input for trending anime/manga */
+export const TrendingInputSchema = z.object({
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Show trending anime or manga"),
+    isAdult: z
+        .boolean()
+        .default(false)
+        .describe("Include adult (18+) content in results"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(25)
+        .default(10)
+        .describe("Number of results to return (default 10, max 25)"),
+});
+/** Input for browsing by genre */
+export const GenreBrowseInputSchema = z.object({
+    genre: z
+        .string()
+        .describe('Genre to browse, e.g. "Action", "Romance", "Horror"'),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Browse anime or manga"),
+    year: z
+        .number()
+        .int()
+        .min(1940)
+        .max(MAX_YEAR)
+        .optional()
+        .describe("Filter by release year"),
+    status: z
+        .enum(["FINISHED", "RELEASING", "NOT_YET_RELEASED", "CANCELLED", "HIATUS"])
+        .optional()
+        .describe("Filter by airing/publishing status"),
+    format: z
+        .enum([
+        "TV",
+        "MOVIE",
+        "OVA",
+        "ONA",
+        "SPECIAL",
+        "MANGA",
+        "NOVEL",
+        "ONE_SHOT",
+    ])
+        .optional()
+        .describe("Filter by format"),
+    sort: z
+        .enum(["SCORE", "POPULARITY", "TRENDING"])
+        .default("SCORE")
+        .describe("How to rank results"),
+    isAdult: z
+        .boolean()
+        .default(false)
+        .describe("Include adult (18+) content in results"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(25)
+        .default(10)
+        .describe("Number of results to return (default 10, max 25)"),
+});
+/** Input for staff/VA credits lookup */
+export const StaffInputSchema = z
+    .object({
+    id: z.number().int().positive().optional().describe("AniList media ID"),
+    title: z.string().optional().describe("Search by title if no ID is known"),
+})
+    .refine((data) => data.id !== undefined || data.title !== undefined, {
+    message: "Provide either an id or a title.",
+});
+/** Input for airing schedule lookup */
+export const ScheduleInputSchema = z
+    .object({
+    id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("AniList media ID for the anime"),
+    title: z.string().optional().describe("Search by title if no ID is known"),
+})
+    .refine((data) => data.id !== undefined || data.title !== undefined, {
+    message: "Provide either an id or a title.",
+});
+/** Input for character search */
+export const CharacterSearchInputSchema = z.object({
+    query: z
+        .string()
+        .min(1, "Search query cannot be empty")
+        .describe('Character name to search for, e.g. "Goku", "Levi Ackerman"'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .default(5)
+        .describe("Number of results to return (default 5, max 10)"),
+});
+/** Input for community recommendations for a specific title */
+export const RecommendationsInputSchema = z
+    .object({
+    id: z.number().int().positive().optional().describe("AniList media ID"),
+    title: z.string().optional().describe("Search by title if no ID is known"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(25)
+        .default(10)
+        .describe("Number of recommendations to return (default 10, max 25)"),
+})
+    .refine((data) => data.id !== undefined || data.title !== undefined, {
+    message: "Provide either an id or a title.",
+});

package/dist/tools/discover.d.ts

@@ -0,0 +1,4 @@
+/** Discovery tools: trending and genre browsing without search terms. */
+import type { FastMCP } from "fastmcp";
+/** Register discovery tools on the MCP server */
+export declare function registerDiscoverTools(server: FastMCP): void;

package/dist/tools/discover.js

@@ -0,0 +1,94 @@
+/** Discovery tools: trending and genre browsing without search terms. */
+import { anilistClient } from "../api/client.js";
+import { TRENDING_MEDIA_QUERY, GENRE_BROWSE_QUERY } from "../api/queries.js";
+import { TrendingInputSchema, GenreBrowseInputSchema } from "../schemas.js";
+import { formatMediaSummary, throwToolError } from "../utils.js";
+/** Register discovery tools on the MCP server */
+export function registerDiscoverTools(server) {
+    // === Trending ===
+    server.addTool({
+        name: "anilist_trending",
+        description: "Show what's trending on AniList right now. " +
+            "Use when the user asks what's hot, trending, or generating buzz. " +
+            "No search term needed - returns titles ranked by current trending score.",
+        parameters: TrendingInputSchema,
+        execute: async (args) => {
+            try {
+                const data = await anilistClient.query(TRENDING_MEDIA_QUERY, {
+                    type: args.type,
+                    isAdult: args.isAdult ? undefined : false,
+                    page: 1,
+                    perPage: args.limit,
+                }, { cache: "search" });
+                const results = data.Page.media;
+                if (!results.length) {
+                    return `No trending ${args.type.toLowerCase()} found.`;
+                }
+                const header = [
+                    `Trending ${args.type} right now (${data.Page.pageInfo.total} total, showing ${results.length})`,
+                    "",
+                ].join("\n");
+                const formatted = results.map((m, i) => `${i + 1}. ${formatMediaSummary(m)}`);
+                return header + formatted.join("\n\n");
+            }
+            catch (error) {
+                return throwToolError(error, "fetching trending");
+            }
+        },
+    });
+    // === Genre Browse ===
+    server.addTool({
+        name: "anilist_genres",
+        description: "Browse top anime or manga in a specific genre. " +
+            "Use when the user asks for the best titles in a genre, " +
+            'e.g. "best romance anime" or "top thriller manga from 2023". ' +
+            "No search term needed - discovers by genre with optional year/status/format filters.",
+        parameters: GenreBrowseInputSchema,
+        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,
+                    isAdult: args.isAdult ? undefined : false,
+                    page: 1,
+                    perPage: args.limit,
+                };
+                if (args.year)
+                    variables.year = args.year;
+                if (args.status)
+                    variables.status = args.status;
+                if (args.format)
+                    variables.format = args.format;
+                const data = await anilistClient.query(GENRE_BROWSE_QUERY, variables, { cache: "search" });
+                const results = data.Page.media;
+                if (!results.length) {
+                    return `No ${args.type.toLowerCase()} found in genre "${args.genre}".`;
+                }
+                const filters = [];
+                if (args.year)
+                    filters.push(`${args.year}`);
+                if (args.status)
+                    filters.push(args.status.replace(/_/g, " "));
+                if (args.format)
+                    filters.push(args.format);
+                const filterStr = filters.length > 0 ? ` (${filters.join(", ")})` : "";
+                const header = [
+                    `Top ${args.genre} ${args.type}${filterStr}`,
+                    `${data.Page.pageInfo.total} total, showing ${results.length} by ${args.sort.toLowerCase()}`,
+                    "",
+                ].join("\n");
+                const formatted = results.map((m, i) => `${i + 1}. ${formatMediaSummary(m)}`);
+                return header + formatted.join("\n\n");
+            }
+            catch (error) {
+                return throwToolError(error, "browsing genres");
+            }
+        },
+    });
+}

package/dist/tools/info.d.ts

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

package/dist/tools/info.js

@@ -0,0 +1,172 @@
+/** Info tools: staff credits, airing schedule, and character search. */
+import { anilistClient } from "../api/client.js";
+import { STAFF_QUERY, AIRING_SCHEDULE_QUERY, CHARACTER_SEARCH_QUERY, } from "../api/queries.js";
+import { StaffInputSchema, ScheduleInputSchema, CharacterSearchInputSchema, } from "../schemas.js";
+import { getTitle, throwToolError } from "../utils.js";
+// === Helpers ===
+/** Format seconds until airing as a readable duration */
+function formatTimeUntil(seconds) {
+    if (seconds <= 0)
+        return "aired";
+    const days = Math.floor(seconds / 86400);
+    const hours = Math.floor((seconds % 86400) / 3600);
+    if (days > 0)
+        return `${days}d ${hours}h`;
+    const mins = Math.floor((seconds % 3600) / 60);
+    return hours > 0 ? `${hours}h ${mins}m` : `${mins}m`;
+}
+// === Tool Registration ===
+/** Register info tools on the MCP server */
+export function registerInfoTools(server) {
+    // === Staff Credits ===
+    server.addTool({
+        name: "anilist_staff",
+        description: "Get staff and voice actor credits for an anime or manga. " +
+            "Use when the user asks who directed, wrote, or voiced characters in a title. " +
+            "Shows directors, writers, character designers, and Japanese voice actors.",
+        parameters: StaffInputSchema,
+        execute: async (args) => {
+            try {
+                const variables = {};
+                if (args.id)
+                    variables.id = args.id;
+                if (args.title)
+                    variables.search = args.title;
+                const data = await anilistClient.query(STAFF_QUERY, variables, { cache: "media" });
+                const m = data.Media;
+                const lines = [
+                    `# Staff: ${getTitle(m.title)}`,
+                    `Format: ${m.format ?? "Unknown"}`,
+                    "",
+                ];
+                // Staff roles (director, writer, etc.)
+                if (m.staff.edges.length > 0) {
+                    lines.push("## Production Staff");
+                    for (const edge of m.staff.edges) {
+                        const name = edge.node.name.full;
+                        const native = edge.node.name.native
+                            ? ` (${edge.node.name.native})`
+                            : "";
+                        lines.push(`  ${edge.role}: ${name}${native}`);
+                    }
+                    lines.push("");
+                }
+                // Characters with voice actors
+                if (m.characters.edges.length > 0) {
+                    lines.push("## Characters & Voice Actors");
+                    for (const edge of m.characters.edges) {
+                        const charName = edge.node.name.full;
+                        const role = edge.role;
+                        const va = edge.voiceActors[0];
+                        const vaStr = va ? ` - VA: ${va.name.full}` : "";
+                        lines.push(`  ${charName} (${role})${vaStr}`);
+                    }
+                    lines.push("");
+                }
+                lines.push(`AniList: ${m.siteUrl}`);
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "fetching staff");
+            }
+        },
+    });
+    // === Airing Schedule ===
+    server.addTool({
+        name: "anilist_schedule",
+        description: "Get the airing schedule for an anime. " +
+            "Use when the user asks when the next episode airs, " +
+            "or wants to see upcoming episode dates for a currently airing show.",
+        parameters: ScheduleInputSchema,
+        execute: async (args) => {
+            try {
+                const variables = { notYetAired: true };
+                if (args.id)
+                    variables.id = args.id;
+                if (args.title)
+                    variables.search = args.title;
+                const data = await anilistClient.query(AIRING_SCHEDULE_QUERY, variables, { cache: "search" });
+                const m = data.Media;
+                const lines = [
+                    `# Schedule: ${getTitle(m.title)}`,
+                    `Status: ${m.status?.replace(/_/g, " ") ?? "Unknown"}`,
+                ];
+                if (m.episodes)
+                    lines.push(`Episodes: ${m.episodes}`);
+                // Next episode
+                if (m.nextAiringEpisode) {
+                    const next = m.nextAiringEpisode;
+                    const date = new Date(next.airingAt * 1000);
+                    lines.push("");
+                    lines.push(`Next Episode: ${next.episode}`);
+                    lines.push(`Airs: ${date.toLocaleDateString("en-US", { weekday: "long", month: "short", day: "numeric" })} ` +
+                        `at ${date.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit" })}`);
+                    lines.push(`In: ${formatTimeUntil(next.timeUntilAiring)}`);
+                }
+                else {
+                    lines.push("", "No upcoming episodes scheduled.");
+                }
+                // Upcoming episodes
+                const upcoming = m.airingSchedule.nodes.filter((n) => n.timeUntilAiring > 0);
+                if (upcoming.length > 1) {
+                    lines.push("", "Upcoming:");
+                    for (const ep of upcoming.slice(0, 8)) {
+                        const date = new Date(ep.airingAt * 1000);
+                        const dateStr = date.toLocaleDateString("en-US", {
+                            month: "short",
+                            day: "numeric",
+                        });
+                        lines.push(`  Ep ${ep.episode}: ${dateStr} (${formatTimeUntil(ep.timeUntilAiring)})`);
+                    }
+                }
+                lines.push("", `AniList: ${m.siteUrl}`);
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "fetching schedule");
+            }
+        },
+    });
+    // === Character Search ===
+    server.addTool({
+        name: "anilist_characters",
+        description: "Search for anime/manga characters by name. " +
+            "Use when the user asks about a specific character, wants to know " +
+            "which series a character appears in, or who voices them.",
+        parameters: CharacterSearchInputSchema,
+        execute: async (args) => {
+            try {
+                const data = await anilistClient.query(CHARACTER_SEARCH_QUERY, { search: args.query, page: 1, perPage: args.limit }, { cache: "search" });
+                const results = data.Page.characters;
+                if (!results.length) {
+                    return `No characters found matching "${args.query}".`;
+                }
+                const lines = [
+                    `Found ${data.Page.pageInfo.total} character(s) matching "${args.query}"`,
+                    "",
+                ];
+                for (let i = 0; i < results.length; i++) {
+                    const char = results[i];
+                    const native = char.name.native ? ` (${char.name.native})` : "";
+                    const favs = char.favourites > 0
+                        ? ` - ${char.favourites.toLocaleString()} favorites`
+                        : "";
+                    lines.push(`${i + 1}. ${char.name.full}${native}${favs}`);
+                    // Appearances
+                    for (const edge of char.media.edges.slice(0, 3)) {
+                        const mediaTitle = edge.node.title.english || edge.node.title.romaji || "?";
+                        const va = edge.voiceActors[0];
+                        const vaStr = va ? ` (VA: ${va.name.full})` : "";
+                        lines.push(`   ${edge.characterRole}: ${mediaTitle} (${edge.node.format ?? edge.node.type})${vaStr}`);
+                    }
+                    lines.push(`   URL: ${char.siteUrl}`);
+                    lines.push("");
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "searching characters");
+            }
+        },
+    });
+}

package/dist/tools/lists.d.ts

@@ -0,0 +1,4 @@
+/** User list tools: fetch and display a user's anime/manga list. */
+import type { FastMCP } from "fastmcp";
+/** Register user list tools on the MCP server */
+export declare function registerListTools(server: FastMCP): void;