# いらすとや MCP

**替助人工作者在日本免費插圖庫「いらすとや」找圖**，用來做衛教單、學習單、簡報。

台灣的醫院診所衛教單大量在用這個圖庫。問題是 **它只吃日文關鍵字** ——
你想找「注意力不集中」的插圖，站上要打的是 `集中` 或 `気が散る`，
而你不會知道要打什麼。

這支 MCP 的價值不在幫你連網，在 **幫你跨過那道語言牆**。

```
你說：幫我找「注意力不集中」的插圖
它做：認出「注意力」→ 展開成日文「集中」「気が散る」→ 去搜 → 回圖檔網址
```

---

## 五分鐘裝好

### 1. 拉下來

```bash
git clone https://github.com/scatjay/kxmind-irasutoya-mcp.git
```

### 2. 裝相依套件

```bash
pip install -r requirements.txt
```

### 3. 接進 Claude

在 Claude Desktop 的設定檔 `claude_desktop_config.json` 裡加：

```json
{
  "mcpServers": {
    "irasutoya": {
      "command": "python",
      "args": ["C:/你的路徑/kxmind-irasutoya-mcp/server.py"]
    }
  }
}
```

把 `C:/你的路徑/` 換成你剛才 clone 下來的實際位置。

### 4. 重開 Claude

**沒有帳號要註冊，沒有金鑰要申請，沒有環境變數要設。** 這支就這樣。

---

## 這個圖庫有多大

實測（2026-08-27）：

| | |
|---|---|
| 素材總數 | **25,419 張** |
| 分類數 | **239 個** |
| 最後更新 | 2026-08-25（還在持續增加） |

隨時可以用 `library_stats` 自己查最新數字。

---

## 九支工具

### 查詢層

| 工具 | 做什麼 |
|---|---|
| `search` | **最常用的一支。** 打中文，它自動翻成日文去搜 |
| `search_ja` | 直接用日文搜（你自己知道要打什麼的時候） |
| `list_topics` | 列出助人者常用主題的中日對照，不知道找什麼時先看這個 |
| `browse_label` | 依 いらすとや 自己的分類瀏覽（例如 `棒人間`、`医療`、`家族`） |
| `list_labels` | 列出分類（預設只列助人者用得到的，**附中譯**） |
| `library_stats` | 圖庫規模、分類數、最後更新時間 |

### 分析層

這一層才是 MCP 跟「自己開瀏覽器去搜」的真正差別。

| 工具 | 做什麼 |
|---|---|
| `suggest_for_worksheet` | **描述一個狀況，一次配好整份衛教單要用的插圖** |
| `license_check` | 算一下用幾張會不會超過免費額度 |

### 產出層

| 工具 | 做什麼 |
|---|---|
| `worksheet_template` | 產生**可列印 A4 ＋ 手機可讀**的衛教單骨架 |
| `inline_images` | **把圖就地內嵌**，解決 Artifact 擋外部圖的問題 |

---

## 做一份衛教單的完整流程

```
1. worksheet_template("我的衛教單.html")
      → A4 骨架，列印與手機的坑都填好了

2. search("讀字會跳行")  或  suggest_for_worksheet("…")
      → 拿到圖檔網址，貼進 HTML 的 <img src>
        （這一步刻意用真實網址，檔案才是人看得懂、改得動的）

3. inline_images("我的衛教單.html")
      → 把圖就地換成內嵌，檔案變成自包含

4. 發布成 Artifact
      → 有公開網址可以傳給家長，家長按 Ctrl+P 就能印
```

### 為什麼第 2、3 步要分開

**Artifact 有嚴格的 CSP，會擋掉所有外部主機的圖片**（唯一例外是 Google Fonts）。
いらすとや 的圖在 `blogger.googleusercontent.com`，直接連一定載不出來。

那為什麼不一開始就內嵌？因為一張 400px 的圖轉成 base64 大約 **148 KB**，
三張就是 445 KB —— 那些字元如果經過對話，會吃掉大量的額度，而且你完全看不懂。

所以：**寫的時候用網址（可讀），最後一步才內嵌（自包含）。
那幾十萬個字元只存在檔案裡，從頭到尾不進對話。**

### 版面已經處理好的事

`worksheet_template` 產生的骨架，這些坑都填過了（實測過三種寬度）：

| | 手機 375px | 桌機 1280px | 列印 |
|---|---|---|---|
| 版面 | 滿版、零橫向捲動 | **210mm 精準 A4** | A4 + 14mm 邊界 |
| 圖文 | 上下堆疊、圖放大置中 | 並排 | 不會被切在兩頁中間 |
| 字級 | 17px | 16px | 12pt |
| 工具列 | 精簡 | 完整 | **自動隱藏** |

另外：列印時自動轉白底（深色底吃碳粉，家長也看不清楚），
頁尾的連結會把網址一起印出來（拿到紙本才知道去哪）。

`suggest_for_worksheet` 是這支的核心。你不用自己拆關鍵字，直接講狀況：

> 一個小三的孩子，讀字會跳行、抄聯絡簿抄不完，家長很焦慮

它會自己拆出「兒童 / 學習障礙 / 聯絡簿 / 焦慮 / 家長」這幾條線，
每條線各配一張，湊成一份版面用得上的組合 —— 而不是同一個概念塞五張。

> ⚠️ 你描述的是**狀況**，不是**個案**。
> 沒有姓名、沒有病歷、沒有可辨識資訊 —— **這本來就是去識別化的**，
> 不需要額外的合規動作。

---

## 🔴 授權：這一段請務必讀完

いらすとや 的規定原文：

> 商用目的の場合、一つの作成物の中に **20点まで** は無料でご利用いただけます。
> それ以上の点数をご希望される場合は **有償** となります。

**【繁體中文】** 商業用途時，同一件作品中最多可免費使用 **20 張**；
超過就要付費，**每張 1,100 日圓（含稅）**。

還有一條同樣重要：

> **素材そのものの販売・再配布は禁止。**
>
> **【繁體中文】** 素材本身不可販售、不可再散布。

### 這對你的實際意義

| 你要做的 | 結果 |
|---|---|
| 一份衛教單用 1–3 張 | ✅ **完全免費**，這正是醫院診所在做的事 |
| 一份簡報用 10 張 | ✅ 免費 |
| 一套 20 張以上的系列教材 | ⚠️ **要付費**，而且是全部計價 |
| 把圖檔重新打包分享給別人 | ❌ **禁止** |

### 「內嵌進作品」和「再散布」是兩件不同的事

這個區別很重要，因為 `inline_images` 確實會下載圖片：

| 行為 | 這是什麼 |
|---|---|
| 把插圖放進**你自己做的衛教單**裡（不管是 Word、PPT、還是內嵌成 data: URI） | **正常使用**，就是圖庫本來預期的用途，受 20 張規則規範 |
| 把圖檔本身重新打包、當素材集發給別人 | **再散布**，這是被禁止的 |

`inline_images` 做的是前者 —— 跟你把圖貼進 Word 是同一件事，
只是換成 HTML 的寫法。

### 這支程式為此做的設計

- **搜尋類的工具只回傳網址**，不下載任何東西
- **`inline_images` 只在你明講的時候才下載**，而且只處理**你自己那個 HTML 檔**裡已經出現的圖
- **預設上限 20 張**，剛好等於授權的免費上限 —— 這不是技術限制，是刻意擋在這裡的
- **repo 本身不夾帶任何素材檔**
- 每次搜尋與內嵌的結果，最後都會附上剩餘額度提醒

> ⚠️ 診所免費發送的衛教單算不算「商用」，是灰色地帶。
> **作者不是律師。** 實務上的安全線：單張沒問題，成套要留意。
> 真的要大量使用，請直接洽詢 いらすとや 官方。

官方說明：<https://www.irasutoya.com/p/terms.html>

---

## 技術筆記

いらすとや 是 Blogger 架的，有標準 feed API，**不用爬 HTML**：

```
GET https://www.irasutoya.com/feeds/posts/default?alt=json&q=<日文關鍵字>&max-results=N
```

回傳的每一筆有：

- `title.$t` — 標題（日文）
- `link[rel=alternate].href` — 頁面網址
- `content.$t` — 內含圖檔的 `<img src>`
- `category[].term` — 標籤

`robots.txt` 是空的（0 bytes），沒有任何爬取限制。
即使如此，這支還是加了 **0.8 秒的請求間隔、序列不並發** ——
這是免費資源，不要把人家打掛。

---

## 中日對照表

目前收了 **167 個中文詞**，涵蓋：

情緒（含細緻版）/ 兒童與發展 / 學校 / 家庭 / 心理與助人 / 醫療 / 長照與高齡 /
生活與 3C / 版面裝飾 / **助人者自己的處境** / **臨床議題** / **介入與技巧**

其中 65 個詞是 **實際打過 API 驗證過的** —— 候選詞全部拿去真的搜一次，
搜不到的直接剔掉。「選擇性緘默」就是這樣被剔掉的：概念存在，但圖庫裡沒有對應素材。

意外撈到的好東西：`沙盤→箱庭`、`桌遊→ボードゲーム`、`繪本→絵本`、
`藝術治療→お絵かき`、`代幣→シール`、`耗竭→燃え尽き症候群`。

一個中文詞會對到多個日文詞，因為日文同一個概念常有
**漢字、假名、外來語** 三種寫法，只打一種會漏掉一大半素材。

```python
"注意力": ["集中", "気が散る"],
"諮商":   ["カウンセリング", "相談"],
"放鬆":   ["リラックス", "深呼吸", "瞑想"],
```

覺得少了什麼詞，直接改 `server.py` 裡的 `ZH_TO_JA` 就行 —— 這就是給你改的。

---

## 授權

**程式碼**：MIT（見 LICENSE）
**插圖素材**：版權屬 いらすとや，本專案不擁有、不散布任何素材，
使用時請遵守上方的授權規定。