@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.
- package/AGENTS.md +346 -0
- package/CLAUDE.md +346 -0
- package/Dockerfile +99 -0
- package/LICENSE +201 -0
- package/README.md +313 -0
- package/changelog/0.1.x/0.1.1.md +42 -0
- package/changelog/template.md +127 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +24 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp-server/prompts/index.d.ts +7 -0
- package/dist/mcp-server/prompts/index.d.ts.map +1 -0
- package/dist/mcp-server/prompts/index.js +7 -0
- package/dist/mcp-server/prompts/index.js.map +1 -0
- package/dist/mcp-server/resources/definitions/anime-media.resource.d.ts +31 -0
- package/dist/mcp-server/resources/definitions/anime-media.resource.d.ts.map +1 -0
- package/dist/mcp-server/resources/definitions/anime-media.resource.js +100 -0
- package/dist/mcp-server/resources/definitions/anime-media.resource.js.map +1 -0
- package/dist/mcp-server/resources/index.d.ts +29 -0
- package/dist/mcp-server/resources/index.d.ts.map +1 -0
- package/dist/mcp-server/resources/index.js +7 -0
- package/dist/mcp-server/resources/index.js.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-find-characters.tool.d.ts +77 -0
- package/dist/mcp-server/tools/definitions/anime-find-characters.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-find-characters.tool.js +308 -0
- package/dist/mcp-server/tools/definitions/anime-find-characters.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-media.tool.d.ts +92 -0
- package/dist/mcp-server/tools/definitions/anime-get-media.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-media.tool.js +425 -0
- package/dist/mcp-server/tools/definitions/anime-get-media.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-rankings.tool.d.ts +73 -0
- package/dist/mcp-server/tools/definitions/anime-get-rankings.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-rankings.tool.js +154 -0
- package/dist/mcp-server/tools/definitions/anime-get-rankings.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-recommendations.tool.d.ts +35 -0
- package/dist/mcp-server/tools/definitions/anime-get-recommendations.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-recommendations.tool.js +174 -0
- package/dist/mcp-server/tools/definitions/anime-get-recommendations.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-relations.tool.d.ts +43 -0
- package/dist/mcp-server/tools/definitions/anime-get-relations.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-relations.tool.js +245 -0
- package/dist/mcp-server/tools/definitions/anime-get-relations.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-schedule.tool.d.ts +51 -0
- package/dist/mcp-server/tools/definitions/anime-get-schedule.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-schedule.tool.js +196 -0
- package/dist/mcp-server/tools/definitions/anime-get-schedule.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-studio.tool.d.ts +50 -0
- package/dist/mcp-server/tools/definitions/anime-get-studio.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-get-studio.tool.js +163 -0
- package/dist/mcp-server/tools/definitions/anime-get-studio.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-search-media.tool.d.ts +73 -0
- package/dist/mcp-server/tools/definitions/anime-search-media.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/anime-search-media.tool.js +229 -0
- package/dist/mcp-server/tools/definitions/anime-search-media.tool.js.map +1 -0
- package/dist/mcp-server/tools/index.d.ts +435 -0
- package/dist/mcp-server/tools/index.d.ts.map +1 -0
- package/dist/mcp-server/tools/index.js +23 -0
- package/dist/mcp-server/tools/index.js.map +1 -0
- package/dist/services/anilist/anilist-service.d.ts +90 -0
- package/dist/services/anilist/anilist-service.d.ts.map +1 -0
- package/dist/services/anilist/anilist-service.js +496 -0
- package/dist/services/anilist/anilist-service.js.map +1 -0
- package/dist/services/anilist/types.d.ts +255 -0
- package/dist/services/anilist/types.d.ts.map +1 -0
- package/dist/services/anilist/types.js +6 -0
- package/dist/services/anilist/types.js.map +1 -0
- package/dist/services/jikan/jikan-service.d.ts +22 -0
- package/dist/services/jikan/jikan-service.d.ts.map +1 -0
- package/dist/services/jikan/jikan-service.js +89 -0
- package/dist/services/jikan/jikan-service.js.map +1 -0
- package/dist/services/jikan/types.d.ts +85 -0
- package/dist/services/jikan/types.d.ts.map +1 -0
- package/dist/services/jikan/types.js +6 -0
- package/dist/services/jikan/types.js.map +1 -0
- package/dist/services/kitsu/kitsu-service.d.ts +14 -0
- package/dist/services/kitsu/kitsu-service.d.ts.map +1 -0
- package/dist/services/kitsu/kitsu-service.js +94 -0
- package/dist/services/kitsu/kitsu-service.js.map +1 -0
- package/dist/services/kitsu/types.d.ts +17 -0
- package/dist/services/kitsu/types.d.ts.map +1 -0
- package/dist/services/kitsu/types.js +6 -0
- package/dist/services/kitsu/types.js.map +1 -0
- package/package.json +103 -0
- 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
|
+
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/anime-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/anime-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
|
+
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
<div align="center">
|
|
15
|
+
|
|
16
|
+
[](https://github.com/cyanheads/anime-mcp-server/releases/latest/download/anime-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=anime-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYW5pbWUtbWNwLXNlcnZlciJdfQ==) [](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
|
+
[](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
|
+
- -->
|
package/dist/index.d.ts
ADDED
|
@@ -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 @@
|
|
|
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"}
|