内容
# danbooru-mcp
本地 Danbooru 标签嵌入搜索和验证的独立 MCP 服务器。
预期的工作流程是：
1. LLM 客户端将用户请求分成短小的视觉单元。
2. LLM 调用此 MCP 服务器获取 Danbooru 标签候选项。
3. LLM 选择最佳候选项并编写提示。
4. LLM 再次调用此 MCP 服务器验证最终标签。
服务器不会调用 LLM。它仅提供本地嵌入搜索、元数据查找和标签验证。
## 工具
- `search_tags`：为一个短小的搜索单元搜索候选项。
- `search_tags_batch`：为多个短小的搜索单元搜索候选项。
- `validate_tags`：根据本地 CSV 验证最终标签，并可选地为无效标签搜索建议。
- `get_tag_info`：返回类别、频率、韩文定义和别名。
- `health`：检查本地 CSV/索引路径。
## 文件
该项目是自包含的。默认情况下，它使用此目录下的路径：
```text
danbooru-tags.csv 必需的源 CSV
models/ 下载的嵌入模型
data/lancedb_b/ 构建的 LanceDB 索引
.env 可选的本地覆盖
```
CSV 必须具有此头部/顺序：
```csv
name,category,post_count,description
```
类别含义：
```text
0 一般
1 艺术家
3 版权
4 角色
5 元数据
```
## 安装
推荐：
```bash
cd /path/to/danbooru-mcp
uv sync
```
替代：
```bash
pip install -e .
```
如果您需要特定 CUDA 版本的 torch，请根据您的 GPU 环境安装，然后安装此软件包。
## 设置
1. 将 `danbooru-tags.csv` 放在项目根目录。
2. 下载嵌入模型：
```bash
uv run danbooru-mcp-download-model
```
这会将 `intfloat/multilingual-e5-large` 下载到 `models/multilingual-e5-large`。
3. 构建默认索引，变体 `b`：
```bash
uv run danbooru-mcp-build-index
```
变体 `b` 嵌入英文标签名称 + 韩文别名。这是默认变体，因为混合韩文/英文提示单元往往能与之配合良好。
可选变体：
```bash
uv run danbooru-mcp-build-index a
uv run danbooru-mcp-build-index c
uv run danbooru-mcp-build-index --all
```
变体：
```text
a = 英文标签名称 + 韩文定义 + 别名
b = 英文标签名称 + 韩文别名
c = 韩文定义 + 别名，在需要时回退到英文标签名称
```
## 运行
标准输入输出传输：
```bash
uv run danbooru-mcp
```
MCP 配置示例：
```json
{
"mcpServers": {
"danbooru": {
"command": "uv",
"args": ["run", "danbooru-mcp"],
"cwd": "/path/to/danbooru-mcp",
"env": {
"EMBEDDING_DEVICE": "cpu"
}
}
}
}
```
用于 GPU 搜索/模型加载：
```json
{
"env": {
"EMBEDDING_DEVICE": "cuda"
}
}
```
HTTP 传输：
```bash
CUDA_VISIBLE_DEVICES=1 uv run danbooru-mcp --transport http --host 127.0.0.1 --port 8000
```
MCP 端点是 `POST http://127.0.0.1:8000/mcp`。您也可以使用专用脚本：
```bash
CUDA_VISIBLE_DEVICES=1 uv run danbooru-mcp-http
```
HTTP 环境变量：
```text
DANBOORU_MCP_TRANSPORT=stdio|http|sse
DANBOORU_MCP_HOST=127.0.0.1
DANBOORU_MCP_PORT=8000
DANBOORU_MCP_HTTP_PATH=/mcp
DANBOORU_MCP_SSE_PATH=/sse
DANBOORU_MCP_MESSAGES_PATH=/messages
DANBOORU_MCP_CORS_ORIGIN=*
DANBOORU_MCP_MAX_BODY_BYTES=10485760
```
SSE 传输：
```bash
CUDA_VISIBLE_DEVICES=1 uv run danbooru-mcp --transport sse --host 127.0.0.1 --port 8000
```
SSE 流端点是 `GET http://127.0.0.1:8000/sse`。服务器发送一个包含会话特定消息 URL 的 `endpoint` 事件，例如 `/messages?session_id=...`。MCP 客户端然后向该 URL 发送 JSON-RPC 消息，并通过 SSE 流上的 `message` 事件接收 JSON-RPC 响应。
您也可以使用专用脚本：
```bash
CUDA_VISIBLE_DEVICES=1 uv run danbooru-mcp-sse
```
## 环境
复制 `.env.example` 到 `.env` 以进行本地覆盖：
```bash
cp .env.example .env
```
支持的变量：
```text
EMBEDDING_DEVICE=cpu|cuda
DATA_DIR=/path/to/data
MODELS_DIR=/path/to/models
DANBOORU_TAGS_CSV=/path/to/danbooru-tags.csv
DANBOORU_INDEX_VARIANT=b
EMBED_BATCH_SIZE=256
MIN_FREQUENCY=50
```
## 推荐的 LLM 工作流程
避免将一个长句子作为一个 `query` 发送。嵌入将平均许多概念，顶级候选项将变得嘈杂。
更好：
```json
{
"queries": ["은발", "트윈테일", "빨간 눈", "비 오는 거리", "우산"],
"top_k": 8,
"categories": ["general"]
}
```
搜索响应默认情况下是紧凑的，以保持 MCP 上下文小。通常，结果仅包括 `tag` 和 `score`。当您需要类别、频率、定义、层次结构或别名时，请传递 `"include_details": true`。
然后从返回的候选项中选择并验证最终列表：
```json
{
"tags": ["grey_hair", "twintails", "red_eyes", "rain", "umbrella"]
}
```
验证器接受下划线和空格形式。如果 CSV 规范标签是 `grey hair`，则 `grey_hair` 规范为 `grey hair`。
## 注意
- 第一次搜索加载嵌入模型，可能需要几秒钟。
- 构建索引是昂贵的步骤。建议使用 GPU。
- 服务器仅将 MCP 协议消息写入标准输出。模型进度输出被重定向到标准错误，因此标准输入输出 MCP 客户端不会损坏。
## 致谢
https://github.com/joykst96/danbooru-tag-rag
