ani-mcp 0.3.0 → 0.5.0

package/README.md

@@ -5,6 +5,7 @@
 # ani-mcp
 
 [![npm version](https://img.shields.io/npm/v/ani-mcp)](https://www.npmjs.com/package/ani-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/ani-mcp)](https://www.npmjs.com/package/ani-mcp)
 [![CI](https://github.com/gavxm/ani-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/gavxm/ani-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Node](https://img.shields.io/node/v/ani-mcp)](https://nodejs.org)

package/dist/api/client.d.ts

@@ -4,7 +4,7 @@
  * Handles rate limiting (token bucket), retry with exponential backoff,
  * and in-memory caching.
  */
-import type { AniListMediaListEntry } from "../types.js";
+import type { AniListMediaListEntry, UserListResponse } from "../types.js";
 /** Per-category TTLs for the query cache */
 export declare const CACHE_TTLS: {
     readonly media: number;
@@ -31,6 +31,8 @@ declare class AniListClient {
     constructor();
     /** Execute a GraphQL query with caching and automatic retry */
     query<T = unknown>(query: string, variables?: Record<string, unknown>, options?: QueryOptions): Promise<T>;
+    /** Fetch a user's media list groups with metadata (name, status, isCustomList) */
+    fetchListGroups(username: string, type: string, status?: string, sort?: string[]): Promise<UserListResponse["MediaListCollection"]["lists"]>;
     /** Fetch a user's media list, flattened into a single array */
     fetchList(username: string, type: string, status?: string, sort?: string[]): Promise<AniListMediaListEntry[]>;
     /** Invalidate the entire query cache */

package/dist/api/client.js

@@ -9,8 +9,8 @@ import pRetry, { AbortError } from "p-retry";
 import pThrottle from "p-throttle";
 import { USER_LIST_QUERY } from "./queries.js";
 const ANILIST_API_URL = process.env.ANILIST_API_URL || "https://graphql.anilist.co";
-// Budget under the 90 req/min limit to leave headroom
-const RATE_LIMIT_PER_MINUTE = 85;
+// No rate limit needed when API is mocked in tests
+const RATE_LIMIT_PER_MINUTE = process.env.VITEST ? 10_000 : 85;
 const MAX_RETRIES = 3;
 // Hard timeout per fetch attempt (retries get their own timeout)
 const FETCH_TIMEOUT_MS = 15_000;
@@ -87,17 +87,22 @@ class AniListClient {
         // No cache category - skip caching entirely
         return this.executeWithRetry(query, variables);
     }
-    /** Fetch a user's media list, flattened into a single array */
-    async fetchList(username, type, status, sort) {
+    /** Fetch a user's media list groups with metadata (name, status, isCustomList) */
+    async fetchListGroups(username, type, status, sort) {
         const variables = { userName: username, type };
         if (status)
             variables.status = status;
         if (sort)
             variables.sort = sort;
         const data = await this.query(USER_LIST_QUERY, variables, { cache: "list" });
+        return data.MediaListCollection.lists;
+    }
+    /** Fetch a user's media list, flattened into a single array */
+    async fetchList(username, type, status, sort) {
+        const lists = await this.fetchListGroups(username, type, status, sort);
         // Flatten across status groups
         const entries = [];
-        for (const list of data.MediaListCollection.lists) {
+        for (const list of lists) {
             entries.push(...list.entries);
         }
         return entries;

package/dist/api/queries.d.ts

@@ -5,21 +5,21 @@
  * if the AniList schema changes.
  */
 /** Paginated search with optional genre, year, and format filters */
-export declare const SEARCH_MEDIA_QUERY = "\n  query SearchMedia(\n    $search: String!\n    $type: MediaType\n    $genre: [String]\n    $year: Int\n    $format: MediaFormat\n    $isAdult: Boolean\n    $page: Int\n    $perPage: Int\n    $sort: [MediaSort]\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo {\n        total\n        currentPage\n        lastPage\n        hasNextPage\n      }\n      media(\n        search: $search\n        type: $type\n        genre_in: $genre\n        startDate_year: $year\n        format: $format\n        isAdult: $isAdult\n        sort: $sort\n      ) {\n        ...MediaFields\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
+export declare const SEARCH_MEDIA_QUERY = "\n  query SearchMedia(\n    $search: String!\n    $type: MediaType\n    $genre: [String]\n    $year: Int\n    $format: MediaFormat\n    $isAdult: Boolean\n    $page: Int\n    $perPage: Int\n    $sort: [MediaSort]\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo {\n        total\n        currentPage\n        lastPage\n        hasNextPage\n      }\n      media(\n        search: $search\n        type: $type\n        genre_in: $genre\n        startDate_year: $year\n        format: $format\n        isAdult: $isAdult\n        sort: $sort\n      ) {\n        ...MediaFields\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    duration\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** Full media lookup with relations and recommendations */
-export declare const MEDIA_DETAILS_QUERY = "\n  query MediaDetails($id: Int, $search: String) {\n    Media(id: $id, search: $search) {\n      ...MediaFields\n      relations {\n        edges {\n          relationType\n          node {\n            id\n            title { romaji english }\n            format\n            status\n            type\n          }\n        }\n      }\n      recommendations(sort: RATING_DESC, perPage: 5) {\n        nodes {\n          rating\n          mediaRecommendation {\n            id\n            title { romaji english }\n            format\n            meanScore\n            genres\n            siteUrl\n          }\n        }\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
+export declare const MEDIA_DETAILS_QUERY = "\n  query MediaDetails($id: Int, $search: String) {\n    Media(id: $id, search: $search) {\n      ...MediaFields\n      relations {\n        edges {\n          relationType\n          node {\n            id\n            title { romaji english }\n            format\n            status\n            type\n          }\n        }\n      }\n      recommendations(sort: RATING_DESC, perPage: 5) {\n        nodes {\n          rating\n          mediaRecommendation {\n            id\n            title { romaji english }\n            format\n            meanScore\n            genres\n            siteUrl\n          }\n        }\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    duration\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** Discover top-rated titles by genre without a search term */
-export declare const DISCOVER_MEDIA_QUERY = "\n  query DiscoverMedia(\n    $type: MediaType\n    $genre_in: [String]\n    $page: Int\n    $perPage: Int\n    $sort: [MediaSort]\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      media(type: $type, genre_in: $genre_in, sort: $sort) {\n        ...MediaFields\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
+export declare const DISCOVER_MEDIA_QUERY = "\n  query DiscoverMedia(\n    $type: MediaType\n    $genre_in: [String]\n    $page: Int\n    $perPage: Int\n    $sort: [MediaSort]\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      media(type: $type, genre_in: $genre_in, sort: $sort) {\n        ...MediaFields\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    duration\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** Browse anime by season and year */
-export declare const SEASONAL_MEDIA_QUERY = "\n  query SeasonalMedia(\n    $season: MediaSeason\n    $seasonYear: Int\n    $type: MediaType\n    $isAdult: Boolean\n    $sort: [MediaSort]\n    $page: Int\n    $perPage: Int\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total currentPage lastPage hasNextPage }\n      media(\n        season: $season\n        seasonYear: $seasonYear\n        type: $type\n        isAdult: $isAdult\n        sort: $sort\n      ) {\n        ...MediaFields\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
+export declare const SEASONAL_MEDIA_QUERY = "\n  query SeasonalMedia(\n    $season: MediaSeason\n    $seasonYear: Int\n    $type: MediaType\n    $isAdult: Boolean\n    $sort: [MediaSort]\n    $page: Int\n    $perPage: Int\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total currentPage lastPage hasNextPage }\n      media(\n        season: $season\n        seasonYear: $seasonYear\n        type: $type\n        isAdult: $isAdult\n        sort: $sort\n      ) {\n        ...MediaFields\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    duration\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** User profile statistics - watching/reading stats, genre/tag/score breakdowns */
 export declare const USER_STATS_QUERY = "\n  query UserStats($name: String!) {\n    User(name: $name) {\n      id\n      name\n      mediaListOptions {\n        scoreFormat\n      }\n      statistics {\n        anime {\n          count\n          meanScore\n          minutesWatched\n          episodesWatched\n          genres(sort: COUNT_DESC, limit: 10) {\n            genre\n            count\n            meanScore\n            minutesWatched\n          }\n          scores(sort: MEAN_SCORE_DESC) {\n            score\n            count\n          }\n          formats(sort: COUNT_DESC) {\n            format\n            count\n          }\n        }\n        manga {\n          count\n          meanScore\n          chaptersRead\n          volumesRead\n          genres(sort: COUNT_DESC, limit: 10) {\n            genre\n            count\n            meanScore\n            chaptersRead\n          }\n          scores(sort: MEAN_SCORE_DESC) {\n            score\n            count\n          }\n          formats(sort: COUNT_DESC) {\n            format\n            count\n          }\n        }\n      }\n    }\n  }\n";
 /** Media recommendations for a given title */
-export declare const RECOMMENDATIONS_QUERY = "\n  query MediaRecommendations($id: Int, $search: String, $perPage: Int) {\n    Media(id: $id, search: $search) {\n      id\n      title { romaji english native }\n      recommendations(sort: RATING_DESC, perPage: $perPage) {\n        nodes {\n          rating\n          mediaRecommendation {\n            ...MediaFields\n          }\n        }\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
+export declare const RECOMMENDATIONS_QUERY = "\n  query MediaRecommendations($id: Int, $search: String, $perPage: Int) {\n    Media(id: $id, search: $search) {\n      id\n      title { romaji english native }\n      recommendations(sort: RATING_DESC, perPage: $perPage) {\n        nodes {\n          rating\n          mediaRecommendation {\n            ...MediaFields\n          }\n        }\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    duration\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** Trending anime or manga right now */
-export declare const TRENDING_MEDIA_QUERY = "\n  query TrendingMedia(\n    $type: MediaType\n    $isAdult: Boolean\n    $page: Int\n    $perPage: Int\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      media(type: $type, isAdult: $isAdult, sort: TRENDING_DESC) {\n        ...MediaFields\n        trending\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
+export declare const TRENDING_MEDIA_QUERY = "\n  query TrendingMedia(\n    $type: MediaType\n    $isAdult: Boolean\n    $page: Int\n    $perPage: Int\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      media(type: $type, isAdult: $isAdult, sort: TRENDING_DESC) {\n        ...MediaFields\n        trending\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    duration\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** Browse by genre without a search term, with optional filters */
-export declare const GENRE_BROWSE_QUERY = "\n  query GenreBrowse(\n    $type: MediaType\n    $genre_in: [String]\n    $year: Int\n    $status: MediaStatus\n    $format: MediaFormat\n    $isAdult: Boolean\n    $sort: [MediaSort]\n    $page: Int\n    $perPage: Int\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      media(\n        type: $type\n        genre_in: $genre_in\n        startDate_year: $year\n        status: $status\n        format: $format\n        isAdult: $isAdult\n        sort: $sort\n      ) {\n        ...MediaFields\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
+export declare const GENRE_BROWSE_QUERY = "\n  query GenreBrowse(\n    $type: MediaType\n    $genre_in: [String]\n    $year: Int\n    $status: MediaStatus\n    $format: MediaFormat\n    $isAdult: Boolean\n    $sort: [MediaSort]\n    $page: Int\n    $perPage: Int\n  ) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      media(\n        type: $type\n        genre_in: $genre_in\n        startDate_year: $year\n        status: $status\n        format: $format\n        isAdult: $isAdult\n        sort: $sort\n      ) {\n        ...MediaFields\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    duration\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** Staff and voice actors for a media title */
 export declare const STAFF_QUERY = "\n  query MediaStaff($id: Int, $search: String) {\n    Media(id: $id, search: $search) {\n      id\n      title { romaji english native }\n      format\n      siteUrl\n      staff(sort: RELEVANCE, perPage: 15) {\n        edges {\n          role\n          node {\n            id\n            name { full native }\n            siteUrl\n          }\n        }\n      }\n      characters(sort: ROLE, perPage: 10) {\n        edges {\n          role\n          node {\n            id\n            name { full native }\n            siteUrl\n          }\n          voiceActors(language: JAPANESE) {\n            id\n            name { full native }\n            siteUrl\n          }\n        }\n      }\n    }\n  }\n";
 /** Airing schedule for currently airing anime */
@@ -31,12 +31,24 @@ export declare const SAVE_MEDIA_LIST_ENTRY_MUTATION = "\n  mutation SaveMediaLis
 /** Remove a list entry */
 export declare const DELETE_MEDIA_LIST_ENTRY_MUTATION = "\n  mutation DeleteMediaListEntry($id: Int!) {\n    DeleteMediaListEntry(id: $id) {\n      deleted\n    }\n  }\n";
 /** User's anime/manga list, grouped by status. Omit $status to get all lists. */
-export declare const USER_LIST_QUERY = "\n  query UserMediaList(\n    $userName: String!\n    $type: MediaType\n    $status: MediaListStatus\n    $sort: [MediaListSort]\n  ) {\n    MediaListCollection(\n      userName: $userName\n      type: $type\n      status: $status\n      sort: $sort\n    ) {\n      lists {\n        name\n        status\n        entries {\n          id\n          score(format: POINT_10)  # normalize to 1-10 scale regardless of user's profile setting\n          progress\n          status\n          updatedAt\n          startedAt { year month day }\n          completedAt { year month day }\n          notes\n          media {\n            ...MediaFields\n          }\n        }\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
+export declare const USER_LIST_QUERY = "\n  query UserMediaList(\n    $userName: String!\n    $type: MediaType\n    $status: MediaListStatus\n    $sort: [MediaListSort]\n  ) {\n    MediaListCollection(\n      userName: $userName\n      type: $type\n      status: $status\n      sort: $sort\n    ) {\n      lists {\n        name\n        status\n        isCustomList\n        entries {\n          id\n          score(format: POINT_10)  # normalize to 1-10 scale regardless of user's profile setting\n          progress\n          status\n          updatedAt\n          startedAt { year month day }\n          completedAt { year month day }\n          notes\n          media {\n            ...MediaFields\n          }\n        }\n      }\n    }\n  }\n  \n  fragment MediaFields on Media {\n    id\n    type\n    title {\n      romaji\n      english\n      native\n    }\n    format\n    status\n    episodes\n    duration\n    chapters\n    volumes\n    meanScore\n    averageScore\n    popularity\n    genres\n    tags {\n      name\n      rank\n      isMediaSpoiler\n    }\n    season\n    seasonYear\n    startDate { year month day }\n    endDate { year month day }\n    studios(isMain: true) {\n      nodes { name }\n    }\n    source\n    isAdult\n    coverImage { large }\n    siteUrl\n    description(asHtml: false)\n  }\n\n";
 /** Search for staff by name with their top works */
 export declare const STAFF_SEARCH_QUERY = "\n  query StaffSearch($search: String!, $page: Int, $perPage: Int, $mediaPerPage: Int) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      staff(search: $search, sort: SEARCH_MATCH) {\n        id\n        name { full native }\n        primaryOccupations\n        siteUrl\n        staffMedia(sort: POPULARITY_DESC, perPage: $mediaPerPage) {\n          edges {\n            staffRole\n            node {\n              id\n              title { romaji english }\n              format\n              type\n              meanScore\n              siteUrl\n            }\n          }\n        }\n      }\n    }\n  }\n";
 /** Authenticated user info */
 export declare const VIEWER_QUERY = "\n  query Viewer {\n    Viewer {\n      id\n      name\n      avatar { medium }\n      siteUrl\n      mediaListOptions {\n        scoreFormat\n      }\n    }\n  }\n";
 /** All valid genres and media tags */
 export declare const GENRE_TAG_COLLECTION_QUERY = "\n  query GenreTagCollection {\n    GenreCollection\n    MediaTagCollection {\n      name\n      description\n      category\n      isAdult\n    }\n  }\n";
+/** Toggle favourite on any entity type */
+export declare const TOGGLE_FAVOURITE_MUTATION = "\n  mutation ToggleFavourite(\n    $animeId: Int\n    $mangaId: Int\n    $characterId: Int\n    $staffId: Int\n    $studioId: Int\n  ) {\n    ToggleFavourite(\n      animeId: $animeId\n      mangaId: $mangaId\n      characterId: $characterId\n      staffId: $staffId\n      studioId: $studioId\n    ) {\n      anime { nodes { id } }\n      manga { nodes { id } }\n      characters { nodes { id } }\n      staff { nodes { id } }\n      studios { nodes { id } }\n    }\n  }\n";
+/** Post a text activity to the authenticated user's feed */
+export declare const SAVE_TEXT_ACTIVITY_MUTATION = "\n  mutation SaveTextActivity($text: String!) {\n    SaveTextActivity(text: $text) {\n      id\n      createdAt\n      text\n      user { name }\n    }\n  }\n";
+/** Recent activity for a user, supports text and list activity types */
+export declare const ACTIVITY_FEED_QUERY = "\n  query ActivityFeed($userId: Int, $type: ActivityType, $page: Int, $perPage: Int) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total currentPage hasNextPage }\n      activities(userId: $userId, type: $type, sort: ID_DESC) {\n        ... on TextActivity {\n          __typename\n          id\n          text\n          createdAt\n          user { name }\n        }\n        ... on ListActivity {\n          __typename\n          id\n          status\n          progress\n          createdAt\n          user { name }\n          media {\n            id\n            title { romaji english native }\n            type\n          }\n        }\n      }\n    }\n  }\n";
+/** User profile with bio, stats summary, and top favourites */
+export declare const USER_PROFILE_QUERY = "\n  query UserProfile($name: String) {\n    User(name: $name) {\n      id\n      name\n      about\n      avatar { large }\n      bannerImage\n      siteUrl\n      createdAt\n      updatedAt\n      donatorTier\n      statistics {\n        anime {\n          count\n          meanScore\n          episodesWatched\n          minutesWatched\n        }\n        manga {\n          count\n          meanScore\n          chaptersRead\n          volumesRead\n        }\n      }\n      favourites {\n        anime(perPage: 5) {\n          nodes { id title { romaji english native } siteUrl }\n        }\n        manga(perPage: 5) {\n          nodes { id title { romaji english native } siteUrl }\n        }\n        characters(perPage: 5) {\n          nodes { id name { full } siteUrl }\n        }\n        staff(perPage: 5) {\n          nodes { id name { full } siteUrl }\n        }\n        studios(perPage: 5) {\n          nodes { id name siteUrl }\n        }\n      }\n    }\n  }\n";
+/** Community reviews for a media title */
+export declare const MEDIA_REVIEWS_QUERY = "\n  query MediaReviews($id: Int, $search: String, $page: Int, $perPage: Int, $sort: [ReviewSort]) {\n    Media(id: $id, search: $search) {\n      id\n      title { romaji english native }\n      reviews(page: $page, perPage: $perPage, sort: $sort) {\n        pageInfo { total hasNextPage }\n        nodes {\n          id\n          score\n          summary\n          body\n          rating\n          ratingAmount\n          createdAt\n          user { name siteUrl }\n        }\n      }\n    }\n  }\n";
 /** Search for a studio by name with their productions */
 export declare const STUDIO_SEARCH_QUERY = "\n  query StudioSearch($search: String!, $perPage: Int) {\n    Studio(search: $search, sort: SEARCH_MATCH) {\n      id\n      name\n      isAnimationStudio\n      siteUrl\n      media(sort: POPULARITY_DESC, perPage: $perPage) {\n        edges {\n          isMainStudio\n          node {\n            id\n            title { romaji english }\n            format\n            type\n            status\n            meanScore\n            siteUrl\n          }\n        }\n      }\n    }\n  }\n";
+/** Batch-fetch relations for a list of media IDs */
+export declare const BATCH_RELATIONS_QUERY = "\n  query BatchRelations($ids: [Int]) {\n    Page(perPage: 50) {\n      media(id_in: $ids) {\n        id\n        title { romaji english }\n        format\n        status\n        relations {\n          edges {\n            relationType\n            node {\n              id\n              title { romaji english }\n              format\n              status\n              type\n              season\n              seasonYear\n            }\n          }\n        }\n      }\n    }\n  }\n";

package/dist/api/queries.js

@@ -17,6 +17,7 @@ const MEDIA_FRAGMENT = `
     format
     status
     episodes
+    duration
     chapters
     volumes
     meanScore
@@ -418,6 +419,7 @@ export const USER_LIST_QUERY = `
       lists {
         name
         status
+        isCustomList
         entries {
           id
           score(format: POINT_10)  # normalize to 1-10 scale regardless of user's profile setting
@@ -489,6 +491,141 @@ export const GENRE_TAG_COLLECTION_QUERY = `
     }
   }
 `;
+// === 0.4.0 Social & Favourites ===
+/** Toggle favourite on any entity type */
+export const TOGGLE_FAVOURITE_MUTATION = `
+  mutation ToggleFavourite(
+    $animeId: Int
+    $mangaId: Int
+    $characterId: Int
+    $staffId: Int
+    $studioId: Int
+  ) {
+    ToggleFavourite(
+      animeId: $animeId
+      mangaId: $mangaId
+      characterId: $characterId
+      staffId: $staffId
+      studioId: $studioId
+    ) {
+      anime { nodes { id } }
+      manga { nodes { id } }
+      characters { nodes { id } }
+      staff { nodes { id } }
+      studios { nodes { id } }
+    }
+  }
+`;
+/** Post a text activity to the authenticated user's feed */
+export const SAVE_TEXT_ACTIVITY_MUTATION = `
+  mutation SaveTextActivity($text: String!) {
+    SaveTextActivity(text: $text) {
+      id
+      createdAt
+      text
+      user { name }
+    }
+  }
+`;
+/** Recent activity for a user, supports text and list activity types */
+export const ACTIVITY_FEED_QUERY = `
+  query ActivityFeed($userId: Int, $type: ActivityType, $page: Int, $perPage: Int) {
+    Page(page: $page, perPage: $perPage) {
+      pageInfo { total currentPage hasNextPage }
+      activities(userId: $userId, type: $type, sort: ID_DESC) {
+        ... on TextActivity {
+          __typename
+          id
+          text
+          createdAt
+          user { name }
+        }
+        ... on ListActivity {
+          __typename
+          id
+          status
+          progress
+          createdAt
+          user { name }
+          media {
+            id
+            title { romaji english native }
+            type
+          }
+        }
+      }
+    }
+  }
+`;
+/** User profile with bio, stats summary, and top favourites */
+export const USER_PROFILE_QUERY = `
+  query UserProfile($name: String) {
+    User(name: $name) {
+      id
+      name
+      about
+      avatar { large }
+      bannerImage
+      siteUrl
+      createdAt
+      updatedAt
+      donatorTier
+      statistics {
+        anime {
+          count
+          meanScore
+          episodesWatched
+          minutesWatched
+        }
+        manga {
+          count
+          meanScore
+          chaptersRead
+          volumesRead
+        }
+      }
+      favourites {
+        anime(perPage: 5) {
+          nodes { id title { romaji english native } siteUrl }
+        }
+        manga(perPage: 5) {
+          nodes { id title { romaji english native } siteUrl }
+        }
+        characters(perPage: 5) {
+          nodes { id name { full } siteUrl }
+        }
+        staff(perPage: 5) {
+          nodes { id name { full } siteUrl }
+        }
+        studios(perPage: 5) {
+          nodes { id name siteUrl }
+        }
+      }
+    }
+  }
+`;
+/** Community reviews for a media title */
+export const MEDIA_REVIEWS_QUERY = `
+  query MediaReviews($id: Int, $search: String, $page: Int, $perPage: Int, $sort: [ReviewSort]) {
+    Media(id: $id, search: $search) {
+      id
+      title { romaji english native }
+      reviews(page: $page, perPage: $perPage, sort: $sort) {
+        pageInfo { total hasNextPage }
+        nodes {
+          id
+          score
+          summary
+          body
+          rating
+          ratingAmount
+          createdAt
+          user { name siteUrl }
+        }
+      }
+    }
+  }
+`;
 /** Search for a studio by name with their productions */
 export const STUDIO_SEARCH_QUERY = `
   query StudioSearch($search: String!, $perPage: Int) {
@@ -514,3 +651,30 @@ export const STUDIO_SEARCH_QUERY = `
     }
   }
 `;
+/** Batch-fetch relations for a list of media IDs */
+export const BATCH_RELATIONS_QUERY = `
+  query BatchRelations($ids: [Int]) {
+    Page(perPage: 50) {
+      media(id_in: $ids) {
+        id
+        title { romaji english }
+        format
+        status
+        relations {
+          edges {
+            relationType
+            node {
+              id
+              title { romaji english }
+              format
+              status
+              type
+              season
+              seasonYear
+            }
+          }
+        }
+      }
+    }
+  }
+`;

package/dist/engine/franchise.d.ts

@@ -0,0 +1,36 @@
+/** Franchise graph traversal for watch order guidance. */
+/** Single entry in a franchise watch order */
+export interface FranchiseEntry {
+    id: number;
+    title: string;
+    format: string | null;
+    status: string | null;
+    type: "main" | "special";
+}
+/** Media entry with its relations */
+export interface RelationNode {
+    id: number;
+    title: {
+        romaji: string | null;
+        english: string | null;
+    };
+    format: string | null;
+    status: string | null;
+    relations: {
+        edges: Array<{
+            relationType: string;
+            node: {
+                id: number;
+                title: {
+                    romaji: string | null;
+                    english: string | null;
+                };
+                format: string | null;
+                status: string | null;
+                type: string;
+            };
+        }>;
+    };
+}
+/** Build a watch order by following SEQUEL edges from the franchise root */
+export declare function buildWatchOrder(startId: number, relationsMap: Map<number, RelationNode>, includeSpecials: boolean): FranchiseEntry[];

package/dist/engine/franchise.js

@@ -0,0 +1,87 @@
+/** Franchise graph traversal for watch order guidance. */
+// Main formats in a franchise timeline
+const MAIN_FORMATS = new Set(["TV", "MOVIE", "ONA", "TV_SHORT"]);
+// Max BFS depth to prevent runaway traversal
+const MAX_DEPTH = 30;
+/** Find the earliest entry by following PREQUEL edges backward */
+function findRoot(startId, relationsMap) {
+    let current = startId;
+    const visited = new Set();
+    while (true) {
+        visited.add(current);
+        const node = relationsMap.get(current);
+        if (!node)
+            break;
+        const prequel = node.relations.edges.find((e) => e.relationType === "PREQUEL" && !visited.has(e.node.id));
+        if (!prequel)
+            break;
+        current = prequel.node.id;
+    }
+    return current;
+}
+/** Resolve format/status for a node from the map or from relation edges */
+function resolveNodeInfo(id, relationsMap) {
+    // Direct lookup
+    const node = relationsMap.get(id);
+    if (node)
+        return { format: node.format, status: node.status };
+    // Fallback: scan relation edges from other nodes
+    for (const n of relationsMap.values()) {
+        for (const edge of n.relations.edges) {
+            if (edge.node.id === id) {
+                return { format: edge.node.format, status: edge.node.status };
+            }
+        }
+    }
+    return { format: null, status: null };
+}
+/** Build a watch order by following SEQUEL edges from the franchise root */
+export function buildWatchOrder(startId, relationsMap, includeSpecials) {
+    const rootId = findRoot(startId, relationsMap);
+    const entries = [];
+    const visited = new Set();
+    // BFS through sequel and side-story edges
+    const queue = [rootId];
+    let depth = 0;
+    while (queue.length > 0 && depth < MAX_DEPTH) {
+        const id = queue.shift();
+        if (id === undefined || visited.has(id))
+            continue;
+        visited.add(id);
+        depth++;
+        const node = relationsMap.get(id);
+        const title = node
+            ? (node.title.english ?? node.title.romaji ?? "Unknown")
+            : "Unknown";
+        const { format, status } = resolveNodeInfo(id, relationsMap);
+        const isMain = MAIN_FORMATS.has(format ?? "");
+        if (isMain || includeSpecials) {
+            entries.push({
+                id,
+                title,
+                format,
+                status,
+                type: isMain ? "main" : "special",
+            });
+        }
+        if (!node)
+            continue;
+        // Collect sequels and side stories
+        const sequels = [];
+        const sides = [];
+        for (const edge of node.relations.edges) {
+            if (visited.has(edge.node.id))
+                continue;
+            if (edge.relationType === "SEQUEL") {
+                sequels.push(edge.node.id);
+            }
+            else if (includeSpecials &&
+                (edge.relationType === "SIDE_STORY" || edge.relationType === "SPIN_OFF")) {
+                sides.push(edge.node.id);
+            }
+        }
+        // Side stories appear after their parent, before the next sequel
+        queue.push(...sides, ...sequels);
+    }
+    return entries;
+}

package/dist/engine/mood.d.ts

@@ -9,12 +9,18 @@ export interface MoodModifiers {
     penalizeGenres: Set<string>;
     penalizeTags: Set<string>;
 }
+export declare function loadCustomMoods(): void;
 /** 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[];
+/** Extract mood keywords as separate genre and tag arrays */
+export declare function parseMoodFilters(mood: string): {
+    genres: string[];
+    tags: string[];
+};
 /** Suggest mood keywords that fit the current anime season */
 export declare function seasonalMoodSuggestions(): {
     season: string;

package/dist/engine/mood.js

@@ -146,16 +146,44 @@ const MOOD_SYNONYMS = {
     // competitive
     rivalry: "competitive",
     tournament: "competitive",
+    // additional natural language terms
+    psychological: "brainy",
+    thoughtful: "brainy",
+    battle: "action",
+    fighting: "action",
+    heartfelt: "sad",
+    touching: "sad",
+    lighthearted: "wholesome",
+    feel: "wholesome",
+    feels: "wholesome",
+    suspense: "intense",
+    suspenseful: "intense",
 };
 // 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];
 }
+// Load user-defined mood overrides from env
+export function loadCustomMoods() {
+    const raw = process.env.ANILIST_MOOD_CONFIG;
+    if (!raw)
+        return;
+    try {
+        const custom = JSON.parse(raw);
+        for (const [key, rule] of Object.entries(custom)) {
+            MOOD_RULES[key.toLowerCase()] = rule;
+        }
+    }
+    catch {
+        console.warn("[ani-mcp] Invalid ANILIST_MOOD_CONFIG JSON, using defaults.");
+    }
+}
+loadCustomMoods();
 // === 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
+    // Lowercase tokens, stripped of punctuation
     const words = mood
         .toLowerCase()
         .replace(/[^a-z\s]/g, "")
@@ -168,7 +196,7 @@ export function parseMood(mood) {
         const rule = MOOD_RULES[word];
         if (!rule)
             continue;
-        // Add to both genre and tag sets since we can't distinguish at parse time
+        // Add to both sets (matcher checks genres and tags separately)
         for (const name of rule.boost) {
             boostGenres.add(name);
             boostTags.add(name);
@@ -192,6 +220,40 @@ export function hasMoodMatch(mood) {
 export function getMoodKeywords() {
     return Object.keys(MOOD_RULES);
 }
+// AniList's fixed genre set (stable, rarely changes)
+const ANILIST_GENRES = new Set([
+    "Action",
+    "Adventure",
+    "Comedy",
+    "Drama",
+    "Ecchi",
+    "Fantasy",
+    "Horror",
+    "Mahou Shoujo",
+    "Mecha",
+    "Music",
+    "Mystery",
+    "Psychological",
+    "Romance",
+    "Sci-Fi",
+    "Slice of Life",
+    "Sports",
+    "Supernatural",
+    "Thriller",
+]);
+/** Extract mood keywords as separate genre and tag arrays */
+export function parseMoodFilters(mood) {
+    const mods = parseMood(mood);
+    const genres = [];
+    const tags = [];
+    for (const name of mods.boostGenres) {
+        if (ANILIST_GENRES.has(name))
+            genres.push(name);
+        else
+            tags.push(name);
+    }
+    return { genres, tags };
+}
 // === Seasonal Suggestions ===
 const SEASONAL_MOODS = {
     WINTER: ["cozy", "dark", "nostalgic", "brainy"],

package/dist/index.js

@@ -8,6 +8,7 @@ import { registerRecommendTools } from "./tools/recommend.js";
 import { registerDiscoverTools } from "./tools/discover.js";
 import { registerInfoTools } from "./tools/info.js";
 import { registerWriteTools } from "./tools/write.js";
+import { registerSocialTools } from "./tools/social.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.");
@@ -17,7 +18,7 @@ if (!process.env.ANILIST_TOKEN) {
 }
 const server = new FastMCP({
     name: "ani-mcp",
-    version: "0.1.0",
+    version: "0.5.0",
 });
 registerSearchTools(server);
 registerListTools(server);
@@ -25,6 +26,7 @@ registerRecommendTools(server);
 registerDiscoverTools(server);
 registerInfoTools(server);
 registerWriteTools(server);
+registerSocialTools(server);
 // === Transport ===
 const transport = process.env.MCP_TRANSPORT === "http" ? "httpStream" : "stdio";
 if (transport === "httpStream") {