内容
# Booru-Pictag-Get-MCP
> **⚠️ 纯 AI 生成声明 | Pure AI-Generated Notice** — 详见 [`AIGC_NOTICE.md`](./AIGC_NOTICE.md)
MCP 服务器，搜索 booru 图片板块（Danbooru / AIBooru / e621 / Gelbooru / Rule34）并清理标签，生成 **可直接使用的 AI 艺术提示**，适用于 Stable Diffusion / Illustrious / Pony / SDXL 及任何基于 booru 标签驱动的模型。
这是 [`booru-prompt-gallery`](https://github.com/Mexes-GM/booru-prompt-gallery) 的 **Python 版本 + MCP 集成**，由 **Mexes-GM** (MIT) 编写。提示清理流程 — 标签提取、多主题保护、智能标签组合、冗余折叠、类别拆分、背景模式 — 是原始 TypeScript 模块的 1:1 移植。以 4 个可调用的 MCP 工具封装，无 Web UI，无 Supabase/Redis/Cloudflare 依赖。详见 [`AIGC_NOTICE.md`](./AIGC_NOTICE.md) 获取完整来源和署名。
| | |
|---|---|
| **上游项目** | [Mexes-GM/booru-prompt-gallery](https://github.com/Mexes-GM/booru-prompt-gallery) — TypeScript + Next.js 15 网页应用（MIT） |
| **本仓库** | [echo-xianyu/Booru-Pictag-Get-MCP](https://github.com/echo-xianyu/Booru-Pictag-Get-MCP) — Python 3 + FastMCP 服务器 |
| **许可证** | MIT — 原始版权保留，双重署名。详见 [`LICENSE`](./LICENSE) |
---
## 安装
### 选项 A — 本地路径
克隆仓库，然后将 `uvx` 指向本地目录：
```bash
git clone https://github.com/echo-xianyu/Booru-Pictag-Get-MCP.git
cd Booru-Pictag-Get-MCP
uvx --from . booru-pictag-get-mcp
```
### 选项 B — 云端 / 直接从 GitHub
```bash
uvx --from "git+https://github.com/echo-xianyu/Booru-Pictag-Get-MCP" booru-pictag-get-mcp
```
### HTTP/2 额外配置（推荐 — e621 必需）
```bash
uvx --from . --with h2 booru-pictag-get-mcp
```
e621 的 TLS 栈在 HTTP/1.1 长连接上经常出错。HTTP 客户端会自动检测 `h2` 并在不存在时回退到 HTTP/1.1。
---
## 配置（开放代码 / 任意 MCP 客户端）
```jsonc
{
"mcp": {
"booru-pictag-get": {
"command": "uvx",
// 选项 A — 本地：
"args": ["--from", "E:\\MCP\\booru-pictag-get-mcp", "booru-pictag-get-mcp"],
// 选项 B — 云端（无需磁盘上checkout）：
// "args": ["--from", "git+https://github.com/echo-xianyu/Booru-Pictag-Get-MCP", "booru-pictag-get-mcp"],
// 为 e621 使用 HTTP/2 — 在上述参数中添加 "--with", "h2"。
"environment": {
"BOORU_DEFAULT_PROVIDER": "danbooru",
"DANBOORU_USERNAME_APIKEY": "youruser:yourkey", // 可选，提高速率限制
"GELBOORU_USER_ID": "<your_user_id>", // Gelbooru 2025-08 起必填
"GELBOORU_API_KEY": "<your_api_key>",
"RULE34_USER_ID": "<your_user_id>", // Rule34 2025-08 起必填
"RULE34_API_KEY": "<your_api_key>"
}
}
}
}
```
> **API 密钥政策（2025 年 8 月）**：Danbooru、AIBooru 和 e621 无需密钥即可工作。Gelbooru 和 Rule34 加强了身份验证，现在需要密钥。没有密钥， 这两个提供商将返回 401；其他提供商仍可正常工作。
---
## 工具
| 工具 | 用途 |
|---|---|
| `search_prompts` | **推荐。** 搜索一个 booru 标签 → 可直接使用的清理提示 + 类别拆分。一步到位。 |
| `build_prompt` | 清理已知的标签集（无需联网）。接受原始 booru 格式或逗号列表。 |
| `search_posts` | 原始帖子列表（无清理）。检查原始标签，决定如何处理它们。 |
| `autocomplete_tags` | 将自然语言转换为规范的 booru 标签形式。在搜索前调用此工具，如果不确定标签的拼写。 |
每个工具的描述都在 `tools/list` 中包含完整的搜索语义指导：
- Booru 搜索是 **基于标签的 AND**，而非关键词搜索。优先使用单个标签 (`hatsune_miku`) 而非堆叠 (`hatsune_miku blue_hair smile`)，后者通常返回 0 篇帖子。
- 多词标签使用下划线：`blue_hair`，而非 `blue hair`。
- 不要编写自然语言查询（“一个蓝发女孩坐在教室里”）；先使用 `autocomplete_tags` 将其转换为 booru 标签。
---
## 范围和设计选择
- **纯 Python** — 无 Supabase / Redis / Cloudflare / Vercel。端点是公共的 booru API；无专有后端。
- **标签冲突规则默认关闭** （在提示流程中，这与原始的 `cleanPrompt.ts` 镜像，它从未调用 `tag-conflicts.ts`）。180 多条规则是假设单个主题编写的；默认启用它们会破坏合法的多角色提示（例如 `1girl+1boy` 性爱场景，`smile+crying` 复杂的情绪场景，`long_hair+short_hair` 双角色镜头）。通过 `booru_mcp.core.tag_conflicts.resolve_conflicts()` 调用冲突解决器进行显式选择。
- **`optimize_tags` 有多主题保护**：当提示包含多角色标记 (`2girls` / `2boys` / `multiple_*` / `couple` / `group` / `duo` ...)，跳过发型 / 乳房大小 / 眼睛颜色的“按层次保留最佳”选择和共享名词的标签组合，以便两个具有不同特征的角色存活。
- **Gelbooru/Rule34 的标签类别** 来自静态的 `data/tag_categories.json` 字典（Danbooru 公共 `tags.json` 的一次性导出，由 `scripts/dump_tag_categories.py` 生成），并使用关键词分类器作为备用。运行时无需外部数据库。
- **标签冲突规则可覆盖**，通过 `data/tag_conflicts_overrides.json` （累加 — 覆盖只能扩大内置规则，不能缩小）。参见 `data/tag_conflicts_overrides.example.json`。使用 `python scripts/inspect_tag_conflicts.py --builtin` 审核当前规则。
---
## 鸣谢
提示清理流程从 [`booru-prompt-gallery`](https://github.com/Mexes-GM/booru-prompt-gallery) （MIT）由 **Mexes-GM** 编写，逐行移植（尽可能 1:1）。原始版权在 [`LICENSE`](./LICENSE) 中保留。
Python 移植 + MCP 服务器由 [**echo-xianyu**](https://github.com/echo-xianyu) 编写。大多数代码由 AI 生成（开放代码 + GLM-5.2）；详见 [`AIGC_NOTICE.md`](./AIGC_NOTICE.md) 获取完整声明。
