anime-filler-mcp 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# anime filler mcp
+
+The question every weeb asks: **is this episode filler?**
+
+Powered by [animefillerlist.com](https://www.animefillerlist.com) (scraped
+politely, no official API exists).
+
+## Tools
+
+- `search_anime`, find an anime, get its slug
+- `get_episode_lists`, full canon/filler breakdown with episode ranges
+- `is_episode_filler`, verdict for one episode, with title + air date
+
+## Run
+
+```bash
+npm install && npm run build && node dist/index.js
+```
+
+## Example
+
+> "Is Naruto Shippuden episode 57 filler?"
+>
+> `is_episode_filler("naruto-shippuden", 57)` →
+> "Episode 57 of Naruto Shippuden is FILLER, skippable, safe to skip.
+> Title: 'Robbed of Sleep' (aired 2008-05-08)"
+
+> "Which One Piece episodes can I skip?"
+> `get_episode_lists("one-piece")` → 1010 canon, 94 filler, with ranges.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `search_anime`: Search for an anime on animefillerlist.com and return its slug
+- `get_episode_lists`: Get the full canon/filler episode breakdown for an anime by slug.
+- `is_episode_filler`: Ask whether a specific episode is filler or canon. The question every weeb asks.
+
+## Limits and privacy
+
+This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. No credentials are required unless the project explicitly says otherwise.
+
+## Try it
+
+After building, connect the server through your MCP client. The repository root also contains `smoke-test.mjs` for projects covered by the shared harness. A typical tool call starts with `search_anime`.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Anime Filler MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/scraper.d.ts

@@ -0,0 +1,40 @@
+/**
+ * animefillerlist.com scraper.
+ *
+ * The site tracks which anime episodes are manga canon, mixed
+ * canon/filler, anime canon, or pure filler. No official API, so this
+ * is a polite HTML scraper.
+ *
+ * Show pages contain an episode table — one <tr id="eps-N"> per episode
+ * with a Number cell, a Title cell, and a Type cell (Manga Canon,
+ * Mixed Canon/Filler, Anime Canon, Filler...). We parse that table.
+ */
+export declare class ScrapeError extends Error {
+}
+export interface AnimeResult {
+    title: string;
+    slug: string;
+    url: string;
+}
+export interface Episode {
+    number: number;
+    title: string;
+    category: string;
+    date?: string;
+}
+export interface EpisodeCategory {
+    label: string;
+    episodes: number[];
+}
+export interface ShowInfo {
+    title: string;
+    slug: string;
+    url: string;
+    totalEpisodes?: number;
+    status?: string;
+    categories: EpisodeCategory[];
+    episodes: Episode[];
+}
+export declare function searchAnime(query: string): Promise<AnimeResult[]>;
+export declare function getShow(slug: string): Promise<ShowInfo>;
+export declare function verdict(info: ShowInfo, episode: number): string;

package/dist/scraper.js

@@ -0,0 +1,173 @@
+/**
+ * animefillerlist.com scraper.
+ *
+ * The site tracks which anime episodes are manga canon, mixed
+ * canon/filler, anime canon, or pure filler. No official API, so this
+ * is a polite HTML scraper.
+ *
+ * Show pages contain an episode table — one <tr id="eps-N"> per episode
+ * with a Number cell, a Title cell, and a Type cell (Manga Canon,
+ * Mixed Canon/Filler, Anime Canon, Filler...). We parse that table.
+ */
+import * as cheerio from "cheerio";
+const BASE = "https://www.animefillerlist.com";
+const UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) " +
+    "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36";
+export class ScrapeError extends Error {
+}
+async function fetchHtml(url) {
+    const res = await fetch(url, {
+        headers: {
+            "User-Agent": UA,
+            Accept: "text/html,application/xhtml+xml",
+            "Accept-Language": "en-US,en;q=0.9",
+        },
+    });
+    if (!res.ok) {
+        throw new ScrapeError(`HTTP ${res.status} fetching ${url}`);
+    }
+    return await res.text();
+}
+// ---------------------------------------------------------------------------
+// Search
+// ---------------------------------------------------------------------------
+export async function searchAnime(query) {
+    const html = await fetchHtml(`${BASE}/search/node?keys=${encodeURIComponent(query)}`);
+    const $ = cheerio.load(html);
+    const results = [];
+    $(".search-results a, ol li h3 a, li h3 a").each((_, el) => {
+        const href = $(el).attr("href") ?? "";
+        const m = /\/shows\/([\w-]+)/.exec(href);
+        if (!m)
+            return;
+        const title = $(el).text().trim();
+        if (!title)
+            return;
+        results.push({ title, slug: m[1], url: `${BASE}/shows/${m[1]}` });
+    });
+    if (results.length === 0) {
+        $('a[href*="/shows/"]').each((_, el) => {
+            const href = $(el).attr("href") ?? "";
+            const m = /\/shows\/([\w-]+)/.exec(href);
+            if (!m)
+                return;
+            const title = $(el).text().trim();
+            if (!title || results.some((r) => r.slug === m[1]))
+                return;
+            results.push({ title, slug: m[1], url: `${BASE}/shows/${m[1]}` });
+        });
+    }
+    return dedupe(results).slice(0, 10);
+}
+// ---------------------------------------------------------------------------
+// Show page
+// ---------------------------------------------------------------------------
+export async function getShow(slug) {
+    const url = `${BASE}/shows/${slug}`;
+    const html = await fetchHtml(url);
+    const $ = cheerio.load(html);
+    const rawTitle = $("h1").first().text().trim() || slug.replace(/-/g, " ");
+    const title = rawTitle.replace(/\s*Filler List\s*$/i, "").trim();
+    const headerText = $("#main-content, .content, main").first().text();
+    const status = /Status:\s*([^,\n]+)/i.exec(headerText);
+    // The episode table is the ground truth.
+    const episodes = [];
+    $("tr[id^='eps-']").each((_, el) => {
+        const $el = $(el);
+        const number = parseInt($el.find("td.Number").text().trim(), 10);
+        const category = $el.find("td.Type span, td.Type").first().text().trim();
+        if (!number || !category)
+            return;
+        episodes.push({
+            number,
+            category,
+            title: $el.find("td.Title").text().trim() || "?",
+            date: $el.find("td.Date").text().trim() || undefined,
+        });
+    });
+    // Group by category label.
+    const byLabel = new Map();
+    for (const ep of episodes) {
+        const arr = byLabel.get(ep.category) ?? [];
+        arr.push(ep.number);
+        byLabel.set(ep.category, arr);
+    }
+    const categories = [...byLabel.entries()].map(([label, nums]) => ({ label, episodes: nums.sort((a, b) => a - b) }));
+    // If the table was empty, fall back to the condensed quick-list.
+    if (episodes.length === 0) {
+        $("#Condensed strong").each((_, el) => {
+            const label = $(el).text().replace(/:$/, "").trim();
+            if (!label)
+                return;
+            const parsed = parseEpisodeText($(el).parent().text());
+            categories.push({ label, episodes: parsed.numbers });
+        });
+    }
+    const maxEp = episodes.reduce((m, e) => Math.max(m, e.number), 0);
+    return {
+        title,
+        slug,
+        url,
+        totalEpisodes: maxEp || undefined,
+        status: status?.[1]?.trim(),
+        categories,
+        episodes,
+    };
+}
+export function verdict(info, episode) {
+    if (episode <= 0)
+        return "Episode numbers start at 1.";
+    const total = info.totalEpisodes;
+    if (total && episode > total) {
+        return `Episode ${episode} is past the show's ${total} episodes.`;
+    }
+    const ep = info.episodes.find((e) => e.number === episode);
+    if (ep) {
+        const verdicts = {
+            "Manga Canon": "MANGA CANON — essential, do not skip",
+            "Mixed Canon/Filler": "MIXED CANON/FILLER — watch it, half of it counts",
+            "Anime Canon": "ANIME CANON — watchable, canon to the anime universe",
+            Filler: "FILLER — skippable, safe to skip",
+            "Semi-Filler": "SEMI-FILLER — partial skip",
+        };
+        const v = verdicts[ep.category] ??
+            (ep.category.includes("Filler") ? "FILLER-ish" : "CANON-ish");
+        return (`Episode ${episode} of ${info.title} is ${v}.` +
+            (ep.title !== "?" ? `\nTitle: "${ep.title}"` : "") +
+            (ep.date ? ` (aired ${ep.date})` : ""));
+    }
+    if (info.episodes.length > 0) {
+        return `Episode ${episode} of ${info.title} isn't in the tracked list (episodes go up to ${info.totalEpisodes}).`;
+    }
+    return `No episode data could be parsed for ${info.title}. The site's layout may have changed.`;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function parseEpisodeText(raw) {
+    const display = raw.replace(/\s+/g, " ").trim().slice(0, 300);
+    const numbers = new Set();
+    const tokenRe = /(\d+)\s*-\s*(\d+)|(\d+)/g;
+    let m;
+    while ((m = tokenRe.exec(raw)) !== null) {
+        if (m[1] !== undefined && m[2] !== undefined) {
+            const lo = Math.min(parseInt(m[1], 10), parseInt(m[2], 10));
+            const hi = Math.max(parseInt(m[1], 10), parseInt(m[2], 10));
+            for (let e = lo; e <= hi; e++)
+                numbers.add(e);
+        }
+        else if (m[3] !== undefined) {
+            numbers.add(parseInt(m[3], 10));
+        }
+    }
+    return { numbers: [...numbers].sort((a, b) => a - b), display };
+}
+function dedupe(results) {
+    const seen = new Set();
+    return results.filter((r) => {
+        if (seen.has(r.slug))
+            return false;
+        seen.add(r.slug);
+        return true;
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,105 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ScrapeError, getShow, searchAnime, verdict } from "./scraper.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "anime-filler-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("search_anime", {
+        title: "Search anime",
+        description: "Search for an anime on animefillerlist.com and return its slug " +
+            "for the other tools.",
+        inputSchema: z.object({ query: z.string().describe("Anime title, e.g. 'Naruto Shippuden' or 'One Piece'") }),
+        annotations: READ_ONLY,
+    }, async ({ query }) => {
+        try {
+            const results = await searchAnime(query);
+            if (results.length === 0) {
+                return text(`No anime found for "${query}".`);
+            }
+            return text(`Anime matching "${query}":\n` +
+                results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url} (slug: ${r.slug})`).join("\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_episode_lists", {
+        title: "Get episode lists",
+        description: "Get the full canon/filler episode breakdown for an anime by slug.",
+        inputSchema: z.object({ slug: z.string().describe("Anime slug from search_anime, e.g. 'naruto-shippuden'") }),
+        annotations: READ_ONLY,
+    }, async ({ slug }) => {
+        try {
+            const info = await getShow(slug);
+            const head = `${info.title} — ${info.totalEpisodes ? info.totalEpisodes + " episodes" : "?"}` +
+                (info.status ? `, ${info.status}` : "") +
+                `\n${info.url}\n`;
+            if (info.categories.length === 0) {
+                return text(head + "No episode categories could be parsed from the page.");
+            }
+            const body = info.categories
+                .map((c) => `• ${c.label} (${c.episodes.length} eps): ${formatRanges(c.episodes)}`)
+                .join("\n");
+            const sample = info.episodes.length > 0
+                ? `\n\nSample (first 8):\n` +
+                    info.episodes
+                        .slice(0, 8)
+                        .map((e) => `  ep${e.number} [${e.category}] ${e.title}`)
+                        .join("\n")
+                : "";
+            return text(head + "\n" + body + sample);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("is_episode_filler", {
+        title: "Is episode filler",
+        description: "Ask whether a specific episode is filler or canon. The question every weeb asks.",
+        inputSchema: z.object({
+            slug: z.string().describe("Anime slug from search_anime"),
+            episode: z.number().int().min(1).describe("Episode number"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ slug, episode }) => {
+        try {
+            const info = await getShow(slug);
+            return text(verdict(info, episode));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof ScrapeError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}
+/** Compact "1-17, 20-21, 35" representation of a sorted episode list. */
+function formatRanges(nums) {
+    if (nums.length === 0)
+        return "—";
+    const parts = [];
+    let start = nums[0];
+    let prev = nums[0];
+    for (let i = 1; i <= nums.length; i++) {
+        const n = nums[i];
+        if (n === prev + 1) {
+            prev = n;
+            continue;
+        }
+        parts.push(start === prev ? `${start}` : `${start}-${prev}`);
+        start = prev = n;
+    }
+    const s = parts.join(", ");
+    return s.length > 160 ? s.slice(0, 157) + "…" : s;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "anime-filler-mcp",
+  "version": "1.0.0",
+  "description": "Use this MCP server to tells you which anime episodes are filler vs canon. Powered by animefillerlist.com",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/anime-filler-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/anime-filler-mcp.git"
+  },
+  "bin": {
+    "anime-filler-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "anime",
+    "filler",
+    "canon",
+    "episodes",
+    "weeb"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "cheerio": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}