# Danbooru Tag RAG MCP Server

Danbooruタグのセマンティック検索を提供するMCP (Model Context Protocol) サーバーです。

## 概要

このMCPサーバーは、自然言語のクエリからDanbooruタグを検索する機能を提供します。SDXLアニメモデルはDanbooruタグで学習されているため、適切なタグを使用することで画像生成の精度が向上します。

### 特徴

- **セマンティック検索**: キーワード一致ではなく、意味的に関連するタグを検索
- **日本語・英語対応**: multilingual-e5-small モデルによる多言語サポート
- **ローカル実行**: 外部APIを使用せず、完全にローカルで動作
- **軽量**: LanceDBによる効率的なベクトル検索

## 技術スタック

| コンポーネント | 技術 | 理由 |
|---------------|------|------|
| MCP SDK | mcp (公式SDK) | 標準プロトコル準拠 |
| ベクトルDB | LanceDB | 軽量、ローカル実行に最適 |
| 埋め込みモデル | multilingual-e5-small | 日英対応、高精度、CPU対応 |
| パッケージ管理 | uv | モダンで高速 |

## インストール

Claude Desktopの設定ファイル（`claude_desktop_config.json`）に以下を追加:

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

初回起動時にインデックスが自動構築されます（約60,000タグ、数分かかります）。

### 使用例

Claude Desktopでこのツールを有効にすると、自然言語でプロンプト生成を依頼できます。

**例1: キャラクター描写**
```
あなた: 「青い髪のツインテールの女の子が魔法を使っているシーンのプロンプトを作って」

Claude: semantic_searchで関連タグを検索し、以下のようなプロンプトを生成します：
→ 1girl, blue hair, twintails, magic, casting spell, glowing, magical effects, ...
```

**例2: 風景シーン**
```
あなた: 「夕焼けのファンタジー風景のプロンプトをお願い」

Claude: 関連タグを検索して組み合わせます：
→ scenery, sunset, fantasy, sky, clouds, orange sky, landscape, no humans, ...
```

**例3: 複雑なシーン**
```
あなた: 「カフェで本を読んでいる眼鏡の女の子、窓から光が差し込んでいる感じで」

Claude: 複数の要素を検索して統合します：
→ 1girl, glasses, book, reading, cafe, indoors, window, sunlight, sitting, ...
```

Claudeが自動的にsemantic_searchツールを使用し、Danbooruタグに基づいた画像生成プロンプトを作成します。

## プロジェクト構造

```
danbooru-rag-mcp/
├── README.md                 # このファイル
├── pyproject.toml            # パッケージ設定
├── danbooru-tags.txt         # ソースデータ
├── src/
│   └── danbooru_rag/
│       ├── __init__.py       # パッケージ初期化
│       ├── __main__.py       # モジュールエントリーポイント
│       ├── config.py         # 設定定数
│       ├── embeddings.py     # 埋め込み生成
│       ├── database.py       # LanceDB操作
│       ├── builder.py        # インデックス自動構築
│       └── server.py         # MCPサーバー本体
├── scripts/
│   └── build_index.py        # インデックス手動構築
└── tests/
    └── ...                   # テスト
```

**データベース保存先:**
- Windows: `%LOCALAPPDATA%\danbooru-rag\lancedb`
- macOS: `~/Library/Application Support/danbooru-rag/lancedb`
- Linux: `~/.local/share/danbooru-rag/lancedb`

## 設計判断

### なぜmultilingual-e5-smallか？

1. **日本語・英語両対応**: ユーザーがどちらの言語でクエリしても対応
2. **高精度**: all-MiniLM-L6-v2より高いベンチマークスコア
3. **CPU対応**: GPUなしでも実用的な速度で動作
4. **E5プレフィックス**: query:/passage: プレフィックスで精度向上

### なぜLanceDBか？

1. **サーバー不要**: ファイルベースでローカル実行に最適
2. **Pythonネイティブ**: 簡単にインストール・使用可能
3. **高速**: ベクトル検索に最適化

### なぜ出現頻度100以下をフィルタリングするか？

1. **学習データの品質**: 低頻度タグはSDXLモデルの学習が不十分
2. **インデックス効率**: 99,999件 → 約60,000件に削減
3. **検索精度向上**: ノイズとなる低頻度タグを除外

## 開発

### テスト実行

```bash
uv run pytest tests/
```

### コード品質

```bash
# 型チェック
uv run mypy src/

# フォーマット
uv run ruff format src/

# リント
uv run ruff check src/
```

## ライセンス

MIT License

## データソース

`danbooru-tags.txt` は [ComfyUI-Custom-Scripts](https://github.com/pythongosssss/ComfyUI-Custom-Scripts) で利用されている以下のデータをベースにしています：

https://gist.githubusercontent.com/pythongosssss/1d3efa6050356a08cea975183088159a/raw/a18fb2f94f9156cf4476b0c24a09544d6c0baec6/danbooru-tags.txt

オリジナルのタグ名はアンダーバー区切り（例: `blue_hair`）ですが、本プロジェクトではスペース区切り（例: `blue hair`）に変換して使用しています。

## 謝辞

- [ComfyUI-Custom-Scripts](https://github.com/pythongosssss/ComfyUI-Custom-Scripts) - Danbooruタグデータの提供元
- [Model Context Protocol](https://modelcontextprotocol.io/) - LLMツール統合の標準プロトコル
- [LanceDB](https://lancedb.com/) - 高速ベクトルデータベース
- [Sentence Transformers](https://www.sbert.net/) - 埋め込みモデルライブラリ