io.github.ArturLys/ao3-mcp

Resolve fuzzy wording to canonical AO3 tag names (live autocomplete). Use before search_works when unsure of exact spelling — e.g. "coffee shop" resolves to "Alternate Universe - Coffee Shops & Cafés". Args: term: partial/fuzzy tag text, e.g. "enemies to", "coffee", "kakashi". kind: what to complete: tag | fandom | relationship | character.

Get the full metadata card for one work: tags, stats, summary, series info. Args: work_id: the numeric AO3 work id (from search results or a URL like archiveofourown.org/works/12345).

⚠️ NOT RECOMMENDED — escape hatch only. Returns the raw full text of ONE fic directly to you, bypassing the mini reader. Prefer `read_works` in almost every case. A fic can run 150k+ words; pulling that into your own context buries everything else, burns your tokens, and throws away the whole reason this server exists — delegating reading to a cheap second model. `read_works` hands you a structured report plus verbatim prose samples, which is enough to judge, compare, and recommend a fic without the fic ever entering your context. Only reach for this when you genuinely need exact wording a report can't carry — e.g. the user explicitly asks you to quote or close-read a specific passage. If you just want to know what a fic is like or whether it's good: use `read_works` instead. Args: work_id: the numeric AO3 work id. max_words: cap the text to the first N words (0 = whole fic). Set a limit to sample a fic's opening instead of dumping the entire thing into your context — a few thousand words is usually plenty to judge voice.

Have the mini reader (a separate AI) read full fics and report on each. Works for a single fic or up to 20 at once. You never receive fic text — only structured reader reports, one per work. The reader answers your query directly (anything works: "is the ending happy?", "how explicit is it?", "which of these should I read first?") plus gives a general digest of plot, characters, style, and content notes. When given several fics, it ends with a comparison section ranking them against your query. This is the ONLY approved way to read a fic. A separate model does the reading so a whole novel never touches your context. You MUST send fics here before you recommend, rank, summarize, or judge them — search blurbs are not enough, and reading raw text yourself defeats the entire point of this server. Shortlist from blurbs, read here, then recommend. Reading depth: a single-fic call sends the reader up to ~150k words (whole novels fit); in a batch each fic is capped at ~100k characters. If a long fic's report matters, read it alone. Batches that exceed the token budget are split internally, then a final reduce pass still produces ONE global comparison across the whole batch. Content refusals: the reader is Gemini, which has a non-configurable safety filter that occasionally refuses explicit or extreme fics — that fic's report comes back as "(mini reader returned no text …)". The server already retries once on the backup model, but the block is intermittent, so if a fic you care about is refused: read it ALONE (a single fic isn't dragged down by an extreme one sharing its batch), or just retry. In a mixed batch, one refused fic does not sink the others — their reports still return. Args: work_ids: 1-20 numeric AO3 work ids (from search results or URLs). query: the question to answer about each fic.

Search AO3 for works. All filters optional; combine freely. RECOMMENDATION WORKFLOW — reading before recommending is MANDATORY, and the reading is done by a SEPARATE model, not you. Blurbs are author-written ads; never recommend, rank, or summarize a fic from its blurb alone. Cast a wide net (pages=2-3, i.e. 40-60 blurbs), shortlist the promising ones, then hand the top ≤20 ids to `read_works` — a second AI reads them and reports back. Recommend ONLY fics that came back from `read_works`. Do not read fic text yourself; delegating it is the entire point of this server. SEARCH STRATEGY — searching is cheap and reading is delegated, so the winning move is always to OVER-FETCH and let `read_works` brute-force the shortlist, never to craft one perfect narrow query. Filters multiply: each one you add cuts the pool, and stacked filters routinely cut it to zero. USE WILDCARDS LIBERALLY — abuse them. A `*` matches any run of characters and works in EVERY name field (`fandom`, `relationship`, `character`, `tags`) and in `query`. Wrapping a term in stars is the single best defence against AO3's exact-canonical-name trap: `fandom="Genshin Impact (Video Game)"` returns ZERO (the canonical tag is actually "原神 | Genshin Impact (Video Game)"), but `fandom="*Genshin Impact*"` returns the whole fandom. Likewise `relationship="*Kazuha*Scaramouche*"`, `tags="*Enemies to Lovers*"`. When you don't know the exact canonical name — which is most of the time — reach for a wildcard first instead of guessing the literal string. IF YOU GET 0 (or few) RESULTS, that is almost always your query being too narrow, NOT the content missing from AO3. Recover instead of giving up: - FIRST, wildcard the name fields (`*Genshin Impact*`). This fixes the most common cause — an exact-match field that didn't match the canonical tag — in one retry, without a separate `find_tags` round-trip. - Still unsure of a name? `find_tags` resolves it, or move the idea into `query` as free text (fuzzy, no canon…