ani-mcp 0.3.0 → 0.4.0

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;

package/dist/api/queries.d.ts

@@ -31,12 +31,22 @@ 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    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

@@ -418,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
@@ -489,6 +490,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) {

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";
@@ -268,3 +270,50 @@ export declare const StudioSearchInputSchema: z.ZodObject<{
     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")
@@ -463,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/lists.js

@@ -28,8 +28,12 @@ export function registerListTools(server) {
         execute: async (args) => {
             try {
                 const username = getDefaultUsername(args.username);
-                // Fetch list and score format in parallel
                 const sort = SORT_MAP[args.sort] ?? SORT_MAP.UPDATED;
+                // Custom list path: fetch all groups and filter to custom lists
+                if (args.status === "CUSTOM") {
+                    return await handleCustomLists(username, args, sort);
+                }
+                // Standard path: fetch list and score format in parallel
                 const status = args.status !== "ALL" ? args.status : undefined;
                 const [allEntries, scoreFormat] = await Promise.all([
                     anilistClient.fetchList(username, args.type, status, sort),
@@ -107,6 +111,53 @@ export function registerListTools(server) {
         },
     });
 }
+/** Fetch and format custom lists for a user */
+async function handleCustomLists(username, args, sort) {
+    const groups = await anilistClient.fetchListGroups(username, args.type, undefined, sort);
+    let customLists = groups.filter((g) => g.isCustomList);
+    if (!customLists.length) {
+        return `${username} has no custom ${args.type.toLowerCase()} lists.`;
+    }
+    // Filter to a specific named list
+    if (args.customListName) {
+        const target = args.customListName.toLowerCase();
+        const match = customLists.filter((g) => g.name.toLowerCase() === target);
+        if (!match.length) {
+            const names = customLists.map((g) => g.name).join(", ");
+            return `Custom list "${args.customListName}" not found. Available: ${names}`;
+        }
+        customLists = match;
+    }
+    // Flatten entries from matching custom lists
+    const allEntries = [];
+    for (const list of customLists) {
+        allEntries.push(...list.entries);
+    }
+    if (!allEntries.length) {
+        const listLabel = args.customListName
+            ? `custom list "${args.customListName}"`
+            : "custom lists";
+        return `${username}'s ${listLabel} have no entries.`;
+    }
+    sortEntries(allEntries, args.sort);
+    // Detect score format
+    const scoreFormat = await detectScoreFormat(async () => {
+        const data = await anilistClient.query(USER_STATS_QUERY, { name: username }, { cache: "stats" });
+        return data.User.mediaListOptions.scoreFormat;
+    });
+    const totalCount = allEntries.length;
+    const offset = (args.page - 1) * args.limit;
+    const limited = allEntries.slice(offset, offset + args.limit);
+    const hasNextPage = offset + args.limit < totalCount;
+    const listLabel = args.customListName
+        ? `custom list "${args.customListName}"`
+        : `custom lists (${customLists.length} lists)`;
+    const header = `${username}'s ${args.type} ${listLabel} - ${totalCount} entries` +
+        (totalCount > limited.length ? `, showing ${limited.length}` : "");
+    const formatted = limited.map((entry, i) => formatListEntry(entry, offset + i + 1, scoreFormat));
+    const footer = paginationFooter(args.page, args.limit, totalCount, hasNextPage);
+    return header + "\n\n" + formatted.join("\n\n") + (footer ? `\n\n${footer}` : "");
+}
 /** Format statistics for a single media type (anime or manga) */
 function formatTypeStats(stats, label) {
     const lines = [`## ${label}`];

package/dist/tools/social.d.ts

@@ -0,0 +1,4 @@
+/** Social tools: activity feed, user profiles, and community reviews. */
+import type { FastMCP } from "fastmcp";
+/** Register social and community tools */
+export declare function registerSocialTools(server: FastMCP): void;

package/dist/tools/social.js

@@ -0,0 +1,195 @@
+/** Social tools: activity feed, user profiles, and community reviews. */
+import { anilistClient } from "../api/client.js";
+import { ACTIVITY_FEED_QUERY, USER_PROFILE_QUERY, USER_STATS_QUERY, MEDIA_REVIEWS_QUERY, } from "../api/queries.js";
+import { FeedInputSchema, ProfileInputSchema, ReviewsInputSchema, } from "../schemas.js";
+import { getTitle, getDefaultUsername, truncateDescription, throwToolError, paginationFooter, } from "../utils.js";
+/** Register social and community tools */
+export function registerSocialTools(server) {
+    // === Activity Feed ===
+    server.addTool({
+        name: "anilist_feed",
+        description: "Get recent activity from a user's AniList feed. " +
+            "Shows text posts and list updates (anime/manga status changes). " +
+            "Defaults to the configured username if not provided.",
+        parameters: FeedInputSchema,
+        annotations: {
+            title: "Activity Feed",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const username = getDefaultUsername(args.username);
+                // Resolve username to numeric ID for the activity query
+                const userData = await anilistClient.query(USER_STATS_QUERY, { name: username }, { cache: "stats" });
+                const userId = userData.User.id;
+                const variables = {
+                    userId,
+                    page: args.page,
+                    perPage: args.limit,
+                };
+                if (args.type !== "ALL")
+                    variables.type = args.type;
+                const data = await anilistClient.query(ACTIVITY_FEED_QUERY, variables, { cache: "search" });
+                const { activities, pageInfo } = data.Page;
+                if (!activities.length) {
+                    return `No recent activity for ${username}.`;
+                }
+                const header = `Activity feed for ${username}`;
+                const lines = activities.map((a, i) => formatActivity(a, i + 1));
+                const footer = paginationFooter(args.page, args.limit, pageInfo.total, pageInfo.hasNextPage);
+                return [header, "", ...lines].join("\n") +
+                    (footer ? `\n\n${footer}` : "");
+            }
+            catch (error) {
+                return throwToolError(error, "fetching activity feed");
+            }
+        },
+    });
+    // === User Profile ===
+    server.addTool({
+        name: "anilist_profile",
+        description: "View a user's AniList profile including bio, stats, and favourites. " +
+            "Defaults to the configured username if not provided.",
+        parameters: ProfileInputSchema,
+        annotations: {
+            title: "User Profile",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const username = getDefaultUsername(args.username);
+                const data = await anilistClient.query(USER_PROFILE_QUERY, { name: username }, { cache: "stats" });
+                const user = data.User;
+                const lines = [`# ${user.name}`, user.siteUrl, ""];
+                // About/bio
+                if (user.about) {
+                    lines.push(truncateDescription(user.about, 500), "");
+                }
+                // Anime stats
+                const a = user.statistics.anime;
+                if (a.count > 0) {
+                    const days = (a.minutesWatched / 1440).toFixed(1);
+                    lines.push(`## Anime: ${a.count} titles | ${a.episodesWatched} episodes | ${days} days | Mean ${a.meanScore.toFixed(1)}`);
+                }
+                // Manga stats
+                const m = user.statistics.manga;
+                if (m.count > 0) {
+                    lines.push(`## Manga: ${m.count} titles | ${m.chaptersRead} chapters | ${m.volumesRead} volumes | Mean ${m.meanScore.toFixed(1)}`);
+                }
+                // Favorites
+                const fav = user.favourites;
+                if (fav.anime.nodes.length) {
+                    lines.push("", "Favourite Anime: " +
+                        fav.anime.nodes.map((n) => getTitle(n.title)).join(", "));
+                }
+                if (fav.manga.nodes.length) {
+                    lines.push("Favourite Manga: " +
+                        fav.manga.nodes.map((n) => getTitle(n.title)).join(", "));
+                }
+                if (fav.characters.nodes.length) {
+                    lines.push("Favourite Characters: " +
+                        fav.characters.nodes.map((n) => n.name.full).join(", "));
+                }
+                if (fav.staff.nodes.length) {
+                    lines.push("Favourite Staff: " +
+                        fav.staff.nodes.map((n) => n.name.full).join(", "));
+                }
+                if (fav.studios.nodes.length) {
+                    lines.push("Favourite Studios: " +
+                        fav.studios.nodes.map((n) => n.name).join(", "));
+                }
+                // Account age
+                const created = new Date(user.createdAt * 1000).toLocaleDateString("en-US", { month: "short", year: "numeric" });
+                lines.push("", `Member since ${created}`);
+                return lines.join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "fetching profile");
+            }
+        },
+    });
+    // === Reviews ===
+    const REVIEW_SORT_MAP = {
+        HELPFUL: ["RATING_DESC"],
+        NEWEST: ["CREATED_AT_DESC"],
+    };
+    server.addTool({
+        name: "anilist_reviews",
+        description: "Get community reviews for an anime or manga. " +
+            "Shows review scores, summaries, and a sentiment overview. " +
+            "Use when the user wants to see what others think about a title.",
+        parameters: ReviewsInputSchema,
+        annotations: {
+            title: "Community Reviews",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                const variables = {
+                    page: args.page,
+                    perPage: args.limit,
+                    sort: REVIEW_SORT_MAP[args.sort],
+                };
+                if (args.id)
+                    variables.id = args.id;
+                if (args.title)
+                    variables.search = args.title;
+                const data = await anilistClient.query(MEDIA_REVIEWS_QUERY, variables, { cache: "media" });
+                const media = data.Media;
+                const title = getTitle(media.title);
+                const { nodes, pageInfo } = media.reviews;
+                if (!nodes.length) {
+                    return `No reviews found for ${title}.`;
+                }
+                // Sentiment summary
+                const avgScore = Math.round(nodes.reduce((sum, r) => sum + r.score, 0) / nodes.length);
+                const sentiment = avgScore >= 75
+                    ? "Generally positive"
+                    : avgScore >= 50
+                        ? "Mixed"
+                        : "Generally negative";
+                const header = `Reviews for ${title} - ${sentiment} (avg ${avgScore}/100 across ${pageInfo.total} reviews)`;
+                const formatted = nodes.map((r, i) => {
+                    const date = new Date(r.createdAt * 1000).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+                    const helpful = r.ratingAmount > 0
+                        ? `${r.rating}/${r.ratingAmount} found helpful`
+                        : "No votes";
+                    const body = truncateDescription(r.body, 300);
+                    return [
+                        `${i + 1}. ${r.score}/100 by ${r.user.name} (${date})`,
+                        `   ${r.summary}`,
+                        `   ${body}`,
+                        `   ${helpful}`,
+                    ].join("\n");
+                });
+                const footer = paginationFooter(args.page, args.limit, pageInfo.total, pageInfo.hasNextPage);
+                return [header, "", ...formatted].join("\n\n") +
+                    (footer ? `\n\n${footer}` : "");
+            }
+            catch (error) {
+                return throwToolError(error, "fetching reviews");
+            }
+        },
+    });
+}
+// === Formatting Helpers ===
+/** Format a single activity entry */
+function formatActivity(activity, index) {
+    const date = new Date(activity.createdAt * 1000).toLocaleDateString("en-US", { month: "short", day: "numeric" });
+    if (activity.__typename === "TextActivity") {
+        const text = activity.text.length > 200
+            ? activity.text.slice(0, 200) + "..."
+            : activity.text;
+        return `${index}. ${activity.user.name} posted (${date}):\n   ${text}`;
+    }
+    // List activity
+    const title = getTitle(activity.media.title);
+    const progress = activity.progress ? ` ${activity.progress}` : "";
+    return `${index}. ${activity.user.name} ${activity.status}${progress} ${title} (${date})`;
+}

package/dist/tools/write.d.ts

@@ -1,4 +1,4 @@
-/** Write tools: update progress, add to list, rate, and delete entries. */
+/** Write tools: list mutations, favourites, and activity posting. */
 import type { FastMCP } from "fastmcp";
 /** Register list mutation tools */
 export declare function registerWriteTools(server: FastMCP): void;

package/dist/tools/write.js

@@ -1,7 +1,7 @@
-/** Write tools: update progress, add to list, rate, and delete entries. */
+/** Write tools: list mutations, favourites, and activity posting. */
 import { anilistClient } from "../api/client.js";
-import { SAVE_MEDIA_LIST_ENTRY_MUTATION, DELETE_MEDIA_LIST_ENTRY_MUTATION, VIEWER_QUERY, } from "../api/queries.js";
-import { UpdateProgressInputSchema, AddToListInputSchema, RateInputSchema, DeleteFromListInputSchema, } from "../schemas.js";
+import { SAVE_MEDIA_LIST_ENTRY_MUTATION, DELETE_MEDIA_LIST_ENTRY_MUTATION, TOGGLE_FAVOURITE_MUTATION, SAVE_TEXT_ACTIVITY_MUTATION, VIEWER_QUERY, } from "../api/queries.js";
+import { UpdateProgressInputSchema, AddToListInputSchema, RateInputSchema, DeleteFromListInputSchema, FavouriteInputSchema, PostActivityInputSchema, } from "../schemas.js";
 import { throwToolError, formatScore, detectScoreFormat } from "../utils.js";
 // === Auth Guard ===
 /** Guard against unauthenticated write attempts */
@@ -160,4 +160,86 @@ export function registerWriteTools(server) {
             }
         },
     });
+    // === Toggle Favourite ===
+    // Map entity type to mutation variable name
+    const FAVOURITE_VAR_MAP = {
+        ANIME: "animeId",
+        MANGA: "mangaId",
+        CHARACTER: "characterId",
+        STAFF: "staffId",
+        STUDIO: "studioId",
+    };
+    // Map entity type to response field name
+    const FAVOURITE_FIELD_MAP = {
+        ANIME: "anime",
+        MANGA: "manga",
+        CHARACTER: "characters",
+        STAFF: "staff",
+        STUDIO: "studios",
+    };
+    server.addTool({
+        name: "anilist_favourite",
+        description: "Toggle favourite on an anime, manga, character, staff member, or studio. " +
+            "Calling again on the same entity removes it from favourites. " +
+            "Requires ANILIST_TOKEN.",
+        parameters: FavouriteInputSchema,
+        annotations: {
+            title: "Toggle Favourite",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                requireAuth();
+                const variables = { [FAVOURITE_VAR_MAP[args.type]]: args.id };
+                const data = await anilistClient.query(TOGGLE_FAVOURITE_MUTATION, variables, { cache: null });
+                anilistClient.clearCache();
+                // Check if entity is now in favourites (added) or absent (removed)
+                const field = FAVOURITE_FIELD_MAP[args.type];
+                const isFavourited = data.ToggleFavourite[field].nodes.some((n) => n.id === args.id);
+                const label = args.type.toLowerCase();
+                return isFavourited
+                    ? `Added ${label} ${args.id} to favourites.`
+                    : `Removed ${label} ${args.id} from favourites.`;
+            }
+            catch (error) {
+                return throwToolError(error, "toggling favourite");
+            }
+        },
+    });
+    // === Post Activity ===
+    server.addTool({
+        name: "anilist_activity",
+        description: "Post a text activity to your AniList feed. " +
+            "Use when the user wants to share a status update, thought, or message. " +
+            "Requires ANILIST_TOKEN.",
+        parameters: PostActivityInputSchema,
+        annotations: {
+            title: "Post Activity",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        execute: async (args) => {
+            try {
+                requireAuth();
+                const data = await anilistClient.query(SAVE_TEXT_ACTIVITY_MUTATION, { text: args.text }, { cache: null });
+                anilistClient.clearCache();
+                const activity = data.SaveTextActivity;
+                const dateStr = new Date(activity.createdAt * 1000).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+                return [
+                    `Activity posted.`,
+                    `By: ${activity.user.name}`,
+                    `Date: ${dateStr}`,
+                    `Activity ID: ${activity.id}`,
+                ].join("\n");
+            }
+            catch (error) {
+                return throwToolError(error, "posting activity");
+            }
+        },
+    });
 }

package/dist/types.d.ts

@@ -315,6 +315,7 @@ export interface UserListResponse {
         lists: Array<{
             name: string;
             status: string;
+            isCustomList: boolean;
             entries: AniListMediaListEntry[];
         }>;
     };
@@ -379,6 +380,199 @@ export interface GenreTagCollectionResponse {
         isAdult: boolean;
     }>;
 }
+/** Response from toggling a favourite */
+export interface ToggleFavouriteResponse {
+    ToggleFavourite: {
+        anime: {
+            nodes: Array<{
+                id: number;
+            }>;
+        };
+        manga: {
+            nodes: Array<{
+                id: number;
+            }>;
+        };
+        characters: {
+            nodes: Array<{
+                id: number;
+            }>;
+        };
+        staff: {
+            nodes: Array<{
+                id: number;
+            }>;
+        };
+        studios: {
+            nodes: Array<{
+                id: number;
+            }>;
+        };
+    };
+}
+/** Response from posting a text activity */
+export interface SaveTextActivityResponse {
+    SaveTextActivity: {
+        id: number;
+        createdAt: number;
+        text: string;
+        user: {
+            name: string;
+        };
+    };
+}
+/** Text-based activity on a user's feed */
+export interface TextActivity {
+    __typename: "TextActivity";
+    id: number;
+    text: string;
+    createdAt: number;
+    user: {
+        name: string;
+    };
+}
+/** List update activity on a user's feed */
+export interface ListActivity {
+    __typename: "ListActivity";
+    id: number;
+    status: string;
+    progress: string | null;
+    createdAt: number;
+    user: {
+        name: string;
+    };
+    media: {
+        id: number;
+        title: {
+            romaji: string | null;
+            english: string | null;
+            native: string | null;
+        };
+        type: string;
+    };
+}
+/** Union of activity types returned by the feed query */
+export type Activity = TextActivity | ListActivity;
+/** Paginated activity feed response */
+export interface ActivityFeedResponse {
+    Page: {
+        pageInfo: {
+            total: number;
+            currentPage: number;
+            hasNextPage: boolean;
+        };
+        activities: Activity[];
+    };
+}
+/** User profile with bio, stats, and favourites */
+export interface UserProfileResponse {
+    User: {
+        id: number;
+        name: string;
+        about: string | null;
+        avatar: {
+            large: string | null;
+        };
+        bannerImage: string | null;
+        siteUrl: string;
+        createdAt: number;
+        updatedAt: number;
+        donatorTier: number;
+        statistics: {
+            anime: {
+                count: number;
+                meanScore: number;
+                episodesWatched: number;
+                minutesWatched: number;
+            };
+            manga: {
+                count: number;
+                meanScore: number;
+                chaptersRead: number;
+                volumesRead: number;
+            };
+        };
+        favourites: {
+            anime: {
+                nodes: Array<{
+                    id: number;
+                    title: {
+                        romaji: string | null;
+                        english: string | null;
+                        native: string | null;
+                    };
+                    siteUrl: string;
+                }>;
+            };
+            manga: {
+                nodes: Array<{
+                    id: number;
+                    title: {
+                        romaji: string | null;
+                        english: string | null;
+                        native: string | null;
+                    };
+                    siteUrl: string;
+                }>;
+            };
+            characters: {
+                nodes: Array<{
+                    id: number;
+                    name: {
+                        full: string;
+                    };
+                    siteUrl: string;
+                }>;
+            };
+            staff: {
+                nodes: Array<{
+                    id: number;
+                    name: {
+                        full: string;
+                    };
+                    siteUrl: string;
+                }>;
+            };
+            studios: {
+                nodes: Array<{
+                    id: number;
+                    name: string;
+                    siteUrl: string;
+                }>;
+            };
+        };
+    };
+}
+/** Community reviews for a media title */
+export interface MediaReviewsResponse {
+    Media: {
+        id: number;
+        title: {
+            romaji: string | null;
+            english: string | null;
+            native: string | null;
+        };
+        reviews: {
+            pageInfo: {
+                total: number;
+                hasNextPage: boolean;
+            };
+            nodes: Array<{
+                id: number;
+                score: number;
+                summary: string;
+                body: string;
+                rating: number;
+                ratingAmount: number;
+                createdAt: number;
+                user: {
+                    name: string;
+                    siteUrl: string;
+                };
+            }>;
+        };
+    };
+}
 /** Single studio with production history */
 export interface StudioSearchResponse {
     Studio: {

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.3",
   "name": "ani-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "display_name": "AniList MCP",
   "description": "A smart MCP server for AniList that gets your anime/manga taste - not just API calls.",
   "author": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ani-mcp",
   "mcpName": "io.github.gavxm/ani-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A smart [MCP](https://modelcontextprotocol.io) server for [AniList](https://anilist.co) that gets your anime/manga taste - not just API calls.",
   "type": "module",
   "main": "dist/index.js",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/gavxm/ani-mcp",
     "source": "github"
   },
-  "version": "0.3.0",
+  "version": "0.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ani-mcp",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "transport": {
         "type": "stdio"
       },