mcp-rule34 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+## 2.0.0
+
+- **This server now needs node 24 or later.** Node 20 reached its end of
+  support on 2026-04-30 and node 22 is no longer what this code is built and
+  typed against. That is what makes this a major version: an install on an
+  older node is refused rather than left to fail somewhere later.
+- **A container image is published for each version**, on ghcr, for amd64 and
+  arm64. The readme carries the configuration that runs it.
+- The published package carries its changelog, and the entry point it declares
+  for the package root now publishes its types.
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+follows [semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-08-24
+
+### Added
+
+- Every error carries the error that led to it as its `cause`. A caller still
+  reads what this server could not do; a maintainer reading a stack finds the
+  parse or URL failure underneath.
+
+### Changed
+
+- The lint configuration matches the one the rest of the collection runs, which
+  is sixty-three rules wider. Reading two repositories the same way is worth
+  more than either set of rules.
+- Shutdown closes the server without discarding the promise, and leaves the
+  process on either path.
+
+## [1.0.0] - 2026-08-24
+
+### Added
+
+- `find_tags`: ask rule34.xxx which tag names begin with a piece of text, and
+  how many posts each one carries. The route needs no credentials, so a server
+  with none configured can still say how a tag is spelled.
+- A search that finds nothing because a required tag does not exist now offers
+  the names the site does hold that begin like it.
+- A page beyond the end of a search says how many pages the search fills and
+  that the page asked for lies past them, rather than serving an empty list with
+  nothing said.
+- A search whose results outrun the page ceiling says so, and names raising
+  `limit` as the way to reach the rest.
+
+### Changed
+
+- A search row leads with the tags the search asked for, so a post matching on a
+  name the site lists late still shows why it is there. Only names the post
+  carries are lifted.
+- `created_at` is described as the date rule34.xxx took the post in. The site
+  imported much of its older catalogue in bulk, so thousands of posts share one
+  day in November 2010, and reading that as a publication date states something
+  about the work that the data says about the upload.
+- The `sort` argument describes all four orders it accepts, `updated` and
+  `random` included.
+
+### Fixed
+
+- A link carrying `id` twice with different values is refused instead of
+  answering about the first of the two.
+- A link whose `id` is not a usable number says so, rather than reporting that
+  the link carries no id at all.
+- A tag written with spaces alone is refused for being empty, without quoting a
+  length it does not exceed.
+
+## [0.1.0] - 2026-08-23
+
+First release.
+
+### Added
+
+- `search_posts`: search rule34.xxx posts by one tag or by several at once, with
+  alternatives and exclusions as their own arguments, a media type, a rating, a
+  sort, and pagination. A row shows the first twelve tags of a post and states
+  how many it carries in all.
+- `get_post`: read one post named by its id or by a link to its page, with every
+  tag typed and counted, the uploader, the comment count and the publication
+  date. The post is read from both formats the API publishes, because neither
+  carries all of that on its own.
+- Credentials read from `RULE34_USER_ID` and `RULE34_API_KEY`. A server without
+  them starts, publishes its tools, and answers each call by naming what to set.
+- An empty search of several tags names the tags the site does not hold.
+- The reading layer published on its own under the `./client` subpath, with the
+  same pacing, cache and error taxonomy and no protocol attached.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 smeet666
+Copyright (c) 2026 Damien Bouissou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -42,6 +42,36 @@ claude mcp add rule34 --env RULE34_USER_ID=your-id --env RULE34_API_KEY=your-key
 }
 ```
 
+### With Docker
+
+```json
+{
+  "mcpServers": {
+    "rule34": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "RULE34_USER_ID",
+        "-e",
+        "RULE34_API_KEY",
+        "ghcr.io/smeet666/mcp-rule34:2.0.0"
+      ],
+      "env": {
+        "RULE34_USER_ID": "your-key",
+        "RULE34_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+`-i` keeps stdin open, which is where the protocol travels, and no `-t` is
+passed: a TTY rewrites the stream and breaks it. The container needs outbound
+HTTPS to `rule34.xxx` and `api.rule34.xxx`, and nothing else: no volume, no port, and the keys travel through the environment rather than inside the image.
+
 Put this in your **user** configuration rather than in a project file: a
 `.mcp.json` at the root of a repository travels with the repository, and the key
 travels with it.
@@ -262,6 +292,37 @@ claude mcp add rule34 --env RULE34_USER_ID=votre-id --env RULE34_API_KEY=votre-c
 }
 ```
 
+### Avec Docker
+
+```json
+{
+  "mcpServers": {
+    "rule34": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "RULE34_USER_ID",
+        "-e",
+        "RULE34_API_KEY",
+        "ghcr.io/smeet666/mcp-rule34:2.0.0"
+      ],
+      "env": {
+        "RULE34_USER_ID": "your-key",
+        "RULE34_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+`-i` garde l'entrée standard ouverte, qui est le canal du protocole, et aucun
+`-t` n'est passé : un terminal réécrit le flux et le casse. Le conteneur a besoin
+d'un accès HTTPS sortant vers `rule34.xxx` et `api.rule34.xxx`, et de rien d'autre :
+aucun volume, aucun port, et les clés voyagent par l'environnement plutôt que dans l'image.
+
 À placer dans votre configuration **utilisateur** plutôt que dans un fichier de
 projet : un `.mcp.json` à la racine d'un dépôt part avec le dépôt, et la clé
 part avec lui.

package/dist/index.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import process2 from "process";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/config.ts
+import process from "process";
+
 // src/version.ts
-var PKG_VERSION = "1.0.0";
+var PKG_VERSION = "2.0.0";
 var REPO_URL = "https://github.com/smeet666/mcp-rule34";
 
 // src/config.ts
@@ -125,8 +129,8 @@ import { z as z6 } from "zod";
 
 // src/errors.ts
 var Rule34Error = class extends Error {
-  constructor(code, text, details = {}) {
-    super(`[${code}] ${text}`);
+  constructor(code, text, details = {}, options) {
+    super(`[${code}] ${text}`, options);
     this.code = code;
     this.details = details;
     this.name = "Rule34Error";
@@ -135,8 +139,8 @@ var Rule34Error = class extends Error {
   details;
 };
 var ISSUES_URL = "https://github.com/smeet666/mcp-rule34/issues";
-function invalidInput(message, hint) {
-  return new Rule34Error("invalid_input", message, hint ? { hint } : {});
+function invalidInput(message, hint, cause) {
+  return new Rule34Error("invalid_input", message, hint ? { hint } : {}, { cause });
 }
 function missingCredentials(url) {
   return new Rule34Error(
@@ -167,11 +171,12 @@ function rateLimited(url, retryAfterMs) {
     }
   );
 }
-function parseFailure(url, what) {
+function parseFailure(url, what, cause) {
   return new Rule34Error(
     "parse_failure",
     `The request was answered, but not with the document this route publishes (${what}).`,
-    { url, hint: `Please report this, with the query you used, at ${ISSUES_URL}` }
+    { url, hint: `Please report this, with the query you used, at ${ISSUES_URL}` },
+    { cause }
   );
 }
 function upstreamFailure(url, message) {
@@ -400,10 +405,11 @@ function readPostPageUrl(raw) {
   let parsed;
   try {
     parsed = new URL(raw.trim());
-  } catch {
+  } catch (error) {
     throw invalidInput(
       `"${raw}" is not a URL.`,
-      "Pass a link to a post's page, such as https://rule34.xxx/index.php?page=post&s=view&id=2195419"
+      "Pass a link to a post's page, such as https://rule34.xxx/index.php?page=post&s=view&id=2195419",
+      error
     );
   }
   const host = parsed.hostname.toLowerCase();
@@ -588,6 +594,8 @@ function asTransportError(error, safeUrl) {
 }
 
 // src/rule34/parsers/postDetail.ts
+var AUTHENTICATION = /authenticat/i;
+var WHITESPACE = /\s+/;
 var TYPES = {
   tag: "general",
   artist: "artist",
@@ -603,11 +611,11 @@ function parsePostDetail(body, url, id) {
   let parsed;
   try {
     parsed = JSON.parse(body);
-  } catch {
-    throw parseFailure(safeUrl, "the response is not JSON");
+  } catch (error) {
+    throw parseFailure(safeUrl, "the response is not JSON", error);
   }
   if (typeof parsed === "string") {
-    if (/authenticat/i.test(parsed)) {
+    if (AUTHENTICATION.test(parsed)) {
       throw missingCredentials(safeUrl);
     }
     throw upstreamFailure(safeUrl, parsed);
@@ -626,7 +634,7 @@ function parsePostDetail(body, url, id) {
 }
 function readPost(raw, askedFor) {
   const id = readInteger(raw.id) ?? askedFor;
-  const tags = readString(raw.tags).split(/\s+/).filter((tag) => tag !== "");
+  const tags = readString(raw.tags).split(WHITESPACE).filter((tag) => tag !== "");
   return {
     id,
     postUrl: buildPostPageUrl(id),
@@ -699,8 +707,8 @@ function parseTagSuggestions(body, url) {
   let parsed;
   try {
     parsed = JSON.parse(body);
-  } catch {
-    throw parseFailure(safeUrl, "the response is not JSON");
+  } catch (error) {
+    throw parseFailure(safeUrl, "the response is not JSON", error);
   }
   if (!Array.isArray(parsed)) {
     throw parseFailure(safeUrl, "the response is not a list of suggestions");
@@ -726,6 +734,7 @@ function parseTagSuggestions(body, url) {
 
 // src/rule34/parsers/document.ts
 import { XMLParser } from "fast-xml-parser";
+var AUTHENTICATION2 = /authenticat/i;
 var parser = new XMLParser({
   ignoreAttributes: false,
   attributeNamePrefix: "@_",
@@ -751,7 +760,7 @@ function readDocument(xml, safeUrl) {
   const failure = parsed.error;
   if (failure !== void 0) {
     const message = typeof failure === "string" ? failure : String(failure);
-    if (/authenticat/i.test(message)) {
+    if (AUTHENTICATION2.test(message)) {
       throw missingCredentials(safeUrl);
     }
     throw upstreamFailure(safeUrl, message);
@@ -778,6 +787,7 @@ function readInteger2(value) {
 }
 
 // src/rule34/parsers/posts.ts
+var WHITESPACE2 = /\s+/;
 var RATINGS = {
   e: "explicit",
   q: "questionable",
@@ -817,7 +827,7 @@ function readPost2(attributes) {
     // An unknown letter is carried as it came: naming it would state a rating
     // the site never wrote.
     rating: RATINGS[rating] ?? rating,
-    tags: (attributes["@_tags"] ?? "").split(/\s+/).filter((tag) => tag !== ""),
+    tags: (attributes["@_tags"] ?? "").split(WHITESPACE2).filter((tag) => tag !== ""),
     source: readText2(attributes["@_source"]),
     // The attribute is present and empty on a post with no parent, and 0 is a
     // post id that belongs to somebody else.
@@ -989,7 +999,7 @@ var Rule34Client = class {
       config: this.deps.config,
       limiter: this.limiter,
       logger: this.deps.logger,
-      fetchImpl: this.deps.fetchImpl
+      ...this.deps.fetchImpl ? { fetchImpl: this.deps.fetchImpl } : {}
     });
     this.cache.set(key, body);
     return { body, cached: false };
@@ -1390,10 +1400,10 @@ var searchPostsOutputShape = {
 function toSearch(args) {
   return {
     tags: args.tags,
-    anyOf: args.any_of,
-    exclude: args.exclude,
+    ...args.any_of ? { anyOf: args.any_of } : {},
+    ...args.exclude ? { exclude: args.exclude } : {},
     mediaType: args.media_type,
-    rating: args.rating,
+    ...args.rating ? { rating: args.rating } : {},
     sort: args.sort,
     limit: args.limit,
     page: args.page
@@ -1587,16 +1597,16 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   const shutdown = () => {
-    void server.close().finally(() => process.exit(0));
+    server.close().catch(() => void 0).finally(() => process2.exit(0));
   };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
+  process2.on("SIGINT", shutdown);
+  process2.on("SIGTERM", shutdown);
 }
 main().catch((error) => {
-  process.stderr.write(
+  process2.stderr.write(
     `[mcp-rule34] fatal: ${error instanceof Error ? error.stack ?? error.message : String(error)}
 `
   );
-  process.exit(1);
+  process2.exit(1);
 });
 //# sourceMappingURL=index.js.map