mcp-metacritic 2.0.0 → 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 +11 -0
- package/PRIVACY.md +154 -0
- package/README.md +378 -245
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/mc/client.js +1 -1
- package/dist/mc/client.js.map +1 -1
- package/package.json +5 -1
- package/server.json +4 -4
package/README.md
CHANGED
|
@@ -8,19 +8,26 @@
|
|
|
8
8
|
[](https://m8ven.ai/mcp/smeet666-mcp-metacritic-1yvblv)
|
|
9
9
|
[](https://cursor.com/en/install-mcp?name=metacritic&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1tZXRhY3JpdGljIl19)
|
|
10
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)
|
|
11
|
+
|
|
11
12
|
<!-- m8ven-verify: 01151bc5a8514e55175f063339bedc6f -->
|
|
12
13
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
the
|
|
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.
|
|
18
25
|
|
|
19
|
-
_
|
|
26
|
+
_[Version française](#mcp-metacritic-français)_
|
|
20
27
|
|
|
21
28
|
---
|
|
22
29
|
|
|
23
|
-
##
|
|
30
|
+
## Install
|
|
24
31
|
|
|
25
32
|
**One-click install**
|
|
26
33
|
|
|
@@ -46,6 +53,8 @@ claude mcp add metacritic -- npx -y mcp-metacritic
|
|
|
46
53
|
}
|
|
47
54
|
```
|
|
48
55
|
|
|
56
|
+
Node 24 or later is required, and no environment variable has to be set.
|
|
57
|
+
|
|
49
58
|
### With Docker
|
|
50
59
|
|
|
51
60
|
```json
|
|
@@ -53,168 +62,217 @@ claude mcp add metacritic -- npx -y mcp-metacritic
|
|
|
53
62
|
"mcpServers": {
|
|
54
63
|
"metacritic": {
|
|
55
64
|
"command": "docker",
|
|
56
|
-
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-metacritic:2.0.
|
|
65
|
+
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-metacritic:2.0.1"]
|
|
57
66
|
}
|
|
58
67
|
}
|
|
59
68
|
}
|
|
60
69
|
```
|
|
61
70
|
|
|
62
|
-
`-i` keeps stdin open, which is where the protocol travels, and
|
|
63
|
-
|
|
64
|
-
|
|
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.
|
|
65
74
|
|
|
66
|
-
|
|
75
|
+
### Bundle, without npm
|
|
67
76
|
|
|
68
|
-
Download `mcp-metacritic
|
|
69
|
-
[the latest release](https://github.com/smeet666/mcp-metacritic/releases/latest)
|
|
70
|
-
it. A client that supports MCP bundles installs it on its own, with no
|
|
71
|
-
no configuration file to edit. The bundle carries its dependencies, so
|
|
72
|
-
is fetched at install time.
|
|
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.
|
|
73
82
|
|
|
74
|
-
##
|
|
83
|
+
## What you can ask
|
|
75
84
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
| `browse_titles` | Rankings: best rated, newest, most looked at. | `kind`, `sort`, `genre`, `limit`, `offset` |
|
|
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?"
|
|
82
90
|
|
|
83
|
-
|
|
84
|
-
|
|
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.
|
|
85
93
|
|
|
86
|
-
|
|
94
|
+
## Tools
|
|
87
95
|
|
|
88
|
-
|
|
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.
|
|
89
182
|
|
|
90
|
-
|
|
91
|
-
the audience score to 10, so 73 and 8.9 describe similar opinions. Every score
|
|
92
|
-
this server returns carries its own `max`, and the tool descriptions say so,
|
|
93
|
-
because averaging the two is the single easiest mistake to make with this data.
|
|
183
|
+
## Configuration
|
|
94
184
|
|
|
95
|
-
|
|
96
|
-
for a film, most of it artwork variants. `get_title` returns `basic` and
|
|
97
|
-
`scores` by default; `awards`, `production`, `networks` and `where_to_watch`
|
|
98
|
-
cost an extra request each and are only fetched when asked for.
|
|
185
|
+
Every variable is optional. Set them in the `env` block of your client config.
|
|
99
186
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
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. |
|
|
104
197
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
not be made says it could not be made, and never that Metacritic publishes
|
|
109
|
-
nothing. Those are very different answers and a model cannot tell them apart on
|
|
110
|
-
its own.
|
|
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.
|
|
111
201
|
|
|
112
|
-
|
|
113
|
-
plot detail, a person or a studio, it cannot page, and for a multi-word query
|
|
114
|
-
the site counts matches loosely: "the matrix" reports over 55 000 entries
|
|
115
|
-
because it counts anything matching either word.
|
|
202
|
+
## Errors
|
|
116
203
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
rather than counting rows.
|
|
204
|
+
Every failure carries one of six codes, a message, and where it helps a hint
|
|
205
|
+
naming the next move.
|
|
120
206
|
|
|
121
|
-
|
|
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. |
|
|
122
215
|
|
|
123
|
-
|
|
216
|
+
## As a library
|
|
124
217
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
| `MC_USER_AGENT` | `mcp-metacritic v<version> (<repo>)` | User-Agent sent to Metacritic. |
|
|
128
|
-
| `MC_MIN_INTERVAL_MS` | `1000` | Minimum gap between requests. Values below 500 ms are ignored. |
|
|
129
|
-
| `MC_TIMEOUT_MS` | `15000` | Per-request timeout. |
|
|
130
|
-
| `MC_MAX_RETRIES` | `3` | Retries on refusals and transient errors. |
|
|
131
|
-
| `MC_CACHE_TTL_MS` | `86400000` | Catalogue cache lifetime (24 hours). |
|
|
132
|
-
| `MC_SCORES_CACHE_TTL_MS` | `3600000` | Scores and reviews cache lifetime (1 hour). |
|
|
133
|
-
| `MC_CACHE_MAX_ENTRIES` | `200` | In-memory cache size. |
|
|
134
|
-
| `MC_LOG_LEVEL` | `error` | `silent`, `error`, `info` or `debug`. Logs go to stderr. |
|
|
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.
|
|
135
220
|
|
|
136
|
-
|
|
137
|
-
|
|
221
|
+
```ts
|
|
222
|
+
import { McClient } from "mcp-metacritic/client";
|
|
138
223
|
|
|
139
|
-
|
|
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
|
+
```
|
|
140
228
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
call. It sends one request at a time, paces itself, backs off when refused, and
|
|
144
|
-
keeps two in-memory caches: a day for catalogue entries, which change when
|
|
145
|
-
someone edits them, and an hour for scores and reviews, which move as reviews
|
|
146
|
-
land.
|
|
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.
|
|
147
231
|
|
|
148
|
-
|
|
149
|
-
characters, with the real destination inside. This server unwraps them: you get
|
|
150
|
-
the provider's own URL, not a tracker.
|
|
232
|
+
## Pacing and attribution
|
|
151
233
|
|
|
152
|
-
|
|
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.
|
|
153
237
|
|
|
154
|
-
|
|
155
|
-
|
|
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.
|
|
156
241
|
|
|
157
|
-
|
|
158
|
-
API key, and did not throttle ten consecutive requests during testing. Those
|
|
159
|
-
are the conditions this server operates under, and it does not take them as
|
|
160
|
-
permission to be greedy. It sends one request per second at most, identifies
|
|
161
|
-
itself, caches what it reads, and carries a link back to Metacritic on every
|
|
162
|
-
result, including on every quoted review.
|
|
242
|
+
This MCP server is an unofficial project, with no affiliation to Metacritic.
|
|
163
243
|
|
|
164
|
-
|
|
244
|
+
## Privacy
|
|
245
|
+
|
|
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.
|
|
165
251
|
|
|
166
252
|
## Development
|
|
167
253
|
|
|
168
254
|
```bash
|
|
169
255
|
npm install
|
|
170
|
-
npm run build:fixtures
|
|
171
|
-
npm test
|
|
172
|
-
npm run
|
|
173
|
-
npm run build
|
|
174
|
-
MC_LIVE=1 npm run test:live # hits the real site, excluded from CI
|
|
175
|
-
npm run inspector # explore the tools in the MCP Inspector
|
|
256
|
+
npm run build:fixtures
|
|
257
|
+
npm test
|
|
258
|
+
npm run check
|
|
176
259
|
```
|
|
177
260
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
The API layer (`src/mc`) does not import the MCP SDK and is published
|
|
183
|
-
separately as `mcp-metacritic/client`, so it can be used as a plain library. It
|
|
184
|
-
enforces the pacing floor and the identifying User-Agent itself, so those hold
|
|
185
|
-
for a library consumer too.
|
|
186
|
-
|
|
187
|
-
## Reviews, scores and copyright
|
|
188
|
-
|
|
189
|
-
Metascores, review texts and the editorial work behind them belong to
|
|
190
|
-
Metacritic and to the publications it aggregates. This project claims no rights
|
|
191
|
-
over them and ships none of their content.
|
|
192
|
-
|
|
193
|
-
Review quotes are returned as excerpts, capped in length, always with the
|
|
194
|
-
publication named and with a link to the original article where the site
|
|
195
|
-
provides one. If you repeat a quote, keep both. If you cite a score, credit
|
|
196
|
-
Metacritic and link the entry: every result carries a `source_url`.
|
|
197
|
-
|
|
198
|
-
This is an unofficial project, with no affiliation to or endorsement by
|
|
199
|
-
Metacritic or Fandom.
|
|
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.
|
|
200
264
|
|
|
201
265
|
## Contributing
|
|
202
266
|
|
|
203
|
-
Bugs, questions and ideas
|
|
204
|
-
[the issue tracker](https://github.com/smeet666/mcp-metacritic/issues). Pull
|
|
205
|
-
are welcome;
|
|
206
|
-
|
|
207
|
-
detail, and [SECURITY.md](SECURITY.md) covers anything exploitable.
|
|
208
|
-
|
|
209
|
-
## Support
|
|
210
|
-
|
|
211
|
-
These servers are free and stay free. If one of them saved you an afternoon,
|
|
212
|
-
you can [buy me a coffee](https://buymeacoffee.com/smeet666).
|
|
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).
|
|
213
271
|
|
|
214
272
|
## License
|
|
215
273
|
|
|
216
|
-
MIT
|
|
217
|
-
|
|
274
|
+
MIT, see [LICENSE](LICENSE). The scores and the reviews belong to Metacritic and
|
|
275
|
+
to the publications it quotes.
|
|
218
276
|
|
|
219
277
|
---
|
|
220
278
|
|
|
@@ -222,13 +280,22 @@ data retrieved through it.
|
|
|
222
280
|
|
|
223
281
|
# mcp-metacritic (français)
|
|
224
282
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
283
|
+
_[English version](#mcp-metacritic)_
|
|
284
|
+
|
|
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.
|
|
230
292
|
|
|
231
|
-
|
|
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
|
|
232
299
|
|
|
233
300
|
**Installation en un clic**
|
|
234
301
|
|
|
@@ -241,7 +308,7 @@ compte, sans configuration.**
|
|
|
241
308
|
claude mcp add metacritic -- npx -y mcp-metacritic
|
|
242
309
|
```
|
|
243
310
|
|
|
244
|
-
**Claude Desktop, Cursor, et tout client
|
|
311
|
+
**Claude Desktop, Cursor, et tout client au format de configuration standard**
|
|
245
312
|
|
|
246
313
|
```json
|
|
247
314
|
{
|
|
@@ -254,6 +321,9 @@ claude mcp add metacritic -- npx -y mcp-metacritic
|
|
|
254
321
|
}
|
|
255
322
|
```
|
|
256
323
|
|
|
324
|
+
Node 24 ou plus récent est nécessaire, et aucune variable d'environnement n'est à
|
|
325
|
+
renseigner.
|
|
326
|
+
|
|
257
327
|
### Avec Docker
|
|
258
328
|
|
|
259
329
|
```json
|
|
@@ -261,155 +331,218 @@ claude mcp add metacritic -- npx -y mcp-metacritic
|
|
|
261
331
|
"mcpServers": {
|
|
262
332
|
"metacritic": {
|
|
263
333
|
"command": "docker",
|
|
264
|
-
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-metacritic:2.0.
|
|
334
|
+
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-metacritic:2.0.1"]
|
|
265
335
|
}
|
|
266
336
|
}
|
|
267
337
|
}
|
|
268
338
|
```
|
|
269
339
|
|
|
270
|
-
`-i` garde l'entrée standard ouverte, qui est le canal du protocole, et
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
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
|
|
274
354
|
|
|
275
|
-
|
|
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 ? »
|
|
276
360
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
ouvrez-le. Un client compatible avec les bundles MCP l'installe seul, sans npm
|
|
280
|
-
ni fichier de configuration à modifier. Le bundle embarque ses dépendances,
|
|
281
|
-
donc rien n'est téléchargé à l'installation.
|
|
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.
|
|
282
363
|
|
|
283
|
-
##
|
|
364
|
+
## Les outils
|
|
284
365
|
|
|
285
|
-
| Outil |
|
|
286
|
-
| --------------- |
|
|
287
|
-
| `search_titles` | Trouve films, séries et jeux par titre.
|
|
288
|
-
| `get_title` | Lit une fiche,
|
|
289
|
-
| `get_reviews` |
|
|
290
|
-
| `browse_titles` |
|
|
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é. |
|
|
291
372
|
|
|
292
|
-
|
|
293
|
-
|
|
373
|
+
Un titre s'adresse par son `slug` accompagné de son `kind`, un même slug pouvant
|
|
374
|
+
nommer un film et un jeu.
|
|
294
375
|
|
|
295
|
-
|
|
376
|
+
### `search_titles`
|
|
296
377
|
|
|
297
|
-
|
|
378
|
+
Trouve des films, des séries et des jeux par leur titre.
|
|
298
379
|
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
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. |
|
|
304
385
|
|
|
305
|
-
**
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
`
|
|
309
|
-
|
|
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.
|
|
310
392
|
|
|
311
|
-
|
|
312
|
-
un film donné et en sert 7 par cette route, quelle que soit la pagination
|
|
313
|
-
demandée. L'outil le dit au lieu de présenter l'échantillon comme la liste
|
|
314
|
-
complète, et renvoie vers la fiche où le reste se lit.
|
|
393
|
+
### `get_title`
|
|
315
394
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
la deviner. Une fiche absente produit une erreur avec un code ; une requête qui
|
|
319
|
-
n'a pas abouti dit qu'elle n'a pas abouti, jamais que Metacritic ne publie rien.
|
|
320
|
-
Ce sont deux réponses très différentes, qu'un modèle ne peut pas distinguer seul.
|
|
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.
|
|
321
397
|
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
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. |
|
|
327
405
|
|
|
328
|
-
**
|
|
329
|
-
|
|
330
|
-
|
|
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.
|
|
331
410
|
|
|
332
|
-
|
|
411
|
+
### `get_reviews`
|
|
412
|
+
|
|
413
|
+
Lit les critiques d'une fiche.
|
|
333
414
|
|
|
334
|
-
|
|
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. |
|
|
335
423
|
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
| `MC_CACHE_TTL_MS` | `86400000` | Durée de vie du cache catalogue (24 heures). |
|
|
343
|
-
| `MC_SCORES_CACHE_TTL_MS` | `3600000` | Durée de vie du cache notes et critiques (1 heure). |
|
|
344
|
-
| `MC_CACHE_MAX_ENTRIES` | `200` | Taille des caches mémoire. |
|
|
345
|
-
| `MC_LOG_LEVEL` | `error` | `silent`, `error`, `info` ou `debug`. Logs sur stderr. |
|
|
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.
|
|
346
430
|
|
|
347
|
-
|
|
348
|
-
du projet, pour que le trafic reste attribuable quoi que règle l'appelant.
|
|
431
|
+
### `browse_titles`
|
|
349
432
|
|
|
350
|
-
|
|
433
|
+
Liste un catalogue.
|
|
351
434
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
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.
|
|
357
453
|
|
|
358
|
-
|
|
359
|
-
d'environ 800 caractères, avec la vraie destination à l'intérieur. Ce serveur
|
|
360
|
-
les déballe : vous obtenez l'URL du fournisseur, pas celle d'un traqueur.
|
|
454
|
+
## Configuration
|
|
361
455
|
|
|
362
|
-
|
|
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);
|
|
499
|
+
```
|
|
363
500
|
|
|
364
|
-
|
|
365
|
-
|
|
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.
|
|
366
503
|
|
|
367
|
-
|
|
368
|
-
aucune clé, et n'a ralenti aucune de dix requêtes consécutives lors des tests.
|
|
369
|
-
Ce sont les conditions dans lesquelles ce serveur opère, et il n'y voit pas une
|
|
370
|
-
autorisation d'être gourmand. Il envoie au plus une requête par seconde,
|
|
371
|
-
s'identifie, met en cache ce qu'il lit, et porte un lien vers Metacritic sur
|
|
372
|
-
chaque résultat, y compris sur chaque critique citée.
|
|
504
|
+
## Rythme et attribution
|
|
373
505
|
|
|
374
|
-
|
|
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.
|
|
516
|
+
|
|
517
|
+
## Confidentialité
|
|
518
|
+
|
|
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.
|
|
375
524
|
|
|
376
525
|
## Développement
|
|
377
526
|
|
|
378
527
|
```bash
|
|
379
528
|
npm install
|
|
380
|
-
npm run build:fixtures
|
|
381
|
-
npm test
|
|
382
|
-
npm run
|
|
383
|
-
npm run build
|
|
384
|
-
MC_LIVE=1 npm run test:live # touche le vrai site, exclu de la CI
|
|
385
|
-
npm run inspector # explorer les outils dans le MCP Inspector
|
|
529
|
+
npm run build:fixtures
|
|
530
|
+
npm test
|
|
531
|
+
npm run check
|
|
386
532
|
```
|
|
387
533
|
|
|
388
|
-
Les
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
La couche API (`src/mc`) n'importe pas le SDK MCP et est publiée séparément sous
|
|
393
|
-
`mcp-metacritic/client`, utilisable comme simple bibliothèque. Elle applique
|
|
394
|
-
elle-même le plancher de cadence et le User-Agent identifiant, qui valent donc
|
|
395
|
-
aussi pour qui l'utilise en bibliothèque.
|
|
396
|
-
|
|
397
|
-
## Critiques, notes et droits d'auteur
|
|
398
|
-
|
|
399
|
-
Les Metascores, les textes de critiques et le travail éditorial qui les
|
|
400
|
-
sous-tend appartiennent à Metacritic et aux publications qu'il agrège. Ce projet
|
|
401
|
-
ne revendique aucun droit dessus et n'embarque aucun de leurs contenus.
|
|
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.
|
|
402
537
|
|
|
403
|
-
|
|
404
|
-
avec la publication nommée et un lien vers l'article d'origine quand le site en
|
|
405
|
-
fournit un. Si vous reprenez une citation, conservez les deux. Si vous citez une
|
|
406
|
-
note, créditez Metacritic et liez la fiche : chaque résultat porte un
|
|
407
|
-
`source_url`.
|
|
538
|
+
## Contribuer
|
|
408
539
|
|
|
409
|
-
|
|
410
|
-
|
|
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).
|
|
411
544
|
|
|
412
545
|
## Licence
|
|
413
546
|
|
|
414
|
-
MIT, voir [LICENSE](
|
|
415
|
-
|
|
547
|
+
MIT, voir [LICENSE](LICENSE). Les notes et les critiques appartiennent à
|
|
548
|
+
Metacritic et aux publications qu'il cite.
|