scanner-mcp 0.1.0__py3-none-any.whl

scanner_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""scanner-mcp: a generic MCP server exposing scan tools for USB and network scanners."""
+
+__version__ = "0.1.0"

scanner_mcp/backends/__init__.py

@@ -0,0 +1,45 @@
+"""Backend registry.
+
+Backends are probed lazily; any that raise on construction or report themselves as
+unavailable (missing tools/OS support) are simply skipped, so the same server runs on
+Windows, macOS and Linux and exposes whatever scanners it can reach.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .base import Backend
+
+log = logging.getLogger("scanner_mcp.backends")
+
+
+def all_backends() -> list[Backend]:
+    from .escl import ESCLBackend
+    from .sane import SaneBackend
+    from .twain import TWAINBackend
+    from .wia import WIABackend
+
+    backends: list[Backend] = []
+    for cls in (ESCLBackend, SaneBackend, WIABackend, TWAINBackend):
+        try:
+            b = cls()
+        except Exception as exc:  # pragma: no cover - defensive
+            log.debug("backend %s failed to construct: %s", cls.__name__, exc)
+            continue
+        try:
+            if b.available():
+                backends.append(b)
+        except Exception as exc:  # pragma: no cover - defensive
+            log.debug("backend %s availability check failed: %s", cls.__name__, exc)
+    return backends
+
+
+def backend_for(scanner_id: str) -> Backend | None:
+    for b in all_backends():
+        if b.handles(scanner_id):
+            return b
+    return None
+
+
+__all__ = ["Backend", "all_backends", "backend_for"]

scanner_mcp/backends/base.py

@@ -0,0 +1,29 @@
+"""Backend abstraction. Each backend discovers scanners and performs scans."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..models import ScannerInfo, ScanOptions, ScanResult
+
+
+class Backend(ABC):
+    #: Human-readable backend name.
+    name: str = "base"
+    #: Prefix used on scanner ids owned by this backend (e.g. "escl").
+    prefix: str = "base"
+
+    def available(self) -> bool:
+        """Whether this backend can run in the current environment."""
+        return True
+
+    def handles(self, scanner_id: str) -> bool:
+        return scanner_id.startswith(self.prefix + ":")
+
+    @abstractmethod
+    def list_scanners(self) -> list[ScannerInfo]:
+        ...
+
+    @abstractmethod
+    def scan(self, scanner_id: str, options: ScanOptions) -> ScanResult:
+        ...

scanner_mcp/backends/escl.py

@@ -0,0 +1,223 @@
+"""eSCL backend: driverless network scanning (a.k.a. Apple AirScan / Mopria eScan).
+
+eSCL is an HTTP/XML protocol supported by the vast majority of modern network
+multifunction printers and scanners. Devices are discovered over mDNS
+(``_uscan._tcp`` / ``_uscans._tcp``) and scanned with a small set of HTTP calls:
+
+    GET  {base}/ScannerCapabilities   -> supported resolutions / max page size
+    POST {base}/ScanJobs              -> 201 Created, Location: {job}
+    GET  {job}/NextDocument           -> page bytes (repeat until 404)
+
+No vendor driver is required, which is what makes this backend "generic".
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+import xml.etree.ElementTree as ET
+
+import httpx
+
+from ..models import ScannerInfo, ScanOptions, ScanResult
+from .base import Backend
+
+log = logging.getLogger("scanner_mcp.escl")
+
+_COLOR = {"color": "RGB24", "gray": "Grayscale8", "lineart": "BlackAndWhite1"}
+_FORMAT_MIME = {"png": "image/png", "jpeg": "image/jpeg", "pdf": "application/pdf"}
+# eSCL scan regions are always expressed in units of 1/300 inch.
+_A4_300 = (2480, 3508)
+
+
+def _discover(timeout: float = 2.5) -> list[dict]:
+    """Discover eSCL devices via mDNS. Returns dicts with base url + metadata."""
+    try:
+        from zeroconf import ServiceBrowser, ServiceListener, Zeroconf
+    except Exception:
+        log.debug("zeroconf unavailable; skipping eSCL discovery")
+        return []
+
+    found: dict[str, dict] = {}
+
+    class _Listener(ServiceListener):
+        def __init__(self, secure: bool):
+            self.secure = secure
+
+        def _resolve(self, zc, type_, name):
+            info = zc.get_service_info(type_, name, timeout=int(timeout * 1000))
+            if not info:
+                return
+            addrs = info.parsed_addresses() or []
+            if not addrs:
+                return
+            host = addrs[0]
+            props = {
+                (k.decode() if isinstance(k, bytes) else k): (
+                    v.decode(errors="replace") if isinstance(v, bytes) else v
+                )
+                for k, v in (info.properties or {}).items()
+            }
+            rs = props.get("rs", "eSCL").strip("/")
+            scheme = "https" if self.secure else "http"
+            base = f"{scheme}://{host}:{info.port}/{rs}"
+            found[base] = {
+                "base": base,
+                "host": host,
+                "port": info.port,
+                "name": props.get("ty") or name.split(".")[0],
+                "note": props.get("note", ""),
+                "uuid": props.get("UUID") or props.get("uuid", ""),
+            }
+
+        def add_service(self, zc, type_, name):
+            self._resolve(zc, type_, name)
+
+        def update_service(self, zc, type_, name):
+            self._resolve(zc, type_, name)
+
+        def remove_service(self, zc, type_, name):
+            pass
+
+    zc = Zeroconf()
+    try:
+        ServiceBrowser(zc, "_uscan._tcp.local.", _Listener(secure=False))
+        ServiceBrowser(zc, "_uscans._tcp.local.", _Listener(secure=True))
+        time.sleep(timeout)
+    finally:
+        zc.close()
+    return list(found.values())
+
+
+def _strip_ns(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+class ESCLBackend(Backend):
+    name = "eSCL (network / AirScan)"
+    prefix = "escl"
+
+    def __init__(self, discovery_timeout: float = 2.5):
+        self._discovery_timeout = discovery_timeout
+
+    def available(self) -> bool:
+        try:
+            import zeroconf  # noqa: F401
+        except Exception:
+            return False
+        return True
+
+    def list_scanners(self) -> list[ScannerInfo]:
+        scanners = []
+        for dev in _discover(self._discovery_timeout):
+            scanners.append(
+                ScannerInfo(
+                    id=f"escl:{dev['base']}",
+                    name=dev["name"],
+                    backend=self.name,
+                    connection="network",
+                    sources=["platen", "adf"],
+                    detail={k: v for k, v in dev.items() if k != "base"},
+                )
+            )
+        return scanners
+
+    # -- scanning -------------------------------------------------------------
+
+    def _base_url(self, scanner_id: str) -> str:
+        return scanner_id[len("escl:") :]
+
+    def _max_region(self, client: httpx.Client, base: str) -> tuple[int, int]:
+        try:
+            r = client.get(f"{base}/ScannerCapabilities", timeout=10)
+            r.raise_for_status()
+            root = ET.fromstring(r.content)
+            w = h = None
+            for el in root.iter():
+                tag = _strip_ns(el.tag)
+                if tag == "MaxWidth" and el.text:
+                    w = int(el.text)
+                elif tag == "MaxHeight" and el.text:
+                    h = int(el.text)
+            if w and h:
+                return w, h
+        except Exception as exc:
+            log.debug("capabilities fetch failed (%s); using A4 default", exc)
+        return _A4_300
+
+    def _build_settings(self, opts: ScanOptions, region: tuple[int, int]) -> str:
+        w, h = region
+        source = "Feeder" if opts.source in ("adf", "adf-duplex") else "Platen"
+        duplex = "true" if opts.source == "adf-duplex" else "false"
+        color = _COLOR.get(opts.color_mode, "RGB24")
+        doc_format = _FORMAT_MIME.get(opts.output_format, "image/png")
+        return f"""<?xml version="1.0" encoding="UTF-8"?>
+<scan:ScanSettings xmlns:scan="http://schemas.hp.com/imaging/escl/2011/05/03"
+                   xmlns:pwg="http://www.pwg.org/schemas/2010/12/sm">
+  <pwg:Version>2.6</pwg:Version>
+  <pwg:ScanRegions pwg:MustHonor="false">
+    <pwg:ScanRegion>
+      <pwg:XOffset>0</pwg:XOffset>
+      <pwg:YOffset>0</pwg:YOffset>
+      <pwg:Width>{w}</pwg:Width>
+      <pwg:Height>{h}</pwg:Height>
+      <pwg:ContentRegionUnits>escl:ThreeHundredthsOfInches</pwg:ContentRegionUnits>
+    </pwg:ScanRegion>
+  </pwg:ScanRegions>
+  <pwg:InputSource>{source}</pwg:InputSource>
+  <scan:Duplex>{duplex}</scan:Duplex>
+  <scan:ColorMode>{color}</scan:ColorMode>
+  <scan:XResolution>{opts.resolution}</scan:XResolution>
+  <scan:YResolution>{opts.resolution}</scan:YResolution>
+  <pwg:DocumentFormat>{doc_format}</pwg:DocumentFormat>
+  <scan:DocumentFormatExt>{doc_format}</scan:DocumentFormatExt>
+</scan:ScanSettings>"""
+
+    def scan(self, scanner_id: str, options: ScanOptions) -> ScanResult:
+        base = self._base_url(scanner_id)
+        verify = not base.startswith("https")  # printers ship self-signed certs
+        client = httpx.Client(verify=False if base.startswith("https") else True)
+        try:
+            region = self._max_region(client, base)
+            body = self._build_settings(options, region)
+            resp = client.post(
+                f"{base}/ScanJobs",
+                content=body.encode("utf-8"),
+                headers={"Content-Type": "text/xml"},
+                timeout=30,
+            )
+            if resp.status_code not in (200, 201):
+                raise RuntimeError(
+                    f"scanner rejected job ({resp.status_code}): {resp.text[:200]}"
+                )
+            job = resp.headers.get("Location")
+            if not job:
+                raise RuntimeError("scanner did not return a job Location header")
+            if job.startswith("/"):
+                # Some devices return a relative path.
+                root = re.match(r"^(https?://[^/]+)", base)
+                job = (root.group(1) if root else base) + job
+
+            pages = self._retrieve_pages(client, job)
+            mime = _FORMAT_MIME.get(options.output_format, "image/png")
+            if not pages:
+                raise RuntimeError("scan produced no pages (empty feeder?)")
+            return ScanResult(pages=pages, mime=mime, backend=self.name, scanner_id=scanner_id)
+        finally:
+            client.close()
+
+    def _retrieve_pages(self, client: httpx.Client, job: str) -> list[bytes]:
+        pages: list[bytes] = []
+        for _ in range(200):  # hard cap to avoid runaway feeders
+            r = client.get(f"{job}/NextDocument", timeout=120)
+            if r.status_code == 404:
+                break  # no more pages
+            if r.status_code == 503:
+                time.sleep(1.0)  # device still warming up / scanning
+                continue
+            r.raise_for_status()
+            if not r.content:
+                break
+            pages.append(r.content)
+        return pages

scanner_mcp/backends/sane.py

@@ -0,0 +1,126 @@
+"""SANE backend: wraps the ``scanimage`` CLI (Linux, and macOS via Homebrew).
+
+Covers most USB scanners plus many network scanners through SANE's own backends.
+Requires the ``sane-utils`` package (provides ``scanimage``); if it is not on PATH the
+backend reports itself unavailable and is skipped.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from ..models import ScannerInfo, ScanOptions, ScanResult
+from .base import Backend
+
+log = logging.getLogger("scanner_mcp.sane")
+
+_MODE = {"color": "Color", "gray": "Gray", "lineart": "Lineart"}
+# scanimage understands png/jpeg/tiff/pdf via --format on recent versions.
+_FORMAT = {"png": ("png", "image/png"), "jpeg": ("jpeg", "image/jpeg"), "pdf": ("pdf", "application/pdf")}
+_DEVICE_RE = re.compile(r"device `([^']+)' is a (.+)")
+
+
+class SaneBackend(Backend):
+    name = "SANE (scanimage)"
+    prefix = "sane"
+
+    def available(self) -> bool:
+        return shutil.which("scanimage") is not None
+
+    def list_scanners(self) -> list[ScannerInfo]:
+        try:
+            out = subprocess.run(
+                ["scanimage", "-L"],
+                capture_output=True,
+                text=True,
+                timeout=20,
+            ).stdout
+        except Exception as exc:
+            log.debug("scanimage -L failed: %s", exc)
+            return []
+        scanners = []
+        for line in out.splitlines():
+            m = _DEVICE_RE.search(line)
+            if not m:
+                continue
+            dev, desc = m.group(1), m.group(2)
+            conn = "network" if any(t in dev for t in ("net:", "airscan", "escl")) else "usb"
+            scanners.append(
+                ScannerInfo(
+                    id=f"sane:{dev}",
+                    name=desc.strip(),
+                    backend=self.name,
+                    connection=conn,
+                    sources=["platen", "adf"],
+                    detail={"device": dev},
+                )
+            )
+        return scanners
+
+    def scan(self, scanner_id: str, options: ScanOptions) -> ScanResult:
+        device = scanner_id[len("sane:") :]
+        fmt_name, mime = _FORMAT.get(options.output_format, ("png", "image/png"))
+        mode = _MODE.get(options.color_mode, "Color")
+
+        with tempfile.TemporaryDirectory(prefix="scanmcp_") as td:
+            tmp = Path(td)
+            cmd = [
+                "scanimage",
+                "-d", device,
+                "--format", fmt_name,
+                "--resolution", str(options.resolution),
+                "--mode", mode,
+            ]
+            source = self._source_arg(options)
+            multipage = options.source in ("adf", "adf-duplex")
+            if source:
+                cmd += ["--source", source]
+
+            if multipage:
+                # --batch writes out-1.ext, out-2.ext, ... for every fed sheet.
+                pattern = str(tmp / f"out-%d.{fmt_name}")
+                cmd += ["--batch=" + pattern]
+                self._run(cmd, allow_no_docs=True)
+                files = sorted(tmp.glob(f"out-*.{fmt_name}"), key=_page_index)
+            else:
+                out_file = tmp / f"out.{fmt_name}"
+                cmd += ["-o", str(out_file)]
+                self._run(cmd)
+                files = [out_file] if out_file.exists() else []
+
+            pages = [f.read_bytes() for f in files if f.exists() and f.stat().st_size > 0]
+
+        if not pages:
+            raise RuntimeError("scanimage produced no output (check device/source and that paper is loaded)")
+        return ScanResult(pages=pages, mime=mime, backend=self.name, scanner_id=scanner_id)
+
+    @staticmethod
+    def _source_arg(options: ScanOptions) -> str | None:
+        if options.source == "platen":
+            return "Flatbed"
+        if options.source == "adf":
+            return "ADF"
+        if options.source == "adf-duplex":
+            return "ADF Duplex"
+        return None  # "auto": let the driver decide
+
+    @staticmethod
+    def _run(cmd: list[str], allow_no_docs: bool = False) -> None:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+        if proc.returncode != 0:
+            err = (proc.stderr or "").strip()
+            # scanimage --batch exits non-zero with "no more documents" once the
+            # feeder empties, which is a normal end-of-batch condition.
+            if allow_no_docs and re.search(r"no more documents|Document feeder out of documents", err, re.I):
+                return
+            raise RuntimeError(f"scanimage failed: {err or proc.stdout.strip()}")
+
+
+def _page_index(p: Path) -> int:
+    m = re.search(r"out-(\d+)\.", p.name)
+    return int(m.group(1)) if m else 0

scanner_mcp/backends/twain.py

@@ -0,0 +1,210 @@
+"""TWAIN backend: Windows scanners exposed through the legacy TWAIN API.
+
+Complements WIA. Some scanners — often older units, or professional document
+scanners — ship only a TWAIN data source and no usable WIA driver. This backend
+reaches those through the optional ``pytwain`` package (imported as ``twain``).
+
+Requirements (all Windows-only):
+  * ``pip install "scanner-mcp[twain]"`` (installs pytwain), and
+  * a TWAIN **DSM** (Data Source Manager) present on the system:
+      - 64-bit Python needs ``TWAINDSM.dll`` (shipped by TWAIN 2.x drivers or the
+        TWAIN DSM redistributable), or
+      - use 32-bit Python, which can load the classic ``twain_32.dll``.
+
+If pytwain is missing or no DSM/driver is installed, the backend simply reports
+itself unavailable and is skipped — the rest of the server keeps working.
+"""
+
+from __future__ import annotations
+
+import logging
+import platform
+
+from ..models import ScannerInfo, ScanOptions, ScanResult
+from .base import Backend
+
+log = logging.getLogger("scanner_mcp.twain")
+
+# pytwain logs a noisy INFO/ERROR pair when no TWAIN DSM is installed (the common
+# case on machines with only WIA scanners). Keep our own graceful handling; hush its.
+logging.getLogger("twain").setLevel(logging.CRITICAL)
+
+# TWAIN pixel types: TWPT_BW=0, TWPT_GRAY=1, TWPT_RGB=2.
+_PIXELTYPE = {"color": 2, "gray": 1, "lineart": 0}
+
+
+def _desktop_hwnd():
+    """A window handle for the TWAIN source manager; TWAIN requires one."""
+    import ctypes
+
+    try:
+        return ctypes.windll.user32.GetDesktopWindow()
+    except Exception:
+        return 0
+
+
+class TWAINBackend(Backend):
+    name = "TWAIN (Windows)"
+    prefix = "twain"
+
+    def __init__(self):
+        self._avail: bool | None = None  # cached availability probe
+
+    # -- availability ---------------------------------------------------------
+
+    def available(self) -> bool:
+        if self._avail is not None:
+            return self._avail
+        self._avail = self._probe()
+        return self._avail
+
+    def _probe(self) -> bool:
+        if platform.system() != "Windows":
+            return False
+        try:
+            import twain  # noqa: F401
+        except Exception:
+            log.debug("pytwain not installed; TWAIN backend disabled")
+            return False
+        # The DSM only loads if a TWAIN data-source manager is actually installed.
+        sm = None
+        try:
+            sm = self._open_sm()
+            return True
+        except Exception as exc:
+            log.debug("TWAIN DSM not available (%s); backend disabled", exc)
+            return False
+        finally:
+            self._close(sm)
+
+    # -- helpers --------------------------------------------------------------
+
+    @staticmethod
+    def _open_sm():
+        import twain
+
+        return twain.SourceManager(_desktop_hwnd())
+
+    @staticmethod
+    def _close(obj) -> None:
+        if obj is None:
+            return
+        try:
+            obj.close()
+        except Exception:
+            try:
+                obj.destroy()
+            except Exception:
+                pass
+
+    @staticmethod
+    def _set_cap(src, cap: int, type_id: int, value) -> None:
+        """Set a capability, ignoring sources that don't support it."""
+        try:
+            src.set_capability(cap, type_id, value)
+        except Exception as exc:
+            log.debug("capability %s not set: %s", cap, exc)
+
+    # -- API ------------------------------------------------------------------
+
+    def list_scanners(self) -> list[ScannerInfo]:
+        if not self.available():
+            return []
+        sm = None
+        try:
+            sm = self._open_sm()
+            names = list(sm.source_list)
+        except Exception as exc:
+            log.debug("TWAIN source enumeration failed: %s", exc)
+            return []
+        finally:
+            self._close(sm)
+
+        scanners = []
+        for name in names:
+            scanners.append(
+                ScannerInfo(
+                    id=f"twain:{name}",
+                    name=name,
+                    backend=self.name,
+                    connection="unknown",
+                    sources=["platen", "adf"],
+                    detail={"source": name},
+                )
+            )
+        return scanners
+
+    def scan(self, scanner_id: str, options: ScanOptions) -> ScanResult:
+        import twain
+
+        source_name = scanner_id[len("twain:") :]
+        sm = None
+        src = None
+        try:
+            sm = self._open_sm()
+            src = sm.open_source(source_name)
+            if src is None:
+                raise RuntimeError(f"could not open TWAIN source {source_name!r}")
+
+            self._configure(src, options, twain)
+
+            # Non-UI acquisition: don't pop the driver's dialog.
+            src.request_acquire(show_ui=False, modal_ui=False)
+
+            raw_pages = self._transfer(src, twain, multipage=options.source in ("adf", "adf-duplex"))
+        finally:
+            self._close(src)
+            self._close(sm)
+
+        if not raw_pages:
+            raise RuntimeError("TWAIN scan produced no images (empty feeder or cancelled?)")
+
+        # TWAIN native transfer yields BMP (DIB) bytes; normalize to the requested format.
+        from ..imaging import convert_image, have_pil, images_to_pdf
+
+        want_pdf = options.output_format == "pdf"
+        img_fmt = "jpeg" if options.output_format == "jpeg" else "png"
+        if have_pil():
+            pages = [convert_image(p, img_fmt) for p in raw_pages]
+        else:
+            pages = raw_pages  # best effort; bytes are BMP
+
+        mime = f"image/{img_fmt}"
+        if want_pdf:
+            pages = [images_to_pdf(pages)]
+            mime = "application/pdf"
+        return ScanResult(pages=pages, mime=mime, backend=self.name, scanner_id=scanner_id)
+
+    def _configure(self, src, options: ScanOptions, twain) -> None:
+        self._set_cap(src, twain.ICAP_PIXELTYPE, twain.TWTY_UINT16,
+                      _PIXELTYPE.get(options.color_mode, 2))
+        for cap in (twain.ICAP_XRESOLUTION, twain.ICAP_YRESOLUTION):
+            self._set_cap(src, cap, twain.TWTY_FIX32, float(options.resolution))
+
+        use_adf = options.source in ("adf", "adf-duplex")
+        self._set_cap(src, twain.CAP_FEEDERENABLED, twain.TWTY_BOOL, 1 if use_adf else 0)
+        if options.source == "adf-duplex":
+            self._set_cap(src, twain.CAP_DUPLEXENABLED, twain.TWTY_BOOL, 1)
+
+    @staticmethod
+    def _transfer(src, twain, multipage: bool) -> list[bytes]:
+        pages: list[bytes] = []
+        for _ in range(200):  # hard cap against runaway feeders
+            try:
+                handle, pending = src.xfer_image_natively()
+            except Exception as exc:
+                # Raised when the source has no (more) images to transfer.
+                log.debug("native transfer ended: %s", exc)
+                break
+            try:
+                bmp = twain.dib_to_bm_file(handle)  # path=None -> returns BMP bytes
+                if bmp:
+                    pages.append(bmp)
+            finally:
+                try:
+                    twain.global_handle_free(handle)
+                except Exception:
+                    pass
+            if not multipage or pending == 0:
+                break
+        return pages