ani-mcp 0.2.5 → 0.4.0

package/README.md

@@ -4,6 +4,11 @@
 
 # ani-mcp
 
+[![npm version](https://img.shields.io/npm/v/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)
+
 A smart [MCP](https://modelcontextprotocol.io) server for [AniList](https://anilist.co) that understands your anime and manga taste - not just raw API calls.
 
 ## What makes this different
@@ -43,6 +48,9 @@ Works with any MCP-compatible client.
 | --- | --- | --- |
 | `ANILIST_USERNAME` | No | Default username for list and stats tools. Can also pass per-call. |
 | `ANILIST_TOKEN` | No | AniList OAuth token. Required for write operations and private lists. |
+| `ANILIST_TITLE_LANGUAGE` | No | Title preference: `english` (default), `romaji`, or `native`. |
+| `ANILIST_SCORE_FORMAT` | No | Override score display: `POINT_100`, `POINT_10_DECIMAL`, `POINT_10`, `POINT_5`, `POINT_3`. |
+| `ANILIST_NSFW` | No | Set to `true` to include adult content in results. Default: `false`. |
 | `DEBUG` | No | Set to `true` for debug logging to stderr. |
 | `MCP_TRANSPORT` | No | Set to `http` for HTTP Stream transport. Default: stdio. |
 | `MCP_PORT` | No | Port for HTTP transport. Default: `3000`. |
@@ -59,6 +67,7 @@ Works with any MCP-compatible client.
 | `anilist_seasonal` | Browse a season's anime lineup |
 | `anilist_trending` | What's trending on AniList right now |
 | `anilist_genres` | Browse top titles in a genre with optional filters |
+| `anilist_genre_list` | List all valid genres and content tags |
 | `anilist_recommendations` | Community recommendations for a specific title |
 
 ### Lists & Stats
@@ -88,6 +97,7 @@ Works with any MCP-compatible client.
 | `anilist_studio_search` | Search for a studio and see their productions |
 | `anilist_schedule` | Airing schedule and next episode countdown |
 | `anilist_characters` | Search characters by name with appearances and VAs |
+| `anilist_whoami` | Check authentication status and score format |
 
 ### Write (requires `ANILIST_TOKEN`)
 

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

@@ -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;
@@ -143,25 +148,29 @@ class AniListClient {
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
             log("network-error", msg);
-            throw new AniListApiError(`Network error connecting to AniList: ${msg}`, undefined, true);
+            const isTimeout = msg.includes("abort") || msg.includes("timeout");
+            throw new AniListApiError(isTimeout
+                ? "Could not reach AniList (request timed out). Try again."
+                : `Network error connecting to AniList: ${msg}`, undefined, true);
         }
         // Map HTTP errors to retryable/non-retryable
         if (!response.ok) {
             // Read error body for context
             const body = await response.text().catch(() => "");
             if (response.status === 429) {
-                log("rate-limit", `429 from AniList`);
                 const retryAfter = response.headers.get("Retry-After");
-                if (retryAfter) {
-                    const delaySec = parseInt(retryAfter, 10);
-                    if (delaySec > 0) {
-                        await new Promise((r) => setTimeout(r, delaySec * 1000));
-                    }
+                const delaySec = retryAfter ? parseInt(retryAfter, 10) : 0;
+                log("rate-limit", `429 from AniList (retry-after: ${delaySec || "none"})`);
+                if (delaySec > 0) {
+                    await new Promise((r) => setTimeout(r, delaySec * 1000));
                 }
-                throw new AniListApiError("AniList rate limit hit. The server will retry automatically.", 429, true);
+                throw new AniListApiError(`AniList rate limit exceeded. Try again in ${delaySec > 0 ? `${delaySec} seconds` : "30-60 seconds"}.`, 429, true);
+            }
+            if (response.status === 401) {
+                throw new AbortError(new AniListApiError("Authentication failed. Check that ANILIST_TOKEN is valid and not expired.", 401, false));
             }
             if (response.status === 404) {
-                throw new AbortError(new AniListApiError("Resource not found on AniList. Check that the ID or username is correct.", 404, false));
+                throw new AbortError(new AniListApiError("Not found on AniList. Check that the ID or username is correct.", 404, false));
             }
             // Only server errors (5xx) are worth retrying
             if (response.status >= 500) {

package/dist/api/queries.d.ts

@@ -13,7 +13,7 @@ export declare const DISCOVER_MEDIA_QUERY = "\n  query DiscoverMedia(\n    $type
 /** 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";
 /** 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      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";
+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";
 /** Trending anime or manga right now */
@@ -27,12 +27,26 @@ export declare const AIRING_SCHEDULE_QUERY = "\n  query AiringSchedule($id: Int,
 /** Search for characters by name */
 export declare const CHARACTER_SEARCH_QUERY = "\n  query CharacterSearch($search: String!, $page: Int, $perPage: Int) {\n    Page(page: $page, perPage: $perPage) {\n      pageInfo { total hasNextPage }\n      characters(search: $search, sort: FAVOURITES_DESC) {\n        id\n        name { full native alternative }\n        image { medium }\n        favourites\n        siteUrl\n        media(sort: POPULARITY_DESC, perPage: 5) {\n          edges {\n            characterRole\n            node {\n              id\n              title { romaji english }\n              format\n              type\n              siteUrl\n            }\n            voiceActors(language: JAPANESE) {\n              id\n              name { full }\n              siteUrl\n            }\n          }\n        }\n      }\n    }\n  }\n";
 /** Create or update a list entry */
-export declare const SAVE_MEDIA_LIST_ENTRY_MUTATION = "\n  mutation SaveMediaListEntry(\n    $mediaId: Int\n    $status: MediaListStatus\n    $score: Float\n    $progress: Int\n    $notes: String\n    $private: Boolean\n  ) {\n    SaveMediaListEntry(\n      mediaId: $mediaId\n      status: $status\n      score: $score\n      progress: $progress\n      notes: $notes\n      private: $private\n    ) {\n      id\n      mediaId\n      status\n      score(format: POINT_10)\n      progress\n    }\n  }\n";
+export declare const SAVE_MEDIA_LIST_ENTRY_MUTATION = "\n  mutation SaveMediaListEntry(\n    $mediaId: Int\n    $status: MediaListStatus\n    $scoreRaw: Int\n    $progress: Int\n    $notes: String\n    $private: Boolean\n  ) {\n    SaveMediaListEntry(\n      mediaId: $mediaId\n      status: $status\n      scoreRaw: $scoreRaw\n      progress: $progress\n      notes: $notes\n      private: $private\n    ) {\n      id\n      mediaId\n      status\n      score(format: POINT_10)\n      progress\n    }\n  }\n";
 /** 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    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";

package/dist/api/queries.js

@@ -161,6 +161,9 @@ export const USER_STATS_QUERY = `
     User(name: $name) {
       id
       name
+      mediaListOptions {
+        scoreFormat
+      }
       statistics {
         anime {
           count
@@ -369,7 +372,7 @@ export const SAVE_MEDIA_LIST_ENTRY_MUTATION = `
   mutation SaveMediaListEntry(
     $mediaId: Int
     $status: MediaListStatus
-    $score: Float
+    $scoreRaw: Int
     $progress: Int
     $notes: String
     $private: Boolean
@@ -377,7 +380,7 @@ export const SAVE_MEDIA_LIST_ENTRY_MUTATION = `
     SaveMediaListEntry(
       mediaId: $mediaId
       status: $status
-      score: $score
+      scoreRaw: $scoreRaw
       progress: $progress
       notes: $notes
       private: $private
@@ -415,6 +418,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
@@ -460,6 +464,167 @@ export const STAFF_SEARCH_QUERY = `
     }
   }
 `;
+/** Authenticated user info */
+export const VIEWER_QUERY = `
+  query Viewer {
+    Viewer {
+      id
+      name
+      avatar { medium }
+      siteUrl
+      mediaListOptions {
+        scoreFormat
+      }
+    }
+  }
+`;
+/** All valid genres and media tags */
+export const GENRE_TAG_COLLECTION_QUERY = `
+  query GenreTagCollection {
+    GenreCollection
+    MediaTagCollection {
+      name
+      description
+      category
+      isAdult
+    }
+  }
+`;
+// === 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) {

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.4.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") {

package/dist/schemas.d.ts

@@ -44,7 +44,9 @@ export declare const ListInputSchema: z.ZodObject<{
         DROPPED: "DROPPED";
         PAUSED: "PAUSED";
         ALL: "ALL";
+        CUSTOM: "CUSTOM";
     }>>;
+    customListName: z.ZodOptional<z.ZodString>;
     sort: z.ZodDefault<z.ZodEnum<{
         SCORE: "SCORE";
         TITLE: "TITLE";
@@ -257,9 +259,61 @@ export declare const StaffSearchInputSchema: z.ZodObject<{
     page: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type StaffSearchInput = z.infer<typeof StaffSearchInputSchema>;
+/** Input for listing all valid genres and tags */
+export declare const GenreListInputSchema: z.ZodObject<{
+    includeAdultTags: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GenreListInput = z.infer<typeof GenreListInputSchema>;
 /** Input for searching studios by name */
 export declare const StudioSearchInputSchema: z.ZodObject<{
     query: z.ZodString;
     limit: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type StudioSearchInput = z.infer<typeof StudioSearchInputSchema>;
+/** Input for toggling a favourite */
+export declare const FavouriteInputSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        ANIME: "ANIME";
+        MANGA: "MANGA";
+        CHARACTER: "CHARACTER";
+        STAFF: "STAFF";
+        STUDIO: "STUDIO";
+    }>;
+    id: z.ZodNumber;
+}, z.core.$strip>;
+export type FavouriteInput = z.infer<typeof FavouriteInputSchema>;
+/** Input for posting a text activity */
+export declare const PostActivityInputSchema: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>;
+export type PostActivityInput = z.infer<typeof PostActivityInputSchema>;
+/** Input for fetching a user's activity feed */
+export declare const FeedInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    type: z.ZodDefault<z.ZodEnum<{
+        ALL: "ALL";
+        TEXT: "TEXT";
+        ANIME_LIST: "ANIME_LIST";
+        MANGA_LIST: "MANGA_LIST";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    page: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type FeedInput = z.infer<typeof FeedInputSchema>;
+/** Input for viewing a user's profile */
+export declare const ProfileInputSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ProfileInput = z.infer<typeof ProfileInputSchema>;
+/** Input for fetching community reviews for a title */
+export declare const ReviewsInputSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodOptional<z.ZodString>;
+    sort: z.ZodDefault<z.ZodEnum<{
+        HELPFUL: "HELPFUL";
+        NEWEST: "NEWEST";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    page: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type ReviewsInput = z.infer<typeof ReviewsInputSchema>;

package/dist/schemas.js

@@ -88,9 +88,13 @@ export const ListInputSchema = z.object({
         .default("ANIME")
         .describe("Get anime or manga list"),
     status: z
-        .enum(["CURRENT", "COMPLETED", "PLANNING", "DROPPED", "PAUSED", "ALL"])
+        .enum(["CURRENT", "COMPLETED", "PLANNING", "DROPPED", "PAUSED", "ALL", "CUSTOM"])
         .default("ALL")
-        .describe("Filter by list status. CURRENT = watching/reading now."),
+        .describe("Filter by list status. CURRENT = watching/reading now. CUSTOM = user-created lists."),
+    customListName: z
+        .string()
+        .optional()
+        .describe("Filter to a specific custom list by name. Only used when status is CUSTOM."),
     sort: z
         .enum(["SCORE", "TITLE", "UPDATED", "PROGRESS"])
         .default("UPDATED")
@@ -442,6 +446,13 @@ export const StaffSearchInputSchema = z.object({
         .describe("Works per person to show (default 10, max 25)"),
     page: pageParam,
 });
+/** Input for listing all valid genres and tags */
+export const GenreListInputSchema = z.object({
+    includeAdultTags: z
+        .boolean()
+        .default(false)
+        .describe("Include adult/NSFW tags in the list"),
+});
 /** Input for searching studios by name */
 export const StudioSearchInputSchema = z.object({
     query: z
@@ -456,3 +467,76 @@ export const StudioSearchInputSchema = z.object({
         .default(10)
         .describe("Number of works to show (default 10, max 25)"),
 });
+// === 0.4.0 Social & Favourites ===
+/** Input for toggling a favourite */
+export const FavouriteInputSchema = z.object({
+    type: z
+        .enum(["ANIME", "MANGA", "CHARACTER", "STAFF", "STUDIO"])
+        .describe("Type of entity to favourite"),
+    id: z
+        .number()
+        .int()
+        .positive()
+        .describe("AniList ID of the entity to toggle favourite on"),
+});
+/** Input for posting a text activity */
+export const PostActivityInputSchema = z.object({
+    text: z
+        .string()
+        .min(1)
+        .max(2000)
+        .describe("Text content of the activity post"),
+});
+/** Input for fetching a user's activity feed */
+export const FeedInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+    type: z
+        .enum(["TEXT", "ANIME_LIST", "MANGA_LIST", "ALL"])
+        .default("ALL")
+        .describe("Filter by activity type"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(25)
+        .default(10)
+        .describe("Number of activities to return (default 10, max 25)"),
+    page: pageParam,
+});
+/** Input for viewing a user's profile */
+export const ProfileInputSchema = z.object({
+    username: usernameSchema
+        .optional()
+        .describe("AniList username. Falls back to configured default if not provided."),
+});
+/** 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"),
+    sort: z
+        .enum(["HELPFUL", "NEWEST"])
+        .default("HELPFUL")
+        .describe("Sort by most helpful or newest"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .default(5)
+        .describe("Number of reviews to return (default 5, max 10)"),
+    page: pageParam,
+})
+    .refine((data) => data.id !== undefined || data.title !== undefined, {
+    message: "Provide either an id or a title.",
+});

package/dist/tools/discover.js

@@ -1,8 +1,8 @@
 /** Discovery tools: trending and genre browsing without search terms. */
 import { anilistClient } from "../api/client.js";
-import { TRENDING_MEDIA_QUERY, GENRE_BROWSE_QUERY } from "../api/queries.js";
-import { TrendingInputSchema, GenreBrowseInputSchema } from "../schemas.js";
-import { formatMediaSummary, throwToolError, paginationFooter } from "../utils.js";
+import { TRENDING_MEDIA_QUERY, GENRE_BROWSE_QUERY, GENRE_TAG_COLLECTION_QUERY, } from "../api/queries.js";
+import { TrendingInputSchema, GenreBrowseInputSchema, GenreListInputSchema, } from "../schemas.js";
+import { formatMediaSummary, throwToolError, paginationFooter, } from "../utils.js";
 /** Register discovery tools on the MCP server */
 export function registerDiscoverTools(server) {
     // === Trending ===
@@ -38,7 +38,7 @@ export function registerDiscoverTools(server) {
                 ].join("\n");
                 const formatted = results.map((m, i) => `${offset + i + 1}. ${formatMediaSummary(m)}`);
                 const footer = paginationFooter(args.page, args.limit, pageInfo.total, pageInfo.hasNextPage);
-                return header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : "");
+                return (header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : ""));
             }
             catch (error) {
                 return throwToolError(error, "fetching trending");
@@ -102,11 +102,62 @@ export function registerDiscoverTools(server) {
                 ].join("\n");
                 const formatted = results.map((m, i) => `${offset + i + 1}. ${formatMediaSummary(m)}`);
                 const footer = paginationFooter(args.page, args.limit, pageInfo.total, pageInfo.hasNextPage);
-                return header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : "");
+                return (header + formatted.join("\n\n") + (footer ? `\n\n${footer}` : ""));
             }
             catch (error) {
                 return throwToolError(error, "browsing genres");
             }
         },
     });
+    // === Genre/Tag List ===
+    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.",
+        parameters: GenreListInputSchema,
+        annotations: {
+            title: "List Genres & Tags",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const data = await anilistClient.query(GENRE_TAG_COLLECTION_QUERY, {}, { cache: "media" });
+                const lines = [
+                    "# AniList Genres",
+                    "",
+                    data.GenreCollection.join(", "),
+                ];
+                // Group tags by category
+                let tags = data.MediaTagCollection;
+                if (!args.includeAdultTags) {
+                    tags = tags.filter((t) => !t.isAdult);
+                }
+                const categories = new Map();
+                for (const tag of tags) {
+                    const cat = tag.category || "Other";
+                    const list = categories.get(cat);
+                    if (list) {
+                        list.push(tag);
+                    }
+                    else {
+                        categories.set(cat, [tag]);
+                    }
+                }
+                lines.push("", "# Content Tags");
+                for (const [category, catTags] of categories) {
+                    lines.push("", `## ${category}`);
+                    for (const tag of catTags) {
+                        lines.push(`  ${tag.name} - ${tag.description}`);
+                    }
+                }
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "fetching genre list");
+            }
+        },
+    });
 }