@cyanheads/anime-mcp-server 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/AGENTS.md +346 -0
  2. package/CLAUDE.md +346 -0
  3. package/Dockerfile +99 -0
  4. package/LICENSE +201 -0
  5. package/README.md +313 -0
  6. package/changelog/0.1.x/0.1.1.md +42 -0
  7. package/changelog/template.md +127 -0
  8. package/dist/index.d.ts +8 -0
  9. package/dist/index.d.ts.map +1 -0
  10. package/dist/index.js +24 -0
  11. package/dist/index.js.map +1 -0
  12. package/dist/mcp-server/prompts/index.d.ts +7 -0
  13. package/dist/mcp-server/prompts/index.d.ts.map +1 -0
  14. package/dist/mcp-server/prompts/index.js +7 -0
  15. package/dist/mcp-server/prompts/index.js.map +1 -0
  16. package/dist/mcp-server/resources/definitions/anime-media.resource.d.ts +31 -0
  17. package/dist/mcp-server/resources/definitions/anime-media.resource.d.ts.map +1 -0
  18. package/dist/mcp-server/resources/definitions/anime-media.resource.js +100 -0
  19. package/dist/mcp-server/resources/definitions/anime-media.resource.js.map +1 -0
  20. package/dist/mcp-server/resources/index.d.ts +29 -0
  21. package/dist/mcp-server/resources/index.d.ts.map +1 -0
  22. package/dist/mcp-server/resources/index.js +7 -0
  23. package/dist/mcp-server/resources/index.js.map +1 -0
  24. package/dist/mcp-server/tools/definitions/anime-find-characters.tool.d.ts +77 -0
  25. package/dist/mcp-server/tools/definitions/anime-find-characters.tool.d.ts.map +1 -0
  26. package/dist/mcp-server/tools/definitions/anime-find-characters.tool.js +308 -0
  27. package/dist/mcp-server/tools/definitions/anime-find-characters.tool.js.map +1 -0
  28. package/dist/mcp-server/tools/definitions/anime-get-media.tool.d.ts +92 -0
  29. package/dist/mcp-server/tools/definitions/anime-get-media.tool.d.ts.map +1 -0
  30. package/dist/mcp-server/tools/definitions/anime-get-media.tool.js +425 -0
  31. package/dist/mcp-server/tools/definitions/anime-get-media.tool.js.map +1 -0
  32. package/dist/mcp-server/tools/definitions/anime-get-rankings.tool.d.ts +73 -0
  33. package/dist/mcp-server/tools/definitions/anime-get-rankings.tool.d.ts.map +1 -0
  34. package/dist/mcp-server/tools/definitions/anime-get-rankings.tool.js +154 -0
  35. package/dist/mcp-server/tools/definitions/anime-get-rankings.tool.js.map +1 -0
  36. package/dist/mcp-server/tools/definitions/anime-get-recommendations.tool.d.ts +35 -0
  37. package/dist/mcp-server/tools/definitions/anime-get-recommendations.tool.d.ts.map +1 -0
  38. package/dist/mcp-server/tools/definitions/anime-get-recommendations.tool.js +174 -0
  39. package/dist/mcp-server/tools/definitions/anime-get-recommendations.tool.js.map +1 -0
  40. package/dist/mcp-server/tools/definitions/anime-get-relations.tool.d.ts +43 -0
  41. package/dist/mcp-server/tools/definitions/anime-get-relations.tool.d.ts.map +1 -0
  42. package/dist/mcp-server/tools/definitions/anime-get-relations.tool.js +245 -0
  43. package/dist/mcp-server/tools/definitions/anime-get-relations.tool.js.map +1 -0
  44. package/dist/mcp-server/tools/definitions/anime-get-schedule.tool.d.ts +51 -0
  45. package/dist/mcp-server/tools/definitions/anime-get-schedule.tool.d.ts.map +1 -0
  46. package/dist/mcp-server/tools/definitions/anime-get-schedule.tool.js +196 -0
  47. package/dist/mcp-server/tools/definitions/anime-get-schedule.tool.js.map +1 -0
  48. package/dist/mcp-server/tools/definitions/anime-get-studio.tool.d.ts +50 -0
  49. package/dist/mcp-server/tools/definitions/anime-get-studio.tool.d.ts.map +1 -0
  50. package/dist/mcp-server/tools/definitions/anime-get-studio.tool.js +163 -0
  51. package/dist/mcp-server/tools/definitions/anime-get-studio.tool.js.map +1 -0
  52. package/dist/mcp-server/tools/definitions/anime-search-media.tool.d.ts +73 -0
  53. package/dist/mcp-server/tools/definitions/anime-search-media.tool.d.ts.map +1 -0
  54. package/dist/mcp-server/tools/definitions/anime-search-media.tool.js +229 -0
  55. package/dist/mcp-server/tools/definitions/anime-search-media.tool.js.map +1 -0
  56. package/dist/mcp-server/tools/index.d.ts +435 -0
  57. package/dist/mcp-server/tools/index.d.ts.map +1 -0
  58. package/dist/mcp-server/tools/index.js +23 -0
  59. package/dist/mcp-server/tools/index.js.map +1 -0
  60. package/dist/services/anilist/anilist-service.d.ts +90 -0
  61. package/dist/services/anilist/anilist-service.d.ts.map +1 -0
  62. package/dist/services/anilist/anilist-service.js +496 -0
  63. package/dist/services/anilist/anilist-service.js.map +1 -0
  64. package/dist/services/anilist/types.d.ts +255 -0
  65. package/dist/services/anilist/types.d.ts.map +1 -0
  66. package/dist/services/anilist/types.js +6 -0
  67. package/dist/services/anilist/types.js.map +1 -0
  68. package/dist/services/jikan/jikan-service.d.ts +22 -0
  69. package/dist/services/jikan/jikan-service.d.ts.map +1 -0
  70. package/dist/services/jikan/jikan-service.js +89 -0
  71. package/dist/services/jikan/jikan-service.js.map +1 -0
  72. package/dist/services/jikan/types.d.ts +85 -0
  73. package/dist/services/jikan/types.d.ts.map +1 -0
  74. package/dist/services/jikan/types.js +6 -0
  75. package/dist/services/jikan/types.js.map +1 -0
  76. package/dist/services/kitsu/kitsu-service.d.ts +14 -0
  77. package/dist/services/kitsu/kitsu-service.d.ts.map +1 -0
  78. package/dist/services/kitsu/kitsu-service.js +94 -0
  79. package/dist/services/kitsu/kitsu-service.js.map +1 -0
  80. package/dist/services/kitsu/types.d.ts +17 -0
  81. package/dist/services/kitsu/types.d.ts.map +1 -0
  82. package/dist/services/kitsu/types.js +6 -0
  83. package/dist/services/kitsu/types.js.map +1 -0
  84. package/package.json +103 -0
  85. package/server.json +99 -0
package/README.md ADDED
@@ -0,0 +1,313 @@
1
+ <div align="center">
2
+ <h1>@cyanheads/anime-mcp-server</h1>
3
+ <p><b>Search anime/manga, get full detail, franchise watch order, seasonal schedule, characters, rankings, and studio filmography via MCP. STDIO or Streamable HTTP.</b>
4
+ <div>8 Tools • 1 Resource</div>
5
+ </p>
6
+ </div>
7
+
8
+ <div align="center">
9
+
10
+ [![Version](https://img.shields.io/badge/Version-0.1.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/anime-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/anime-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/anime-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
+
12
+ </div>
13
+
14
+ <div align="center">
15
+
16
+ [![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/anime-mcp-server/releases/latest/download/anime-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=anime-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYW5pbWUtbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22anime-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fanime-mcp-server%22%5D%7D)
17
+
18
+ [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
19
+
20
+ </div>
21
+
22
+ ---
23
+
24
+ ## Tools
25
+
26
+ Eight tools covering anime and manga discovery, detail, and navigation:
27
+
28
+ | Tool | Description |
29
+ |:---|:---|
30
+ | `anime_search_media` | Search anime or manga by title, genre, tag, season, year, format, or status. Returns ranked results with IDs, titles, scores, format, and episode/chapter counts. AniList primary; Jikan fallback on empty results. |
31
+ | `anime_get_media` | Full detail for one anime or manga by AniList ID — synopsis, format, episode/chapter count, status, season, studios, source material, genres and tags (spoiler-flagged), AniList and MAL scores side by side, streaming links, cover/banner, and direct relations. |
32
+ | `anime_get_relations` | Franchise untangler. Walks the related-works graph from a media ID beyond one hop — sequels, prequels, side stories, movies, OVAs, source and adaptation — and returns them in suggested watch/read order. |
33
+ | `anime_get_schedule` | Airing schedule for a season or upcoming episode window. Season mode lists all anime airing in a given season/year. Upcoming mode returns the next episode for each airing title within a date window, with UTC timestamp and countdown. |
34
+ | `anime_find_characters` | Characters and voice actors for a title, or look up a character/VA by name. Returns characters with role (main/supporting/background), voice actors by language, and cross-links to other media. |
35
+ | `anime_get_recommendations` | Recommendations for a title, merged from AniList and Jikan (MAL), with scores and vote counts. Optionally accepts what the user liked about the source title to contextualize picks. |
36
+ | `anime_get_rankings` | Top, trending, or seasonal rankings. Filterable by genre, tag, and format. Top returns all-time by score; trending returns current week; seasonal returns the current or specified season sorted by popularity. |
37
+ | `anime_get_studio` | A studio's full filmography by name or AniList studio ID — all titles the studio produced, sortable by year or score, with format, status, and episode count. |
38
+
39
+ ### `anime_search_media`
40
+
41
+ Search for anime or manga across multiple dimensions.
42
+
43
+ - Free-text title search with AniList primary; falls back to Jikan when AniList returns empty
44
+ - Filter by genre, tag, season, year, format (`TV`, `MOVIE`, `OVA`, `MANGA`, `NOVEL`, etc.), and status (`RELEASING`, `FINISHED`, etc.)
45
+ - Adult content gated behind explicit `include_adult: true` (default off)
46
+ - Pagination via `page` and `per_page`
47
+
48
+ ---
49
+
50
+ ### `anime_get_media`
51
+
52
+ Full detail for a single anime or manga — the flagship tool for a title's complete profile.
53
+
54
+ - AniList full-detail query supplemented in parallel by Jikan (MAL score) and Kitsu (streaming links with sub/dub language flags)
55
+ - AniList and MAL scores surfaced side by side — never blended
56
+ - Spoiler-safe by default: tags carry a `spoiler` flag; relation descriptions omitted unless `reveal_spoilers: true`
57
+ - All timestamps UTC; season labels included to avoid boundary ambiguity
58
+
59
+ ---
60
+
61
+ ### `anime_get_relations`
62
+
63
+ Build the watch/read order for an entire franchise.
64
+
65
+ - Multi-hop BFS over AniList's relation graph, up to `max_depth` hops (default 2, max 4)
66
+ - Relation types: SOURCE, PREQUEL, SEQUEL, SIDE_STORY, SPIN_OFF, ADAPTATION, OVA, SPECIAL, MOVIE
67
+ - Topological sort: SOURCE → PREQUEL → main story chain → SEQUEL → SIDE_STORY → SPIN_OFF → supplementary entries
68
+ - Each entry includes `seasonYear` and episode/chapter count for context
69
+
70
+ ---
71
+
72
+ ### `anime_find_characters`
73
+
74
+ Bidirectional character and voice actor lookup.
75
+
76
+ - By media ID: characters for a title with voice actors by language
77
+ - By character name: find the character and all media they appear in
78
+ - By voice actor name: find the VA and all roles across media
79
+ - Language filter via AniList `StaffLanguage` enum (JAPANESE, ENGLISH, KOREAN, etc.)
80
+
81
+ ---
82
+
83
+ ## Resources and prompts
84
+
85
+ | Type | Name | Description |
86
+ |:---|:---|:---|
87
+ | Resource | `anime://media/{id}` | Full media record for an anime or manga by AniList ID — same data as `anime_get_media`. Stable URI for injectable context. |
88
+
89
+ All resource data is also reachable via tools. Use `anime_search_media` to discover AniList IDs before fetching the resource URI.
90
+
91
+ ---
92
+
93
+ ## Features
94
+
95
+ Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
96
+
97
+ - Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
98
+ - Unified error handling — handlers throw, framework catches, classifies, and formats
99
+ - Pluggable auth: `none`, `jwt`, `oauth`
100
+ - Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
101
+ - Structured logging with optional OpenTelemetry tracing
102
+ - STDIO and Streamable HTTP transports
103
+
104
+ Anime/manga-specific:
105
+
106
+ - Three-source architecture: AniList GraphQL (primary), Jikan v4 REST (MAL scores + recommendations), Kitsu JSON:API (streaming links with sub/dub language detail)
107
+ - ID reconciliation via AniList's `idMal` bridge — no cross-source ID guessing
108
+ - Franchise relation graph traversal with topological watch-order sort
109
+ - Rate-limit-aware service layer: AniList 30 req/30s with automatic backoff; Jikan 350ms floor between calls
110
+ - Keyless by design — all three sources are public and require no API credentials
111
+ - **Local-only by design:** free APIs are tightly rate-limited per IP; hosting would pool users onto one IP and risk throttling or bans. Each local user brings their own IP and modest usage.
112
+
113
+ Agent-friendly output:
114
+
115
+ - Dual scores surfaced separately — AniList `meanScore` (0–100) and MAL `score` (0–10) with population size (`scored_by`) so agents can reason about weight; never blended into a composite
116
+ - Spoiler safety by default — AniList tags carry `isGeneralSpoiler`; relation descriptions omitted unless opted in
117
+ - Supplement provenance — each response indicates which sources contributed (AniList, Jikan, Kitsu) and which failed gracefully, so agents know what data is present
118
+ - UTC timestamps throughout; season labels echoed (`WINTER 2024`) to avoid the winter/spring/summer/fall boundary footgun
119
+
120
+ ---
121
+
122
+ ## Getting started
123
+
124
+ No API keys required — all three upstream sources (AniList, Jikan, Kitsu) are keyless public APIs.
125
+
126
+ Add the following to your MCP client configuration file:
127
+
128
+ ```json
129
+ {
130
+ "mcpServers": {
131
+ "anime-mcp-server": {
132
+ "type": "stdio",
133
+ "command": "bunx",
134
+ "args": ["@cyanheads/anime-mcp-server@latest"],
135
+ "env": {
136
+ "MCP_TRANSPORT_TYPE": "stdio",
137
+ "MCP_LOG_LEVEL": "info"
138
+ }
139
+ }
140
+ }
141
+ }
142
+ ```
143
+
144
+ Or with npx (no Bun required):
145
+
146
+ ```json
147
+ {
148
+ "mcpServers": {
149
+ "anime-mcp-server": {
150
+ "type": "stdio",
151
+ "command": "npx",
152
+ "args": ["-y", "@cyanheads/anime-mcp-server@latest"],
153
+ "env": {
154
+ "MCP_TRANSPORT_TYPE": "stdio",
155
+ "MCP_LOG_LEVEL": "info"
156
+ }
157
+ }
158
+ }
159
+ }
160
+ ```
161
+
162
+ Or with Docker:
163
+
164
+ ```json
165
+ {
166
+ "mcpServers": {
167
+ "anime-mcp-server": {
168
+ "type": "stdio",
169
+ "command": "docker",
170
+ "args": [
171
+ "run", "-i", "--rm",
172
+ "-e", "MCP_TRANSPORT_TYPE=stdio",
173
+ "ghcr.io/cyanheads/anime-mcp-server:latest"
174
+ ]
175
+ }
176
+ }
177
+ }
178
+ ```
179
+
180
+ For Streamable HTTP, set the transport and start the server:
181
+
182
+ ```sh
183
+ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
184
+ # Server listens at http://localhost:3010/mcp
185
+ ```
186
+
187
+ ### Prerequisites
188
+
189
+ - [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+). No API keys needed.
190
+
191
+ ### Installation
192
+
193
+ 1. **Clone the repository:**
194
+
195
+ ```sh
196
+ git clone https://github.com/cyanheads/anime-mcp-server.git
197
+ ```
198
+
199
+ 2. **Navigate into the directory:**
200
+
201
+ ```sh
202
+ cd anime-mcp-server
203
+ ```
204
+
205
+ 3. **Install dependencies:**
206
+
207
+ ```sh
208
+ bun install
209
+ ```
210
+
211
+ 4. **Configure environment (optional):**
212
+
213
+ ```sh
214
+ cp .env.example .env
215
+ # edit .env if you want to change transport or log level
216
+ ```
217
+
218
+ ---
219
+
220
+ ## Configuration
221
+
222
+ No server-specific env vars are required. All framework variables are optional with sensible defaults.
223
+
224
+ | Variable | Description | Default |
225
+ |:---------|:------------|:--------|
226
+ | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
227
+ | `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
228
+ | `MCP_HTTP_HOST` | Hostname for HTTP server. | `127.0.0.1` |
229
+ | `MCP_HTTP_ENDPOINT_PATH` | Endpoint path for the MCP server. | `/mcp` |
230
+ | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
231
+ | `MCP_LOG_LEVEL` | Log level (RFC 5424): `debug`, `info`, `notice`, `warning`, `error`. | `info` |
232
+ | `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
233
+
234
+ See [`.env.example`](./.env.example) for the full list of optional overrides.
235
+
236
+ ---
237
+
238
+ ## Running the server
239
+
240
+ ### Local development
241
+
242
+ - **Build and run:**
243
+
244
+ ```sh
245
+ # One-time build
246
+ bun run rebuild
247
+
248
+ # Run the built server
249
+ bun run start:stdio
250
+ # or
251
+ bun run start:http
252
+ ```
253
+
254
+ - **Run checks and tests:**
255
+
256
+ ```sh
257
+ bun run devcheck # Lint, format, typecheck, security
258
+ bun run test # Vitest test suite
259
+ bun run lint:mcp # Validate MCP definitions against spec
260
+ ```
261
+
262
+ ### Docker
263
+
264
+ ```sh
265
+ docker build -t anime-mcp-server .
266
+ docker run --rm -p 3010:3010 anime-mcp-server
267
+ ```
268
+
269
+ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/anime-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
270
+
271
+ ---
272
+
273
+ ## Project structure
274
+
275
+ | Directory | Purpose |
276
+ |:----------|:--------|
277
+ | `src/index.ts` | `createApp()` entry point — registers tools, resources, and inits services. |
278
+ | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |
279
+ | `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). |
280
+ | `src/services/anilist` | AniList GraphQL client — primary source for all queries. |
281
+ | `src/services/jikan` | Jikan v4 REST client — MAL scores and recommendations. |
282
+ | `src/services/kitsu` | Kitsu JSON:API client — streaming links with sub/dub language detail. |
283
+ | `tests/` | Unit and integration tests mirroring `src/`. |
284
+ | `changelog/` | Per-version changelog files (`changelog/<minor>.x/<version>.md`). |
285
+
286
+ ---
287
+
288
+ ## Development guide
289
+
290
+ See [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
291
+
292
+ - Handlers throw, framework catches — no `try/catch` in tool logic
293
+ - Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage
294
+ - Register new tools and resources via the barrels in `src/mcp-server/*/definitions/index.ts`
295
+ - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
296
+ - AniList is primary — supplement failures (Jikan, Kitsu) degrade gracefully via `Promise.allSettled`
297
+
298
+ ---
299
+
300
+ ## Contributing
301
+
302
+ Issues and pull requests are welcome. Run checks and tests before submitting:
303
+
304
+ ```sh
305
+ bun run devcheck
306
+ bun run test
307
+ ```
308
+
309
+ ---
310
+
311
+ ## License
312
+
313
+ Apache-2.0 — see [LICENSE](LICENSE) for details.
@@ -0,0 +1,42 @@
1
+ ---
2
+ summary: "Initial public release — 8 anime/manga tools + 1 resource over AniList, Jikan, and Kitsu with input-bounds hardening"
3
+ breaking: false
4
+ security: true
5
+ ---
6
+
7
+ # 0.1.1 — 2026-06-05
8
+
9
+ Initial public release of `@cyanheads/anime-mcp-server`. Provides 8 MCP tools and 1 resource over three keyless anime/manga APIs — [AniList](https://anilist.co/graphiql) (primary), [Jikan](https://jikan.moe/) (MAL scores and recommendations), and [Kitsu](https://kitsu.io/api/edge/) (streaming links):
10
+
11
+ - **`anime_search_media`** — search anime or manga by title, genre, tag, season, year, format, status, and sort
12
+ - **`anime_get_media`** — full detail record for an anime or manga by AniList ID (dual score: AniList mean + MAL rating)
13
+ - **`anime_get_relations`** — franchise watch order — sequels, prequels, side stories, and spin-offs via the AniList relations graph
14
+ - **`anime_get_schedule`** — current airing schedule by weekday with episode info and countdown
15
+ - **`anime_find_characters`** — find characters or staff (voice actors) by name, filtered by media or language
16
+ - **`anime_get_recommendations`** — recommendations for a title, optionally guided by liked aspects (freeform)
17
+ - **`anime_get_rankings`** — top, trending, or seasonal rankings for anime or manga with genre/format filters
18
+ - **`anime_get_studio`** — studio profile and full filmography by name or AniList studio ID
19
+ - **`anime://media/{id}`** resource — full JSON media record by AniList ID
20
+
21
+ ## Added
22
+
23
+ - **`anime_search_media`** — AniList search with title, genre, tag, season, year, format, status, and sort fields
24
+ - **`anime_get_media`** — full media detail with dual score (AniList mean + MAL rating via Jikan), streaming links via Kitsu, and normalized status/format/season fields
25
+ - **`anime_get_relations`** — franchise graph traversal for watch-order — sequels, prequels, side stories, spin-offs, adaptations
26
+ - **`anime_get_schedule`** — current airing schedule from AniList, grouped by weekday with next-episode countdown
27
+ - **`anime_find_characters`** — character and voice actor/staff search across AniList, with optional media and language filters
28
+ - **`anime_get_recommendations`** — cross-source recommendations (AniList primary, Jikan supplement) with optional free-text aspect guidance
29
+ - **`anime_get_rankings`** — AniList top/trending/seasonal rankings with genre, format, and season filters
30
+ - **`anime_get_studio`** — studio profile and full filmography (popularity-sorted)
31
+ - **`anime://media/{id}`** — URI-addressable full media record (AniList ID as string param)
32
+ - **Three-source service layer** — `anilist-service.ts` (GraphQL), `jikan-service.ts` (REST), `kitsu-service.ts` (JSON:API), each with independent retry and graceful degradation
33
+
34
+ ## Security
35
+
36
+ - **`anime_search_media`** — `query`, `genre`, `tag` bounded to `max(200)`, `max(100)`, `max(100)`; `sort` array capped at `max(5)` items with each element `max(50)` — prevents unbounded injection into AniList GraphQL variables
37
+ - **`anime_get_rankings`** — `genre` bounded to `max(100)`
38
+ - **`anime_get_recommendations`** — `liked_aspects` bounded to `max(500)` — free-text field forwarded to AniList
39
+ - **`anime_get_studio`** — `name` bounded to `max(200)`
40
+ - **`anime_find_characters`** — `character_name` and `voice_actor_name` bounded to `max(200)` each
41
+ - **`kitsu-service.ts`** — numeric-only guard on Kitsu IDs (`/^\d+$/`) — rejects path-traversal or scheme-injection via malformed API response before the ID reaches the Kitsu endpoint URL
42
+ - **`anime-media.resource.ts`** — `Number.isNaN` instead of `isNaN` for AniList ID validation (avoids implicit coercion)
@@ -0,0 +1,127 @@
1
+ ---
2
+ # FORMAT REFERENCE — do not edit. Copy this file to
3
+ # `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
4
+ # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
5
+ # with a concrete date.
6
+
7
+ # Required. One-line GitHub Release-style headline. 350 character cap.
8
+ # Default short and scannable. Don't pad, don't stitch unrelated changes with
9
+ # semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
10
+ # inside the value as a key separator and fails GitHub's strict parser.
11
+ summary: ""
12
+
13
+ # Set `true` when consumers must change code to upgrade: API removals,
14
+ # signature changes, config renames, behavior changes that break existing
15
+ # usage. Flagged as `Breaking` in the rollup.
16
+ breaking: false
17
+
18
+ # Set `true` if this release contains any security fix. Pairs with the
19
+ # `## Security` section below. Flagged as `Security` in the rollup so
20
+ # users can triage upgrade urgency at a glance.
21
+ security: false
22
+
23
+ # Optional free-form notes for maintenance agents processing this release.
24
+ # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
25
+ # downstream servers. Use for adoption instructions that don't fit the
26
+ # human-facing sections: new files to create, fields to populate, one-time
27
+ # migration steps. Omit the field entirely when there's nothing to say.
28
+ # agent-notes: |
29
+ # <instructions for downstream maintenance agents>
30
+ ---
31
+
32
+ # <version> — YYYY-MM-DD
33
+
34
+ <!--
35
+ AUTHORING GUIDE — applies to the new per-version file you create from this
36
+ template.
37
+
38
+ Audience: someone scanning release notes to decide what affects them. Lead
39
+ each bullet with the symbol or concept name in **bold** so they can skip
40
+ what's irrelevant and zoom in on what's not.
41
+
42
+ Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
43
+ name the symbol, state what changed, stop. Use a second sentence only when
44
+ it carries weight. If a bullet feels long, it is.
45
+
46
+ Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
47
+ relevant skill), ceremonial framings ("This release introduces…",
48
+ backwards-compat paragraphs), file-by-file test enumerations, internal
49
+ implementation notes. Prefer code/symbol names over English re-explanations.
50
+
51
+ Narrative intro: skip by default. Add one short sentence only when the
52
+ release theme genuinely needs framing the bullets can't carry.
53
+
54
+ Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
55
+ Fixed, Security. Include only sections with entries; delete the rest
56
+ (including the commented-out scaffolding below). Don't ship empty headers.
57
+
58
+ Include: every distinct fact a reader needs to adopt or audit the release —
59
+ new exports, signatures, lint rule IDs, env vars, breaking changes, version
60
+ bumps on shipped skills. Nothing more.
61
+
62
+ Links: link issues, PRs, docs, or skills where they help a reader jump to
63
+ context. Once per item per entry — don't re-link the same issue in summary,
64
+ narrative, and bullet. Skip links for inline symbol names; code spans speak
65
+ for themselves.
66
+
67
+ Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
68
+ inside its own UI, not in npm reads or local editors.
69
+
70
+ [#38](https://github.com/cyanheads/mcp-ts-core/issues/38) ← issue
71
+ [#42](https://github.com/cyanheads/mcp-ts-core/pull/42) ← PR
72
+
73
+ Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
74
+ Never speculate on a future number — `#42` for an upcoming PR silently
75
+ resolves to whatever real item already owns 42, and timeline previews pull
76
+ in that unrelated item's metadata.
77
+
78
+ TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
79
+ via `gh release create --notes-from-tag`. The tag is a derivative of this
80
+ changelog entry — a condensed, scannable version, not a copy. Format:
81
+
82
+ <theme — omit version number, GitHub prepends it>
83
+ ← blank line
84
+ <1-2 sentence context: what this release does>
85
+ ← blank line
86
+ Dependency bumps: ← section header
87
+ ← blank line
88
+ - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6 ← bullet
89
+ ← blank line
90
+ Changed: ← only sections with entries
91
+ ← blank line
92
+ - `format()` output includes `query` in text mode
93
+ ← blank line
94
+ Added:
95
+ ← blank line
96
+ - `manifest.json` scaffolded for MCPB bundle support
97
+ - Install badges (Claude Desktop, Cursor, VS Code)
98
+ ← blank line
99
+ <N> tests pass; `bun run devcheck` clean. ← footer
100
+
101
+ Never a flat comma-separated string. Always structured markdown with
102
+ sections. The tag must scan well as a rendered GitHub Release page.
103
+ -->
104
+
105
+ ## Added
106
+
107
+ -
108
+
109
+ ## Changed
110
+
111
+ -
112
+
113
+ <!-- ## Deprecated
114
+
115
+ - -->
116
+
117
+ <!-- ## Removed
118
+
119
+ - -->
120
+
121
+ ## Fixed
122
+
123
+ -
124
+
125
+ <!-- ## Security
126
+
127
+ - -->
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * @fileoverview anime-mcp-server MCP server entry point.
4
+ * Multi-source anime and manga server over AniList GraphQL, Jikan v4, and Kitsu JSON:API.
5
+ * @module index
6
+ */
7
+ export {};
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;GAIG"}
package/dist/index.js ADDED
@@ -0,0 +1,24 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * @fileoverview anime-mcp-server MCP server entry point.
4
+ * Multi-source anime and manga server over AniList GraphQL, Jikan v4, and Kitsu JSON:API.
5
+ * @module index
6
+ */
7
+ import { createApp } from '@cyanheads/mcp-ts-core';
8
+ import { allPromptDefinitions } from './mcp-server/prompts/index.js';
9
+ import { allResourceDefinitions } from './mcp-server/resources/index.js';
10
+ import { allToolDefinitions } from './mcp-server/tools/index.js';
11
+ await createApp({
12
+ tools: allToolDefinitions,
13
+ resources: allResourceDefinitions,
14
+ prompts: allPromptDefinitions,
15
+ instructions: `Anime and manga data from AniList, MAL (via Jikan), and Kitsu.
16
+ - Use anime_search_media to discover AniList IDs, then anime_get_media for full detail.
17
+ - Use anime_get_relations to build watch/read order for a franchise.
18
+ - Use anime_get_schedule for seasonal airing schedules or upcoming episodes.
19
+ - Use anime_find_characters for cast lookup or voice actor role search.
20
+ - Scores: AniList and MAL scores are surfaced separately — never blended.
21
+ - Adult content: off by default; opt in via include_adult: true.
22
+ - Rate limits: AniList 30 req/30s, Jikan ~3 req/sec. Service layer handles backoff automatically.`,
23
+ });
24
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,SAAS,CAAC;IACd,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC,OAAO,EAAE,oBAAoB;IAC7B,YAAY,EAAE;;;;;;;kGAOkF;CACjG,CAAC,CAAC"}
@@ -0,0 +1,7 @@
1
+ /**
2
+ * @fileoverview Barrel export for anime-mcp-server prompt definitions.
3
+ * No prompts defined — this is a data-retrieval server.
4
+ * @module mcp-server/prompts/index
5
+ */
6
+ export declare const allPromptDefinitions: never[];
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/prompts/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,oBAAoB,EAAE,KAAK,EAAO,CAAC"}
@@ -0,0 +1,7 @@
1
+ /**
2
+ * @fileoverview Barrel export for anime-mcp-server prompt definitions.
3
+ * No prompts defined — this is a data-retrieval server.
4
+ * @module mcp-server/prompts/index
5
+ */
6
+ export const allPromptDefinitions = [];
7
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp-server/prompts/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAY,EAAE,CAAC"}
@@ -0,0 +1,31 @@
1
+ /**
2
+ * @fileoverview anime://media/{id} resource — full media record by AniList ID.
3
+ * Delegates to the same service layer as anime_get_media for stable URI-injectable context.
4
+ * @module mcp-server/resources/definitions/anime-media.resource
5
+ */
6
+ import { z } from '@cyanheads/mcp-ts-core';
7
+ export declare const animeMediaResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
8
+ id: z.ZodString;
9
+ }, z.core.$strip>, z.ZodObject<{
10
+ id: z.ZodNumber;
11
+ id_mal: z.ZodNullable<z.ZodNumber>;
12
+ type: z.ZodString;
13
+ title: z.ZodObject<{
14
+ romaji: z.ZodNullable<z.ZodString>;
15
+ english: z.ZodNullable<z.ZodString>;
16
+ native: z.ZodNullable<z.ZodString>;
17
+ }, z.core.$strip>;
18
+ format: z.ZodNullable<z.ZodString>;
19
+ status: z.ZodNullable<z.ZodString>;
20
+ season: z.ZodNullable<z.ZodString>;
21
+ description: z.ZodNullable<z.ZodString>;
22
+ episodes: z.ZodNullable<z.ZodNumber>;
23
+ chapters: z.ZodNullable<z.ZodNumber>;
24
+ genres: z.ZodArray<z.ZodString>;
25
+ mean_score: z.ZodNullable<z.ZodNumber>;
26
+ mal_score: z.ZodNullable<z.ZodNumber>;
27
+ streaming_count: z.ZodNumber;
28
+ cover_image_url: z.ZodNullable<z.ZodString>;
29
+ site_url: z.ZodNullable<z.ZodString>;
30
+ }, z.core.$strip>, undefined>;
31
+ //# sourceMappingURL=anime-media.resource.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"anime-media.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/anime-media.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAMrD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;6BAiG7B,CAAC"}