mcp-rule34 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 +156 -0
- package/README.md +337 -306
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +5 -1
- 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,6 +45,9 @@ claude mcp add rule34 --env RULE34_USER_ID=your-id --env RULE34_API_KEY=your-key
|
|
|
42
45
|
}
|
|
43
46
|
```
|
|
44
47
|
|
|
48
|
+
Node 24 or later is required. The two credentials are required; everything else
|
|
49
|
+
under [Configuration](#configuration) is optional.
|
|
50
|
+
|
|
45
51
|
### With Docker
|
|
46
52
|
|
|
47
53
|
```json
|
|
@@ -57,225 +63,238 @@ claude mcp add rule34 --env RULE34_USER_ID=your-id --env RULE34_API_KEY=your-key
|
|
|
57
63
|
"RULE34_USER_ID",
|
|
58
64
|
"-e",
|
|
59
65
|
"RULE34_API_KEY",
|
|
60
|
-
"ghcr.io/smeet666/mcp-rule34:2.0.
|
|
61
|
-
]
|
|
62
|
-
"env": {
|
|
63
|
-
"RULE34_USER_ID": "your-key",
|
|
64
|
-
"RULE34_API_KEY": "your-key"
|
|
65
|
-
}
|
|
66
|
+
"ghcr.io/smeet666/mcp-rule34:2.0.1"
|
|
67
|
+
]
|
|
66
68
|
}
|
|
67
69
|
}
|
|
68
70
|
}
|
|
69
71
|
```
|
|
70
72
|
|
|
71
|
-
`-i` keeps stdin open, which is where the protocol travels, and
|
|
72
|
-
|
|
73
|
-
|
|
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.
|
|
74
77
|
|
|
75
|
-
|
|
76
|
-
`.mcp.json` at the root of a repository travels with the repository, and the key
|
|
77
|
-
travels with it.
|
|
78
|
+
### Bundle, without npm
|
|
78
79
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
| `RULE34_USER_ID` | Your numeric account id. Required. | — |
|
|
84
|
-
| `RULE34_API_KEY` | Your API key. Required, and personal. | — |
|
|
85
|
-
| `RULE34_MIN_INTERVAL_MS` | Milliseconds between two requests. | `1000`, and never lower |
|
|
86
|
-
| `RULE34_TIMEOUT_MS` | How long one request may take. | `20000` |
|
|
87
|
-
| `RULE34_MAX_RETRIES` | Attempts after the first, for transient failures. | `3` |
|
|
88
|
-
| `RULE34_CACHE_TTL_MS` | How long an answer stays in memory. | `300000` |
|
|
89
|
-
| `RULE34_CACHE_MAX_ENTRIES` | How many answers stay in memory. | `300` |
|
|
90
|
-
| `RULE34_USER_AGENT` | Overrides the agent this client sends. | `mcp-rule34/<version> (+…)` |
|
|
91
|
-
| `RULE34_LOG_LEVEL` | `silent`, `error`, `info` or `debug`, on stderr. | `error` |
|
|
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.
|
|
92
84
|
|
|
93
|
-
|
|
94
|
-
[Account options](https://rule34.xxx/index.php?page=account&s=options), and find
|
|
95
|
-
the row named _API Access Credentials_. It shows `&api_key=…&user_id=…`; those
|
|
96
|
-
two values are what goes in the configuration above. If the key is empty, tick
|
|
97
|
-
_Generate New Key?_ and save.
|
|
85
|
+
## What you can ask
|
|
98
86
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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?"
|
|
102
92
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
it knows the site will refuse.
|
|
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.
|
|
106
95
|
|
|
107
96
|
## Tools
|
|
108
97
|
|
|
109
|
-
| Tool | What it does |
|
|
110
|
-
| -------------- | ------------------------------------------------------------- |
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
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. |
|
|
114
103
|
|
|
115
|
-
|
|
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.
|
|
116
107
|
|
|
117
|
-
`find_tags`
|
|
118
|
-
posts each one carries. It matches from the start of a name, so `kimagure` finds
|
|
119
|
-
`kimagure_orange_road` while a word sitting in the middle of a name finds
|
|
120
|
-
nothing. The site offers at most ten names and the answer says so, since ten
|
|
121
|
-
back means the list was cut rather than exhausted.
|
|
108
|
+
### `find_tags`
|
|
122
109
|
|
|
123
|
-
|
|
124
|
-
does not exist, the answer names it and offers the names the site does hold that
|
|
125
|
-
begin like it.
|
|
110
|
+
Finds how the site spells a tag.
|
|
126
111
|
|
|
127
|
-
|
|
112
|
+
| Argument | Type | Required | What it does |
|
|
113
|
+
| -------- | --------------------------- | -------- | -------------------- |
|
|
114
|
+
| `query` | string, up to 60 characters | yes | The text to look up. |
|
|
128
115
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
four fifths of its answer on tag strings nobody reads, so a search row shows the
|
|
132
|
-
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.
|
|
133
118
|
|
|
134
|
-
`
|
|
135
|
-
tag with its kind, character, copyright, artist, general or metadata, and how
|
|
136
|
-
many posts share it, alongside the uploader, the number of comments and the
|
|
137
|
-
date the site took it in. A link is read rather than followed: this server builds its
|
|
138
|
-
own request from the id it finds in it.
|
|
119
|
+
### `search_posts`
|
|
139
120
|
|
|
140
|
-
|
|
141
|
-
carries everything: the date the site took the post in comes from one, and the
|
|
142
|
-
uploader's name, the comment count and the tag kinds from the other.
|
|
121
|
+
Searches the posts by tags.
|
|
143
122
|
|
|
144
|
-
|
|
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. |
|
|
145
133
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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.
|
|
150
138
|
|
|
151
|
-
|
|
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.
|
|
152
145
|
|
|
153
|
-
|
|
154
|
-
{
|
|
155
|
-
"tags": ["asuka langley sohryu", "black hair"], // every one of these
|
|
156
|
-
"any_of": ["blonde hair", "red hair"], // at least one of these
|
|
157
|
-
"exclude": ["monochrome", "3d"], // none of these
|
|
158
|
-
}
|
|
159
|
-
```
|
|
146
|
+
### `get_post`
|
|
160
147
|
|
|
161
|
-
|
|
162
|
-
can state the rating and the sort it actually used.
|
|
148
|
+
Reads one post's record.
|
|
163
149
|
|
|
164
|
-
|
|
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. |
|
|
165
154
|
|
|
166
|
-
|
|
167
|
-
distinction in its own tags, so the site does the filtering and the total it
|
|
168
|
-
returns counts what was asked for. The classification is therefore as good as
|
|
169
|
-
the site's tagging.
|
|
155
|
+
**In return:** the post a search row carries, with its full tag list.
|
|
170
156
|
|
|
171
|
-
|
|
172
|
-
nothing to say a post is in colour. Ask for colour with
|
|
173
|
-
`"exclude": ["monochrome", "greyscale", "grayscale"]`.
|
|
157
|
+
## Configuration
|
|
174
158
|
|
|
175
|
-
|
|
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. |
|
|
176
173
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
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.
|
|
181
179
|
|
|
182
|
-
|
|
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.
|
|
183
185
|
|
|
184
|
-
A
|
|
185
|
-
|
|
186
|
-
this server asks the site which of the names it holds, and the answer says which
|
|
187
|
-
one it does not:
|
|
186
|
+
A value outside its range falls back to the default, and the reason is written to
|
|
187
|
+
stderr.
|
|
188
188
|
|
|
189
|
-
|
|
190
|
-
No post on rule34.xxx matches neon_genesis_evangelion asuka_langley_sohry.
|
|
189
|
+
## Errors
|
|
191
190
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
```
|
|
191
|
+
Every failure carries one of six codes, a message, and where it helps a hint
|
|
192
|
+
naming the next move.
|
|
195
193
|
|
|
196
|
-
|
|
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. |
|
|
197
202
|
|
|
198
|
-
|
|
199
|
-
that was served, and the search as it was sent in the site's own language. A
|
|
200
|
-
post carries its rule34.xxx page, its file, its thumbnail, its dimensions, its
|
|
201
|
-
score, its rating, its tags, whatever the uploader credited as a source, and the
|
|
202
|
-
date rule34.xxx took it in.
|
|
203
|
+
## As a library
|
|
203
204
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
changed, which retagging moves. rule34.xxx imported much of its older catalogue
|
|
207
|
-
in bulk, so thousands of posts share one day in November 2010: a question about
|
|
208
|
-
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.
|
|
209
207
|
|
|
210
|
-
|
|
208
|
+
```ts
|
|
209
|
+
import { Rule34Client } from "mcp-rule34/client";
|
|
211
210
|
|
|
212
|
-
|
|
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
|
+
```
|
|
213
215
|
|
|
214
|
-
|
|
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.
|
|
215
218
|
|
|
216
|
-
|
|
217
|
-
`not_found`, `invalid_input`, `rate_limited`, `parse_failure`, `network_error`,
|
|
218
|
-
`timeout`.
|
|
219
|
+
## Pacing and attribution
|
|
219
220
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
two requests that no configuration can shorten, and it backs further off when the
|
|
224
|
-
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.
|
|
225
224
|
|
|
226
|
-
|
|
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.
|
|
227
229
|
|
|
228
|
-
|
|
230
|
+
This MCP server is an unofficial project, with no affiliation to rule34.xxx.
|
|
229
231
|
|
|
230
|
-
|
|
231
|
-
import { Rule34Client } from "mcp-rule34/client";
|
|
232
|
-
```
|
|
232
|
+
## Privacy
|
|
233
233
|
|
|
234
|
-
|
|
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.
|
|
235
240
|
|
|
236
241
|
## Development
|
|
237
242
|
|
|
238
243
|
```bash
|
|
239
244
|
npm install
|
|
240
|
-
npm
|
|
241
|
-
npm
|
|
242
|
-
npm run check
|
|
243
|
-
npm run build
|
|
245
|
+
npm run build:fixtures
|
|
246
|
+
npm test
|
|
247
|
+
npm run check
|
|
244
248
|
```
|
|
245
249
|
|
|
246
|
-
|
|
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.
|
|
247
253
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
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).
|
|
251
260
|
|
|
252
261
|
## License
|
|
253
262
|
|
|
254
|
-
MIT.
|
|
263
|
+
MIT, see [LICENSE](LICENSE). The posts and the tags belong to rule34.xxx and to
|
|
264
|
+
the people who uploaded them.
|
|
255
265
|
|
|
256
266
|
---
|
|
257
267
|
|
|
268
|
+
<a name="mcp-rule34-français"></a>
|
|
269
|
+
|
|
258
270
|
# mcp-rule34 (français)
|
|
259
271
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
272
|
+
_[English version](#mcp-rule34)_
|
|
273
|
+
|
|
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é.
|
|
265
281
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
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.
|
|
269
288
|
|
|
270
|
-
##
|
|
289
|
+
## Installation
|
|
271
290
|
|
|
272
291
|
**Claude Code**
|
|
273
292
|
|
|
274
293
|
```bash
|
|
275
|
-
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
|
|
276
295
|
```
|
|
277
296
|
|
|
278
|
-
**Claude Desktop, Cursor, et tout client au format standard**
|
|
297
|
+
**Claude Desktop, Cursor, et tout client au format de configuration standard**
|
|
279
298
|
|
|
280
299
|
```json
|
|
281
300
|
{
|
|
@@ -285,13 +304,16 @@ claude mcp add rule34 --env RULE34_USER_ID=votre-id --env RULE34_API_KEY=votre-c
|
|
|
285
304
|
"args": ["-y", "mcp-rule34"],
|
|
286
305
|
"env": {
|
|
287
306
|
"RULE34_USER_ID": "votre-id",
|
|
288
|
-
"RULE34_API_KEY": "votre-
|
|
307
|
+
"RULE34_API_KEY": "votre-cle"
|
|
289
308
|
}
|
|
290
309
|
}
|
|
291
310
|
}
|
|
292
311
|
}
|
|
293
312
|
```
|
|
294
313
|
|
|
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.
|
|
316
|
+
|
|
295
317
|
### Avec Docker
|
|
296
318
|
|
|
297
319
|
```json
|
|
@@ -307,197 +329,206 @@ claude mcp add rule34 --env RULE34_USER_ID=votre-id --env RULE34_API_KEY=votre-c
|
|
|
307
329
|
"RULE34_USER_ID",
|
|
308
330
|
"-e",
|
|
309
331
|
"RULE34_API_KEY",
|
|
310
|
-
"ghcr.io/smeet666/mcp-rule34:2.0.
|
|
311
|
-
]
|
|
312
|
-
"env": {
|
|
313
|
-
"RULE34_USER_ID": "your-key",
|
|
314
|
-
"RULE34_API_KEY": "your-key"
|
|
315
|
-
}
|
|
332
|
+
"ghcr.io/smeet666/mcp-rule34:2.0.1"
|
|
333
|
+
]
|
|
316
334
|
}
|
|
317
335
|
}
|
|
318
336
|
}
|
|
319
337
|
```
|
|
320
338
|
|
|
321
|
-
`-i` garde l'entrée standard ouverte, qui est le canal du protocole, et
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
aucun volume, aucun port
|
|
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.
|
|
325
343
|
|
|
326
|
-
|
|
327
|
-
projet : un `.mcp.json` à la racine d'un dépôt part avec le dépôt, et la clé
|
|
328
|
-
part avec lui.
|
|
344
|
+
### Bundle, sans npm
|
|
329
345
|
|
|
330
|
-
|
|
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.
|
|
331
350
|
|
|
332
|
-
|
|
333
|
-
| -------------------------- | -------------------------------------------------- | --------------------------- |
|
|
334
|
-
| `RULE34_USER_ID` | L'identifiant numérique du compte. Obligatoire. | — |
|
|
335
|
-
| `RULE34_API_KEY` | La clé d'API. Obligatoire, et personnelle. | — |
|
|
336
|
-
| `RULE34_MIN_INTERVAL_MS` | Millisecondes entre deux requêtes. | `1000`, jamais moins |
|
|
337
|
-
| `RULE34_TIMEOUT_MS` | Durée maximale d'une requête. | `20000` |
|
|
338
|
-
| `RULE34_MAX_RETRIES` | Tentatives après la première, sur panne passagère. | `3` |
|
|
339
|
-
| `RULE34_CACHE_TTL_MS` | Durée de vie d'une réponse en mémoire. | `300000` |
|
|
340
|
-
| `RULE34_CACHE_MAX_ENTRIES` | Nombre de réponses gardées en mémoire. | `300` |
|
|
341
|
-
| `RULE34_USER_AGENT` | Remplace l'agent que ce client envoie. | `mcp-rule34/<version> (+…)` |
|
|
342
|
-
| `RULE34_LOG_LEVEL` | `silent`, `error`, `info` ou `debug`, sur stderr. | `error` |
|
|
343
|
-
|
|
344
|
-
**Où trouver les identifiants.** Connectez-vous, ouvrez
|
|
345
|
-
[les options du compte](https://rule34.xxx/index.php?page=account&s=options), et
|
|
346
|
-
cherchez la ligne _API Access Credentials_. Elle affiche `&api_key=…&user_id=…` :
|
|
347
|
-
ces deux valeurs vont dans la configuration ci-dessus. Si la clé est vide, cochez
|
|
348
|
-
_Generate New Key?_ puis enregistrez.
|
|
349
|
-
|
|
350
|
-
Le site délivre **une clé par personne** et demande qu'une application servant
|
|
351
|
-
son contenu n'affiche aucune publicité et ne le mette derrière aucun péage. Ce
|
|
352
|
-
serveur n'embarque aucune clé, et chacun apporte la sienne.
|
|
353
|
-
|
|
354
|
-
Un serveur démarré sans identifiants démarre quand même, publie son outil, et
|
|
355
|
-
répond à chaque appel en nommant les deux variables à régler. Il n'émet jamais
|
|
356
|
-
une requête dont il sait que le site la refusera.
|
|
351
|
+
## Ce qu'on peut demander
|
|
357
352
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
| `get_post` | Lit un post en entier, avec le type de chacun de ses tags. | `id`, `url` |
|
|
364
|
-
| `find_tags` | Trouve comment le site écrit un tag, et combien de posts le portent. | `query` |
|
|
365
|
-
|
|
366
|
-
### Trouver comment un tag s'écrit
|
|
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 ? »
|
|
367
358
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
rien. Le site propose au plus dix noms et la réponse le dit, puisque dix en
|
|
372
|
-
retour signifie une liste coupée plutôt qu'épuisée.
|
|
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.
|
|
373
362
|
|
|
374
|
-
|
|
375
|
-
n'existe pas, la réponse le nomme et propose les noms que le site détient et qui
|
|
376
|
-
commencent comme lui.
|
|
377
|
-
|
|
378
|
-
### La recherche nomme les posts, la fiche les lit en entier
|
|
379
|
-
|
|
380
|
-
Un post de rule34.xxx porte une médiane d'environ deux cents tags, et certains
|
|
381
|
-
en portent neuf cents. Une page de vingt résultats avec tous les tags écrits
|
|
382
|
-
dépenserait quatre cinquièmes de sa réponse en chaînes que personne ne lit, donc
|
|
383
|
-
une ligne de recherche montre les douze premiers et dit combien le post en porte
|
|
384
|
-
au total.
|
|
363
|
+
## Les outils
|
|
385
364
|
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
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. |
|
|
391
370
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
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.
|
|
396
374
|
|
|
397
|
-
###
|
|
375
|
+
### `find_tags`
|
|
398
376
|
|
|
399
|
-
|
|
400
|
-
personne dit en plusieurs. `asuka langley sohryu` et `asuka_langley_sohryu` sont
|
|
401
|
-
le même tag, et ce serveur écrit le second à partir du premier. La ponctuation
|
|
402
|
-
d'un nom lui appartient : le tag de la série est `ranma_1/2`, barre oblique
|
|
403
|
-
comprise.
|
|
377
|
+
Trouve l'orthographe d'une étiquette.
|
|
404
378
|
|
|
405
|
-
|
|
379
|
+
| Argument | Type | Requis | Ce qu'il fait |
|
|
380
|
+
| -------- | ----------------------------- | ------ | -------------------- |
|
|
381
|
+
| `query` | chaîne, jusqu'à 60 caractères | oui | Le texte à vérifier. |
|
|
406
382
|
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
"tags": ["asuka langley sohryu", "black hair"], // tous ceux-là
|
|
410
|
-
"any_of": ["blonde hair", "red hair"], // au moins un de ceux-là
|
|
411
|
-
"exclude": ["monochrome", "3d"], // aucun de ceux-là
|
|
412
|
-
}
|
|
413
|
-
```
|
|
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.
|
|
414
385
|
|
|
415
|
-
|
|
416
|
-
permet à une réponse d'énoncer la classification et le tri qu'elle a réellement
|
|
417
|
-
appliqués.
|
|
386
|
+
### `search_posts`
|
|
418
387
|
|
|
419
|
-
|
|
388
|
+
Cherche les publications par étiquettes.
|
|
420
389
|
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
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. |
|
|
425
400
|
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
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.
|
|
429
405
|
|
|
430
|
-
|
|
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.
|
|
431
413
|
|
|
432
|
-
|
|
433
|
-
`safe`, `general` ou `sensitive` à rule34.xxx rend zéro post et aucune erreur, ce
|
|
434
|
-
qui se lit comme une absence plutôt que comme une classification que le site n'a
|
|
435
|
-
jamais eue, donc ce serveur refuse ces trois-là au lieu de les transmettre.
|
|
414
|
+
### `get_post`
|
|
436
415
|
|
|
437
|
-
|
|
416
|
+
Lit la fiche d'une publication.
|
|
438
417
|
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
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. |
|
|
443
422
|
|
|
444
|
-
|
|
423
|
+
**En retour :** la publication que porte une ligne de recherche, avec sa liste
|
|
424
|
+
complète d'étiquettes.
|
|
445
425
|
|
|
446
|
-
|
|
447
|
-
page servie, et la requête telle qu'elle a été envoyée dans le langage du site.
|
|
448
|
-
Un post porte sa page rule34.xxx, son fichier, sa vignette, ses dimensions, son
|
|
449
|
-
score, sa classification, ses tags, la source créditée par le déposant quand il
|
|
450
|
-
en a crédité une, et la date à laquelle rule34.xxx l'a pris.
|
|
426
|
+
## Configuration
|
|
451
427
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
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é.
|
|
458
477
|
|
|
459
|
-
|
|
478
|
+
```ts
|
|
479
|
+
import { Rule34Client } from "mcp-rule34/client";
|
|
460
480
|
|
|
461
|
-
|
|
462
|
-
|
|
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
|
+
```
|
|
463
485
|
|
|
464
|
-
|
|
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.
|
|
465
488
|
|
|
466
|
-
|
|
467
|
-
`invalid_input`, `rate_limited`, `parse_failure`, `network_error`, `timeout`.
|
|
489
|
+
## Rythme et attribution
|
|
468
490
|
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
requêtes qu'aucune configuration ne peut raccourcir, et il s'écarte davantage
|
|
473
|
-
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.
|
|
474
494
|
|
|
475
|
-
|
|
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.
|
|
476
500
|
|
|
477
|
-
|
|
501
|
+
Ce MCP est un projet non officiel, sans affiliation à rule34.xxx.
|
|
478
502
|
|
|
479
|
-
|
|
480
|
-
import { Rule34Client } from "mcp-rule34/client";
|
|
481
|
-
```
|
|
503
|
+
## Confidentialité
|
|
482
504
|
|
|
483
|
-
|
|
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.
|
|
484
510
|
|
|
485
|
-
##
|
|
511
|
+
## Développement
|
|
486
512
|
|
|
487
513
|
```bash
|
|
488
514
|
npm install
|
|
489
|
-
npm
|
|
490
|
-
npm
|
|
491
|
-
npm run check
|
|
492
|
-
npm run build
|
|
515
|
+
npm run build:fixtures
|
|
516
|
+
npm test
|
|
517
|
+
npm run check
|
|
493
518
|
```
|
|
494
519
|
|
|
495
|
-
|
|
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.
|
|
496
523
|
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
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).
|
|
500
530
|
|
|
501
531
|
## Licence
|
|
502
532
|
|
|
503
|
-
MIT.
|
|
533
|
+
MIT, voir [LICENSE](LICENSE). Les publications et les étiquettes appartiennent à
|
|
534
|
+
rule34.xxx et aux personnes qui les ont déposées.
|