ani-mcp 0.4.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.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;

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,7 +31,7 @@ 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        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    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 */
@@ -50,3 +50,5 @@ export declare const USER_PROFILE_QUERY = "\n  query UserProfile($name: String)
 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
@@ -650,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

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

package/dist/schemas.d.ts

@@ -74,11 +74,57 @@ export declare const PickInputSchema: z.ZodObject<{
         ANIME: "ANIME";
         MANGA: "MANGA";
     }>>;
+    profileType: z.ZodOptional<z.ZodEnum<{
+        ANIME: "ANIME";
+        MANGA: "MANGA";
+    }>>;
+    source: z.ZodDefault<z.ZodEnum<{
+        PLANNING: "PLANNING";
+        SEASONAL: "SEASONAL";
+        DISCOVER: "DISCOVER";
+    }>>;
+    season: z.ZodOptional<z.ZodEnum<{
+        WINTER: "WINTER";
+        SPRING: "SPRING";
+        SUMMER: "SUMMER";
+        FALL: "FALL";
+    }>>;
+    year: z.ZodOptional<z.ZodNumber>;
     mood: z.ZodOptional<z.ZodString>;
     maxEpisodes: z.ZodOptional<z.ZodNumber>;
     limit: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type PickInput = z.infer<typeof PickInputSchema>;
+/** Input for planning a watch/read session within a time budget */
+export declare const SessionInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    type: z.ZodDefault<z.ZodEnum<{
+        ANIME: "ANIME";
+        MANGA: "MANGA";
+    }>>;
+    minutes: z.ZodNumber;
+    mood: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SessionInput = z.infer<typeof SessionInputSchema>;
+/** Input for finding sequels to completed titles airing this season */
+export declare const SequelAlertInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    season: z.ZodOptional<z.ZodEnum<{
+        WINTER: "WINTER";
+        SPRING: "SPRING";
+        SUMMER: "SUMMER";
+        FALL: "FALL";
+    }>>;
+    year: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SequelAlertInput = z.infer<typeof SequelAlertInputSchema>;
+/** Input for franchise watch order guidance */
+export declare const WatchOrderInputSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodOptional<z.ZodString>;
+    includeSpecials: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WatchOrderInput = z.infer<typeof WatchOrderInputSchema>;
 /** Input for comparing taste profiles between two users */
 export declare const CompareInputSchema: z.ZodObject<{
     user1: z.ZodString;

package/dist/schemas.js

@@ -88,7 +88,15 @@ export const ListInputSchema = z.object({
         .default("ANIME")
         .describe("Get anime or manga list"),
     status: z
-        .enum(["CURRENT", "COMPLETED", "PLANNING", "DROPPED", "PAUSED", "ALL", "CUSTOM"])
+        .enum([
+        "CURRENT",
+        "COMPLETED",
+        "PLANNING",
+        "DROPPED",
+        "PAUSED",
+        "ALL",
+        "CUSTOM",
+    ])
         .default("ALL")
         .describe("Filter by list status. CURRENT = watching/reading now. CUSTOM = user-created lists."),
     customListName: z
@@ -127,6 +135,27 @@ export const PickInputSchema = z.object({
         .enum(["ANIME", "MANGA"])
         .default("ANIME")
         .describe("Recommend from anime or manga planning list"),
+    profileType: z
+        .enum(["ANIME", "MANGA"])
+        .optional()
+        .describe("Build taste profile from this media type. Defaults to same as type. " +
+        "Set to get cross-media recs, e.g. anime picks based on manga taste."),
+    source: z
+        .enum(["PLANNING", "SEASONAL", "DISCOVER"])
+        .default("PLANNING")
+        .describe("Where to find candidates. PLANNING = user's plan-to-watch list (default). " +
+        "SEASONAL = currently airing anime. DISCOVER = top-rated titles matching taste."),
+    season: z
+        .enum(["WINTER", "SPRING", "SUMMER", "FALL"])
+        .optional()
+        .describe("Season for SEASONAL source. Defaults to the current season."),
+    year: z
+        .number()
+        .int()
+        .min(1940)
+        .max(new Date().getFullYear() + 2)
+        .optional()
+        .describe("Year for SEASONAL source. Defaults to the current year."),
     mood: z
         .string()
         .optional()
@@ -145,6 +174,61 @@ export const PickInputSchema = z.object({
         .default(5)
         .describe("Number of recommendations to return (default 5, max 15)"),
 });
+/** Input for planning a watch/read session within a time budget */
+export const SessionInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    type: z
+        .enum(["ANIME", "MANGA"])
+        .default("ANIME")
+        .describe("Plan session from anime or manga currently-watching list"),
+    minutes: z
+        .number()
+        .int()
+        .min(10)
+        .max(720)
+        .describe("Time budget in minutes (10-720)"),
+    mood: z
+        .string()
+        .optional()
+        .describe('Optional mood to prioritize titles, e.g. "dark", "chill"'),
+});
+/** Input for finding sequels to completed titles airing this season */
+export const SequelAlertInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    season: z
+        .enum(["WINTER", "SPRING", "SUMMER", "FALL"])
+        .optional()
+        .describe("Season to check for sequels. Defaults to the current season."),
+    year: z
+        .number()
+        .int()
+        .min(1940)
+        .max(new Date().getFullYear() + 2)
+        .optional()
+        .describe("Year to check. Defaults to the current year."),
+});
+/** Input for franchise watch order guidance */
+export const WatchOrderInputSchema = z
+    .object({
+    id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("AniList media ID of any title in the franchise"),
+    title: z.string().optional().describe("Search by title if no ID is known"),
+    includeSpecials: z
+        .boolean()
+        .default(false)
+        .describe("Include OVAs, specials, and spin-offs in the watch order"),
+})
+    .refine((data) => data.id !== undefined || data.title !== undefined, {
+    message: "Provide either an id or a title.",
+});
 /** Input for comparing taste profiles between two users */
 export const CompareInputSchema = z.object({
     user1: usernameSchema.describe("First AniList username"),
@@ -514,16 +598,8 @@ export const ProfileInputSchema = z.object({
 /** Input for fetching community reviews for a title */
 export const ReviewsInputSchema = 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"),
+    id: z.number().int().positive().optional().describe("AniList media ID"),
+    title: z.string().optional().describe("Search by title if no ID is known"),
     sort: z
         .enum(["HELPFUL", "NEWEST"])
         .default("HELPFUL")

package/dist/tools/discover.js

@@ -10,7 +10,7 @@ export function registerDiscoverTools(server) {
         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.",
+            "No search term needed. Returns ranked list with title, format, score, genres, and episode count.",
         parameters: TrendingInputSchema,
         annotations: {
             title: "Trending Now",
@@ -51,7 +51,7 @@ export function registerDiscoverTools(server) {
         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.",
+            "Supports year, status, and format filters. Returns ranked list with title, score, and genres.",
         parameters: GenreBrowseInputSchema,
         annotations: {
             title: "Browse by Genre",
@@ -113,8 +113,8 @@ export function registerDiscoverTools(server) {
     server.addTool({
         name: "anilist_genre_list",
         description: "List all valid AniList genres and content tags. " +
-            "Use when the user asks what genres exist, wants to see available tags, " +
-            "or needs valid genre names for filtering other tools.",
+            "Use before genre-filtering tools to ensure valid genre names. " +
+            "Returns genres and content tags grouped by category with descriptions.",
         parameters: GenreListInputSchema,
         annotations: {
             title: "List Genres & Tags",

package/dist/tools/info.js

@@ -79,7 +79,7 @@ export function registerInfoTools(server) {
         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.",
+            "Returns production staff with roles and characters with Japanese voice actors.",
         parameters: StaffInputSchema,
         annotations: {
             title: "Get Staff Credits",
@@ -138,7 +138,8 @@ export function registerInfoTools(server) {
         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.",
+            "or wants to see upcoming episode dates for a currently airing show. " +
+            "Returns next episode date/countdown and upcoming episode schedule.",
         parameters: ScheduleInputSchema,
         annotations: {
             title: "Airing Schedule",
@@ -200,7 +201,8 @@ export function registerInfoTools(server) {
         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.",
+            "which series a character appears in, or who voices them. " +
+            "Returns character appearances with roles and voice actors.",
         parameters: CharacterSearchInputSchema,
         annotations: {
             title: "Search Characters",
@@ -250,8 +252,8 @@ export function registerInfoTools(server) {
     server.addTool({
         name: "anilist_staff_search",
         description: "Search for anime/manga staff by name and see their works. " +
-            "Use when the user asks about a director, voice actor, animator, or writer " +
-            "and wants to see everything they have worked on.",
+            "Use when the user asks about a director, voice actor, animator, or writer. " +
+            "Returns staff occupations, works with roles, and scores.",
         parameters: StaffSearchInputSchema,
         annotations: {
             title: "Search Staff",
@@ -325,8 +327,8 @@ export function registerInfoTools(server) {
     server.addTool({
         name: "anilist_studio_search",
         description: "Search for an animation studio by name and see their productions. " +
-            "Use when the user asks about a studio like MAPPA, Kyoto Animation, or Bones " +
-            "and wants to see what they have produced.",
+            "Use when the user asks about a studio like MAPPA, Kyoto Animation, or Bones. " +
+            "Returns main and supporting productions with format, score, and status.",
         parameters: StudioSearchInputSchema,
         annotations: {
             title: "Search Studios",