mcp-metacritic 1.2.1 → 2.0.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/CHANGELOG.md +137 -0
- package/LICENSE +1 -1
- package/PRIVACY.md +154 -0
- package/README.md +405 -235
- package/dist/index.js +420 -172
- package/dist/index.js.map +1 -1
- package/dist/mc/client.js +225 -91
- package/dist/mc/client.js.map +1 -1
- package/package.json +19 -11
- package/server.json +6 -10
package/README.md
CHANGED
|
@@ -5,20 +5,29 @@
|
|
|
5
5
|
[](./LICENSE)
|
|
6
6
|
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.smeet666/mcp-metacritic)
|
|
7
7
|
[](https://glama.ai/mcp/servers/smeet666/mcp-metacritic)
|
|
8
|
+
[](https://m8ven.ai/mcp/smeet666-mcp-metacritic-1yvblv)
|
|
8
9
|
[](https://cursor.com/en/install-mcp?name=metacritic&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1tZXRhY3JpdGljIl19)
|
|
9
10
|
[](https://insiders.vscode.dev/redirect/mcp/install?name=metacritic&config=%7B%22name%22%3A%22metacritic%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-metacritic%22%5D%7D)
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
[Metacritic](https://www.metacritic.com). Search films, shows and games, read
|
|
13
|
-
Metascores and audience scores, and quote what individual critics wrote, with
|
|
14
|
-
the publication named and the article linked. **No API key, no account, no
|
|
15
|
-
configuration.**
|
|
12
|
+
<!-- m8ven-verify: 01151bc5a8514e55175f063339bedc6f -->
|
|
16
13
|
|
|
17
|
-
|
|
14
|
+
[Metacritic](https://www.metacritic.com) gathers what critics and audiences said
|
|
15
|
+
about films, television series and video games. Each entry carries the year, the
|
|
16
|
+
age rating, the genres, and two scores of its own: the Metascore, a weighted
|
|
17
|
+
average of the professional reviews, and the user score, out of ten, from the
|
|
18
|
+
people who signed up to rate it. Under each entry sit the reviews themselves,
|
|
19
|
+
with the publication that ran them and the quoted line.
|
|
20
|
+
|
|
21
|
+
This server connects a chat client to that catalogue. You can search for a title,
|
|
22
|
+
read its entry with its scores and its details, browse a catalogue by score,
|
|
23
|
+
recency or popularity, and read the reviews of one title, filtered by critic or
|
|
24
|
+
audience and by how favourable they were. It needs no API key and no account.
|
|
25
|
+
|
|
26
|
+
_[Version française](#mcp-metacritic-français)_
|
|
18
27
|
|
|
19
28
|
---
|
|
20
29
|
|
|
21
|
-
##
|
|
30
|
+
## Install
|
|
22
31
|
|
|
23
32
|
**One-click install**
|
|
24
33
|
|
|
@@ -44,158 +53,226 @@ claude mcp add metacritic -- npx -y mcp-metacritic
|
|
|
44
53
|
}
|
|
45
54
|
```
|
|
46
55
|
|
|
47
|
-
|
|
56
|
+
Node 24 or later is required, and no environment variable has to be set.
|
|
48
57
|
|
|
49
|
-
|
|
50
|
-
[the latest release](https://github.com/smeet666/mcp-metacritic/releases/latest) and open
|
|
51
|
-
it. A client that supports MCP bundles installs it on its own, with no npm and
|
|
52
|
-
no configuration file to edit. The bundle carries its dependencies, so nothing
|
|
53
|
-
is fetched at install time.
|
|
54
|
-
|
|
55
|
-
## Tools
|
|
58
|
+
### With Docker
|
|
56
59
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"mcpServers": {
|
|
63
|
+
"metacritic": {
|
|
64
|
+
"command": "docker",
|
|
65
|
+
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-metacritic:2.0.1"]
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
66
70
|
|
|
67
|
-
|
|
71
|
+
`-i` keeps stdin open, which is where the protocol travels, and `-t` is left out
|
|
72
|
+
because a TTY rewrites the stream. The container needs outbound HTTPS to
|
|
73
|
+
`backend.metacritic.com`, and nothing else: no volume, no port, no credential.
|
|
68
74
|
|
|
69
|
-
###
|
|
75
|
+
### Bundle, without npm
|
|
70
76
|
|
|
71
|
-
|
|
72
|
-
the
|
|
73
|
-
|
|
74
|
-
|
|
77
|
+
Download `mcp-metacritic-2.0.1.mcpb` from
|
|
78
|
+
[the latest release](https://github.com/smeet666/mcp-metacritic/releases/latest)
|
|
79
|
+
and open it. A client that supports MCP bundles installs it on its own, with no
|
|
80
|
+
npm and no configuration file to edit. The bundle carries its dependencies, so
|
|
81
|
+
nothing is fetched at install time.
|
|
75
82
|
|
|
76
|
-
|
|
77
|
-
for a film, most of it artwork variants. `get_title` returns `basic` and
|
|
78
|
-
`scores` by default; `awards`, `production`, `networks` and `where_to_watch`
|
|
79
|
-
cost an extra request each and are only fetched when asked for.
|
|
83
|
+
## What you can ask
|
|
80
84
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
+
- "What did critics make of The Matrix?"
|
|
86
|
+
- "Read me a few negative reviews of that game."
|
|
87
|
+
- "What are the best-reviewed horror films?"
|
|
88
|
+
- "How does the user score compare to the Metascore?"
|
|
89
|
+
- "What came out recently that reviewed well?"
|
|
85
90
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
guessing. A missing entry produces an error with a code; a request that could
|
|
89
|
-
not be made says it could not be made, and never that Metacritic publishes
|
|
90
|
-
nothing. Those are very different answers and a model cannot tell them apart on
|
|
91
|
-
its own.
|
|
91
|
+
The ordinary path runs from a search to an entry: a row carries a `slug` and a
|
|
92
|
+
`kind`, and `get_title` and `get_reviews` take both together.
|
|
92
93
|
|
|
93
|
-
|
|
94
|
-
plot detail, a person or a studio, it cannot page, and for a multi-word query
|
|
95
|
-
the site counts matches loosely: "the matrix" reports over 55 000 entries
|
|
96
|
-
because it counts anything matching either word.
|
|
94
|
+
## Tools
|
|
97
95
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
96
|
+
| Tool | What it does |
|
|
97
|
+
| --------------- | ----------------------------------------------------------- |
|
|
98
|
+
| `search_titles` | Finds films, series and games by title. |
|
|
99
|
+
| `get_title` | Reads one entry, its scores and its details. |
|
|
100
|
+
| `get_reviews` | Reads the reviews of one entry, by source and by sentiment. |
|
|
101
|
+
| `browse_titles` | Lists a catalogue by score, recency or popularity. |
|
|
102
|
+
|
|
103
|
+
A title is addressed by its `slug` together with its `kind`, since the same slug
|
|
104
|
+
can name a film and a game.
|
|
105
|
+
|
|
106
|
+
### `search_titles`
|
|
107
|
+
|
|
108
|
+
Finds films, series and games by title.
|
|
109
|
+
|
|
110
|
+
| Argument | Type | Required | What it does |
|
|
111
|
+
| -------- | ----------------------------------------------- | -------- | -------------------------- |
|
|
112
|
+
| `query` | string, at least 1 character | yes | A title, or part of one. |
|
|
113
|
+
| `kind` | `movie`, `show`, `game` or `any`, default `any` | no | Which catalogue to search. |
|
|
114
|
+
| `limit` | integer, 1 to 50, default `10` | no | Rows to serve. |
|
|
115
|
+
|
|
116
|
+
**In return:** rows carrying `slug` and `kind`, which `get_title` and
|
|
117
|
+
`get_reviews` take together; `title`; `year`; `release_date`; `rating`, the age
|
|
118
|
+
rating as published; `metascore`; `user_score`; and `source_url`. **A score the
|
|
119
|
+
site has not computed is `null`, never `0`:** on a scale that starts at zero the
|
|
120
|
+
two would be indistinguishable, and a title with too few reviews carries none.
|
|
121
|
+
|
|
122
|
+
### `get_title`
|
|
123
|
+
|
|
124
|
+
Reads one entry. The heavier parts are asked for rather than served by default,
|
|
125
|
+
and each one beyond the default costs a request.
|
|
126
|
+
|
|
127
|
+
| Argument | Type | Required | What it does |
|
|
128
|
+
| ----------- | --------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------- |
|
|
129
|
+
| `slug` | string, at least 1 character | yes | The identifier a row carries. |
|
|
130
|
+
| `kind` | `movie`, `show` or `game` | yes | Which catalogue it belongs to. |
|
|
131
|
+
| `sections` | array of `basic`, `scores`, `awards`, `production`, `networks`, `where_to_watch`, default `["basic", "scores"]` | no | Which parts to return. |
|
|
132
|
+
| `max_chars` | integer, 200 to 20000, default `4000` | no | How much of the description to serve. |
|
|
133
|
+
| `offset` | integer, 0 or more, default `0` | no | Where to resume the description. |
|
|
134
|
+
|
|
135
|
+
**In return:** the entry a search row carries, plus `description`, `tagline`,
|
|
136
|
+
`genres`, `duration_minutes` and `imdb_id`, each `null` where the page states
|
|
137
|
+
nothing. `total_chars`, `returned_chars` and `offset` describe the slice of the
|
|
138
|
+
description served.
|
|
139
|
+
|
|
140
|
+
### `get_reviews`
|
|
141
|
+
|
|
142
|
+
Reads the reviews of one entry.
|
|
143
|
+
|
|
144
|
+
| Argument | Type | Required | What it does |
|
|
145
|
+
| ----------- | --------------------------------------------------------- | -------- | ---------------------------------- |
|
|
146
|
+
| `slug` | string, at least 1 character | yes | The identifier a row carries. |
|
|
147
|
+
| `kind` | `movie`, `show` or `game` | yes | Which catalogue it belongs to. |
|
|
148
|
+
| `source` | `critic` or `user`, default `critic` | no | Whose reviews to read. |
|
|
149
|
+
| `sentiment` | `all`, `positive`, `neutral` or `negative`, default `all` | no | How favourable a review has to be. |
|
|
150
|
+
| `limit` | integer, 1 to 50, default `10` | no | Reviews to serve. |
|
|
151
|
+
| `offset` | integer, 0 or more, default `0` | no | Reviews to skip, for paging. |
|
|
152
|
+
|
|
153
|
+
**In return:** `reviews`, each with its `quote` as published, its `score`, the
|
|
154
|
+
`max` that score is out of, which is 100 for a critic and 10 for a user, and the
|
|
155
|
+
`publication` that ran it. **Name the publication when quoting a review.**
|
|
156
|
+
`total_available` counts the reviews matching the source and the sentiment asked
|
|
157
|
+
for, and `next_offset` continues.
|
|
158
|
+
|
|
159
|
+
### `browse_titles`
|
|
160
|
+
|
|
161
|
+
Lists a catalogue.
|
|
162
|
+
|
|
163
|
+
| Argument | Type | Required | What it does |
|
|
164
|
+
| -------- | ----------------------------------------------- | -------- | -------------------------------------- |
|
|
165
|
+
| `kind` | `movie`, `show` or `game`, default `movie` | no | Which catalogue to list. |
|
|
166
|
+
| `sort` | `score`, `recent` or `popular`, default `score` | no | How the rows are ordered. |
|
|
167
|
+
| `genre` | string | no | A single genre name, such as `Horror`. |
|
|
168
|
+
| `limit` | integer, 1 to 50, default `20` | no | Rows to serve. |
|
|
169
|
+
| `offset` | integer, 0 or more, default `0` | no | Rows to skip, for paging. |
|
|
170
|
+
|
|
171
|
+
**In return:** the rows `search_titles` returns, with `total_available`,
|
|
172
|
+
`offset`, `next_offset` and the `kind`, `sort` and `genre` the listing was read
|
|
173
|
+
under.
|
|
174
|
+
|
|
175
|
+
## Two scores, two things measured
|
|
176
|
+
|
|
177
|
+
The Metascore is a weighted average of professional reviews, out of 100. The user
|
|
178
|
+
score is the average of what registered members gave, out of 10. They measure
|
|
179
|
+
different populations on different scales, and a title can carry one and not the
|
|
180
|
+
other. Read each with the `max` its reviews state, and report a missing score as
|
|
181
|
+
missing.
|
|
101
182
|
|
|
102
183
|
## Configuration
|
|
103
184
|
|
|
104
|
-
Every variable is optional. Set them in the `env` block of your
|
|
185
|
+
Every variable is optional. Set them in the `env` block of your client config.
|
|
105
186
|
|
|
106
|
-
| Variable | Default
|
|
107
|
-
| ------------------------ |
|
|
108
|
-
| `MC_USER_AGENT` |
|
|
109
|
-
| `MC_MIN_INTERVAL_MS` | `1000`
|
|
110
|
-
| `MC_TIMEOUT_MS` | `15000`
|
|
111
|
-
| `MC_MAX_RETRIES` | `3`
|
|
112
|
-
| `MC_CACHE_TTL_MS` | `86400000`
|
|
113
|
-
| `MC_SCORES_CACHE_TTL_MS` | `3600000`
|
|
114
|
-
| `MC_CACHE_MAX_ENTRIES` | `200`
|
|
115
|
-
| `MC_LOG_LEVEL` | `error`
|
|
187
|
+
| Variable | Default | What it does |
|
|
188
|
+
| ------------------------ | -------------------- | ---------------------------------------------------------------------------------- |
|
|
189
|
+
| `MC_USER_AGENT` | the project identity | Names your application to the site, with an address where a person can be reached. |
|
|
190
|
+
| `MC_MIN_INTERVAL_MS` | `1000` | Gap between two requests, from 500 to 60000. |
|
|
191
|
+
| `MC_TIMEOUT_MS` | `15000` | Deadline for one request, from 1000 to 120000. |
|
|
192
|
+
| `MC_MAX_RETRIES` | `3` | Attempts after a transient failure, from 0 to 10. |
|
|
193
|
+
| `MC_CACHE_TTL_MS` | `86400000` | How long a catalogue entry stays in memory, from 0 to 604800000. |
|
|
194
|
+
| `MC_SCORES_CACHE_TTL_MS` | `3600000` | How long scores and reviews stay in memory, from 0 to 86400000. |
|
|
195
|
+
| `MC_CACHE_MAX_ENTRIES` | `200` | Answers held in memory at once, from 0 to 10000. |
|
|
196
|
+
| `MC_LOG_LEVEL` | `error` | `silent`, `error`, `info` or `debug`, written to stderr. |
|
|
116
197
|
|
|
117
|
-
|
|
118
|
-
|
|
198
|
+
Scores move as reviews come in, especially around a release, so they are held for
|
|
199
|
+
an hour where a catalogue entry is held for a day. A value outside its range
|
|
200
|
+
falls back to the default, and the reason is written to stderr.
|
|
119
201
|
|
|
120
|
-
##
|
|
202
|
+
## Errors
|
|
121
203
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
call. It sends one request at a time, paces itself, backs off when refused, and
|
|
125
|
-
keeps two in-memory caches: a day for catalogue entries, which change when
|
|
126
|
-
someone edits them, and an hour for scores and reviews, which move as reviews
|
|
127
|
-
land.
|
|
204
|
+
Every failure carries one of six codes, a message, and where it helps a hint
|
|
205
|
+
naming the next move.
|
|
128
206
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
207
|
+
| Code | What happened | What to do |
|
|
208
|
+
| --------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
209
|
+
| `not_found` | The site answered, and holds no such entry. | Check the slug and the kind with `search_titles`. |
|
|
210
|
+
| `invalid_input` | The arguments were refused before any request went out. | Read the message, which names the argument. |
|
|
211
|
+
| `rate_limited` | The site asked this client to slow down. | Wait the number of seconds the hint names and call again with the same arguments. The entry is still there. |
|
|
212
|
+
| `parse_failure` | The answer arrived in a shape this client cannot read. | Report it at [the issue tracker](https://github.com/smeet666/mcp-metacritic/issues). |
|
|
213
|
+
| `network_error` | The request did not complete. | Try again shortly. |
|
|
214
|
+
| `timeout` | The request passed its deadline. | Raise `MC_TIMEOUT_MS`, or ask for fewer rows. |
|
|
132
215
|
|
|
133
|
-
|
|
216
|
+
## As a library
|
|
134
217
|
|
|
135
|
-
|
|
136
|
-
|
|
218
|
+
The layer reading the site is published on its own, with its pacing, its cache
|
|
219
|
+
and its errors, and with no protocol attached.
|
|
137
220
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
are the conditions this server operates under, and it does not take them as
|
|
141
|
-
permission to be greedy. It sends one request per second at most, identifies
|
|
142
|
-
itself, caches what it reads, and carries a link back to Metacritic on every
|
|
143
|
-
result, including on every quoted review.
|
|
221
|
+
```ts
|
|
222
|
+
import { McClient } from "mcp-metacritic/client";
|
|
144
223
|
|
|
145
|
-
|
|
224
|
+
const client = new McClient();
|
|
225
|
+
const { data, cached } = await client.getTitle({ slug: "the-matrix", kind: "movie" });
|
|
226
|
+
console.log(data.title, data.metascore, cached);
|
|
227
|
+
```
|
|
146
228
|
|
|
147
|
-
|
|
229
|
+
Each read answers `{ data, cached }`, and throws an error carrying one of the six
|
|
230
|
+
codes. The floor between two requests holds here as well.
|
|
148
231
|
|
|
149
|
-
|
|
150
|
-
npm install
|
|
151
|
-
npm run build:fixtures # regenerate the JSON test fixtures
|
|
152
|
-
npm test # unit tests, no network
|
|
153
|
-
npm run typecheck
|
|
154
|
-
npm run build
|
|
155
|
-
MC_LIVE=1 npm run test:live # hits the real site, excluded from CI
|
|
156
|
-
npm run inspector # explore the tools in the MCP Inspector
|
|
157
|
-
```
|
|
232
|
+
## Pacing and attribution
|
|
158
233
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
234
|
+
Requests go out one at a time with at least a second between them, and the floor
|
|
235
|
+
of half a second holds however the server is configured. The `User-Agent` always
|
|
236
|
+
ends with the project identity and an address where a person can be reached.
|
|
162
237
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
for a library consumer too.
|
|
238
|
+
Every result carries the address of the Metacritic page, and every quoted review
|
|
239
|
+
carries the publication that ran it. The reviews belong to their authors and to
|
|
240
|
+
the publications that ran them.
|
|
167
241
|
|
|
168
|
-
|
|
242
|
+
This MCP server is an unofficial project, with no affiliation to Metacritic.
|
|
169
243
|
|
|
170
|
-
|
|
171
|
-
Metacritic and to the publications it aggregates. This project claims no rights
|
|
172
|
-
over them and ships none of their content.
|
|
244
|
+
## Privacy
|
|
173
245
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
246
|
+
This server collects nothing about you and sends nothing to its author. It runs
|
|
247
|
+
on your machine, contacts `backend.metacritic.com` and nothing else, holds its
|
|
248
|
+
answers in memory while it runs, and writes nothing to disk.
|
|
249
|
+
[PRIVACY.md](PRIVACY.md) states what a request carries and which settings change
|
|
250
|
+
any of it.
|
|
178
251
|
|
|
179
|
-
|
|
180
|
-
Metacritic or Fandom.
|
|
252
|
+
## Development
|
|
181
253
|
|
|
182
|
-
|
|
254
|
+
```bash
|
|
255
|
+
npm install
|
|
256
|
+
npm run build:fixtures
|
|
257
|
+
npm test
|
|
258
|
+
npm run check
|
|
259
|
+
```
|
|
183
260
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
answer is before you write it. [CONTRIBUTING.md](CONTRIBUTING.md) has the
|
|
188
|
-
detail, and [SECURITY.md](SECURITY.md) covers anything exploitable.
|
|
261
|
+
Tests run against generated fixtures and make no network request. The live suite,
|
|
262
|
+
`npm run test:live`, makes one request per route and runs nightly against the
|
|
263
|
+
site itself.
|
|
189
264
|
|
|
190
|
-
##
|
|
265
|
+
## Contributing
|
|
191
266
|
|
|
192
|
-
|
|
193
|
-
|
|
267
|
+
Bugs, questions and ideas belong in
|
|
268
|
+
[the issue tracker](https://github.com/smeet666/mcp-metacritic/issues). Pull
|
|
269
|
+
requests are welcome; opening an issue first helps agree on the shape of the
|
|
270
|
+
change. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
194
271
|
|
|
195
272
|
## License
|
|
196
273
|
|
|
197
|
-
MIT
|
|
198
|
-
|
|
274
|
+
MIT, see [LICENSE](LICENSE). The scores and the reviews belong to Metacritic and
|
|
275
|
+
to the publications it quotes.
|
|
199
276
|
|
|
200
277
|
---
|
|
201
278
|
|
|
@@ -203,13 +280,22 @@ data retrieved through it.
|
|
|
203
280
|
|
|
204
281
|
# mcp-metacritic (français)
|
|
205
282
|
|
|
206
|
-
|
|
207
|
-
[Metacritic](https://www.metacritic.com). Cherchez des films, séries et jeux,
|
|
208
|
-
lisez les Metascores et les notes du public, et citez ce qu'ont écrit les
|
|
209
|
-
critiques, avec la publication nommée et l'article lié. **Sans clé d'API, sans
|
|
210
|
-
compte, sans configuration.**
|
|
283
|
+
_[English version](#mcp-metacritic)_
|
|
211
284
|
|
|
212
|
-
|
|
285
|
+
[Metacritic](https://www.metacritic.com) rassemble ce que la critique et le
|
|
286
|
+
public ont dit des films, des séries et des jeux vidéo. Chaque fiche porte
|
|
287
|
+
l'année, la classification par âge, les genres, et deux notes qui lui sont
|
|
288
|
+
propres : le Metascore, moyenne pondérée des critiques professionnelles, et la
|
|
289
|
+
note des utilisateurs, sur dix, donnée par les inscrits. Sous chaque fiche se
|
|
290
|
+
trouvent les critiques elles-mêmes, avec la publication qui les a signées et la
|
|
291
|
+
phrase citée.
|
|
292
|
+
|
|
293
|
+
Ce serveur relie un client de conversation à ce catalogue. On peut y chercher un
|
|
294
|
+
titre, lire sa fiche avec ses notes et ses détails, parcourir un catalogue par
|
|
295
|
+
note, par fraîcheur ou par popularité, et lire les critiques d'un titre, filtrées
|
|
296
|
+
par source et par tonalité. Aucune clé d'API, aucun compte.
|
|
297
|
+
|
|
298
|
+
## Installation
|
|
213
299
|
|
|
214
300
|
**Installation en un clic**
|
|
215
301
|
|
|
@@ -222,7 +308,7 @@ compte, sans configuration.**
|
|
|
222
308
|
claude mcp add metacritic -- npx -y mcp-metacritic
|
|
223
309
|
```
|
|
224
310
|
|
|
225
|
-
**Claude Desktop, Cursor, et tout client
|
|
311
|
+
**Claude Desktop, Cursor, et tout client au format de configuration standard**
|
|
226
312
|
|
|
227
313
|
```json
|
|
228
314
|
{
|
|
@@ -235,144 +321,228 @@ claude mcp add metacritic -- npx -y mcp-metacritic
|
|
|
235
321
|
}
|
|
236
322
|
```
|
|
237
323
|
|
|
238
|
-
|
|
324
|
+
Node 24 ou plus récent est nécessaire, et aucune variable d'environnement n'est à
|
|
325
|
+
renseigner.
|
|
239
326
|
|
|
240
|
-
|
|
241
|
-
[la dernière release](https://github.com/smeet666/mcp-metacritic/releases/latest) et
|
|
242
|
-
ouvrez-le. Un client compatible avec les bundles MCP l'installe seul, sans npm
|
|
243
|
-
ni fichier de configuration à modifier. Le bundle embarque ses dépendances,
|
|
244
|
-
donc rien n'est téléchargé à l'installation.
|
|
327
|
+
### Avec Docker
|
|
245
328
|
|
|
246
|
-
|
|
329
|
+
```json
|
|
330
|
+
{
|
|
331
|
+
"mcpServers": {
|
|
332
|
+
"metacritic": {
|
|
333
|
+
"command": "docker",
|
|
334
|
+
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-metacritic:2.0.1"]
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
```
|
|
247
339
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
340
|
+
`-i` garde l'entrée standard ouverte, qui est le canal du protocole, et `-t` est
|
|
341
|
+
omis parce qu'un TTY réécrit le flux. Le conteneur a besoin d'un accès HTTPS
|
|
342
|
+
sortant vers `backend.metacritic.com`, et de rien d'autre : aucun volume, aucun
|
|
343
|
+
port, aucun identifiant.
|
|
344
|
+
|
|
345
|
+
### Bundle, sans npm
|
|
346
|
+
|
|
347
|
+
Téléchargez `mcp-metacritic-2.0.1.mcpb` depuis
|
|
348
|
+
[la dernière publication](https://github.com/smeet666/mcp-metacritic/releases/latest)
|
|
349
|
+
et ouvrez-le. Un client qui gère les bundles MCP l'installe seul, sans npm et
|
|
350
|
+
sans fichier de configuration à modifier. Le bundle emporte ses dépendances, donc
|
|
351
|
+
rien n'est téléchargé à l'installation.
|
|
352
|
+
|
|
353
|
+
## Ce qu'on peut demander
|
|
254
354
|
|
|
255
|
-
|
|
256
|
-
|
|
355
|
+
- « Qu'a pensé la critique de Matrix ? »
|
|
356
|
+
- « Lis-moi quelques critiques négatives de ce jeu. »
|
|
357
|
+
- « Quels sont les films d'horreur les mieux notés ? »
|
|
358
|
+
- « Comment la note du public se compare-t-elle au Metascore ? »
|
|
359
|
+
- « Qu'est-il sorti récemment qui a été bien reçu ? »
|
|
257
360
|
|
|
258
|
-
Le
|
|
361
|
+
Le chemin ordinaire va d'une recherche à une fiche : une ligne porte un `slug` et
|
|
362
|
+
un `kind`, et `get_title` comme `get_reviews` reprennent les deux ensemble.
|
|
259
363
|
|
|
260
|
-
|
|
364
|
+
## Les outils
|
|
261
365
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
366
|
+
| Outil | Ce qu'il fait |
|
|
367
|
+
| --------------- | ------------------------------------------------------------- |
|
|
368
|
+
| `search_titles` | Trouve des films, des séries et des jeux par leur titre. |
|
|
369
|
+
| `get_title` | Lit une fiche, ses notes et ses détails. |
|
|
370
|
+
| `get_reviews` | Lit les critiques d'une fiche, par source et par tonalité. |
|
|
371
|
+
| `browse_titles` | Liste un catalogue par note, par fraîcheur ou par popularité. |
|
|
267
372
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
`get_title` renvoie `basic` et `scores` par défaut ; `awards`, `production`,
|
|
271
|
-
`networks` et `where_to_watch` coûtent une requête chacune et ne sont récupérées
|
|
272
|
-
que si on les demande.
|
|
373
|
+
Un titre s'adresse par son `slug` accompagné de son `kind`, un même slug pouvant
|
|
374
|
+
nommer un film et un jeu.
|
|
273
375
|
|
|
274
|
-
|
|
275
|
-
un film donné et en sert 7 par cette route, quelle que soit la pagination
|
|
276
|
-
demandée. L'outil le dit au lieu de présenter l'échantillon comme la liste
|
|
277
|
-
complète, et renvoie vers la fiche où le reste se lit.
|
|
376
|
+
### `search_titles`
|
|
278
377
|
|
|
279
|
-
|
|
280
|
-
`data`, soit un tableau `errors`, et ce serveur lit cette distinction au lieu de
|
|
281
|
-
la deviner. Une fiche absente produit une erreur avec un code ; une requête qui
|
|
282
|
-
n'a pas abouti dit qu'elle n'a pas abouti, jamais que Metacritic ne publie rien.
|
|
283
|
-
Ce sont deux réponses très différentes, qu'un modèle ne peut pas distinguer seul.
|
|
378
|
+
Trouve des films, des séries et des jeux par leur titre.
|
|
284
379
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
380
|
+
| Argument | Type | Requis | Ce qu'il fait |
|
|
381
|
+
| -------- | ---------------------------------------------- | ------ | ------------------------- |
|
|
382
|
+
| `query` | chaîne, au moins 1 caractère | oui | Un titre, ou une partie. |
|
|
383
|
+
| `kind` | `movie`, `show`, `game` ou `any`, défaut `any` | non | Le catalogue où chercher. |
|
|
384
|
+
| `limit` | entier, 1 à 50, défaut `10` | non | Lignes à servir. |
|
|
290
385
|
|
|
291
|
-
**
|
|
292
|
-
|
|
293
|
-
|
|
386
|
+
**En retour :** des lignes portant `slug` et `kind`, que `get_title` et
|
|
387
|
+
`get_reviews` reprennent ensemble ; `title` ; `year` ; `release_date` ; `rating`,
|
|
388
|
+
la classification par âge telle que publiée ; `metascore` ; `user_score` ; et
|
|
389
|
+
`source_url`. **Une note que le site n'a pas calculée vaut `null`, jamais `0` :**
|
|
390
|
+
sur une échelle qui commence à zéro les deux seraient indiscernables, et un titre
|
|
391
|
+
avec trop peu de critiques n'en porte aucune.
|
|
294
392
|
|
|
295
|
-
|
|
393
|
+
### `get_title`
|
|
296
394
|
|
|
297
|
-
|
|
395
|
+
Lit une fiche. Les parties lourdes se demandent au lieu d'être servies par
|
|
396
|
+
défaut, et chacune au-delà du défaut coûte une requête.
|
|
298
397
|
|
|
299
|
-
|
|
|
300
|
-
|
|
|
301
|
-
| `
|
|
302
|
-
| `
|
|
303
|
-
| `
|
|
304
|
-
| `
|
|
305
|
-
| `
|
|
306
|
-
| `MC_SCORES_CACHE_TTL_MS` | `3600000` | Durée de vie du cache notes et critiques (1 heure). |
|
|
307
|
-
| `MC_CACHE_MAX_ENTRIES` | `200` | Taille des caches mémoire. |
|
|
308
|
-
| `MC_LOG_LEVEL` | `error` | `silent`, `error`, `info` ou `debug`. Logs sur stderr. |
|
|
398
|
+
| Argument | Type | Requis | Ce qu'il fait |
|
|
399
|
+
| ----------- | ---------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------ |
|
|
400
|
+
| `slug` | chaîne, au moins 1 caractère | oui | L'identifiant d'une ligne. |
|
|
401
|
+
| `kind` | `movie`, `show` ou `game` | oui | Le catalogue dont il relève. |
|
|
402
|
+
| `sections` | tableau de `basic`, `scores`, `awards`, `production`, `networks`, `where_to_watch`, défaut `["basic", "scores"]` | non | Les parties à rendre. |
|
|
403
|
+
| `max_chars` | entier, 200 à 20000, défaut `4000` | non | La longueur de description à servir. |
|
|
404
|
+
| `offset` | entier, 0 ou plus, défaut `0` | non | Où reprendre la description. |
|
|
309
405
|
|
|
310
|
-
|
|
311
|
-
|
|
406
|
+
**En retour :** la fiche que porte une ligne de recherche, plus `description`,
|
|
407
|
+
`tagline`, `genres`, `duration_minutes` et `imdb_id`, chacun `null` là où la page
|
|
408
|
+
n'indique rien. `total_chars`, `returned_chars` et `offset` décrivent la tranche
|
|
409
|
+
de description servie.
|
|
312
410
|
|
|
313
|
-
|
|
411
|
+
### `get_reviews`
|
|
314
412
|
|
|
315
|
-
|
|
316
|
-
et ce serveur appelle les mêmes routes que leurs propres pages. Il envoie une
|
|
317
|
-
requête à la fois, s'impose un rythme, ralentit en cas de refus, et garde deux
|
|
318
|
-
caches mémoire : un jour pour les fiches, qui ne bougent qu'à l'édition, et une
|
|
319
|
-
heure pour les notes et critiques, qui évoluent au fil des publications.
|
|
413
|
+
Lit les critiques d'une fiche.
|
|
320
414
|
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
415
|
+
| Argument | Type | Requis | Ce qu'il fait |
|
|
416
|
+
| ----------- | -------------------------------------------------------- | ------ | ---------------------------------- |
|
|
417
|
+
| `slug` | chaîne, au moins 1 caractère | oui | L'identifiant d'une ligne. |
|
|
418
|
+
| `kind` | `movie`, `show` ou `game` | oui | Le catalogue dont il relève. |
|
|
419
|
+
| `source` | `critic` ou `user`, défaut `critic` | non | De qui lire les critiques. |
|
|
420
|
+
| `sentiment` | `all`, `positive`, `neutral` ou `negative`, défaut `all` | non | La tonalité exigée d'une critique. |
|
|
421
|
+
| `limit` | entier, 1 à 50, défaut `10` | non | Critiques à servir. |
|
|
422
|
+
| `offset` | entier, 0 ou plus, défaut `0` | non | Critiques à sauter, pour paginer. |
|
|
324
423
|
|
|
325
|
-
|
|
424
|
+
**En retour :** `reviews`, chacune avec sa `quote` telle que publiée, son
|
|
425
|
+
`score`, le `max` sur lequel cette note est donnée, qui vaut 100 pour un critique
|
|
426
|
+
et 10 pour un utilisateur, et la `publication` qui l'a signée. **Nommez la
|
|
427
|
+
publication quand vous citez une critique.** `total_available` compte les
|
|
428
|
+
critiques correspondant à la source et à la tonalité demandées, et `next_offset`
|
|
429
|
+
poursuit.
|
|
326
430
|
|
|
327
|
-
`
|
|
328
|
-
être lues. Autant le dire clairement plutôt que de le passer sous silence.
|
|
431
|
+
### `browse_titles`
|
|
329
432
|
|
|
330
|
-
|
|
331
|
-
aucune clé, et n'a ralenti aucune de dix requêtes consécutives lors des tests.
|
|
332
|
-
Ce sont les conditions dans lesquelles ce serveur opère, et il n'y voit pas une
|
|
333
|
-
autorisation d'être gourmand. Il envoie au plus une requête par seconde,
|
|
334
|
-
s'identifie, met en cache ce qu'il lit, et porte un lien vers Metacritic sur
|
|
335
|
-
chaque résultat, y compris sur chaque critique citée.
|
|
433
|
+
Liste un catalogue.
|
|
336
434
|
|
|
337
|
-
|
|
435
|
+
| Argument | Type | Requis | Ce qu'il fait |
|
|
436
|
+
| -------- | ---------------------------------------------- | ------ | ------------------------------------- |
|
|
437
|
+
| `kind` | `movie`, `show` ou `game`, défaut `movie` | non | Le catalogue à lister. |
|
|
438
|
+
| `sort` | `score`, `recent` ou `popular`, défaut `score` | non | L'ordre des lignes. |
|
|
439
|
+
| `genre` | chaîne | non | Un seul nom de genre, comme `Horror`. |
|
|
440
|
+
| `limit` | entier, 1 à 50, défaut `20` | non | Lignes à servir. |
|
|
441
|
+
| `offset` | entier, 0 ou plus, défaut `0` | non | Lignes à sauter, pour paginer. |
|
|
442
|
+
|
|
443
|
+
**En retour :** les lignes que rend `search_titles`, avec `total_available`,
|
|
444
|
+
`offset`, `next_offset` et les `kind`, `sort` et `genre` sous lesquels la liste a
|
|
445
|
+
été lue.
|
|
446
|
+
|
|
447
|
+
## Deux notes, deux choses mesurées
|
|
448
|
+
|
|
449
|
+
Le Metascore est une moyenne pondérée des critiques professionnelles, sur 100. La
|
|
450
|
+
note des utilisateurs est la moyenne de ce qu'ont donné les membres inscrits, sur 10. Elles mesurent des populations différentes sur des échelles différentes, et
|
|
451
|
+
un titre peut porter l'une sans l'autre. Lisez chacune avec le `max` que ses
|
|
452
|
+
critiques indiquent, et rapportez une note absente comme absente.
|
|
338
453
|
|
|
339
|
-
##
|
|
454
|
+
## Configuration
|
|
340
455
|
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
456
|
+
Chaque variable est facultative. Elles se posent dans le bloc `env` de la
|
|
457
|
+
configuration du client.
|
|
458
|
+
|
|
459
|
+
| Variable | Défaut | Ce qu'elle fait |
|
|
460
|
+
| ------------------------ | -------------------- | ---------------------------------------------------------------------------------- |
|
|
461
|
+
| `MC_USER_AGENT` | l'identité du projet | Nomme votre application auprès du site, avec une adresse où joindre une personne. |
|
|
462
|
+
| `MC_MIN_INTERVAL_MS` | `1000` | Écart entre deux requêtes, de 500 à 60000. |
|
|
463
|
+
| `MC_TIMEOUT_MS` | `15000` | Délai d'une requête, de 1000 à 120000. |
|
|
464
|
+
| `MC_MAX_RETRIES` | `3` | Tentatives après un échec passager, de 0 à 10. |
|
|
465
|
+
| `MC_CACHE_TTL_MS` | `86400000` | Durée pendant laquelle une fiche reste en mémoire, de 0 à 604800000. |
|
|
466
|
+
| `MC_SCORES_CACHE_TTL_MS` | `3600000` | Durée pendant laquelle les notes et critiques restent en mémoire, de 0 à 86400000. |
|
|
467
|
+
| `MC_CACHE_MAX_ENTRIES` | `200` | Réponses gardées en mémoire à la fois, de 0 à 10000. |
|
|
468
|
+
| `MC_LOG_LEVEL` | `error` | `silent`, `error`, `info` ou `debug`, écrit sur la sortie d'erreur. |
|
|
469
|
+
|
|
470
|
+
Les notes bougent au fil des critiques, surtout autour d'une sortie, donc elles
|
|
471
|
+
sont gardées une heure là où une fiche l'est un jour. Une valeur hors de sa plage
|
|
472
|
+
retombe sur le défaut, et la raison est écrite sur la sortie d'erreur.
|
|
473
|
+
|
|
474
|
+
## Erreurs
|
|
475
|
+
|
|
476
|
+
Chaque échec porte un des six codes, un message, et quand cela aide une
|
|
477
|
+
indication du geste suivant.
|
|
478
|
+
|
|
479
|
+
| Code | Ce qui s'est passé | Que faire |
|
|
480
|
+
| --------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
481
|
+
| `not_found` | Le site a répondu, et n'a pas cette fiche. | Vérifiez le slug et le type avec `search_titles`. |
|
|
482
|
+
| `invalid_input` | Les arguments ont été refusés avant toute requête. | Lisez le message, qui nomme l'argument. |
|
|
483
|
+
| `rate_limited` | Le site demande à ce client de ralentir. | Attendez les secondes indiquées et rappelez avec les mêmes arguments. La fiche est toujours là. |
|
|
484
|
+
| `parse_failure` | La réponse est arrivée dans une forme illisible ici. | Signalez-le sur [le suivi d'incidents](https://github.com/smeet666/mcp-metacritic/issues). |
|
|
485
|
+
| `network_error` | La requête n'a pas abouti. | Réessayez sous peu. |
|
|
486
|
+
| `timeout` | La requête a dépassé son délai. | Augmentez `MC_TIMEOUT_MS`, ou demandez moins de lignes. |
|
|
487
|
+
|
|
488
|
+
## Comme bibliothèque
|
|
489
|
+
|
|
490
|
+
La couche qui lit le site est publiée seule, avec son rythme, son cache et ses
|
|
491
|
+
erreurs, sans protocole attaché.
|
|
492
|
+
|
|
493
|
+
```ts
|
|
494
|
+
import { McClient } from "mcp-metacritic/client";
|
|
495
|
+
|
|
496
|
+
const client = new McClient();
|
|
497
|
+
const { data, cached } = await client.getTitle({ slug: "the-matrix", kind: "movie" });
|
|
498
|
+
console.log(data.title, data.metascore, cached);
|
|
349
499
|
```
|
|
350
500
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
501
|
+
Chaque lecture répond `{ data, cached }`, et lève une erreur portant un des six
|
|
502
|
+
codes. Le plancher entre deux requêtes tient également ici.
|
|
503
|
+
|
|
504
|
+
## Rythme et attribution
|
|
505
|
+
|
|
506
|
+
Les requêtes partent une à une avec au moins une seconde entre elles, et le
|
|
507
|
+
plancher d'une demi-seconde tient quelle que soit la configuration. Le
|
|
508
|
+
`User-Agent` se termine toujours par l'identité du projet et une adresse où
|
|
509
|
+
joindre une personne.
|
|
510
|
+
|
|
511
|
+
Chaque résultat porte l'adresse de la page Metacritic, et chaque critique citée
|
|
512
|
+
porte la publication qui l'a signée. Les critiques appartiennent à leurs auteurs
|
|
513
|
+
et aux publications qui les ont publiées.
|
|
514
|
+
|
|
515
|
+
Ce MCP est un projet non officiel, sans affiliation à Metacritic.
|
|
354
516
|
|
|
355
|
-
|
|
356
|
-
`mcp-metacritic/client`, utilisable comme simple bibliothèque. Elle applique
|
|
357
|
-
elle-même le plancher de cadence et le User-Agent identifiant, qui valent donc
|
|
358
|
-
aussi pour qui l'utilise en bibliothèque.
|
|
517
|
+
## Confidentialité
|
|
359
518
|
|
|
360
|
-
|
|
519
|
+
Ce serveur ne collecte rien sur vous et n'envoie rien à son auteur. Il tourne sur
|
|
520
|
+
votre machine, ne joint que `backend.metacritic.com`, garde ses réponses en
|
|
521
|
+
mémoire le temps qu'il tourne, et n'écrit rien sur le disque.
|
|
522
|
+
[PRIVACY.md](PRIVACY.md) dit ce qu'une requête emporte et quels réglages changent
|
|
523
|
+
cela.
|
|
524
|
+
|
|
525
|
+
## Développement
|
|
526
|
+
|
|
527
|
+
```bash
|
|
528
|
+
npm install
|
|
529
|
+
npm run build:fixtures
|
|
530
|
+
npm test
|
|
531
|
+
npm run check
|
|
532
|
+
```
|
|
361
533
|
|
|
362
|
-
Les
|
|
363
|
-
|
|
364
|
-
|
|
534
|
+
Les tests s'exécutent sur des fixtures engendrées et n'émettent aucune requête.
|
|
535
|
+
La suite en direct, `npm run test:live`, émet une requête par route et tourne
|
|
536
|
+
chaque nuit contre le site lui-même.
|
|
365
537
|
|
|
366
|
-
|
|
367
|
-
avec la publication nommée et un lien vers l'article d'origine quand le site en
|
|
368
|
-
fournit un. Si vous reprenez une citation, conservez les deux. Si vous citez une
|
|
369
|
-
note, créditez Metacritic et liez la fiche : chaque résultat porte un
|
|
370
|
-
`source_url`.
|
|
538
|
+
## Contribuer
|
|
371
539
|
|
|
372
|
-
|
|
373
|
-
|
|
540
|
+
Les anomalies, les questions et les idées ont leur place dans
|
|
541
|
+
[le suivi d'incidents](https://github.com/smeet666/mcp-metacritic/issues). Les
|
|
542
|
+
propositions de modification sont bienvenues ; ouvrir un ticket d'abord aide à
|
|
543
|
+
s'accorder sur la forme du changement. Voir [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
374
544
|
|
|
375
545
|
## Licence
|
|
376
546
|
|
|
377
|
-
MIT, voir [LICENSE](
|
|
378
|
-
|
|
547
|
+
MIT, voir [LICENSE](LICENSE). Les notes et les critiques appartiennent à
|
|
548
|
+
Metacritic et aux publications qu'il cite.
|