# Booru-Pictag-Get-MCP

> **⚠️ 纯 AI 生成声明 | Pure AI-Generated Notice** — 详见 [`AIGC_NOTICE.md`](./AIGC_NOTICE.md)

An [MCP](https://modelcontextprotocol.io) server that searches booru image boards (Danbooru / AIBooru / e621 / Gelbooru / Rule34) and cleans their tags into **ready-to-use AI-art prompts** for Stable Diffusion / Illustrious / Pony / SDXL and any booru-tag-driven model.

This is a **Python port + MCP integration** of [`booru-prompt-gallery`](https://github.com/Mexes-GM/booru-prompt-gallery) by **Mexes-GM** (MIT). The prompt-cleaning pipeline — tag extraction, multi-subject guard, smart tag combination, redundancy folding, category splitting, background modes — is a 1:1 port of the original TypeScript modules. Wrapped as 9 callable MCP tools (4 prompt-building + 5 Danbooru character/tag analysis tools, the latter ported from the former standalone Danbooru-Search-MCP so callers have a single booru MCP), no Web UI, no Supabase/Redis/Cloudflare deps. See [`AIGC_NOTICE.md`](./AIGC_NOTICE.md) for the full derivation & attribution.

| | |
|---|---|
| **Upstream** | [Mexes-GM/booru-prompt-gallery](https://github.com/Mexes-GM/booru-prompt-gallery) — TypeScript + Next.js 15 web app (MIT) |
| **This repo** | [echo-xianyu/Booru-Pictag-Get-MCP](https://github.com/echo-xianyu/Booru-Pictag-Get-MCP) — Python 3 + FastMCP server |
| **License** | MIT — original credit preserved, dual attribution. See [`LICENSE`](./LICENSE) |

---

## Install

### Option A — local path

Clone, then point `uvx` at the local checkout:

```bash
git clone https://github.com/echo-xianyu/Booru-Pictag-Get-MCP.git
cd Booru-Pictag-Get-MCP
uvx --from . booru-pictag-get-mcp
```

### Option B — cloud / direct from GitHub

```bash
uvx --from "git+https://github.com/echo-xianyu/Booru-Pictag-Get-MCP" booru-pictag-get-mcp
```


### HTTP/2 extra (recommended — required for e621)

```bash
uvx --from . --with h2 booru-pictag-get-mcp
```
e621's TLS stack frequently errors out on HTTP/1.1 keep-alive. The HTTP client auto-detects `h2` and falls back to HTTP/1.1 if absent.

---

## Configure (opencode / any MCP client)

```jsonc
{
  "mcp": {
    "booru-pictag-get": {
      "command": "uvx",
      // Option A — local:
      "args": ["--from", "E:\\MCP\\booru-pictag-get-mcp", "booru-pictag-get-mcp"],
      // Option B — cloud (no checkout on disk):
      // "args": ["--from", "git+https://github.com/echo-xianyu/Booru-Pictag-Get-MCP", "booru-pictag-get-mcp"],
      // HTTP/2 for e621 — prepend "--with", "h2" to args above.
      "environment": {
        "BOORU_DEFAULT_PROVIDER": "danbooru",
        "DANBOORU_USERNAME_APIKEY": "youruser:yourkey",    // optional, raises rate limit
        "GELBOORU_USER_ID": "<your_user_id>",             // required by Gelbooru since 2025-08
        "GELBOORU_API_KEY": "<your_api_key>",
        "RULE34_USER_ID": "<your_user_id>",               // required by Rule34 since 2025-08
        "RULE34_API_KEY": "<your_api_key>",
        "BOORU_MAX_TAGS_DANBOORU": "6"                     // optional: raise a provider's per-search tag cap (default: danbooru/aibooru/e621 = 2, gelbooru/rule34 = 10)
      }
    }
  }
}
```

> **API key policy (Aug 2025):** Danbooru, AIBooru, and e621 work with **no key**. Gelbooru and Rule34 tightened auth and now require keys. Without them, those two providers return 401; the others keep working.

> **Multi-tag search limits:** every provider caps how many plain tags one query may combine — **danbooru / aibooru / e621 = 2 tags** (per site docs; Danbooru Gold accounts get 6), **gelbooru / rule34 = 10 tags** (per their API docs' "any tag combination"). Metatags (`order:rank`, `rating:safe`, `sort:score`, …) do **not** count toward the limit. Exceeding the cap returns a clear error telling you how to fix it. To raise (or lower) a cap, set `BOORU_MAX_TAGS_<PROVIDER>` (e.g. `BOORU_MAX_TAGS_DANBOORU=6` for a Gold account).

---

## Tools

### Prompt-building tools (multi-provider: Danbooru / AIBooru / e621 / Gelbooru / Rule34)

| Tool | Use it for |
|---|---|
| `search_prompts` | **Recommended for ready-to-use prompts.** Search a booru tag → cleaned prompt + category split. One step. |
| `build_prompt` | Clean an already-known tag set (no network). Accepts raw booru format or comma-list. |
| `search_posts` | Raw post list (no cleaning). Inspect original tags before deciding how to process them. |
| `autocomplete_tags` | Turn a natural word, partial fragment, **or non-English term** (Chinese / Japanese `other_names`) into the canonical booru tag form. Alias + fuzzy + auto-correction aware. Call BEFORE search if unsure of a tag's spelling. |

### Danbooru character / tag analysis tools (Danbooru-only — ported from the former Danbooru-Search-MCP)

These answer a *different* question from the prompt builders above. The prompt builders return **sample images each turned into a prompt**; the analysis tools **describe a known character/tag**: visual-trait frequency tables, wiki text, tag-implication chains, costume variants.

| Tool | Use it for |
|---|---|
| `danbooru_get_character_profile` | **Recommended first for character lookups.** One call returns: trait frequencies (e.g. halo/ahoge/pink_hair for Hoshino), wiki page + multilingual aliases, and bidirectional tag implications (source work + all costume variants). Auto-resolves misspellings/Chinese names. |
| `danbooru_search_character` | Just the visual-trait co-occurrence table for a character tag (with optional category filter and frequency threshold). |
| `danbooru_lookup_tag` | Find or verify a tag's exact canonical name. Alias/fuzzy/prefix matching; supports `*` wildcards; falls back to `tags.json`. Use to list e.g. all `*_(blue_archive)` character variants. |
| `danbooru_get_wiki_page` | Get the textual wiki page for a tag (DText stripped to readable plain text; exposes `other_names`). |
| `danbooru_get_tag_implications` | Get the implication chain for a tag (what does this tag auto-add). For *reverse* direction (costume variants implying this tag) use `danbooru_get_character_profile` instead. |

### Routing guidance

Each tool's description in `tools/list` carries full guidance, but the short version:

- **"What does character X look like?" / "list X's costume variants" / "describe tag Y"** → `danbooru_get_character_profile` (it aggregates everything). Do **not** route these to `search_prompts` — that returns sample-image prompts, not a description.
- **Find the canonical tag name for a Chinese/Japanese term or a misspelling** → `autocomplete_tags` (alias / fuzzy / `other_names` aware). `search_prompts` cannot do this.
- Booru search is **tag-based AND**, not keyword search. Multi-tag queries are supported up to each provider's limit (danbooru/aibooru/e621 = 2, gelbooru/rule34 = 10), but prefer a single tag (`hatsune_miku`) over stacking (`hatsune_miku blue_hair smile`), which usually returns 0 posts.
- Multi-word tags use underscore: `blue_hair`, never `blue hair`.
- Don't write natural-language queries ("a girl with blue hair sitting in a classroom"); translate to booru tags first via `autocomplete_tags`.

---

## Scope & design choices

- **Pure Python** — no Supabase / Redis / Cloudflare / Vercel. Endpoints are public booru APIs; no proprietary backend.
- **Tag-conflict rules are off by default** in the prompt pipeline (mirrors the original `cleanPrompt.ts`, which never called `tag-conflicts.ts`). The 180+ rules were authored assuming a single subject — enabling them by default would mangle legitimate multi-character prompts (e.g. `1girl+1boy` sex scenes, `smile+crying` bittersweet scenes, `long_hair+short_hair` two-character shots). The resolver remains callable via `booru_mcp.core.tag_conflicts.resolve_conflicts()` for explicit opt-in.
- **`optimize_tags` has a multi-subject guard**: when the prompt contains multi-character markers (`2girls` / `2boys` / `multiple_*` / `couple` / `group` / `duo` …), it skips the hair-length / breast-size / eye-color "keep best per hierarchy" pick and the shared-noun tag combination — so two characters with different features survive intact.
- **Tag categories for Gelbooru/Rule34** come from a static `data/tag_categories.json` dictionary (one-shot dump from Danbooru's public `tags.json`, generated by `scripts/dump_tag_categories.py`) with a keyword-classifier fallback. No external database at runtime.
- **Tag-conflict rules are overridable** via `data/tag_conflicts_overrides.json` (additive — overrides can only widen a built-in rule, never narrow it). See `data/tag_conflicts_overrides.example.json`. Audit current rules with `python scripts/inspect_tag_conflicts.py --builtin`.
- **Danbooru character/tag analysis tools are integrated.** The five `danbooru_get_character_profile` / `danbooru_search_character` / `danbooru_lookup_tag` / `danbooru_get_wiki_page` / `danbooru_get_tag_implications` tools were originally a separate MCP (`Danbooru-Search-MCP`). They now live inside this package via `core/danbooru_meta.py`, all reusing the same HTTP client — so Danbooru Basic Auth uses the same env vars as the rest of this server (`DANBOORU_USERNAME` + `DANBOORU_API_KEY`, or the combined `DANBOORU_USERNAME_APIKEY`), **not** the old `DANBOORU_LOGIN`/`DANBOORU_API_KEY` pair. The standalone `Danbooru-Search-MCP` can be removed from your MCP client config once this version is installed.

---

## Credits

Prompt-cleaning pipeline ported (1:1 line-for-line where possible) from [`booru-prompt-gallery`](https://github.com/Mexes-GM/booru-prompt-gallery) by **Mexes-GM** (MIT). Original copyright preserved in [`LICENSE`](./LICENSE).

Python port + MCP server by [**echo-xianyu**](https://github.com/echo-xianyu). The vast majority of the code was generated by AI (opencode + GLM-5.2); see [`AIGC_NOTICE.md`](./AIGC_NOTICE.md) for the full statement.