scanner-mcp 0.1.0__tar.gz

scanner_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+# Publishes to PyPI whenever you publish a GitHub Release.
+# Uses PyPI Trusted Publishing (OIDC) — no API token needs to be stored as a secret.
+# One-time setup on PyPI: create a "pending publisher" for project `scanner-mcp` with
+#   Owner: AminHA1248   Repo: scanner-mcp   Workflow: publish.yml   Environment: pypi
+# (https://pypi.org/manage/account/publishing/)
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check distributions
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

scanner_mcp-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python bytecode / caches
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Local scan output (if ever pointed inside the repo)
+Scans/
+*.bak

scanner_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amin Haji-Abolhassani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scanner_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: scanner-mcp
+Version: 0.1.0
+Summary: Generic MCP server exposing a scan tool to network (eSCL/AirScan) and USB (WIA/SANE/TWAIN) scanners.
+Project-URL: Homepage, https://github.com/AminHA1248/scanner-mcp
+Project-URL: Repository, https://github.com/AminHA1248/scanner-mcp
+Project-URL: Issues, https://github.com/AminHA1248/scanner-mcp/issues
+Author-email: Amin Haji-Abolhassani <amin.h.a@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: airscan,claude,escl,mcp,model-context-protocol,mopria,ocr,sane,scanner,scanning,twain,wia
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Scanners
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pillow>=10.0
+Requires-Dist: zeroconf>=0.132
+Provides-Extra: ocr
+Requires-Dist: pytesseract>=0.3.10; extra == 'ocr'
+Provides-Extra: twain
+Requires-Dist: pytwain>=2.3; (platform_system == 'Windows') and extra == 'twain'
+Description-Content-Type: text/markdown
+
+# scanner-mcp
+
+![License: MIT](https://img.shields.io/github/license/AminHA1248/scanner-mcp?color=blue)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
+![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)
+![Stars](https://img.shields.io/github/stars/AminHA1248/scanner-mcp?style=social)
+
+> **Let Claude scan and read paper documents** from any USB or network scanner.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AminHA1248/scanner-mcp/main/docs/demo.gif" alt="Ask Claude to scan a document; it calls the scan_document tool and reads the page back" width="760">
+</p>
+
+A **generic MCP server** that exposes a scanning tool to Claude (and any other MCP
+client). It works with **network scanners** through the standard **eSCL / AirScan /
+Mopria** protocol and with **USB scanners** through the platform driver stack —
+**WIA** on Windows and **SANE** on Linux/macOS. No vendor-specific driver code.
+
+When Claude needs to read a paper document, it can call `scan_document`, and the page
+image is returned inline so Claude can read it directly (optionally OCR'd to text, or
+saved as PDF).
+
+## What it exposes
+
+| Tool | Purpose |
+|------|---------|
+| `list_scanners` | Discover every scanner reachable from this machine (network + USB). |
+| `scan_document` | Scan a page/stack and return it as inline images, a saved file, and/or OCR text. |
+
+Backends are auto-detected and degrade gracefully — the same server runs on any OS and
+lights up whatever scanners it can reach:
+
+- **eSCL** (`_uscan._tcp` mDNS) — driverless network MFPs/scanners. *Cross-platform.*
+- **WIA** — USB (and some network) scanners on **Windows**, driven via PowerShell COM.
+- **TWAIN** — Windows scanners that expose only a TWAIN data source (older/pro units
+  with no usable WIA driver). Optional; needs `pytwain` + a TWAIN DSM (see below).
+- **SANE** (`scanimage`) — USB/network scanners on **Linux** and **macOS**.
+
+## Install
+
+```bash
+cd scanner-mcp
+python -m venv .venv
+# Windows:  .venv\Scripts\activate
+# macOS/Linux:  source .venv/bin/activate
+pip install -e .
+# optional OCR support:
+pip install -e ".[ocr]"      # also needs the Tesseract binary installed
+# optional TWAIN backend (Windows only):
+pip install -e ".[twain]"    # also needs a TWAIN DSM (see below)
+```
+
+Platform prerequisites:
+
+- **Windows**: nothing extra for WIA — it and PowerShell ship with Windows. Install the
+  scanner's normal Windows driver so it appears in *Devices*.
+  - **TWAIN (optional)**: install `pytwain` (`pip install -e ".[twain]"`) and make sure a
+    TWAIN **DSM** is present. 64-bit Python needs `TWAINDSM.dll` (shipped by most TWAIN
+    2.x drivers or the TWAIN DSM redistributable); 32-bit Python can use the classic
+    `twain_32.dll`. If neither is installed, the TWAIN backend just stays disabled.
+- **Linux**: `sudo apt install sane-utils` (provides `scanimage`).
+- **macOS**: `brew install sane-backends` for USB; network scanners work via eSCL with no extras.
+- **Network scanners**: just be on the same LAN/subnet; mDNS handles discovery.
+
+## Connect it to Claude
+
+### Claude Desktop
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "scanner": {
+      "command": "C:\\Users\\aminh\\scanner-mcp\\.venv\\Scripts\\scanner-mcp.exe"
+    }
+  }
+}
+```
+
+On macOS/Linux use the venv path `/path/to/scanner-mcp/.venv/bin/scanner-mcp`.
+
+### Claude Code (CLI)
+```bash
+claude mcp add scanner -- /path/to/scanner-mcp/.venv/bin/scanner-mcp
+```
+
+Restart the client, then ask Claude: *"List my scanners"* or *"Scan the document on the
+glass and read it."*
+
+## How you actually run it
+
+You normally **don't launch anything yourself** — Claude Desktop/Code starts the
+`scanner-mcp` server in the background (per the config above) and calls its tools when
+you ask. Running `scanner-mcp` by hand just starts the MCP server, which waits silently
+for JSON-RPC on stdin; it is not an interactive shell.
+
+To test the hardware **without Claude**, use the bundled CLI, [`test_scan.py`](test_scan.py):
+
+```bash
+# from the project folder, using the venv's Python
+python test_scan.py --list                 # discover scanners
+python test_scan.py --dpi 300              # scan (auto-selects if only one)
+python test_scan.py --scanner "<id>" --source adf --format pdf
+```
+
+## Configuration (env vars)
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `SCANNER_MCP_SAVE_DIR` | `~/Scans` | Where scans are written. |
+| `SCANNER_MCP_LOG` | `INFO` | Log level. |
+
+## `scan_document` options
+
+`scanner_id` (from `list_scanners`; auto if only one), `source`
+(`auto`/`platen`/`adf`/`adf-duplex`), `resolution` (DPI), `color_mode`
+(`color`/`gray`/`lineart`), `output_format` (`png`/`jpeg`/`pdf`), `save_dir`,
+`return_image` (inline images for Claude to read), `ocr` (extract text).
+
+## Notes & limitations
+
+- **eSCL** covers most scanners sold in the last ~decade (anything "AirPrint/AirScan"
+  or "Mopria" capable). Older USB-only units go through WIA/SANE instead.
+- PDF output for multi-page WIA scans is assembled with Pillow.
+- HTTPS eSCL devices use self-signed certs, so TLS verification is disabled for them
+  (typical for LAN scanners); prefer a trusted network.
+- This server performs local hardware I/O only — it does not send anything to the cloud.
+
+## License
+
+MIT

scanner_mcp-0.1.0/README.md

@@ -0,0 +1,132 @@
+# scanner-mcp
+
+![License: MIT](https://img.shields.io/github/license/AminHA1248/scanner-mcp?color=blue)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
+![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)
+![Stars](https://img.shields.io/github/stars/AminHA1248/scanner-mcp?style=social)
+
+> **Let Claude scan and read paper documents** from any USB or network scanner.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AminHA1248/scanner-mcp/main/docs/demo.gif" alt="Ask Claude to scan a document; it calls the scan_document tool and reads the page back" width="760">
+</p>
+
+A **generic MCP server** that exposes a scanning tool to Claude (and any other MCP
+client). It works with **network scanners** through the standard **eSCL / AirScan /
+Mopria** protocol and with **USB scanners** through the platform driver stack —
+**WIA** on Windows and **SANE** on Linux/macOS. No vendor-specific driver code.
+
+When Claude needs to read a paper document, it can call `scan_document`, and the page
+image is returned inline so Claude can read it directly (optionally OCR'd to text, or
+saved as PDF).
+
+## What it exposes
+
+| Tool | Purpose |
+|------|---------|
+| `list_scanners` | Discover every scanner reachable from this machine (network + USB). |
+| `scan_document` | Scan a page/stack and return it as inline images, a saved file, and/or OCR text. |
+
+Backends are auto-detected and degrade gracefully — the same server runs on any OS and
+lights up whatever scanners it can reach:
+
+- **eSCL** (`_uscan._tcp` mDNS) — driverless network MFPs/scanners. *Cross-platform.*
+- **WIA** — USB (and some network) scanners on **Windows**, driven via PowerShell COM.
+- **TWAIN** — Windows scanners that expose only a TWAIN data source (older/pro units
+  with no usable WIA driver). Optional; needs `pytwain` + a TWAIN DSM (see below).
+- **SANE** (`scanimage`) — USB/network scanners on **Linux** and **macOS**.
+
+## Install
+
+```bash
+cd scanner-mcp
+python -m venv .venv
+# Windows:  .venv\Scripts\activate
+# macOS/Linux:  source .venv/bin/activate
+pip install -e .
+# optional OCR support:
+pip install -e ".[ocr]"      # also needs the Tesseract binary installed
+# optional TWAIN backend (Windows only):
+pip install -e ".[twain]"    # also needs a TWAIN DSM (see below)
+```
+
+Platform prerequisites:
+
+- **Windows**: nothing extra for WIA — it and PowerShell ship with Windows. Install the
+  scanner's normal Windows driver so it appears in *Devices*.
+  - **TWAIN (optional)**: install `pytwain` (`pip install -e ".[twain]"`) and make sure a
+    TWAIN **DSM** is present. 64-bit Python needs `TWAINDSM.dll` (shipped by most TWAIN
+    2.x drivers or the TWAIN DSM redistributable); 32-bit Python can use the classic
+    `twain_32.dll`. If neither is installed, the TWAIN backend just stays disabled.
+- **Linux**: `sudo apt install sane-utils` (provides `scanimage`).
+- **macOS**: `brew install sane-backends` for USB; network scanners work via eSCL with no extras.
+- **Network scanners**: just be on the same LAN/subnet; mDNS handles discovery.
+
+## Connect it to Claude
+
+### Claude Desktop
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "scanner": {
+      "command": "C:\\Users\\aminh\\scanner-mcp\\.venv\\Scripts\\scanner-mcp.exe"
+    }
+  }
+}
+```
+
+On macOS/Linux use the venv path `/path/to/scanner-mcp/.venv/bin/scanner-mcp`.
+
+### Claude Code (CLI)
+```bash
+claude mcp add scanner -- /path/to/scanner-mcp/.venv/bin/scanner-mcp
+```
+
+Restart the client, then ask Claude: *"List my scanners"* or *"Scan the document on the
+glass and read it."*
+
+## How you actually run it
+
+You normally **don't launch anything yourself** — Claude Desktop/Code starts the
+`scanner-mcp` server in the background (per the config above) and calls its tools when
+you ask. Running `scanner-mcp` by hand just starts the MCP server, which waits silently
+for JSON-RPC on stdin; it is not an interactive shell.
+
+To test the hardware **without Claude**, use the bundled CLI, [`test_scan.py`](test_scan.py):
+
+```bash
+# from the project folder, using the venv's Python
+python test_scan.py --list                 # discover scanners
+python test_scan.py --dpi 300              # scan (auto-selects if only one)
+python test_scan.py --scanner "<id>" --source adf --format pdf
+```
+
+## Configuration (env vars)
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `SCANNER_MCP_SAVE_DIR` | `~/Scans` | Where scans are written. |
+| `SCANNER_MCP_LOG` | `INFO` | Log level. |
+
+## `scan_document` options
+
+`scanner_id` (from `list_scanners`; auto if only one), `source`
+(`auto`/`platen`/`adf`/`adf-duplex`), `resolution` (DPI), `color_mode`
+(`color`/`gray`/`lineart`), `output_format` (`png`/`jpeg`/`pdf`), `save_dir`,
+`return_image` (inline images for Claude to read), `ocr` (extract text).
+
+## Notes & limitations
+
+- **eSCL** covers most scanners sold in the last ~decade (anything "AirPrint/AirScan"
+  or "Mopria" capable). Older USB-only units go through WIA/SANE instead.
+- PDF output for multi-page WIA scans is assembled with Pillow.
+- HTTPS eSCL devices use self-signed certs, so TLS verification is disabled for them
+  (typical for LAN scanners); prefer a trusted network.
+- This server performs local hardware I/O only — it does not send anything to the cloud.
+
+## License
+
+MIT

scanner_mcp-0.1.0/docs/PROMOTION.md

@@ -0,0 +1,89 @@
+# Promotion kit
+
+Ready-to-paste copy for getting scanner-mcp in front of people. Nothing here posts
+automatically — pick what you want and I (or you) can submit it.
+
+---
+
+## 1. awesome-mcp-servers list entries
+
+**[punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)**
+(icons: 🐍 Python · 🏠 local · 🪟 Windows · 🐧 Linux · 🍎 macOS). Best-fit section:
+**🖥️ OS Automation**.
+
+```markdown
+- [AminHA1248/scanner-mcp](https://github.com/AminHA1248/scanner-mcp) 🐍 🏠 🪟 🐧 🍎 - Let Claude scan and read paper documents from any USB or network scanner (eSCL/AirScan, WIA, SANE, TWAIN)
+```
+
+**[wong2/awesome-mcp-servers](https://github.com/wong2/awesome-mcp-servers)** (plainer format):
+
+```markdown
+- [scanner-mcp](https://github.com/AminHA1248/scanner-mcp) - Scan and read paper documents from any USB or network scanner (eSCL, WIA, SANE, TWAIN)
+```
+
+**Directory sites that also accept submissions:** mcp.so, Glama, Smithery, PulseMCP,
+mcpservers.org. Most have a "submit" form and take the same one-line description.
+
+---
+
+## 2. Show HN
+
+**Title:**
+```
+Show HN: Scanner MCP – let Claude scan and read paper documents
+```
+
+**Body:**
+```
+I wanted Claude to be able to read a physical document, so I built an MCP server
+that exposes scan tools to any scanner Claude can reach.
+
+It's generic on purpose — instead of vendor SDKs it targets the standard interfaces
+each scanner category already exposes:
+- eSCL / AirScan / Mopria for network scanners (driverless, cross-platform)
+- WIA on Windows and SANE on Linux/macOS for USB
+- TWAIN on Windows for older units with no usable WIA driver
+
+Ask Claude "scan my document and read it" — it calls scan_document, and the page
+comes back as an inline image Claude reads directly (or OCR'd, or saved as PDF).
+
+Honest status: eSCL + WIA are tested on real hardware (a Canon TS3400); SANE and
+TWAIN are written to the standard interfaces but not yet hardware-verified.
+
+Repo (MIT): https://github.com/AminHA1248/scanner-mcp
+```
+
+---
+
+## 3. Reddit — r/ClaudeAI and r/mcp
+
+**Title:**
+```
+I built an MCP server that lets Claude scan and read paper documents
+```
+
+**Body:**
+```
+Sharing a weekend project: an MCP server that gives Claude a scan_document tool.
+Put a page on your scanner, ask Claude to "scan and read it," and it reads the page
+back (inline image, or OCR to text, or save a PDF).
+
+It's driverless where it can be — eSCL/AirScan for network scanners, WIA for Windows
+USB, SANE for Linux/macOS, TWAIN for older Windows scanners. One pip install, one line
+in your Claude Desktop config.
+
+Tested end-to-end on a Canon TS3400. MIT licensed, feedback welcome:
+https://github.com/AminHA1248/scanner-mcp
+```
+
+Reddit etiquette: post as "I built…", reply to comments, don't cross-post the same
+text to five subs at once. r/ClaudeAI and r/mcp are the on-topic homes.
+
+---
+
+## 4. Sequencing (do this order)
+
+1. Publish to PyPI so every link can say `pip install scanner-mcp` (see README/workflow).
+2. Submit the awesome-mcp PRs (durable, targeted traffic).
+3. Post Show HN once, mid-morning US time; then the Reddit posts.
+4. Watch GitHub → Insights → Traffic → Referrers and lean into whatever converts.

scanner_mcp-0.1.0/docs/make_demo.py

@@ -0,0 +1,176 @@
+"""Generate docs/demo.gif — a Claude-chat demo of scanner-mcp.
+
+Shows the real way the server is used: you ask Claude, it calls the
+`scan_document` tool, then reads the page back. Built from the actual scan.
+Run:  python docs/make_demo.py   (needs Pillow; uses the real scan if present).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+W, H = 860, 560
+TITLEBAR = 34
+PAD = 22
+LH = 25
+FONT_DIR = r"C:\Windows\Fonts"
+
+BG = (13, 17, 23)
+BAR = (22, 27, 34)
+BORDER = (48, 54, 61)
+GRAY = (139, 148, 158)
+CYAN = (86, 182, 194)
+GREEN = (86, 211, 100)
+YELLOW = (210, 168, 60)
+WHITE = (230, 237, 243)
+USER_BUBBLE = (35, 66, 120)
+PILL_BG = (26, 31, 39)
+
+HERE = Path(__file__).resolve().parent
+SCAN = Path(os.environ.get("DEMO_SCAN", r"C:\Users\aminh\Scans\scan-20260711-145133.png"))
+OUT = HERE / "demo.gif"
+
+
+def font(size, bold=False, mono=True):
+    if mono:
+        name = "consolab.ttf" if bold else "consola.ttf"
+    else:
+        name = "segoeuib.ttf" if bold else "segoeui.ttf"
+    try:
+        return ImageFont.truetype(os.path.join(FONT_DIR, name), size)
+    except Exception:
+        return ImageFont.load_default()
+
+
+F = font(18, mono=False)
+FB = font(18, bold=True, mono=False)
+FM = font(16)  # mono for tool pill
+FT = font(14, bold=True, mono=False)
+
+frames: list[Image.Image] = []
+durations: list[int] = []
+
+# --- prepare the scanned page (downscaled) --------------------------------
+doc_w = 214
+if SCAN.exists():
+    doc = Image.open(SCAN).convert("RGB")
+else:
+    doc = Image.new("RGB", (500, 700), (245, 244, 236))
+doc = doc.resize((doc_w, int(doc.height * doc_w / doc.width)))
+
+USER_TEXT = "Scan my document and read it"
+bullets = [
+    "Upstream → Packloop → Accumulator",
+    "2026-06-06  20:03:02 UTC",
+    "KPI · Offline processing",
+    "Yolo26 + SAM + active",
+    "Wedged GPU · 1TB  (userid 1000)",
+    "C39 > SMB > logs",
+]
+
+# --- layout ---------------------------------------------------------------
+ub_y0 = TITLEBAR + PAD
+ub_h = 42
+asst_y = ub_y0 + ub_h + 26
+pill_y = asst_y + 22
+msg_y = pill_y + 42
+doc_x = PAD
+doc_y = msg_y + 34
+doc_h = min(doc.height, H - doc_y - PAD)
+doc = doc.crop((0, 0, doc_w, doc_h))
+tx = doc_x + doc_w + 34
+bullets_y = doc_y + 2
+
+
+def base():
+    img = Image.new("RGB", (W, H), BG)
+    d = ImageDraw.Draw(img)
+    d.rectangle([0, 0, W, TITLEBAR], fill=BAR)
+    d.line([0, TITLEBAR, W, TITLEBAR], fill=BORDER)
+    for i, c in enumerate([(255, 95, 86), (255, 189, 46), (39, 201, 63)]):
+        d.ellipse([PAD + i * 22, 11, PAD + i * 22 + 12, 23], fill=c)
+    d.text((W // 2 - 26, 9), "Claude", font=FT, fill=GRAY)
+    return img, d
+
+
+def user_bubble(d, visible):
+    full_w = d.textlength(USER_TEXT, font=F)
+    bw = full_w + 28
+    x1 = W - PAD
+    x0 = x1 - bw
+    d.rounded_rectangle([x0, ub_y0, x1, ub_y0 + ub_h], radius=12, fill=USER_BUBBLE)
+    d.text((x0 + 14, ub_y0 + 9), visible, font=F, fill=WHITE)
+
+
+def tool_pill(d, state):
+    # state: None | "run" | "done"
+    if state is None:
+        return
+    label = "scanner ▸ scan_document"
+    tw = d.textlength(label, font=FM)
+    x0, y0 = PAD, pill_y
+    x1, y1 = x0 + tw + 58, y0 + 30
+    d.rounded_rectangle([x0, y0, x1, y1], radius=8, fill=PILL_BG, outline=BORDER)
+    dot = YELLOW if state == "run" else GREEN
+    d.ellipse([x0 + 12, y0 + 11, x0 + 20, y0 + 19], fill=dot)
+    d.text((x0 + 30, y0 + 6), label, font=FM, fill=GRAY)
+    tail = "  running…" if state == "run" else "  done"
+    d.text((x1 - 6, y0 + 6), "", font=FM)
+    d.text((x0 + 30 + tw + 6, y0 + 6), tail, font=FM, fill=dot)
+
+
+def push(visible=USER_TEXT, pill=None, msg=False, reveal=0, nb=0, dur=90, blue_line=True):
+    img, d = base()
+    user_bubble(d, visible)
+    tool_pill(d, pill)
+    if msg:
+        d.text((PAD, msg_y), "Scanned 1 page — here's what's on it:", font=F, fill=WHITE)
+    if reveal > 0:
+        h = int(doc_h * min(reveal, 1.0))
+        img.paste(doc.crop((0, 0, doc_w, h)), (doc_x, doc_y))
+        if blue_line and reveal < 1.0:
+            ImageDraw.Draw(img).line(
+                [doc_x, doc_y + h, doc_x + doc_w, doc_y + h], fill=(88, 166, 255), width=2
+            )
+    if nb > 0:
+        d2 = ImageDraw.Draw(img)
+        y = bullets_y
+        for i in range(nb):
+            d2.text((tx, y), "●", font=FB, fill=GREEN)
+            d2.text((tx + 22, y), bullets[i], font=F, fill=WHITE)
+            y += LH + 8
+    frames.append(img)
+    durations.append(dur)
+
+
+# 1) user types the request
+for i in range(len(USER_TEXT) + 1):
+    push(visible=USER_TEXT[:i], dur=45)
+push(dur=650)
+
+# 2) Claude invokes the tool
+push(pill="run", dur=500)
+push(pill="run", dur=900)
+push(pill="done", dur=600)
+
+# 3) message + scan-line reveal of the page
+push(pill="done", msg=True, dur=450)
+reveal_steps = 14
+for s in range(1, reveal_steps + 1):
+    push(pill="done", msg=True, reveal=s / reveal_steps, dur=70)
+
+# 4) Claude's read-back bullets type in
+for nb in range(len(bullets) + 1):
+    push(pill="done", msg=True, reveal=1.0, nb=nb, dur=90 if nb == 0 else 360)
+push(pill="done", msg=True, reveal=1.0, nb=len(bullets), dur=2600)
+
+# --- save -----------------------------------------------------------------
+pal = [f.quantize(colors=128, method=Image.FASTOCTREE) for f in frames]
+pal[0].save(
+    OUT, save_all=True, append_images=pal[1:], duration=durations,
+    loop=0, optimize=True, disposal=2,
+)
+print(f"wrote {OUT}  ({len(frames)} frames, {OUT.stat().st_size/1024:.0f} KB)")