mcp-rule34 0.1.0 → 1.0.0

package/README.md

@@ -76,10 +76,23 @@ it knows the site will refuse.
 
 ## Tools
 
-| Tool           | What it does                                     | Key parameters                                                               |
-| -------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
-| `search_posts` | Finds posts carrying a tag, or several at once.  | `tags`, `any_of`, `exclude`, `media_type`, `rating`, `sort`, `limit`, `page` |
-| `get_post`     | Reads one post whole, with a kind for every tag. | `id`, `url`                                                                  |
+| Tool           | What it does                                                  | Key parameters                                                               |
+| -------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `search_posts` | Finds posts carrying a tag, or several at once.               | `tags`, `any_of`, `exclude`, `media_type`, `rating`, `sort`, `limit`, `page` |
+| `get_post`     | Reads one post whole, with a kind for every tag.              | `id`, `url`                                                                  |
+| `find_tags`    | Finds how the site spells a tag, and how many posts carry it. | `query`                                                                      |
+
+### Finding how a tag is spelled
+
+`find_tags` asks rule34.xxx which names begin with a piece of text, and how many
+posts each one carries. It matches from the start of a name, so `kimagure` finds
+`kimagure_orange_road` while a word sitting in the middle of a name finds
+nothing. The site offers at most ten names and the answer says so, since ten
+back means the list was cut rather than exhausted.
+
+This is also what a search that found nothing falls back on: when a required tag
+does not exist, the answer names it and offers the names the site does hold that
+begin like it.
 
 ### A search names posts, a post is then read whole
 
@@ -91,12 +104,12 @@ first twelve and states how many the post carries in all.
 `get_post` reads one post by its id, or by a link to its page, and returns every
 tag with its kind, character, copyright, artist, general or metadata, and how
 many posts share it, alongside the uploader, the number of comments and the
-publication date. A link is read rather than followed: this server builds its
+date the site took it in. A link is read rather than followed: this server builds its
 own request from the id it finds in it.
 
 Reading one post costs two requests, because neither format the API publishes
-carries everything: the publication date comes from one, and the uploader's
-name, the comment count and the tag kinds from the other.
+carries everything: the date the site took the post in comes from one, and the
+uploader's name, the comment count and the tag kinds from the other.
 
 ### Tags are single tokens
 
@@ -156,11 +169,13 @@ Every answer carries the total the site counted for the whole search, the page
 that was served, and the search as it was sent in the site's own language. A
 post carries its rule34.xxx page, its file, its thumbnail, its dimensions, its
 score, its rating, its tags, whatever the uploader credited as a source, and the
-date it was published.
+date rule34.xxx took it in.
 
-Two dates exist on a post and only one of them is publication: a post first
-uploaded in 2016 and retagged last spring carries both, and this server reports
-the first.
+A post carries two dates, and neither one is when its subject was made. The
+first is the day the site took the post in, the second the day the post last
+changed, which retagging moves. rule34.xxx imported much of its older catalogue
+in bulk, so thousands of posts share one day in November 2010: a question about
+what came first is answered by the import, not by the work.
 
 ## What this server does not do
 
@@ -281,10 +296,23 @@ une requête dont il sait que le site la refusera.
 
 ## Les outils
 
-| Outil          | Ce qu'il fait                                              | Paramètres principaux                                                        |
-| -------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `search_posts` | Trouve les posts portant un tag, ou plusieurs.             | `tags`, `any_of`, `exclude`, `media_type`, `rating`, `sort`, `limit`, `page` |
-| `get_post`     | Lit un post en entier, avec le type de chacun de ses tags. | `id`, `url`                                                                  |
+| Outil          | Ce qu'il fait                                                        | Paramètres principaux                                                        |
+| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `search_posts` | Trouve les posts portant un tag, ou plusieurs.                       | `tags`, `any_of`, `exclude`, `media_type`, `rating`, `sort`, `limit`, `page` |
+| `get_post`     | Lit un post en entier, avec le type de chacun de ses tags.           | `id`, `url`                                                                  |
+| `find_tags`    | Trouve comment le site écrit un tag, et combien de posts le portent. | `query`                                                                      |
+
+### Trouver comment un tag s'écrit
+
+`find_tags` demande à rule34.xxx quels noms commencent par un texte, et combien
+de posts chacun porte. La correspondance part du début d'un nom, donc `kimagure`
+trouve `kimagure_orange_road` là où un mot situé au milieu d'un nom ne trouve
+rien. Le site propose au plus dix noms et la réponse le dit, puisque dix en
+retour signifie une liste coupée plutôt qu'épuisée.
+
+C'est aussi le repli d'une recherche qui n'a rien trouvé : quand un tag requis
+n'existe pas, la réponse le nomme et propose les noms que le site détient et qui
+commencent comme lui.
 
 ### La recherche nomme les posts, la fiche les lit en entier
 
@@ -297,12 +325,13 @@ au total.
 `get_post` lit un post par son identifiant, ou par un lien vers sa page, et rend
 chaque tag avec son type, personnage, copyright, artiste, général ou métadonnée,
 et le nombre de posts qui le partagent, avec le déposant, le nombre de
-commentaires et la date de publication. Un lien est lu et non suivi : ce serveur
+commentaires et la date à laquelle le site l'a pris. Un lien est lu et non suivi : ce serveur
 construit sa propre requête à partir de l'identifiant qu'il y trouve.
 
 Lire une fiche coûte deux requêtes, parce qu'aucun des deux formats publiés par
-l'API ne porte tout : la date de publication vient de l'un, et le nom du
-déposant, le nombre de commentaires et les types de tags viennent de l'autre.
+l'API ne porte tout : la date à laquelle le site a pris le post vient de l'un,
+et le nom du déposant, le nombre de commentaires et les types de tags viennent
+de l'autre.
 
 ### Un tag est un seul mot
 
@@ -357,11 +386,14 @@ Chaque réponse porte le total compté par le site pour la recherche entière, l
 page servie, et la requête telle qu'elle a été envoyée dans le langage du site.
 Un post porte sa page rule34.xxx, son fichier, sa vignette, ses dimensions, son
 score, sa classification, ses tags, la source créditée par le déposant quand il
-en a crédité une, et sa date de publication.
-
-Un post porte deux dates et une seule est la publication : une image déposée en
-2016 et retaguée au printemps dernier porte les deux, et ce serveur rend la
-première.
+en a crédité une, et la date à laquelle rule34.xxx l'a pris.
+
+Un post porte deux dates, et aucune n'est celle où son sujet a été fait. La
+première est le jour où le site a pris le post, la seconde le jour où il a
+changé pour la dernière fois, que le retaguage déplace. rule34.xxx a importé en
+masse une grande partie de son fonds ancien, donc des milliers de posts portent
+un même jour de novembre 2010 : une question sur ce qui vient en premier est
+répondue par l'import, jamais par l'œuvre.
 
 ## Ce que ce serveur ne fait pas
 

package/dist/index.js

@@ -4,7 +4,7 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/version.ts
-var PKG_VERSION = "0.1.0";
+var PKG_VERSION = "1.0.0";
 var REPO_URL = "https://github.com/smeet666/mcp-rule34";
 
 // src/config.ts
@@ -121,7 +121,7 @@ function createLogger(level) {
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 
 // src/errors.ts
 var Rule34Error = class extends Error {
@@ -295,6 +295,7 @@ function sleep(ms) {
 
 // src/rule34/urls.ts
 var API_URL = "https://api.rule34.xxx/index.php";
+var SUGGEST_URL = "https://api.rule34.xxx/autocomplete.php";
 var SITE_URL = "https://rule34.xxx/index.php";
 var MAX_LIMIT = 1e3;
 var MEDIA_TOKENS = {
@@ -418,10 +419,24 @@ function readPostPageUrl(raw) {
       "A post's page looks like https://rule34.xxx/index.php?page=post&s=view&id=2195419"
     );
   }
-  const id = Number(parsed.searchParams.get("id"));
-  if (!Number.isInteger(id) || id < 1) {
+  const named = [...new Set(parsed.searchParams.getAll("id"))];
+  if (named.length > 1) {
+    throw invalidInput(
+      `"${raw}" names ${named.length} different posts: ${named.join(", ")}.`,
+      "Pass a link to one post."
+    );
+  }
+  const written = named[0] ?? "";
+  if (written === "") {
     throw invalidInput(`"${raw}" carries no post id.`);
   }
+  const id = Number(written);
+  if (!Number.isInteger(id) || id < 1) {
+    throw invalidInput(
+      `"${raw}" carries '${written}', which is not a post id.`,
+      "A post id is a whole number from 1 upwards."
+    );
+  }
   return id;
 }
 function resolvePostRef(ref) {
@@ -456,6 +471,9 @@ function buildPostByIdJsonUrl(id, credentials) {
 function credentialsQuery(credentials) {
   return `&api_key=${encodeURIComponent(credentials.apiKey)}&user_id=${encodeURIComponent(credentials.userId)}`;
 }
+function buildTagSuggestUrl(text) {
+  return `${SUGGEST_URL}?q=${encodeURIComponent(normalizeTag(text))}`;
+}
 function buildPostPageUrl(id) {
   return `${SITE_URL}?page=post&s=view&id=${id}`;
 }
@@ -671,6 +689,41 @@ function readInteger(value) {
   return Number.isFinite(parsed) ? parsed : null;
 }
 
+// src/rule34/parsers/suggestions.ts
+var COUNT_IN_LABEL = /\((\d+)\)\s*$/;
+function parseTagSuggestions(body, url) {
+  const safeUrl = redactCredentials(url);
+  if (body.trim() === "") {
+    throw parseFailure(safeUrl, "the response was empty");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw parseFailure(safeUrl, "the response is not JSON");
+  }
+  if (!Array.isArray(parsed)) {
+    throw parseFailure(safeUrl, "the response is not a list of suggestions");
+  }
+  const suggestions = [];
+  for (const entry of parsed) {
+    const raw = entry ?? {};
+    const name = typeof raw.value === "string" ? raw.value.trim() : "";
+    if (name === "") {
+      continue;
+    }
+    const label = typeof raw.label === "string" ? raw.label : "";
+    const counted = COUNT_IN_LABEL.exec(label);
+    suggestions.push({
+      name,
+      // Zero is a number of posts. A label the site printed no count into
+      // leaves the count unknown.
+      postCount: counted?.[1] === void 0 ? null : Number(counted[1])
+    });
+  }
+  return suggestions;
+}
+
 // src/rule34/parsers/document.ts
 import { XMLParser } from "fast-xml-parser";
 var parser = new XMLParser({
@@ -870,6 +923,18 @@ var Rule34Client = class {
       cached: json.cached && xml.cached
     };
   }
+  /**
+   * The names rule34.xxx offers for a piece of text.
+   *
+   * This route needs no credentials, so none are required to call it: a server
+   * with no key configured can still tell a caller how a tag is spelled, which
+   * is the one useful thing it can do.
+   */
+  async findTags(text) {
+    const url = buildTagSuggestUrl(text);
+    const { body, cached } = await this.read(url);
+    return { data: parseTagSuggestions(body, url), cached };
+  }
   /** The tag under this exact name, or nothing when the site holds no such tag. */
   async lookupTag(name) {
     const url = buildTagLookupUrl(name, this.credentials());
@@ -931,7 +996,7 @@ var Rule34Client = class {
   }
 };
 
-// src/tools/getPost.ts
+// src/tools/findTags.ts
 import { z as z3 } from "zod";
 
 // src/tools/arguments.ts
@@ -947,8 +1012,9 @@ function wholeNumber(argument, min, max) {
   return z.number({ error }).int(error).min(min, error).max(max, error);
 }
 function tagName(argument, most) {
-  const error = `${CODE} ${argument} takes a tag name, at most ${most} characters. Written empty it narrows nothing.`;
-  return z.string({ error }).trim().min(1, error).max(most, error);
+  const empty = `${CODE} ${argument} takes a tag name. Written empty, spaces alone included, it narrows nothing.`;
+  const long = `${CODE} ${argument} takes a tag name of at most ${most} characters.`;
+  return z.string({ error: empty }).trim().min(1, empty).max(most, long);
 }
 function tagNames(argument, least, most) {
   const error = `${CODE} ${argument} takes between ${least} and ${most} tag names.`;
@@ -1037,11 +1103,18 @@ var postSchema = z2.object({
   tags: z2.array(z2.string()).describe("The first tags of the post, at most 12 of them."),
   tags_total: z2.number().int().describe("How many tags the post carries in all."),
   source: z2.string().nullable().describe("Whatever the uploader credited, when they credited any."),
-  created_at: z2.string().nullable().describe("When the post was published, ISO 8601."),
+  created_at: z2.string().nullable().describe(
+    "When the post was added to rule34.xxx, ISO 8601. The site imported much of its older catalogue in bulk, so thousands of posts share one day."
+  ),
   has_comments: z2.boolean(),
   parent_id: z2.number().int().nullable()
 });
-function toPostOut(post) {
+function previewTags(tags, asked) {
+  const carried = asked.filter((tag) => tags.includes(tag));
+  const rest = tags.filter((tag) => !carried.includes(tag));
+  return [...carried, ...rest].slice(0, TAG_PREVIEW);
+}
+function toPostOut(post, asked = []) {
   return {
     id: post.id,
     post_url: post.postUrl,
@@ -1052,7 +1125,7 @@ function toPostOut(post) {
     height: post.height,
     score: post.score,
     rating: post.rating,
-    tags: post.tags.slice(0, TAG_PREVIEW),
+    tags: previewTags(post.tags, asked),
     tags_total: post.tags.length,
     source: post.source,
     created_at: post.createdAt,
@@ -1100,48 +1173,107 @@ function renderPostList(posts) {
   }).join("\n");
 }
 
+// src/tools/findTags.ts
+var SUGGEST_CAP = 10;
+var findTagsDescription = [
+  "Find how rule34.xxx spells a tag, and how many posts carry it.",
+  "The site matches from the start of a name, so 'kimagure' finds 'kimagure_orange_road'",
+  "while 'orange road' finds nothing. It offers at most ten names.",
+  "Use this before searching when a name might be spelled differently, and after a search that found",
+  "nothing because a tag does not exist."
+].join(" ");
+var findTagsInput = strictInput({
+  query: tagName("query", 60).describe(
+    "The start of a tag name, such as 'kimagure' or 'prince of tennis'. Spaces are joined with underscores."
+  )
+});
+var findTagsOutputShape = {
+  query: z3.string().describe("The text as rule34.xxx would spell it."),
+  tags: z3.array(
+    z3.object({
+      name: z3.string().describe("The name a search takes."),
+      post_count: z3.number().int().nullable().describe("Posts the site credits to it, or nothing when it printed no count.")
+    })
+  ),
+  source: z3.literal("rule34.xxx"),
+  notes: z3.array(z3.string())
+};
+async function runFindTags(client, args) {
+  try {
+    const { data, cached } = await client.findTags(args.query);
+    const notes = cached ? ["Served from this server's short-lived in-memory cache."] : [];
+    if (data.length === 0) {
+      notes.push(
+        "rule34.xxx offers no name for this text. It matches from the start of a name, so a word sitting inside a tag finds nothing here; try the words a name begins with."
+      );
+    } else if (data.length >= SUGGEST_CAP) {
+      notes.push(
+        "rule34.xxx caps this list at ten names, and it returned ten, so more may begin the same way. Type more of the name to narrow it."
+      );
+    }
+    const asked = normalizeTag(args.query);
+    const structured = {
+      query: asked,
+      tags: data.map((tag) => ({ name: tag.name, post_count: tag.postCount })),
+      source: "rule34.xxx",
+      notes
+    };
+    const body = data.length === 0 ? `rule34.xxx offers no tag name beginning with ${asked}.` : `${data.length} name(s) rule34.xxx offers for ${asked}:
+${data.map(
+      (tag) => `  ${tag.name}${tag.postCount === null ? "" : ` (${tag.postCount} posts)`}`
+    ).join("\n")}`;
+    return ok(structured, body, notes);
+  } catch (error) {
+    return toToolError(error);
+  }
+}
+
 // src/tools/getPost.ts
+import { z as z4 } from "zod";
 var getPostDescription = [
   "Read one rule34.xxx post, named by its id or by a link to its page.",
   "Returns every tag the post carries, each with its kind (character, copyright, artist, general or",
   "metadata) and how many posts share it, alongside the image or video, the dimensions, the score,",
-  "the rating, the uploader, the number of comments, the credited source and the publication date.",
+  "the rating, the uploader, the number of comments, the credited source and the date the site",
+  "took the post in.",
   "Use this after a search, whose rows show only the first few tags of each post."
 ].join(" ");
 var getPostInput = strictInput({
   id: wholeNumber("id", 1, Number.MAX_SAFE_INTEGER).optional().describe("The post's numeric id, as a search returns it."),
-  url: z3.string().max(500).optional().describe(
+  url: z4.string().max(500).optional().describe(
     "A link to the post's page, such as https://rule34.xxx/index.php?page=post&s=view&id=2195419. The link is read rather than followed."
   )
 });
 var getPostOutputShape = {
-  id: z3.number().int(),
-  post_url: z3.string(),
-  file_url: z3.string(),
-  preview_url: z3.string().nullable(),
-  sample_url: z3.string().nullable(),
-  width: z3.number().int(),
-  height: z3.number().int(),
-  md5: z3.string(),
-  score: z3.number().int().describe("The site's own score, updated once a day."),
-  rating: z3.string(),
-  tags: z3.array(
-    z3.object({
-      name: z3.string(),
-      type: z3.string().describe("character, copyright, artist, general or metadata."),
-      post_count: z3.number().int().describe("Posts the site credits to this tag.")
+  id: z4.number().int(),
+  post_url: z4.string(),
+  file_url: z4.string(),
+  preview_url: z4.string().nullable(),
+  sample_url: z4.string().nullable(),
+  width: z4.number().int(),
+  height: z4.number().int(),
+  md5: z4.string(),
+  score: z4.number().int().describe("The site's own score, updated once a day."),
+  rating: z4.string(),
+  tags: z4.array(
+    z4.object({
+      name: z4.string(),
+      type: z4.string().describe("character, copyright, artist, general or metadata."),
+      post_count: z4.number().int().describe("Posts the site credits to this tag.")
     })
   ),
-  source: z3.string().nullable(),
-  parent_id: z3.number().int().nullable(),
-  owner: z3.string().nullable().describe("The account that uploaded the post."),
-  comment_count: z3.number().int().nullable(),
-  created_at: z3.string().nullable().describe("When the post was published, ISO 8601."),
-  changed_at: z3.string().nullable().describe("When the post last changed, ISO 8601."),
-  status: z3.string(),
-  has_notes: z3.boolean(),
-  source_site: z3.literal("rule34.xxx"),
-  notes: z3.array(z3.string())
+  source: z4.string().nullable(),
+  parent_id: z4.number().int().nullable(),
+  owner: z4.string().nullable().describe("The account that uploaded the post."),
+  comment_count: z4.number().int().nullable(),
+  created_at: z4.string().nullable().describe(
+    "When the post was added to rule34.xxx, ISO 8601. The site imported much of its older catalogue in bulk, so thousands of posts share one day."
+  ),
+  changed_at: z4.string().nullable().describe("When the post last changed, ISO 8601."),
+  status: z4.string(),
+  has_notes: z4.boolean(),
+  source_site: z4.literal("rule34.xxx"),
+  notes: z4.array(z4.string())
 };
 async function runGetPost(client, args) {
   try {
@@ -1189,8 +1321,8 @@ function render(post) {
     `  ${post.post_url}`,
     `  ${post.file_url}`
   ];
-  const posted = post.created_at ? post.created_at.slice(0, 10) : "an unstated date";
-  lines.push(`  posted ${posted}${post.owner ? ` by ${post.owner}` : ""}`);
+  const added = post.created_at ? post.created_at.slice(0, 10) : "an unstated date";
+  lines.push(`  added to rule34.xxx ${added}${post.owner ? ` by ${post.owner}` : ""}`);
   if (post.comment_count !== null) {
     lines.push(`  ${post.comment_count} comment(s)`);
   }
@@ -1206,7 +1338,7 @@ function render(post) {
 }
 
 // src/tools/searchPosts.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var searchPostsDescription = [
   "Search rule34.xxx for posts carrying a tag, or several tags at once.",
   "Tags are written as one token, so a name said as words is joined by underscores:",
@@ -1236,22 +1368,24 @@ var searchPostsInput = strictInput({
     ["questionable", "explicit"],
     "These are the two ratings rule34.xxx holds; any other answers zero posts and no error, which would hand back an absence the site never had."
   ).optional().describe("The two ratings rule34.xxx holds. Leave unset to search both."),
-  sort: choice("sort", ["score", "id", "updated", "random"], "The order the site sorts by.").default("score").describe("'score' is the site's own, updated once a day. 'id' is newest first."),
+  sort: choice("sort", ["score", "id", "updated", "random"], "The order the site sorts by.").default("score").describe(
+    "'score' is the site's own tally of votes, recomputed once a day. 'id' is newest first. 'updated' is by when a post last changed, which retagging moves. 'random' draws a different set on each call."
+  ),
   limit: wholeNumber("limit", 1, 100).default(20),
   page: wholeNumber("page", 1, MAX_PAGE).default(1)
 });
 var searchPostsOutputShape = {
-  tags: z4.array(z4.string()).describe("The required tags, as rule34.xxx spells them."),
-  any_of: z4.array(z4.string()).describe("The alternatives, as rule34.xxx spells them."),
-  exclude: z4.array(z4.string()).describe("The excluded tags, as rule34.xxx spells them."),
-  query: z4.string().describe("The search as it was sent, in the site's own language."),
-  total: z4.number().int().describe("Posts the whole search matches, as counted by the site."),
-  page: z4.number().int(),
-  posts: z4.array(postSchema),
-  has_more: z4.boolean(),
-  next_page: z4.number().int().nullable(),
-  source: z4.literal("rule34.xxx"),
-  notes: z4.array(z4.string())
+  tags: z5.array(z5.string()).describe("The required tags, as rule34.xxx spells them."),
+  any_of: z5.array(z5.string()).describe("The alternatives, as rule34.xxx spells them."),
+  exclude: z5.array(z5.string()).describe("The excluded tags, as rule34.xxx spells them."),
+  query: z5.string().describe("The search as it was sent, in the site's own language."),
+  total: z5.number().int().describe("Posts the whole search matches, as counted by the site."),
+  page: z5.number().int(),
+  posts: z5.array(postSchema),
+  has_more: z5.boolean(),
+  next_page: z5.number().int().nullable(),
+  source: z5.literal("rule34.xxx"),
+  notes: z5.array(z5.string())
 };
 function toSearch(args) {
   return {
@@ -1265,20 +1399,27 @@ function toSearch(args) {
     page: args.page
   };
 }
-function whatFollowsThisPage(hasMore, page) {
-  if (!hasMore) {
-    return "";
-  }
-  if (page < MAX_PAGE) {
-    return `
-
-More posts match: call again with page=${page + 1}.`;
-  }
-  return `
+function lastPageOf(total, limit) {
+  return total === 0 ? 1 : Math.ceil(total / limit);
+}
+function whatFollowsThisPage(nextPage) {
+  return nextPage === null ? "" : `
 
-rule34.xxx holds more, and page ${MAX_PAGE} is as far as this tool reads. Narrow the search instead.`;
+More posts match: call again with page=${nextPage}.`;
 }
 var quoted = (tags) => tags.map((tag) => `'${tag}'`).join(", ");
+function openingOf(name) {
+  return name.slice(0, Math.max(3, Math.floor(name.length * 0.6)));
+}
+async function namesLike(client, unknown) {
+  try {
+    const { data } = await client.findTags(openingOf(unknown));
+    const offered = data.slice(0, 3).map((tag) => `'${tag.name}'${tag.postCount === null ? "" : ` (${tag.postCount} posts)`}`);
+    return offered.length === 0 ? "" : ` It does offer ${offered.join(", ")}.`;
+  } catch {
+    return "";
+  }
+}
 function restrictionsIn(args) {
   const named = [];
   if ((args.any_of ?? []).length > 0) {
@@ -1299,9 +1440,11 @@ async function explainEmptySearch(client, args) {
   const alternatives = args.any_of ?? [];
   const unknownRequired = await client.findUnknownTags(args.tags);
   const unknownAlternatives = alternatives.length > 0 ? await client.findUnknownTags(alternatives) : [];
-  if (unknownRequired.length > 0) {
+  const [firstUnknown] = unknownRequired;
+  if (firstUnknown !== void 0) {
+    const near = await namesLike(client, firstUnknown);
     return [
-      `rule34.xxx holds no tag named ${quoted(unknownRequired)}. A tag a search requires and the site does not hold empties that search on its own.`
+      `rule34.xxx holds no tag named ${quoted(unknownRequired)}. A tag a search requires and the site does not hold empties that search on its own.` + near
     ];
   }
   if (alternatives.length > 0 && unknownAlternatives.length === alternatives.length) {
@@ -1330,14 +1473,27 @@ async function runSearchPosts(client, args) {
     if (cached) {
       notes.push("Served from this server's short-lived in-memory cache.");
     }
-    const posts = data.posts.map(toPostOut);
+    const asked = [...spelled.required, ...spelled.alternatives];
+    const posts = data.posts.map((post) => toPostOut(post, asked));
     const trimmed = posts.filter((post) => post.tags_total > post.tags.length).length;
     if (trimmed > 0) {
       notes.push(
         `${trimmed} of these posts carry more tags than a row shows. Call get_post with an id for the whole list, with a kind and a post count for every tag.`
       );
     }
-    const hasMore = args.page * args.limit < data.total;
+    const lastPage = lastPageOf(data.total, args.limit);
+    const hasMore = args.page < lastPage;
+    const nextPage = hasMore && args.page < MAX_PAGE ? args.page + 1 : null;
+    if (data.total > 0 && args.page > lastPage) {
+      notes.push(
+        `This search fills ${lastPage} page(s) at limit ${args.limit}, and page ${args.page} lies past the end, so no post is served.`
+      );
+    }
+    if (hasMore && nextPage === null) {
+      notes.push(
+        `rule34.xxx holds more posts, and page ${MAX_PAGE} is as far as this tool reads. Raise limit to carry more of them per page, or narrow the search.`
+      );
+    }
     if (data.total === 0) {
       notes.push(...await explainEmptySearch(client, args));
     }
@@ -1350,14 +1506,14 @@ async function runSearchPosts(client, args) {
       page: args.page,
       posts,
       has_more: hasMore,
-      next_page: hasMore && args.page < MAX_PAGE ? args.page + 1 : null,
+      next_page: nextPage,
       source: "rule34.xxx",
       notes
     };
     const header = data.total === 0 ? `No post on rule34.xxx matches ${query}.` : `${data.total.toLocaleString("en-US")} post(s) match ${query}. Page ${args.page}:`;
     const body = posts.length > 0 ? `
 ${renderPostList(posts)}` : "";
-    return ok(structured, `${header}${body}${whatFollowsThisPage(hasMore, args.page)}`, notes);
+    return ok(structured, `${header}${body}${whatFollowsThisPage(nextPage)}`, notes);
   } catch (error) {
     return toToolError(error);
   }
@@ -1381,7 +1537,7 @@ function createServer(options = {}) {
   const server = new McpServer(
     { name: "mcp-rule34", version: PKG_VERSION },
     {
-      instructions: "Tools for searching rule34.xxx by tag, through the site's own API. This server reads and never contributes anything back. It needs credentials: set RULE34_USER_ID and RULE34_API_KEY, both shown under 'API Access Credentials' at https://rule34.xxx/index.php?page=account&s=options once signed in, and note that the site issues one key per person. Tags are single tokens: a name said as words, such as 'asuka langley sohryu', is one tag, and the tools join it for you. The site holds two ratings, 'questionable' and 'explicit'; asking for anything else is refused rather than answered with nothing. Typical flow: search_posts to find posts by tag, then get_post with an id for one post's whole tag list, since a search row shows only its first few tags. A 'rate_limited' error means the site is refusing this client for now, not that a search found nothing. When you show a post to a user, link its rule34.xxx page."
+      instructions: "Tools for searching rule34.xxx by tag, through the site's own API. This server reads and never contributes anything back. It needs credentials: set RULE34_USER_ID and RULE34_API_KEY, both shown under 'API Access Credentials' at https://rule34.xxx/index.php?page=account&s=options once signed in, and note that the site issues one key per person. Tags are single tokens: a name said as words, such as 'asuka langley sohryu', is one tag, and the tools join it for you. The site holds two ratings, 'questionable' and 'explicit'; asking for anything else is refused rather than answered with nothing. Typical flow: search_posts to find posts by tag, then get_post with an id for one post's whole tag list, since a search row shows only its first few tags. When a name might be spelled otherwise, or when a search found nothing because a tag does not exist, find_tags says how the site spells it. A 'rate_limited' error means the site is refusing this client for now, not that a search found nothing. When you show a post to a user, link its rule34.xxx page."
     }
   );
   server.registerTool(
@@ -1390,7 +1546,7 @@ function createServer(options = {}) {
       title: "Search posts by tag",
       description: searchPostsDescription,
       inputSchema: searchPostsInput,
-      outputSchema: z5.object(searchPostsOutputShape),
+      outputSchema: z6.object(searchPostsOutputShape),
       annotations: READ_ONLY
     },
     async (args) => runSearchPosts(client, args)
@@ -1401,11 +1557,22 @@ function createServer(options = {}) {
       title: "Read one post",
       description: getPostDescription,
       inputSchema: getPostInput,
-      outputSchema: z5.object(getPostOutputShape),
+      outputSchema: z6.object(getPostOutputShape),
       annotations: READ_ONLY
     },
     async (args) => runGetPost(client, args)
   );
+  server.registerTool(
+    "find_tags",
+    {
+      title: "Find how a tag is spelled",
+      description: findTagsDescription,
+      inputSchema: findTagsInput,
+      outputSchema: z6.object(findTagsOutputShape),
+      annotations: READ_ONLY
+    },
+    async (args) => runFindTags(client, args)
+  );
   logger.info(
     `ready: user-agent="${config.userAgent}", min interval ${config.minIntervalMs}ms, cache ${config.cacheTtlMs}ms, credentials ${config.credentials ? "set" : "missing"}`
   );