ani-mcp 0.2.3 → 0.2.4

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/icon.svg" width="128" height="128" alt="ani-mcp">
+</p>
+
 # ani-mcp
 
 A smart [MCP](https://modelcontextprotocol.io) server for [AniList](https://anilist.co) that understands your anime and manga taste - not just raw API calls.
@@ -94,6 +98,29 @@ Works with any MCP-compatible client.
 | `anilist_rate` | Score a title (0-10) |
 | `anilist_delete_from_list` | Remove an entry from your list |
 
+## Examples
+
+Here are some things you can ask your AI assistant once ani-mcp is connected:
+
+**"What should I watch next?"**
+Uses `anilist_pick` to analyze your completed list, build a taste profile, and recommend titles from your Planning list (or discover new ones) ranked by how well they match your preferences.
+
+**"Compare my taste with username123"**
+Uses `anilist_compare` to find shared titles, compute a compatibility score, highlight biggest disagreements, and suggest cross-recommendations between the two profiles.
+
+**"What's airing this season?"**
+Uses `anilist_seasonal` to show the current season's anime lineup sorted by popularity, with scores, genres, and episode counts.
+
+**"Why would I like Vinland Saga?"**
+Uses `anilist_explain` to score a specific title against your taste profile, breaking down genre affinity, theme alignment, and community reception.
+
+**"Show me my anime year in review"**
+Uses `anilist_wrapped` to summarize everything you watched in a given year - titles completed, average score, top genres, most controversial pick, and total episodes.
+
+## Privacy
+
+See [PRIVACY.md](PRIVACY.md) for details. In short: ani-mcp runs locally, sends requests only to the AniList API, stores nothing, and collects no analytics.
+
 ## Docker
 
 ```sh
@@ -113,6 +140,10 @@ npm run build
 npm test
 ```
 
+## Support
+
+Bug reports and feature requests: [GitHub Issues](https://github.com/gavxm/ani-mcp/issues)
+
 ## License
 
 MIT

package/dist/tools/discover.js

@@ -12,6 +12,12 @@ export function registerDiscoverTools(server) {
             "Use when the user asks what's hot, trending, or generating buzz. " +
             "No search term needed - returns titles ranked by current trending score.",
         parameters: TrendingInputSchema,
+        annotations: {
+            title: "Trending Now",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const data = await anilistClient.query(TRENDING_MEDIA_QUERY, {
@@ -47,6 +53,12 @@ export function registerDiscoverTools(server) {
             'e.g. "best romance anime" or "top thriller manga from 2023". ' +
             "No search term needed - discovers by genre with optional year/status/format filters.",
         parameters: GenreBrowseInputSchema,
+        annotations: {
+            title: "Browse by Genre",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const sortMap = {

package/dist/tools/info.js

@@ -25,6 +25,12 @@ export function registerInfoTools(server) {
             "Use when the user asks who directed, wrote, or voiced characters in a title. " +
             "Shows directors, writers, character designers, and Japanese voice actors.",
         parameters: StaffInputSchema,
+        annotations: {
+            title: "Get Staff Credits",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const variables = {};
@@ -78,6 +84,12 @@ export function registerInfoTools(server) {
             "Use when the user asks when the next episode airs, " +
             "or wants to see upcoming episode dates for a currently airing show.",
         parameters: ScheduleInputSchema,
+        annotations: {
+            title: "Airing Schedule",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const variables = { notYetAired: true };
@@ -134,6 +146,12 @@ export function registerInfoTools(server) {
             "Use when the user asks about a specific character, wants to know " +
             "which series a character appears in, or who voices them.",
         parameters: CharacterSearchInputSchema,
+        annotations: {
+            title: "Search Characters",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const data = await anilistClient.query(CHARACTER_SEARCH_QUERY, { search: args.query, page: args.page, perPage: args.limit }, { cache: "search" });
@@ -179,6 +197,12 @@ export function registerInfoTools(server) {
             "Use when the user asks about a director, voice actor, animator, or writer " +
             "and wants to see everything they have worked on.",
         parameters: StaffSearchInputSchema,
+        annotations: {
+            title: "Search Staff",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const data = await anilistClient.query(STAFF_SEARCH_QUERY, { search: args.query, page: args.page, perPage: args.limit, mediaPerPage: args.mediaLimit }, { cache: "search" });
@@ -243,6 +267,12 @@ export function registerInfoTools(server) {
             "Use when the user asks about a studio like MAPPA, Kyoto Animation, or Bones " +
             "and wants to see what they have produced.",
         parameters: StudioSearchInputSchema,
+        annotations: {
+            title: "Search Studios",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const data = await anilistClient.query(STUDIO_SEARCH_QUERY, { search: args.query, perPage: args.limit }, { cache: "search" });

package/dist/tools/lists.js

@@ -19,6 +19,12 @@ export function registerListTools(server) {
             "what they've completed, or what's on their plan-to-watch. " +
             "Defaults to the configured username if not provided.",
         parameters: ListInputSchema,
+        annotations: {
+            title: "Get User List",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const username = getDefaultUsername(args.username);
@@ -61,6 +67,12 @@ export function registerListTools(server) {
             "their average score, top genres, or score distribution. " +
             "Shows anime and manga stats side by side.",
         parameters: StatsInputSchema,
+        annotations: {
+            title: "Get User Stats",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const username = getDefaultUsername(args.username);

package/dist/tools/recommend.js

@@ -50,6 +50,12 @@ export function registerRecommendTools(server) {
             "what genres they like, or how they tend to score. " +
             "Analyzes genre preferences, theme weights, scoring patterns, and format split.",
         parameters: TasteInputSchema,
+        annotations: {
+            title: "Taste Profile",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const username = getDefaultUsername(args.username);
@@ -99,6 +105,12 @@ export function registerRecommendTools(server) {
             "based on your taste profile. Falls back to top-rated AniList titles " +
             "if the Planning list is empty. Optionally filter by mood or max episodes.",
         parameters: PickInputSchema,
+        annotations: {
+            title: "Pick Next Watch",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const username = getDefaultUsername(args.username);
@@ -200,6 +212,12 @@ export function registerRecommendTools(server) {
             "and genre divergences. Use when someone asks to compare their taste " +
             "with another user.",
         parameters: CompareInputSchema,
+        annotations: {
+            title: "Compare Users",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 // Fetch both users' completed lists in parallel
@@ -311,6 +329,12 @@ export function registerRecommendTools(server) {
             "Use when the user asks about their anime/manga year, what they watched/read " +
             "in a given year, or wants a recap. Defaults to the current year.",
         parameters: WrappedInputSchema,
+        annotations: {
+            title: "Year in Review",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const username = getDefaultUsername(args.username);
@@ -415,6 +439,12 @@ export function registerRecommendTools(server) {
             'Use when the user asks "why would I like this?", "is this for me?", or ' +
             "wants to know how well a specific anime/manga matches their preferences.",
         parameters: ExplainInputSchema,
+        annotations: {
+            title: "Explain Match",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const username = getDefaultUsername(args.username);
@@ -500,6 +530,12 @@ export function registerRecommendTools(server) {
             "Use when the user asks for shows like a specific title, " +
             "or wants content-based recommendations without needing a user profile.",
         parameters: SimilarInputSchema,
+        annotations: {
+            title: "Find Similar",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 // Fetch source details and recommendations in parallel

package/dist/tools/search.js

@@ -15,6 +15,12 @@ export function registerSearchTools(server) {
             "in a genre, or find what aired in a specific year. " +
             "Returns a ranked list with title, format, score, genres, and AniList URL.",
         parameters: SearchInputSchema,
+        annotations: {
+            title: "Search Anime/Manga",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const variables = {
@@ -61,6 +67,12 @@ export function registerSearchTools(server) {
             "episodes, studios, related works, and recommendations. " +
             "Provide either an AniList ID (faster, exact) or a title (fuzzy match).",
         parameters: DetailsInputSchema,
+        annotations: {
+            title: "Get Title Details",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 // AniList uses "search" as the GraphQL variable name for title lookups
@@ -147,6 +159,12 @@ export function registerSearchTools(server) {
             "Use when the user asks what's airing this season, what aired in a past season, " +
             "or wants to discover seasonal anime. Defaults to the current season/year.",
         parameters: SeasonalInputSchema,
+        annotations: {
+            title: "Browse Seasonal Anime",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const { season, year } = resolveSeasonYear(args.season, args.year);
@@ -192,6 +210,12 @@ export function registerSearchTools(server) {
             'or says "I liked X, what else should I watch?" ' +
             "Returns titles recommended by AniList users, sorted by recommendation count.",
         parameters: RecommendationsInputSchema,
+        annotations: {
+            title: "Get Recommendations",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 const variables = {

package/dist/tools/write.js

@@ -20,6 +20,13 @@ export function registerWriteTools(server) {
             "Use when the user says they watched an episode, finished a chapter, " +
             "or wants to record how far they are. Requires ANILIST_TOKEN.",
         parameters: UpdateProgressInputSchema,
+        annotations: {
+            title: "Update Progress",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 requireAuth();
@@ -50,6 +57,13 @@ export function registerWriteTools(server) {
             "Use when the user wants to start watching, plan to watch, " +
             "or mark a title as completed. Requires ANILIST_TOKEN.",
         parameters: AddToListInputSchema,
+        annotations: {
+            title: "Add to List",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 requireAuth();
@@ -81,6 +95,13 @@ export function registerWriteTools(server) {
             "Use when the user wants to give a rating (0-10). " +
             "Use 0 to remove an existing score. Requires ANILIST_TOKEN.",
         parameters: RateInputSchema,
+        annotations: {
+            title: "Rate Title",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 requireAuth();
@@ -104,6 +125,13 @@ export function registerWriteTools(server) {
             "Requires the list entry ID (not the media ID) - use anilist_list to find it. " +
             "Requires ANILIST_TOKEN.",
         parameters: DeleteFromListInputSchema,
+        annotations: {
+            title: "Delete from List",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         execute: async (args) => {
             try {
                 requireAuth();

package/manifest.json

@@ -0,0 +1,121 @@
+{
+  "manifest_version": "0.3",
+  "name": "ani-mcp",
+  "version": "0.2.4",
+  "display_name": "AniList MCP",
+  "description": "A smart MCP server for AniList that gets your anime/manga taste - not just API calls.",
+  "author": {
+    "name": "gavxm"
+  },
+  "license": "MIT",
+  "icon": "assets/icon.png",
+  "keywords": [
+    "anime",
+    "manga",
+    "anilist",
+    "recommendations"
+  ],
+  "privacy_policies": [
+    "https://github.com/gavxm/ani-mcp/blob/main/PRIVACY.md"
+  ],
+  "server": {
+    "type": "node",
+    "entry_point": "dist/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/dist/index.js"
+      ],
+      "env": {
+        "ANILIST_USERNAME": "${user_config.anilist_username}",
+        "ANILIST_TOKEN": "${user_config.anilist_token}"
+      }
+    }
+  },
+  "user_config": {
+    "anilist_username": {
+      "type": "string",
+      "title": "AniList Username",
+      "description": "Default AniList username for list and stats tools",
+      "required": false
+    },
+    "anilist_token": {
+      "type": "string",
+      "title": "AniList Token",
+      "description": "AniList OAuth token for write operations (update progress, rate, etc.)",
+      "required": false,
+      "sensitive": true
+    }
+  },
+  "tools": [
+    {
+      "name": "anilist_search"
+    },
+    {
+      "name": "anilist_details"
+    },
+    {
+      "name": "anilist_seasonal"
+    },
+    {
+      "name": "anilist_recommendations"
+    },
+    {
+      "name": "anilist_list"
+    },
+    {
+      "name": "anilist_stats"
+    },
+    {
+      "name": "anilist_trending"
+    },
+    {
+      "name": "anilist_genres"
+    },
+    {
+      "name": "anilist_taste"
+    },
+    {
+      "name": "anilist_pick"
+    },
+    {
+      "name": "anilist_compare"
+    },
+    {
+      "name": "anilist_wrapped"
+    },
+    {
+      "name": "anilist_explain"
+    },
+    {
+      "name": "anilist_similar"
+    },
+    {
+      "name": "anilist_staff"
+    },
+    {
+      "name": "anilist_staff_search"
+    },
+    {
+      "name": "anilist_studio_search"
+    },
+    {
+      "name": "anilist_schedule"
+    },
+    {
+      "name": "anilist_characters"
+    },
+    {
+      "name": "anilist_update_progress"
+    },
+    {
+      "name": "anilist_add_to_list"
+    },
+    {
+      "name": "anilist_rate"
+    },
+    {
+      "name": "anilist_delete_from_list"
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ani-mcp",
   "mcpName": "io.github.gavxm/ani-mcp",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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",
@@ -19,6 +19,7 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
+    "pack": "npx @anthropic-ai/mcpb pack",
     "release": "git tag v$(node -p \"require('./package.json').version\") && git push origin v$(node -p \"require('./package.json').version\")"
   },
   "keywords": [
@@ -36,7 +37,8 @@
   "homepage": "https://github.com/gavxm/ani-mcp",
   "files": [
     "dist",
-    "server.json"
+    "server.json",
+    "manifest.json"
   ],
   "engines": {
     "node": ">=18"

package/server.json

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