# ⚠️ 纯 AI 生成声明 | Pure AI-Generated Notice

> **本项目代码由 AI（opencode + GLM-5.2）完全生成，未经人工编写。**
>
> **This project's code is entirely generated by AI (opencode + GLM-5.2), without human-written code.**

---

> ## ⚠️ Deprecated — 已废弃
>
> This repository has been **merged into**
> [`echo-xianyu/Booru-Pictag-Get-MCP`](https://github.com/echo-xianyu/Booru-Pictag-Get-MCP)
> (v0.2.0+). All five tools (`danbooru_get_character_profile`,
> `danbooru_search_character`, `danbooru_lookup_tag`, `danbooru_get_wiki_page`,
> `danbooru_get_tag_implications`) now live there alongside the prompt-building
> tools, behind a single MCP. This repo is archived — please migrate. See
> [`DEPRECATED.md`](./DEPRECATED.md) for details and migration steps.
>
> 本仓库已**合并进** [`echo-xianyu/Booru-Pictag-Get-MCP`](https://github.com/echo-xianyu/Booru-Pictag-Get-MCP)
> （v0.2.0+），五个工具已整体迁入并和多站点搜图工具合并为单一 MCP。本仓库归档停更，请迁移至新仓库。

---

# Danbooru Search MCP

[English](#english) | [中文](#中文)

---

<a id="english"></a>

## English

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that searches [Danbooru](https://danbooru.donmai.us) for anime/game characters and their related tags. Given a character tag like `hoshino_(blue_archive)`, it returns the most relevant co-occurring tags (`ahoge`, `pink_hair`, `blue_eyes`, `heterochromia`, ...) ranked by how often they appear together.

### Features

- **Character profile in one call** — visual traits, wiki description, multilingual aliases, and costume variant implications, all aggregated in parallel.
- **Auto-correction** — misspelled tags are automatically resolved via Danbooru's autocomplete (e.g. `amamya_kokoro` → `amamiya_kokoro`).
- **No authentication required** — the Danbooru read API is public. Setting `DANBOORU_LOGIN` / `DANBOORU_API_KEY` is optional and only raises your rate limit.
- **Zero-install deployment** — runs via `uvx` with no manual install step.

### Tools

| # | Tool | Purpose |
|---|------|---------|
| 1 | `danbooru_get_character_profile` | ⭐ **Recommended first.** Complete profile: traits + wiki + aliases + implications. |
| 2 | `danbooru_search_character` | Visual trait frequencies for a character tag (ahoge, pink_hair, etc.). |
| 3 | `danbooru_lookup_tag` | Find/verify a tag's exact canonical name. Alias-corrected. |
| 4 | `danbooru_get_wiki_page` | Get the textual wiki description for a tag. |
| 5 | `danbooru_get_tag_implications` | Get the implication chain (A → B auto-adds). |

### Requirements

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or `pip`

### Install & Configure

Add this to your MCP client config (`claude_desktop_config.json`, `opencode.json`, etc.):

```json
{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/echo-xianyu/danbooru-MCP", "danbooru-mcp"]
    }
  }
}
```

**From a local directory:**

```json
{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "E:\\path\\to\\Danbooru-Search-MCP", "danbooru-mcp"]
    }
  }
}
```

**With optional authentication (higher rate limit):**

```json
{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/echo-xianyu/danbooru-MCP", "danbooru-mcp"],
      "env": {
        "DANBOORU_LOGIN": "your_username",
        "DANBOORU_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Usage Examples

Ask your MCP-enabled assistant:

- *"Search `hoshino_(blue_archive)`, return the most relevant trait tags"*
  → calls `danbooru_search_character`, returns `ahoge` (0.92), `pink_hair` (0.92), `halo` (0.93), ...
- *"Give me the full profile of Amamiya Kokoro"*
  → calls `danbooru_get_character_profile` with `tag=amamiya_kokoro`.
- *"What does the ahoge tag mean?"*
  → calls `danbooru_get_wiki_page` with `title=ahoge`.

### Danbooru Tag Format

Tags use lowercase with underscores, and parentheses for disambiguation:

- Spaces → underscores: `blue archive` → `blue_archive`
- Disambiguation suffix: `hoshino_(blue_archive)`, `rem_(re:zero)`

Use `danbooru_lookup_tag` with a `*` wildcard to discover the exact canonical name first.

### Rate Limits

- Anonymous reads: 10 requests/second (shared global limit).
- With API key: higher per-account limits.
- The server sets a custom `User-Agent` as required by Danbooru's policy.

### License

MIT

---

<a id="中文"></a>

## 中文

一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io)服务器，通过 [Danbooru](https://danbooru.donmai.us) 搜索动漫/游戏角色及其相关标签。输入角色标签如 `hoshino_(blue_archive)`，返回最相关的共现标签（`ahoge`、`pink_hair`、`blue_eyes`、`heterochromia`...），按共现频率排序。

### 功能特点

- **一次调用获取完整角色档案** — 视觉特征、Wiki 描述、多语言别名、服装变体蕴含关系，并行聚合。
- **自动纠错** — 拼写的标签名自动通过 Danbooru autocomplete 纠正（如 `amamya_kokoro` → `amamiya_kokoro`）。
- **无需认证** — Danbooru 只读 API 公开可用。设置 `DANBOORU_LOGIN` / `DANBOORU_API_KEY` 是可选的，仅用于提升限速。
- **零安装部署** — 通过 `uvx` 运行，无需手动安装。

### 工具列表

| # | 工具 | 用途 |
|---|------|------|
| 1 | `danbooru_get_character_profile` | ⭐ **推荐首选。** 完整档案：特征 + Wiki + 别名 + 蕴含关系。 |
| 2 | `danbooru_search_character` | 获取角色视觉特征频率（ahoge、pink_hair 等）。 |
| 3 | `danbooru_lookup_tag` | 查找/验证标签的规范名称，支持别名纠错。 |
| 4 | `danbooru_get_wiki_page` | 获取标签的 Wiki 文字描述。 |
| 5 | `danbooru_get_tag_implications` | 获取标签蕴含链（A → B 自动附加）。 |

### 环境要求

- Python 3.10+
- [uv](https://docs.astral.sh/uv/)（推荐）或 `pip`

### 安装与配置

将以下内容添加到 MCP 客户端配置中（`claude_desktop_config.json`、`opencode.json` 等）：

```json
{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/echo-xianyu/danbooru-MCP", "danbooru-mcp"]
    }
  }
}
```

**从本地目录运行：**

```json
{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "E:\\path\\to\\Danbooru-Search-MCP", "danbooru-mcp"]
    }
  }
}
```

**带认证（提升限速，可选）：**

```json
{
  "mcpServers": {
    "danbooru": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/echo-xianyu/danbooru-MCP", "danbooru-mcp"],
      "env": {
        "DANBOORU_LOGIN": "你的用户名",
        "DANBOORU_API_KEY": "你的API密钥"
      }
    }
  }
}
```

### 使用示例

对支持 MCP 的 AI 助手说：

- *"搜索 `hoshino_(blue_archive)`，返回最相关的特征标签"*
  → 调用 `danbooru_search_character`，返回 `ahoge`（0.92）、`pink_hair`（0.92）、`halo`（0.93）...
- *"给我天宫心（Amamiya Kokoro）的完整角色档案"*
  → 调用 `danbooru_get_character_profile`，参数 `tag=amamiya_kokoro`。
- *"ahoge 这个标签是什么意思？"*
  → 调用 `danbooru_get_wiki_page`，参数 `title=ahoge`。

### Danbooru 标签格式

标签使用小写 + 下划线，括号用于消歧：

- 空格 → 下划线：`blue archive` → `blue_archive`
- 消歧后缀：`hoshino_(blue_archive)`、`rem_(re:zero)`

不确定标签名时，先用 `danbooru_lookup_tag` 加 `*` 通配符查找。

### 限速

- 匿名读取：10 请求/秒（全站共享）。
- 带 API 密钥：更高的账户级限速。
- 服务器已设置 Danbooru 要求的自定义 `User-Agent`。

### 许可证

MIT