mcp-rule34 1.1.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 +99 -0
- package/LICENSE +1 -1
- package/PRIVACY.md +156 -0
- package/README.md +374 -282
- package/dist/index.js +22 -14
- package/dist/index.js.map +1 -1
- package/dist/rule34/client.js +9 -5
- package/dist/rule34/client.js.map +1 -1
- package/package.json +15 -9
- package/server.json +10 -2
package/README.md
CHANGED
|
@@ -4,20 +4,23 @@
|
|
|
4
4
|
[](https://github.com/smeet666/mcp-rule34/actions/workflows/ci.yml)
|
|
5
5
|
[](./LICENSE)
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
the
|
|
7
|
+
[rule34.xxx](https://rule34.xxx) is a large image board whose posts are indexed
|
|
8
|
+
entirely by tags, and it publishes an API for reading them. A post carries its
|
|
9
|
+
identifier, the address of its page and of its file, its dimensions, the score
|
|
10
|
+
its viewers gave it, its rating, and the full list of tags it was filed under.
|
|
11
|
+
The site holds tens of millions of posts and answers a tag search with the number
|
|
12
|
+
it matched.
|
|
11
13
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
14
|
+
This server connects a chat client to that index. You can search the posts by
|
|
15
|
+
tags, combining required tags, alternatives and exclusions, read one post's
|
|
16
|
+
record by its identifier, and look up how the site spells a tag before searching
|
|
17
|
+
on it. **It needs an account and an API key**, which the site issues per person.
|
|
15
18
|
|
|
16
|
-
_
|
|
19
|
+
_[Version française](#mcp-rule34-français)_
|
|
17
20
|
|
|
18
21
|
---
|
|
19
22
|
|
|
20
|
-
##
|
|
23
|
+
## Install
|
|
21
24
|
|
|
22
25
|
**Claude Code**
|
|
23
26
|
|
|
@@ -42,210 +45,256 @@ claude mcp add rule34 --env RULE34_USER_ID=your-id --env RULE34_API_KEY=your-key
|
|
|
42
45
|
}
|
|
43
46
|
```
|
|
44
47
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
travels with it.
|
|
48
|
+
Node 24 or later is required. The two credentials are required; everything else
|
|
49
|
+
under [Configuration](#configuration) is optional.
|
|
48
50
|
|
|
49
|
-
|
|
51
|
+
### With Docker
|
|
50
52
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"mcpServers": {
|
|
56
|
+
"rule34": {
|
|
57
|
+
"command": "docker",
|
|
58
|
+
"args": [
|
|
59
|
+
"run",
|
|
60
|
+
"-i",
|
|
61
|
+
"--rm",
|
|
62
|
+
"-e",
|
|
63
|
+
"RULE34_USER_ID",
|
|
64
|
+
"-e",
|
|
65
|
+
"RULE34_API_KEY",
|
|
66
|
+
"ghcr.io/smeet666/mcp-rule34:2.0.1"
|
|
67
|
+
]
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
62
72
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
73
|
+
`-i` keeps stdin open, which is where the protocol travels, and `-t` is left out
|
|
74
|
+
because a TTY rewrites the stream. The container needs outbound HTTPS to
|
|
75
|
+
`api.rule34.xxx` and `rule34.xxx`, and the two credentials from your environment:
|
|
76
|
+
no volume, no port.
|
|
77
|
+
|
|
78
|
+
### Bundle, without npm
|
|
68
79
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
80
|
+
Download `mcp-rule34-2.0.1.mcpb` from
|
|
81
|
+
[the latest release](https://github.com/smeet666/mcp-rule34/releases/latest) and
|
|
82
|
+
open it. A client that supports MCP bundles installs it on its own, with no npm
|
|
83
|
+
to run. The credentials are still set in the client's configuration.
|
|
72
84
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
85
|
+
## What you can ask
|
|
86
|
+
|
|
87
|
+
- "How does the site spell that tag?"
|
|
88
|
+
- "Find posts tagged with those two, sorted by score."
|
|
89
|
+
- "Same search, leaving out monochrome."
|
|
90
|
+
- "Read me the record for post 1234567."
|
|
91
|
+
- "How many posts does that search match?"
|
|
92
|
+
|
|
93
|
+
The ordinary path runs from a tag lookup to a search: `find_tags` gives the
|
|
94
|
+
spelling the site uses, and `search_posts` takes it.
|
|
76
95
|
|
|
77
96
|
## Tools
|
|
78
97
|
|
|
79
|
-
| Tool | What it does |
|
|
80
|
-
| -------------- | ------------------------------------------------------------- |
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
98
|
+
| Tool | What it does |
|
|
99
|
+
| -------------- | ------------------------------------------------------------- |
|
|
100
|
+
| `find_tags` | Finds how the site spells a tag, and how many posts carry it. |
|
|
101
|
+
| `search_posts` | Searches the posts by tags, with alternatives and exclusions. |
|
|
102
|
+
| `get_post` | Reads one post's record by its identifier or its address. |
|
|
84
103
|
|
|
85
|
-
|
|
104
|
+
**Look a tag up before searching on it.** The site indexes by tag alone, and a
|
|
105
|
+
tag it does not hold matches nothing, which reads as an empty result rather than
|
|
106
|
+
as a misspelling.
|
|
86
107
|
|
|
87
|
-
`find_tags`
|
|
88
|
-
posts each one carries. It matches from the start of a name, so `kimagure` finds
|
|
89
|
-
`kimagure_orange_road` while a word sitting in the middle of a name finds
|
|
90
|
-
nothing. The site offers at most ten names and the answer says so, since ten
|
|
91
|
-
back means the list was cut rather than exhausted.
|
|
108
|
+
### `find_tags`
|
|
92
109
|
|
|
93
|
-
|
|
94
|
-
does not exist, the answer names it and offers the names the site does hold that
|
|
95
|
-
begin like it.
|
|
110
|
+
Finds how the site spells a tag.
|
|
96
111
|
|
|
97
|
-
|
|
112
|
+
| Argument | Type | Required | What it does |
|
|
113
|
+
| -------- | --------------------------- | -------- | -------------------- |
|
|
114
|
+
| `query` | string, up to 60 characters | yes | The text to look up. |
|
|
98
115
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
four fifths of its answer on tag strings nobody reads, so a search row shows the
|
|
102
|
-
first twelve and states how many the post carries in all.
|
|
116
|
+
**In return:** `query` as it was sent, and `tags`, each with the spelling the site
|
|
117
|
+
uses and the number of posts carrying it.
|
|
103
118
|
|
|
104
|
-
`
|
|
105
|
-
tag with its kind, character, copyright, artist, general or metadata, and how
|
|
106
|
-
many posts share it, alongside the uploader, the number of comments and the
|
|
107
|
-
date the site took it in. A link is read rather than followed: this server builds its
|
|
108
|
-
own request from the id it finds in it.
|
|
119
|
+
### `search_posts`
|
|
109
120
|
|
|
110
|
-
|
|
111
|
-
carries everything: the date the site took the post in comes from one, and the
|
|
112
|
-
uploader's name, the comment count and the tag kinds from the other.
|
|
121
|
+
Searches the posts by tags.
|
|
113
122
|
|
|
114
|
-
|
|
123
|
+
| Argument | Type | Required | What it does |
|
|
124
|
+
| ------------ | ----------------------------------------------------- | -------- | ---------------------------------------- |
|
|
125
|
+
| `tags` | array of 1 to 10 tag names | yes | Tags a post must carry. |
|
|
126
|
+
| `any_of` | array of 1 to 10 tag names | no | Tags a post must carry at least one of. |
|
|
127
|
+
| `exclude` | array of 1 to 10 tag names | no | Tags a post must carry none of. |
|
|
128
|
+
| `media_type` | `image`, `animated`, `video` or `any`, default `any` | no | Stills, GIFs or MP4. |
|
|
129
|
+
| `rating` | `questionable` or `explicit` | no | Both are searched when this is left out. |
|
|
130
|
+
| `sort` | `score`, `id`, `updated` or `random`, default `score` | no | The order the site sorts by. |
|
|
131
|
+
| `limit` | integer, 1 to 100, default `20` | no | Posts to serve. |
|
|
132
|
+
| `page` | integer, 1 to 200, default `1` | no | Which page of posts. |
|
|
115
133
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
134
|
+
`media_type` is read off the site's own tags, so the classification is as good as
|
|
135
|
+
the tagging. The two ratings above are the only ones the site holds: any other
|
|
136
|
+
value answers zero posts and no error, which would hand back an absence the site
|
|
137
|
+
never had.
|
|
120
138
|
|
|
121
|
-
|
|
139
|
+
**In return:** `tags`, `any_of` and `exclude` as the site spells them; `query`,
|
|
140
|
+
the search as it was sent in the site's own language; `total`, the posts the
|
|
141
|
+
whole search matches as counted by the site; and the posts themselves, each with
|
|
142
|
+
its `id`, `post_url`, `file_url`, `preview_url`, `sample_url`, `width`,
|
|
143
|
+
`height`, `score`, `rating` and `tags`. The score is the site's own and it is
|
|
144
|
+
updated once a day.
|
|
122
145
|
|
|
123
|
-
|
|
124
|
-
{
|
|
125
|
-
"tags": ["asuka langley sohryu", "black hair"], // every one of these
|
|
126
|
-
"any_of": ["blonde hair", "red hair"], // at least one of these
|
|
127
|
-
"exclude": ["monochrome", "3d"], // none of these
|
|
128
|
-
}
|
|
129
|
-
```
|
|
146
|
+
### `get_post`
|
|
130
147
|
|
|
131
|
-
|
|
132
|
-
can state the rating and the sort it actually used.
|
|
148
|
+
Reads one post's record.
|
|
133
149
|
|
|
134
|
-
|
|
150
|
+
| Argument | Type | Required | What it does |
|
|
151
|
+
| -------- | --------------------- | ---------- | ------------------------------- |
|
|
152
|
+
| `id` | integer, 1 or more | one of two | The post identifier. |
|
|
153
|
+
| `url` | a rule34.xxx post URL | one of two | The address of the post's page. |
|
|
135
154
|
|
|
136
|
-
|
|
137
|
-
distinction in its own tags, so the site does the filtering and the total it
|
|
138
|
-
returns counts what was asked for. The classification is therefore as good as
|
|
139
|
-
the site's tagging.
|
|
155
|
+
**In return:** the post a search row carries, with its full tag list.
|
|
140
156
|
|
|
141
|
-
|
|
142
|
-
nothing to say a post is in colour. Ask for colour with
|
|
143
|
-
`"exclude": ["monochrome", "greyscale", "grayscale"]`.
|
|
157
|
+
## Configuration
|
|
144
158
|
|
|
145
|
-
|
|
159
|
+
The two credentials are required. Everything else is optional, and all of it goes
|
|
160
|
+
in the `env` block of your client config.
|
|
161
|
+
|
|
162
|
+
| Variable | Default | What it does |
|
|
163
|
+
| -------------------------- | -------------------- | ---------------------------------------------------------------------------------- |
|
|
164
|
+
| `RULE34_USER_ID` | none, required | Your numeric account id. |
|
|
165
|
+
| `RULE34_API_KEY` | none, required | Your API key, which is personal. |
|
|
166
|
+
| `RULE34_USER_AGENT` | the project identity | Names your application to the site, with an address where a person can be reached. |
|
|
167
|
+
| `RULE34_MIN_INTERVAL_MS` | `1000` | Gap between two requests, from 1000 to 60000. |
|
|
168
|
+
| `RULE34_TIMEOUT_MS` | `20000` | Deadline for one request, from 1000 to 120000. |
|
|
169
|
+
| `RULE34_MAX_RETRIES` | `3` | Attempts after a transient failure, from 0 to 10. |
|
|
170
|
+
| `RULE34_CACHE_TTL_MS` | `300000` | How long an answer stays in memory, from 0 to 86400000. |
|
|
171
|
+
| `RULE34_CACHE_MAX_ENTRIES` | `300` | Answers held in memory at once, from 0 to 10000. |
|
|
172
|
+
| `RULE34_LOG_LEVEL` | `error` | `silent`, `error`, `info` or `debug`, written to stderr. |
|
|
146
173
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
those
|
|
174
|
+
**Where the credentials come from.** Sign in, open
|
|
175
|
+
[Account options](https://rule34.xxx/index.php?page=account&s=options), and find
|
|
176
|
+
the row named _API Access Credentials_. It shows `&api_key=…&user_id=…`, and
|
|
177
|
+
those two values are what goes in the configuration above. If the key is empty,
|
|
178
|
+
tick _Generate New Key?_ and save.
|
|
151
179
|
|
|
152
|
-
|
|
180
|
+
The site issues one key per person, and asks that applications serving its
|
|
181
|
+
content display no advertising and put it behind no paywall. This server ships no
|
|
182
|
+
key of its own, and each user brings their own. Started without credentials, it
|
|
183
|
+
runs, publishes its tools, and answers every call by naming the two variables to
|
|
184
|
+
set: it sends no request it knows the site will refuse.
|
|
153
185
|
|
|
154
|
-
A
|
|
155
|
-
|
|
156
|
-
this server asks the site which of the names it holds, and the answer says which
|
|
157
|
-
one it does not:
|
|
186
|
+
A value outside its range falls back to the default, and the reason is written to
|
|
187
|
+
stderr.
|
|
158
188
|
|
|
159
|
-
|
|
160
|
-
No post on rule34.xxx matches neon_genesis_evangelion asuka_langley_sohry.
|
|
189
|
+
## Errors
|
|
161
190
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
```
|
|
191
|
+
Every failure carries one of six codes, a message, and where it helps a hint
|
|
192
|
+
naming the next move.
|
|
165
193
|
|
|
166
|
-
|
|
194
|
+
| Code | What happened | What to do |
|
|
195
|
+
| --------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
196
|
+
| `not_found` | The site answered, and holds nothing at that address. | Check the identifier with `search_posts`. |
|
|
197
|
+
| `invalid_input` | The arguments were refused before any request went out. | Read the message, which names the argument. A missing credential is reported here. |
|
|
198
|
+
| `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 post is still there. |
|
|
199
|
+
| `parse_failure` | The answer arrived in a shape this client cannot read. | Report it at [the issue tracker](https://github.com/smeet666/mcp-rule34/issues). |
|
|
200
|
+
| `network_error` | The request did not complete. | Try again shortly. |
|
|
201
|
+
| `timeout` | The request passed its deadline. | Raise `RULE34_TIMEOUT_MS`, or ask for fewer posts. |
|
|
167
202
|
|
|
168
|
-
|
|
169
|
-
that was served, and the search as it was sent in the site's own language. A
|
|
170
|
-
post carries its rule34.xxx page, its file, its thumbnail, its dimensions, its
|
|
171
|
-
score, its rating, its tags, whatever the uploader credited as a source, and the
|
|
172
|
-
date rule34.xxx took it in.
|
|
203
|
+
## As a library
|
|
173
204
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
changed, which retagging moves. rule34.xxx imported much of its older catalogue
|
|
177
|
-
in bulk, so thousands of posts share one day in November 2010: a question about
|
|
178
|
-
what came first is answered by the import, not by the work.
|
|
205
|
+
The layer reading the site is published on its own, with its pacing, its cache
|
|
206
|
+
and its errors, and with no protocol attached.
|
|
179
207
|
|
|
180
|
-
|
|
208
|
+
```ts
|
|
209
|
+
import { Rule34Client } from "mcp-rule34/client";
|
|
181
210
|
|
|
182
|
-
|
|
211
|
+
const client = new Rule34Client({ credentials: { userId: "…", apiKey: "…" } });
|
|
212
|
+
const { data, cached } = await client.searchPosts({ tags: ["example"], limit: 5 });
|
|
213
|
+
console.log(data.total, cached);
|
|
214
|
+
```
|
|
183
215
|
|
|
184
|
-
|
|
216
|
+
Each read answers `{ data, cached }`, and throws an error carrying one of the six
|
|
217
|
+
codes. The one-second floor between two requests holds here as well.
|
|
185
218
|
|
|
186
|
-
|
|
187
|
-
`not_found`, `invalid_input`, `rate_limited`, `parse_failure`, `network_error`,
|
|
188
|
-
`timeout`.
|
|
219
|
+
## Pacing and attribution
|
|
189
220
|
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
two requests that no configuration can shorten, and it backs further off when the
|
|
194
|
-
site pushes back.
|
|
221
|
+
Requests go out one at a time with at least a second between them, and that floor
|
|
222
|
+
holds however the server is configured. The `User-Agent` always ends with the
|
|
223
|
+
project identity and an address where a person can be reached.
|
|
195
224
|
|
|
196
|
-
|
|
225
|
+
Reads go to the API the site documents, and the credentials it issues are what
|
|
226
|
+
its terms ask automated reading to use. Every result carries the address of the
|
|
227
|
+
post's page. Nothing is downloaded: a file address travels through an answer as a
|
|
228
|
+
string.
|
|
197
229
|
|
|
198
|
-
|
|
230
|
+
This MCP server is an unofficial project, with no affiliation to rule34.xxx.
|
|
199
231
|
|
|
200
|
-
|
|
201
|
-
import { Rule34Client } from "mcp-rule34/client";
|
|
202
|
-
```
|
|
232
|
+
## Privacy
|
|
203
233
|
|
|
204
|
-
|
|
234
|
+
This server collects nothing about you and sends nothing to its author. It runs
|
|
235
|
+
on your machine, contacts `api.rule34.xxx` and `rule34.xxx` and nothing else,
|
|
236
|
+
holds its answers in memory while it runs, and writes nothing to disk. Your
|
|
237
|
+
credentials are read from the environment and sent to that site alone.
|
|
238
|
+
[PRIVACY.md](PRIVACY.md) states what a request carries and which settings change
|
|
239
|
+
any of it.
|
|
205
240
|
|
|
206
241
|
## Development
|
|
207
242
|
|
|
208
243
|
```bash
|
|
209
244
|
npm install
|
|
210
|
-
npm
|
|
211
|
-
npm
|
|
212
|
-
npm run check
|
|
213
|
-
npm run build
|
|
245
|
+
npm run build:fixtures
|
|
246
|
+
npm test
|
|
247
|
+
npm run check
|
|
214
248
|
```
|
|
215
249
|
|
|
216
|
-
|
|
250
|
+
Tests run against generated fixtures and make no network request. The live suite,
|
|
251
|
+
`npm run test:live`, makes one request per route and runs nightly against the
|
|
252
|
+
site itself.
|
|
217
253
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
254
|
+
## Contributing
|
|
255
|
+
|
|
256
|
+
Bugs, questions and ideas belong in
|
|
257
|
+
[the issue tracker](https://github.com/smeet666/mcp-rule34/issues). Pull requests
|
|
258
|
+
are welcome; opening an issue first helps agree on the shape of the change. See
|
|
259
|
+
[CONTRIBUTING.md](CONTRIBUTING.md).
|
|
221
260
|
|
|
222
261
|
## License
|
|
223
262
|
|
|
224
|
-
MIT.
|
|
263
|
+
MIT, see [LICENSE](LICENSE). The posts and the tags belong to rule34.xxx and to
|
|
264
|
+
the people who uploaded them.
|
|
225
265
|
|
|
226
266
|
---
|
|
227
267
|
|
|
268
|
+
<a name="mcp-rule34-français"></a>
|
|
269
|
+
|
|
228
270
|
# mcp-rule34 (français)
|
|
229
271
|
|
|
230
|
-
|
|
231
|
-
[rule34.xxx](https://rule34.xxx). Cherche les posts du site par tag, à travers sa
|
|
232
|
-
propre API, et rend pour chacun sa page, son fichier, ses dimensions, son score,
|
|
233
|
-
sa classification et ses tags, avec le nombre de posts que la recherche entière
|
|
234
|
-
trouve.
|
|
272
|
+
_[English version](#mcp-rule34)_
|
|
235
273
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
274
|
+
[rule34.xxx](https://rule34.xxx) est un grand imageboard dont les publications
|
|
275
|
+
sont indexées entièrement par étiquettes, et il publie une API pour les lire. Une
|
|
276
|
+
publication porte son identifiant, l'adresse de sa page et de son fichier, ses
|
|
277
|
+
dimensions, la note que ses visiteurs lui ont donnée, son classement, et la liste
|
|
278
|
+
complète des étiquettes sous lesquelles elle est rangée. Le site contient des
|
|
279
|
+
dizaines de millions de publications et répond à une recherche par étiquettes en
|
|
280
|
+
donnant le nombre qu'elle a trouvé.
|
|
239
281
|
|
|
240
|
-
|
|
282
|
+
Ce serveur relie un client de conversation à cet index. On peut chercher les
|
|
283
|
+
publications par étiquettes, en combinant les étiquettes exigées, les
|
|
284
|
+
alternatives et les exclusions, lire la fiche d'une publication par son
|
|
285
|
+
identifiant, et vérifier comment le site orthographie une étiquette avant de
|
|
286
|
+
chercher dessus. **Il demande un compte et une clé d'API**, que le site délivre
|
|
287
|
+
par personne.
|
|
288
|
+
|
|
289
|
+
## Installation
|
|
241
290
|
|
|
242
291
|
**Claude Code**
|
|
243
292
|
|
|
244
293
|
```bash
|
|
245
|
-
claude mcp add rule34 --env RULE34_USER_ID=votre-id --env RULE34_API_KEY=votre-
|
|
294
|
+
claude mcp add rule34 --env RULE34_USER_ID=votre-id --env RULE34_API_KEY=votre-cle -- npx -y mcp-rule34
|
|
246
295
|
```
|
|
247
296
|
|
|
248
|
-
**Claude Desktop, Cursor, et tout client au format standard**
|
|
297
|
+
**Claude Desktop, Cursor, et tout client au format de configuration standard**
|
|
249
298
|
|
|
250
299
|
```json
|
|
251
300
|
{
|
|
@@ -255,188 +304,231 @@ claude mcp add rule34 --env RULE34_USER_ID=votre-id --env RULE34_API_KEY=votre-c
|
|
|
255
304
|
"args": ["-y", "mcp-rule34"],
|
|
256
305
|
"env": {
|
|
257
306
|
"RULE34_USER_ID": "votre-id",
|
|
258
|
-
"RULE34_API_KEY": "votre-
|
|
307
|
+
"RULE34_API_KEY": "votre-cle"
|
|
259
308
|
}
|
|
260
309
|
}
|
|
261
310
|
}
|
|
262
311
|
}
|
|
263
312
|
```
|
|
264
313
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
part avec lui.
|
|
314
|
+
Node 24 ou plus récent est nécessaire. Les deux identifiants sont obligatoires ;
|
|
315
|
+
tout le reste, sous [Configuration](#configuration-1), est facultatif.
|
|
268
316
|
|
|
269
|
-
|
|
317
|
+
### Avec Docker
|
|
270
318
|
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
son contenu n'affiche aucune publicité et ne le mette derrière aucun péage. Ce
|
|
291
|
-
serveur n'embarque aucune clé, et chacun apporte la sienne.
|
|
292
|
-
|
|
293
|
-
Un serveur démarré sans identifiants démarre quand même, publie son outil, et
|
|
294
|
-
répond à chaque appel en nommant les deux variables à régler. Il n'émet jamais
|
|
295
|
-
une requête dont il sait que le site la refusera.
|
|
319
|
+
```json
|
|
320
|
+
{
|
|
321
|
+
"mcpServers": {
|
|
322
|
+
"rule34": {
|
|
323
|
+
"command": "docker",
|
|
324
|
+
"args": [
|
|
325
|
+
"run",
|
|
326
|
+
"-i",
|
|
327
|
+
"--rm",
|
|
328
|
+
"-e",
|
|
329
|
+
"RULE34_USER_ID",
|
|
330
|
+
"-e",
|
|
331
|
+
"RULE34_API_KEY",
|
|
332
|
+
"ghcr.io/smeet666/mcp-rule34:2.0.1"
|
|
333
|
+
]
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
```
|
|
296
338
|
|
|
297
|
-
|
|
339
|
+
`-i` garde l'entrée standard ouverte, qui est le canal du protocole, et `-t` est
|
|
340
|
+
omis parce qu'un TTY réécrit le flux. Le conteneur a besoin d'un accès HTTPS
|
|
341
|
+
sortant vers `api.rule34.xxx` et `rule34.xxx`, et des deux identifiants pris dans
|
|
342
|
+
votre environnement : aucun volume, aucun port.
|
|
298
343
|
|
|
299
|
-
|
|
300
|
-
| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
301
|
-
| `search_posts` | Trouve les posts portant un tag, ou plusieurs. | `tags`, `any_of`, `exclude`, `media_type`, `rating`, `sort`, `limit`, `page` |
|
|
302
|
-
| `get_post` | Lit un post en entier, avec le type de chacun de ses tags. | `id`, `url` |
|
|
303
|
-
| `find_tags` | Trouve comment le site écrit un tag, et combien de posts le portent. | `query` |
|
|
344
|
+
### Bundle, sans npm
|
|
304
345
|
|
|
305
|
-
|
|
346
|
+
Téléchargez `mcp-rule34-2.0.1.mcpb` depuis
|
|
347
|
+
[la dernière publication](https://github.com/smeet666/mcp-rule34/releases/latest)
|
|
348
|
+
et ouvrez-le. Un client qui gère les bundles MCP l'installe seul, sans npm à
|
|
349
|
+
lancer. Les identifiants se posent toujours dans la configuration du client.
|
|
306
350
|
|
|
307
|
-
|
|
308
|
-
de posts chacun porte. La correspondance part du début d'un nom, donc `kimagure`
|
|
309
|
-
trouve `kimagure_orange_road` là où un mot situé au milieu d'un nom ne trouve
|
|
310
|
-
rien. Le site propose au plus dix noms et la réponse le dit, puisque dix en
|
|
311
|
-
retour signifie une liste coupée plutôt qu'épuisée.
|
|
351
|
+
## Ce qu'on peut demander
|
|
312
352
|
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
353
|
+
- « Comment le site orthographie-t-il cette étiquette ? »
|
|
354
|
+
- « Trouve les publications portant ces deux étiquettes, triées par note. »
|
|
355
|
+
- « La même recherche, sans monochrome. »
|
|
356
|
+
- « Lis-moi la fiche de la publication 1234567. »
|
|
357
|
+
- « Combien de publications cette recherche trouve-t-elle ? »
|
|
316
358
|
|
|
317
|
-
|
|
359
|
+
Le chemin ordinaire va d'une recherche d'étiquette à une recherche de
|
|
360
|
+
publications : `find_tags` donne l'orthographe qu'emploie le site, et
|
|
361
|
+
`search_posts` la reprend.
|
|
318
362
|
|
|
319
|
-
|
|
320
|
-
en portent neuf cents. Une page de vingt résultats avec tous les tags écrits
|
|
321
|
-
dépenserait quatre cinquièmes de sa réponse en chaînes que personne ne lit, donc
|
|
322
|
-
une ligne de recherche montre les douze premiers et dit combien le post en porte
|
|
323
|
-
au total.
|
|
363
|
+
## Les outils
|
|
324
364
|
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
365
|
+
| Outil | Ce qu'il fait |
|
|
366
|
+
| -------------- | ---------------------------------------------------------------------------- |
|
|
367
|
+
| `find_tags` | Trouve l'orthographe d'une étiquette, et combien de publications la portent. |
|
|
368
|
+
| `search_posts` | Cherche les publications par étiquettes, avec alternatives et exclusions. |
|
|
369
|
+
| `get_post` | Lit la fiche d'une publication par son identifiant ou son adresse. |
|
|
330
370
|
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
de l'autre.
|
|
371
|
+
**Vérifiez une étiquette avant de chercher dessus.** Le site indexe par étiquette
|
|
372
|
+
seule, et une étiquette qu'il ne connaît pas ne correspond à rien, ce qui se lit
|
|
373
|
+
comme un résultat vide plutôt que comme une faute d'orthographe.
|
|
335
374
|
|
|
336
|
-
###
|
|
375
|
+
### `find_tags`
|
|
337
376
|
|
|
338
|
-
|
|
339
|
-
personne dit en plusieurs. `asuka langley sohryu` et `asuka_langley_sohryu` sont
|
|
340
|
-
le même tag, et ce serveur écrit le second à partir du premier. La ponctuation
|
|
341
|
-
d'un nom lui appartient : le tag de la série est `ranma_1/2`, barre oblique
|
|
342
|
-
comprise.
|
|
377
|
+
Trouve l'orthographe d'une étiquette.
|
|
343
378
|
|
|
344
|
-
|
|
379
|
+
| Argument | Type | Requis | Ce qu'il fait |
|
|
380
|
+
| -------- | ----------------------------- | ------ | -------------------- |
|
|
381
|
+
| `query` | chaîne, jusqu'à 60 caractères | oui | Le texte à vérifier. |
|
|
345
382
|
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
"tags": ["asuka langley sohryu", "black hair"], // tous ceux-là
|
|
349
|
-
"any_of": ["blonde hair", "red hair"], // au moins un de ceux-là
|
|
350
|
-
"exclude": ["monochrome", "3d"], // aucun de ceux-là
|
|
351
|
-
}
|
|
352
|
-
```
|
|
383
|
+
**En retour :** `query` tel qu'envoyé, et `tags`, chacune avec l'orthographe
|
|
384
|
+
qu'emploie le site et le nombre de publications qui la portent.
|
|
353
385
|
|
|
354
|
-
|
|
355
|
-
permet à une réponse d'énoncer la classification et le tri qu'elle a réellement
|
|
356
|
-
appliqués.
|
|
386
|
+
### `search_posts`
|
|
357
387
|
|
|
358
|
-
|
|
388
|
+
Cherche les publications par étiquettes.
|
|
359
389
|
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
390
|
+
| Argument | Type | Requis | Ce qu'il fait |
|
|
391
|
+
| ------------ | ---------------------------------------------------- | ------ | --------------------------------------------------------- |
|
|
392
|
+
| `tags` | tableau de 1 à 10 noms d'étiquettes | oui | Étiquettes qu'une publication doit porter. |
|
|
393
|
+
| `any_of` | tableau de 1 à 10 noms d'étiquettes | non | Étiquettes dont une publication doit porter au moins une. |
|
|
394
|
+
| `exclude` | tableau de 1 à 10 noms d'étiquettes | non | Étiquettes qu'une publication ne doit pas porter. |
|
|
395
|
+
| `media_type` | `image`, `animated`, `video` ou `any`, défaut `any` | non | Images fixes, GIF ou MP4. |
|
|
396
|
+
| `rating` | `questionable` ou `explicit` | non | Les deux sont cherchés quand il est omis. |
|
|
397
|
+
| `sort` | `score`, `id`, `updated` ou `random`, défaut `score` | non | L'ordre de tri du site. |
|
|
398
|
+
| `limit` | entier, 1 à 100, défaut `20` | non | Publications à servir. |
|
|
399
|
+
| `page` | entier, 1 à 200, défaut `1` | non | Quelle page de publications. |
|
|
364
400
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
401
|
+
`media_type` se lit sur les étiquettes du site lui-même, donc la classification
|
|
402
|
+
vaut ce que vaut l'étiquetage. Les deux classements ci-dessus sont les seuls que
|
|
403
|
+
le site connaisse : toute autre valeur rend zéro publication et aucune erreur, ce
|
|
404
|
+
qui livrerait une absence que le site n'a jamais eue.
|
|
368
405
|
|
|
369
|
-
|
|
406
|
+
**En retour :** `tags`, `any_of` et `exclude` tels que le site les
|
|
407
|
+
orthographie ; `query`, la recherche telle qu'elle a été envoyée dans la langue
|
|
408
|
+
du site ; `total`, les publications que toute la recherche trouve, tel que le
|
|
409
|
+
site les compte ; et les publications elles-mêmes, chacune avec son `id`,
|
|
410
|
+
`post_url`, `file_url`, `preview_url`, `sample_url`, `width`, `height`, `score`,
|
|
411
|
+
`rating` et `tags`. La note est celle du site et elle est mise à jour une fois
|
|
412
|
+
par jour.
|
|
370
413
|
|
|
371
|
-
|
|
372
|
-
`safe`, `general` ou `sensitive` à rule34.xxx rend zéro post et aucune erreur, ce
|
|
373
|
-
qui se lit comme une absence plutôt que comme une classification que le site n'a
|
|
374
|
-
jamais eue, donc ce serveur refuse ces trois-là au lieu de les transmettre.
|
|
414
|
+
### `get_post`
|
|
375
415
|
|
|
376
|
-
|
|
416
|
+
Lit la fiche d'une publication.
|
|
377
417
|
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
418
|
+
| Argument | Type | Requis | Ce qu'il fait |
|
|
419
|
+
| -------- | ------------------------------ | ------------- | -------------------------------- |
|
|
420
|
+
| `id` | entier, 1 ou plus | l'un des deux | L'identifiant de la publication. |
|
|
421
|
+
| `url` | une adresse de page rule34.xxx | l'un des deux | L'adresse de la page. |
|
|
382
422
|
|
|
383
|
-
|
|
423
|
+
**En retour :** la publication que porte une ligne de recherche, avec sa liste
|
|
424
|
+
complète d'étiquettes.
|
|
384
425
|
|
|
385
|
-
|
|
386
|
-
page servie, et la requête telle qu'elle a été envoyée dans le langage du site.
|
|
387
|
-
Un post porte sa page rule34.xxx, son fichier, sa vignette, ses dimensions, son
|
|
388
|
-
score, sa classification, ses tags, la source créditée par le déposant quand il
|
|
389
|
-
en a crédité une, et la date à laquelle rule34.xxx l'a pris.
|
|
426
|
+
## Configuration
|
|
390
427
|
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
428
|
+
Les deux identifiants sont obligatoires. Tout le reste est facultatif, et tout se
|
|
429
|
+
pose dans le bloc `env` de la configuration du client.
|
|
430
|
+
|
|
431
|
+
| Variable | Défaut | Ce qu'elle fait |
|
|
432
|
+
| -------------------------- | -------------------- | --------------------------------------------------------------------------------- |
|
|
433
|
+
| `RULE34_USER_ID` | aucun, obligatoire | L'identifiant numérique de votre compte. |
|
|
434
|
+
| `RULE34_API_KEY` | aucun, obligatoire | Votre clé d'API, qui est personnelle. |
|
|
435
|
+
| `RULE34_USER_AGENT` | l'identité du projet | Nomme votre application auprès du site, avec une adresse où joindre une personne. |
|
|
436
|
+
| `RULE34_MIN_INTERVAL_MS` | `1000` | Écart entre deux requêtes, de 1000 à 60000. |
|
|
437
|
+
| `RULE34_TIMEOUT_MS` | `20000` | Délai d'une requête, de 1000 à 120000. |
|
|
438
|
+
| `RULE34_MAX_RETRIES` | `3` | Tentatives après un échec passager, de 0 à 10. |
|
|
439
|
+
| `RULE34_CACHE_TTL_MS` | `300000` | Durée pendant laquelle une réponse reste en mémoire, de 0 à 86400000. |
|
|
440
|
+
| `RULE34_CACHE_MAX_ENTRIES` | `300` | Réponses gardées en mémoire à la fois, de 0 à 10000. |
|
|
441
|
+
| `RULE34_LOG_LEVEL` | `error` | `silent`, `error`, `info` ou `debug`, écrit sur la sortie d'erreur. |
|
|
442
|
+
|
|
443
|
+
**D'où viennent les identifiants.** Connectez-vous, ouvrez
|
|
444
|
+
[Account options](https://rule34.xxx/index.php?page=account&s=options), et
|
|
445
|
+
trouvez la ligne _API Access Credentials_. Elle affiche `&api_key=…&user_id=…`,
|
|
446
|
+
et ces deux valeurs sont ce qui va dans la configuration ci-dessus. Si la clé est
|
|
447
|
+
vide, cochez _Generate New Key?_ et enregistrez.
|
|
448
|
+
|
|
449
|
+
Le site délivre une clé par personne, et demande que les applications servant son
|
|
450
|
+
contenu n'affichent aucune publicité et ne le placent derrière aucun péage. Ce
|
|
451
|
+
serveur n'embarque aucune clé, et chacun apporte la sienne. Démarré sans
|
|
452
|
+
identifiants, il tourne, publie ses outils, et répond à chaque appel en nommant
|
|
453
|
+
les deux variables à poser : il n'envoie aucune requête dont il sait que le site
|
|
454
|
+
la refusera.
|
|
455
|
+
|
|
456
|
+
Une valeur hors de sa plage retombe sur le défaut, et la raison est écrite sur la
|
|
457
|
+
sortie d'erreur.
|
|
458
|
+
|
|
459
|
+
## Erreurs
|
|
460
|
+
|
|
461
|
+
Chaque échec porte un des six codes, un message, et quand cela aide une
|
|
462
|
+
indication du geste suivant.
|
|
463
|
+
|
|
464
|
+
| Code | Ce qui s'est passé | Que faire |
|
|
465
|
+
| --------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
466
|
+
| `not_found` | Le site a répondu, et n'a rien à cette adresse. | Vérifiez l'identifiant avec `search_posts`. |
|
|
467
|
+
| `invalid_input` | Les arguments ont été refusés avant toute requête. | Lisez le message, qui nomme l'argument. Un identifiant manquant est signalé ici. |
|
|
468
|
+
| `rate_limited` | Le site demande à ce client de ralentir. | Attendez les secondes indiquées et rappelez avec les mêmes arguments. La publication est toujours là. |
|
|
469
|
+
| `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-rule34/issues). |
|
|
470
|
+
| `network_error` | La requête n'a pas abouti. | Réessayez sous peu. |
|
|
471
|
+
| `timeout` | La requête a dépassé son délai. | Augmentez `RULE34_TIMEOUT_MS`, ou demandez moins de publications. |
|
|
472
|
+
|
|
473
|
+
## Comme bibliothèque
|
|
474
|
+
|
|
475
|
+
La couche qui lit le site est publiée seule, avec son rythme, son cache et ses
|
|
476
|
+
erreurs, sans protocole attaché.
|
|
397
477
|
|
|
398
|
-
|
|
478
|
+
```ts
|
|
479
|
+
import { Rule34Client } from "mcp-rule34/client";
|
|
399
480
|
|
|
400
|
-
|
|
401
|
-
|
|
481
|
+
const client = new Rule34Client({ credentials: { userId: "…", apiKey: "…" } });
|
|
482
|
+
const { data, cached } = await client.searchPosts({ tags: ["example"], limit: 5 });
|
|
483
|
+
console.log(data.total, cached);
|
|
484
|
+
```
|
|
402
485
|
|
|
403
|
-
|
|
486
|
+
Chaque lecture répond `{ data, cached }`, et lève une erreur portant un des six
|
|
487
|
+
codes. Le plancher d'une seconde entre deux requêtes tient également ici.
|
|
404
488
|
|
|
405
|
-
|
|
406
|
-
`invalid_input`, `rate_limited`, `parse_failure`, `network_error`, `timeout`.
|
|
489
|
+
## Rythme et attribution
|
|
407
490
|
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
requêtes qu'aucune configuration ne peut raccourcir, et il s'écarte davantage
|
|
412
|
-
quand le site le repousse.
|
|
491
|
+
Les requêtes partent une à une avec au moins une seconde entre elles, et ce
|
|
492
|
+
plancher tient quelle que soit la configuration. Le `User-Agent` se termine
|
|
493
|
+
toujours par l'identité du projet et une adresse où joindre une personne.
|
|
413
494
|
|
|
414
|
-
|
|
495
|
+
Les lectures passent par l'API que le site documente, et les identifiants qu'il
|
|
496
|
+
délivre sont ce que ses conditions demandent d'employer pour une lecture
|
|
497
|
+
automatisée. Chaque résultat porte l'adresse de la page de la publication. Rien
|
|
498
|
+
n'est téléchargé : une adresse de fichier traverse une réponse comme une chaîne
|
|
499
|
+
de caractères.
|
|
415
500
|
|
|
416
|
-
|
|
501
|
+
Ce MCP est un projet non officiel, sans affiliation à rule34.xxx.
|
|
417
502
|
|
|
418
|
-
|
|
419
|
-
import { Rule34Client } from "mcp-rule34/client";
|
|
420
|
-
```
|
|
503
|
+
## Confidentialité
|
|
421
504
|
|
|
422
|
-
|
|
505
|
+
Ce serveur ne collecte rien sur vous et n'envoie rien à son auteur. Il tourne sur
|
|
506
|
+
votre machine, ne joint que `api.rule34.xxx` et `rule34.xxx`, garde ses réponses
|
|
507
|
+
en mémoire le temps qu'il tourne, et n'écrit rien sur le disque. Vos identifiants
|
|
508
|
+
sont lus dans l'environnement et envoyés à ce seul site. [PRIVACY.md](PRIVACY.md)
|
|
509
|
+
dit ce qu'une requête emporte et quels réglages changent cela.
|
|
423
510
|
|
|
424
|
-
##
|
|
511
|
+
## Développement
|
|
425
512
|
|
|
426
513
|
```bash
|
|
427
514
|
npm install
|
|
428
|
-
npm
|
|
429
|
-
npm
|
|
430
|
-
npm run check
|
|
431
|
-
npm run build
|
|
515
|
+
npm run build:fixtures
|
|
516
|
+
npm test
|
|
517
|
+
npm run check
|
|
432
518
|
```
|
|
433
519
|
|
|
434
|
-
|
|
520
|
+
Les tests s'exécutent sur des fixtures engendrées et n'émettent aucune requête.
|
|
521
|
+
La suite en direct, `npm run test:live`, émet une requête par route et tourne
|
|
522
|
+
chaque nuit contre le site lui-même.
|
|
435
523
|
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
524
|
+
## Contribuer
|
|
525
|
+
|
|
526
|
+
Les anomalies, les questions et les idées ont leur place dans
|
|
527
|
+
[le suivi d'incidents](https://github.com/smeet666/mcp-rule34/issues). Les
|
|
528
|
+
propositions de modification sont bienvenues ; ouvrir un ticket d'abord aide à
|
|
529
|
+
s'accorder sur la forme du changement. Voir [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
439
530
|
|
|
440
531
|
## Licence
|
|
441
532
|
|
|
442
|
-
MIT.
|
|
533
|
+
MIT, voir [LICENSE](LICENSE). Les publications et les étiquettes appartiennent à
|
|
534
|
+
rule34.xxx et aux personnes qui les ont déposées.
|