mcp-server-kit 0.1.0__py3-none-any.whl

mcp_server_kit/__init__.py

@@ -0,0 +1,9 @@
+"""Shared plumbing for FastMCP servers: bearer auth, off-loop tools, serving, healthcheck,
+collision-safe file staging (`files`) and PDF reading (`pdf`, extra `[pdf]`)."""
+
+from mcp_server_kit.auth import BearerAuthMiddleware
+from mcp_server_kit.serve import serve
+from mcp_server_kit.tools import offload_sync_tools, request_logger, rss_mib
+
+__all__ = ["BearerAuthMiddleware", "offload_sync_tools", "request_logger", "rss_mib", "serve"]
+__version__ = "0.1.0"

mcp_server_kit/auth.py

@@ -0,0 +1,48 @@
+"""Bearer-token gate for a Streamable HTTP MCP app."""
+
+import hmac
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+_LOOPBACK = ("127.0.0.1", "::1")
+
+
+class BearerAuthMiddleware:
+    """Pure ASGI bearer-token middleware (streaming-safe, timing-safe compare).
+
+    Every HTTP/websocket request needs `Authorization: Bearer <expected_token>`,
+    except `/.well-known/` discovery paths. That exemption is a prefix match on
+    purpose: a substring match would become an auth bypass the moment the app
+    routes anything under /mcp. Rejections get a JSON 401. A loopback request
+    with no credentials (a liveness probe) is logged at debug; anything else is
+    a warning. The token itself is never logged.
+    """
+
+    def __init__(self, app, expected_token: str):
+        if not expected_token:
+            raise ValueError("BearerAuthMiddleware needs a non-empty token")
+        self.app = app
+        self.expected_token = expected_token
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] not in ("http", "websocket"):
+            return await self.app(scope, receive, send)
+        if scope.get("path", "").startswith("/.well-known/"):
+            return await self.app(scope, receive, send)
+        auth = dict(scope.get("headers", [])).get(b"authorization", b"").decode()
+        if auth.startswith("Bearer ") and hmac.compare_digest(auth[7:], self.expected_token):
+            return await self.app(scope, receive, send)
+
+        client_host = (scope.get("client") or ("unknown",))[0]
+        if client_host in _LOOPBACK and not auth:
+            logger.debug("Health probe 401 (loopback, no credentials, expected)")
+        else:
+            logger.warning("Rejected request: invalid or missing bearer token from %s", client_host)
+        body = json.dumps({"error": "unauthorized"}).encode()
+        await send({"type": "http.response.start", "status": 401, "headers": [
+            [b"content-type", b"application/json"],
+            [b"content-length", str(len(body)).encode()],
+        ]})
+        await send({"type": "http.response.body", "body": body})

mcp_server_kit/files.py

@@ -0,0 +1,62 @@
+"""Collision-safe file staging, e.g. a directory shared by several MCP servers.
+
+Servers that hand files to each other through a shared directory (one writes
+`shared:<name>`, another reads it) need identical semantics, or a file staged
+by one isn't where the other looks: bare filenames only, never overwrite, and
+on a collision append -2, -3, ... before the extension. Creation uses
+O_CREAT|O_EXCL, so parallel writers in different processes can't clobber each
+other. Every transfer reports the sha256 of the bytes, so the caller can verify
+a handoff in-band.
+"""
+
+import hashlib
+import os
+from pathlib import Path
+
+MAX_SUFFIX = 1000
+
+
+class NoFreeNameError(RuntimeError):
+    """Every candidate name up to -MAX_SUFFIX already exists."""
+
+
+def sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def require_bare(name: str, what: str = "filename") -> str:
+    """`name`, if it is a bare filename (no directory part, not . or ..); else ValueError."""
+    if not name or name != os.path.basename(name) or name in (".", ".."):
+        raise ValueError(f"Invalid {what} {name!r} — must be a bare filename.")
+    return name
+
+
+def exclusive_open(root: Path, filename: str, mode: int = 0o644) -> tuple[Path, int]:
+    """Create a new file under `root` and return (path, fd) open for writing.
+
+    Tries `filename`, then `<stem>-2<ext>`, `<stem>-3<ext>`, ... `filename` must already
+    be bare (see require_bare). For streaming writers; `atomic_create` writes bytes.
+    """
+    root = Path(root)
+    root.mkdir(parents=True, exist_ok=True)
+    stem, ext = os.path.splitext(filename)
+    for i in range(MAX_SUFFIX + 1):
+        candidate = root / (filename if i == 0 else f"{stem}-{i + 1}{ext}")
+        try:
+            return candidate, os.open(candidate, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+        except FileExistsError:
+            continue
+    raise NoFreeNameError(f"No free filename for {filename!r} in {root} (tried -{MAX_SUFFIX}).")
+
+
+def atomic_create(root: Path, filename: str, data: bytes) -> Path:
+    """Write `data` to a new file under `root` (see exclusive_open) and return its path.
+    A failed write removes the partial file."""
+    path, fd = exclusive_open(root, filename)
+    try:
+        with os.fdopen(fd, "wb") as fp:
+            fp.write(data)
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+    return path

mcp_server_kit/healthcheck.py

@@ -0,0 +1,29 @@
+"""Container liveness probe for a kit-served MCP server.
+
+A full HTTP round-trip to /mcp within a short timeout proves the event loop is
+alive. The bearer middleware's 401 to this unauthenticated loopback probe is a
+completed response and counts as healthy. A transport failure or timeout exits
+non-zero, so a restart-on-unhealthy policy (Podman `HealthOnFailure=kill`)
+self-heals a wedged loop. Wire it from the server's own module:
+
+    # <package>/healthcheck.py
+    from mcp_server_kit.healthcheck import probe
+    from <package>.config import PORT
+
+    def main() -> None:
+        probe(PORT)
+"""
+
+import sys
+import urllib.error
+import urllib.request
+
+
+def probe(port: int, timeout: float = 5) -> None:
+    try:
+        urllib.request.urlopen(f"http://127.0.0.1:{port}/mcp", timeout=timeout)
+    except urllib.error.HTTPError:
+        return
+    except Exception as exc:  # noqa: BLE001 - any transport failure = unhealthy
+        print(f"health: unreachable on :{port}: {exc}", file=sys.stderr)
+        sys.exit(1)

mcp_server_kit/pdf.py

@@ -0,0 +1,557 @@
+"""PDF reading helpers: text extraction, xberg OCR, page render.
+
+Install with the extra: `mcp-server-kit[pdf]` (pdfplumber, pypdfium2, pillow, httpx).
+Those are imported lazily inside the functions, so importing this module is cheap and
+a server only pays for them on its first PDF call.
+
+Reading tiers
+  A. Native text — pdfplumber (pdfminer.six) text / layout / tables.
+  B. OCR        — pages rasterised at 2x via pypdfium2 and sent to an
+     xberg server (https://github.com/xberg-io/xberg — POST /extract,
+     markdown out). Default backend
+     tesseract: xberg's paddle-ocr (the PP-OCR family the pre-2026-08
+     in-process RapidOCR used) takes 4-5+ MINUTES on a dense text page
+     on CPU in either model tier (measured 2026-08-03) vs ~3 s for
+     tesseract — set XBERG_OCR_BACKEND=paddle-ocr only if you can eat
+     that latency; use ocr='llm' for hard documents instead.
+  C. VLM OCR    — same xberg call with the ``vlm`` backend: xberg forwards
+     page images to an OpenAI-compatible vision endpoint (e.g. a
+     LiteLLM gateway). The gateway key rides in the per-request vlm_config —
+     xberg 1.0.8 cannot resolve provider env keys once base_url is
+     overridden per request (verified 2026-08-03; revisit if upstream
+     fixes env-key resolution, the server-side key was the preferred
+     design). Best quality on handwriting / messy tables.
+
+The ``ocr`` parameter of :func:`extract_pdf_text` selects the tier:
+  'auto'  (default) — tier A, then tier B for requested pages whose native
+          text came back < OCR_AUTO_MIN_CHARS non-whitespace chars.
+  'off'   — tier A only.
+  'force' — tier B on every requested page (skips tier A).
+  'llm'   — tier C on every requested page (skips tier A).
+
+Env: XBERG_BASE_URL (default http://xberg:8000 — point it at your xberg
+server; if none is reachable, auto-tier OCR degrades to native text with
+an ocr_error note), XBERG_TIMEOUT (s, default 120), XBERG_OCR_BACKEND (default 'tesseract'),
+XBERG_VLM_MODEL (default 'cheap' — e.g. a LiteLLM gateway alias,
+passed verbatim),
+XBERG_VLM_BASE_URL (default http://litellm:4000/v1 — an
+OpenAI-compatible endpoint, resolved by the xberg SERVER, not this
+process), XBERG_VLM_API_KEY (required for ocr='llm' only — the
+LiteLLM virtual key).
+"""
+
+import contextlib
+import io
+import json
+import logging
+import os
+import threading
+
+logger = logging.getLogger(__name__)
+
+VALID_MODES = ("text", "layout", "tables")
+VALID_OCR = ("auto", "off", "force", "llm")
+
+# Below this many non-whitespace chars of native text, a page is treated as
+# image-only and OCR'd in 'auto' mode. Real text pages are hundreds of chars;
+# scans typically yield 0 (or a few stray glyphs from a vector letterhead).
+OCR_AUTO_MIN_CHARS = 20
+
+# 72 dpi * 2 = 144 dpi input to the OCR engine — the PP-OCR sweet spot for
+# ordinary print sizes; higher scales cost quadratic memory for no gain.
+OCR_RENDER_SCALE = 2.0
+
+XBERG_BASE_URL_DEFAULT = "http://xberg:8000"
+XBERG_TIMEOUT_DEFAULT = 120.0
+XBERG_OCR_BACKEND_DEFAULT = "tesseract"
+XBERG_VLM_MODEL_DEFAULT = "cheap"
+XBERG_VLM_BASE_URL_DEFAULT = "http://litellm:4000/v1"
+
+
+def validate_options(mode: str, ocr: str) -> tuple[str, str]:
+    """Normalise and validate the ``mode`` / ``ocr`` options, raising
+    ValueError on anything unknown. Exposed separately so tool wrappers can
+    fail fast on bad parameters BEFORE fetching the document bytes."""
+    mode_norm = (mode or "text").strip().lower()
+    if mode_norm not in VALID_MODES:
+        raise ValueError(
+            f"mode must be one of 'text', 'layout', 'tables' — got {mode!r}."
+        )
+    ocr_norm = (ocr or "auto").strip().lower()
+    if ocr_norm not in VALID_OCR:
+        raise ValueError(
+            f"ocr must be one of 'auto', 'off', 'force', 'llm' — got {ocr!r}."
+        )
+    return mode_norm, ocr_norm
+
+
+class PageOutOfRangeError(ValueError):
+    """Requested page exceeds the document's page count."""
+
+    def __init__(self, page: int, page_count: int):
+        self.page = page
+        self.page_count = page_count
+        super().__init__(
+            f"page {page} out of range (document has {page_count} pages)."
+        )
+
+
+def parse_page_spec(spec: str | None, page_count: int) -> list[int]:
+    """Parse a ``pdftotext``-style page range string into a sorted list of
+    1-indexed page numbers, clamped to ``1..page_count``.
+
+    Accepts ``None`` / ``""`` (all pages), a single page (``"3"``), a range
+    (``"1-5"``), a comma-separated list (``"1,3,5"``), or a mix
+    (``"1-3,7,10-12"``). Whitespace is tolerated. Pages outside
+    ``1..page_count`` are silently dropped — callers report the effective
+    set via ``pages_returned`` in the response."""
+    if spec is None or not str(spec).strip():
+        return list(range(1, page_count + 1))
+    wanted: set[int] = set()
+    for chunk in str(spec).split(","):
+        chunk = chunk.strip()
+        if not chunk:
+            continue
+        if "-" in chunk:
+            lo_s, _, hi_s = chunk.partition("-")
+            try:
+                lo, hi = int(lo_s), int(hi_s)
+            except ValueError as e:
+                raise ValueError(
+                    f"Invalid page range '{chunk}' in pages={spec!r}."
+                ) from e
+            if lo > hi:
+                lo, hi = hi, lo
+            for p in range(lo, hi + 1):
+                if 1 <= p <= page_count:
+                    wanted.add(p)
+        else:
+            try:
+                p = int(chunk)
+            except ValueError as e:
+                raise ValueError(
+                    f"Invalid page number '{chunk}' in pages={spec!r}."
+                ) from e
+            if 1 <= p <= page_count:
+                wanted.add(p)
+    return sorted(wanted)
+
+
+# --- rendering --------------------------------------------------------------
+
+
+def _null_or(concurrency: threading.Semaphore | None):
+    return concurrency if concurrency is not None else contextlib.nullcontext()
+
+
+def _render_page_pil(pdf, page_index: int, scale: float):
+    """Render one pypdfium2 page to a PIL image with explicit native-memory
+    cleanup. pypdfium2 holds PDFium buffers the GC reclaims only
+    non-deterministically — close page and bitmap explicitly so a multi-page
+    OCR sweep can't pile up native allocations. The returned PIL image owns
+    a Python-side copy (``.convert()`` detaches from the bitmap buffer)."""
+    page = pdf[page_index]
+    try:
+        bitmap = page.render(scale=scale)
+        try:
+            return bitmap.to_pil().convert("RGB")
+        finally:
+            bitmap.close()
+    finally:
+        page.close()
+
+
+def render_pdf_page_bytes(
+    file_bytes: bytes,
+    page: int,
+    max_width: int = 1200,
+    fmt: str = "jpeg",
+    quality: int = 75,
+    concurrency: threading.Semaphore | None = None,
+) -> tuple[bytes, str, int, int, int]:
+    """Render one 1-indexed PDF page to encoded image bytes.
+
+    Returns ``(image_bytes, mime_type, width, height, page_count)``.
+    Raises :class:`PageOutOfRangeError` when ``page > page_count``."""
+    import pypdfium2  # type: ignore
+    from PIL import Image  # type: ignore
+
+    buf = io.BytesIO()
+    with _null_or(concurrency):
+        pdf = pypdfium2.PdfDocument(io.BytesIO(file_bytes))
+        try:
+            page_count = len(pdf)
+            if page > page_count:
+                raise PageOutOfRangeError(page, page_count)
+            pdf_page = pdf[page - 1]
+            try:
+                # pypdfium2 renders at 72 DPI * scale. Pick the scale that
+                # makes the output width land near max_width.
+                native_w, _native_h = pdf_page.get_size()
+                if native_w <= 0:
+                    native_w = 612.0  # US Letter fallback
+                scale = max_width / float(native_w)
+                if scale <= 0:
+                    scale = 1.0
+                bitmap = pdf_page.render(scale=scale)
+                try:
+                    pil = bitmap.to_pil()
+                    # PDFium can overshoot max_width by a pixel — downscale
+                    # rather than ship a larger image than asked.
+                    if pil.width > max_width:
+                        ratio = max_width / pil.width
+                        pil = pil.resize(
+                            (max_width, max(1, int(pil.height * ratio))),
+                            Image.Resampling.LANCZOS,
+                        )
+                    if fmt == "jpeg":
+                        # PDFium renders with alpha; JPEG can't hold one.
+                        if pil.mode != "RGB":
+                            pil = pil.convert("RGB")
+                        pil.save(
+                            buf, format="JPEG", quality=quality, optimize=True,
+                        )
+                        out_mime = "image/jpeg"
+                    else:
+                        pil.save(buf, format="PNG", optimize=True)
+                        out_mime = "image/png"
+                    out_w, out_h = pil.width, pil.height
+                finally:
+                    bitmap.close()
+            finally:
+                pdf_page.close()
+        finally:
+            pdf.close()
+    return buf.getvalue(), out_mime, out_w, out_h, page_count
+
+
+def _render_pages_png(
+    file_bytes: bytes,
+    page_numbers: list[int],
+    scale: float,
+    concurrency: threading.Semaphore | None,
+) -> dict[int, bytes]:
+    """Rasterise the given 1-indexed pages to PNG bytes at ``scale``."""
+    import pypdfium2  # type: ignore
+
+    out: dict[int, bytes] = {}
+    with _null_or(concurrency):
+        pdf = pypdfium2.PdfDocument(io.BytesIO(file_bytes))
+        try:
+            for p in page_numbers:
+                pil = _render_page_pil(pdf, p - 1, scale)
+                buf = io.BytesIO()
+                pil.save(buf, format="PNG")
+                out[p] = buf.getvalue()
+        finally:
+            pdf.close()
+    return out
+
+
+def _pdf_page_count(file_bytes: bytes) -> int:
+    import pypdfium2  # type: ignore
+
+    pdf = pypdfium2.PdfDocument(io.BytesIO(file_bytes))
+    try:
+        return len(pdf)
+    finally:
+        pdf.close()
+
+
+# --- xberg OCR (tiers B and C) ----------------------------------------------
+
+
+def _xberg_config() -> tuple[str, float]:
+    base_url = (
+        os.environ.get("XBERG_BASE_URL", "").strip().rstrip("/")
+        or XBERG_BASE_URL_DEFAULT
+    )
+    timeout = float(
+        os.environ.get("XBERG_TIMEOUT", "").strip() or XBERG_TIMEOUT_DEFAULT
+    )
+    return base_url, timeout
+
+
+def xberg_ocr_pages(
+    file_bytes: bytes,
+    page_numbers: list[int],
+    *,
+    vlm: bool = False,
+    concurrency: threading.Semaphore | None = None,
+) -> tuple[dict[int, str], str]:
+    """OCR the given 1-indexed pages via the configured xberg server.
+
+    Pages are rasterised locally (PNG at OCR_RENDER_SCALE) and uploaded in
+    ONE multipart request — xberg's ``results`` array maps 1:1 to the
+    uploaded files, which keeps the per-page mapping trivial and sidesteps
+    any question of how xberg splits a multi-page PDF. ``vlm=True`` selects
+    xberg's vision-model backend (tier C); the provider key lives in
+    xberg's own env, never in this process.
+
+    Returns ``({page: markdown_text}, engine_label)``. Raises RuntimeError
+    with xberg's status/body on failure so the caller sees exactly what
+    the service said."""
+    import httpx  # type: ignore
+
+    base_url, timeout = _xberg_config()
+    if vlm:
+        model = (
+            os.environ.get("XBERG_VLM_MODEL", "").strip()
+            or XBERG_VLM_MODEL_DEFAULT
+        )
+        vlm_base = (
+            os.environ.get("XBERG_VLM_BASE_URL", "").strip().rstrip("/")
+            or XBERG_VLM_BASE_URL_DEFAULT
+        )
+        api_key = os.environ.get("XBERG_VLM_API_KEY", "").strip()
+        if not api_key:
+            raise RuntimeError(
+                "ocr='llm' requires XBERG_VLM_API_KEY in the server env "
+                "(the LiteLLM virtual key; xberg 1.0.8 cannot resolve "
+                "provider env keys when base_url is overridden per "
+                "request). Use ocr='force' for classical OCR instead."
+            )
+        config = {
+            "ocr": {
+                "backend": "vlm",
+                "vlm_config": {
+                    "model": model,
+                    "base_url": vlm_base,
+                    "api_key": api_key,
+                },
+            }
+        }
+        engine = f"xberg:vlm:{model}"
+    else:
+        backend = (
+            os.environ.get("XBERG_OCR_BACKEND", "").strip()
+            or XBERG_OCR_BACKEND_DEFAULT
+        )
+        # Language codes are backend-specific: tesseract wants ISO 639-2
+        # ("eng"), the paddle/candle family wants ISO 639-1 ("en").
+        language = "eng" if backend == "tesseract" else "en"
+        config = {"ocr": {"backend": backend, "language": language}}
+        engine = f"xberg:{backend}"
+
+    rendered = _render_pages_png(
+        file_bytes, page_numbers, OCR_RENDER_SCALE, concurrency,
+    )
+    ordered = sorted(rendered.keys())
+    files = [
+        ("files", (f"page-{p}.png", rendered[p], "image/png"))
+        for p in ordered
+    ]
+    data = {"output_format": "markdown", "config": json.dumps(config)}
+
+    with httpx.Client(timeout=timeout) as http:
+        resp = http.post(f"{base_url}/extract", data=data, files=files)
+    if resp.status_code != 200:
+        raise RuntimeError(
+            f"xberg OCR request for pages {ordered} failed: HTTP "
+            f"{resp.status_code} from {base_url}: {resp.text[:500]}"
+        )
+    try:
+        payload = resp.json()
+        errors = payload.get("summary", {}).get("errors", 0)
+        results = payload["results"]
+    except (KeyError, ValueError) as e:
+        raise RuntimeError(
+            f"xberg OCR response had an unexpected shape: {resp.text[:500]}"
+        ) from e
+    if errors:
+        raise RuntimeError(
+            f"xberg reported {errors} extraction error(s) for pages "
+            f"{ordered}: {resp.text[:500]}"
+        )
+    if len(results) != len(ordered):
+        raise RuntimeError(
+            f"xberg returned {len(results)} results for {len(ordered)} "
+            f"uploaded pages — refusing to guess the page mapping."
+        )
+    out = {
+        p: (results[i].get("content") or "").strip()
+        for i, p in enumerate(ordered)
+    }
+    return out, engine
+
+
+# --- assembly ----------------------------------------------------------------
+
+
+def assemble_pages(
+    per_page_text: dict[int, str], max_bytes: int,
+) -> tuple[str, list[int], bool]:
+    """Join per-page text under a byte ceiling. Walk pages in order and stop
+    as soon as appending the next page would exceed the ceiling. If the
+    first page on its own is already over the ceiling, include it but
+    truncate mid-text so the caller at least gets something.
+
+    Returns ``(text, pages_included, truncated)`` — the truncation marker
+    telling the caller which pages to fetch next is appended to ``text``."""
+    targets_in_order = sorted(per_page_text.keys())
+    pieces: list[str] = []
+    pages_included: list[int] = []
+    running_bytes = 0
+    truncated = False
+    truncation_note: str | None = None
+    for p in targets_in_order:
+        body = per_page_text[p]
+        chunk = ("\f" if pieces else "") + body
+        encoded = chunk.encode("utf-8", errors="replace")
+        if running_bytes + len(encoded) > max_bytes:
+            included_p = False
+            if not pieces:
+                # Single page is already too big — truncate it.
+                slack = max_bytes - running_bytes
+                body_enc = body.encode("utf-8", errors="replace")[:slack]
+                pieces.append(body_enc.decode("utf-8", errors="replace"))
+                pages_included.append(p)
+                running_bytes += len(body_enc)
+                included_p = True
+            truncated = True
+            # The overflowing page p was dropped unless it was force-included
+            # above — the retry hint must cover it in that case (the original
+            # original implementation skipped it: off-by-one).
+            remaining = [
+                q for q in targets_in_order
+                if (q > p if included_p else q >= p)
+            ]
+            if remaining:
+                lo, hi = remaining[0], remaining[-1]
+                truncation_note = (
+                    f"...[truncated at page {pages_included[-1]}, "
+                    f"call again with pages={lo}-{hi}]"
+                )
+            else:
+                truncation_note = (
+                    f"...[truncated mid-page {pages_included[-1]}, "
+                    f"call again with pages={pages_included[-1]} and "
+                    f"a narrower mode]"
+                )
+            break
+        pieces.append(chunk)
+        pages_included.append(p)
+        running_bytes += len(encoded)
+
+    text_out = "".join(pieces)
+    if truncation_note:
+        text_out += "\n" + truncation_note
+    return text_out, pages_included, truncated
+
+
+# --- top-level extraction ------------------------------------------------------
+
+
+def extract_pdf_text(
+    file_bytes: bytes,
+    pages: str | None = None,
+    mode: str = "text",
+    ocr: str = "auto",
+    *,
+    max_bytes: int = 200_000,
+    concurrency: threading.Semaphore | None = None,
+) -> dict:
+    """Extract text from PDF bytes. Returns a dict with keys ``text``,
+    ``page_count``, ``pages_returned``, ``mode``, ``truncated``, plus
+    ``ocr_used`` / ``ocr_pages`` / ``ocr_engine`` when OCR ran (and
+    ``ocr_error`` when 'auto'-mode OCR was needed but failed — the caller
+    then still gets the native-text result instead of an exception).
+
+    ``mode`` applies to native extraction only; OCR'd pages come back as
+    markdown-flavoured text from xberg (both tiers)."""
+    mode_norm, ocr_norm = validate_options(mode, ocr)
+
+    per_page_text: dict[int, str] = {}
+
+    if ocr_norm in ("force", "llm"):
+        # Native extraction would be discarded — only the page count is
+        # needed to resolve the page spec.
+        page_count = _pdf_page_count(file_bytes)
+        targets = parse_page_spec(pages, page_count)
+        per_page_text = {p: "" for p in targets}
+    else:
+        import pdfplumber  # type: ignore
+
+        with _null_or(concurrency), pdfplumber.open(
+            io.BytesIO(file_bytes)
+        ) as pdf:
+            page_count = len(pdf.pages)
+            targets = parse_page_spec(pages, page_count)
+            for p in targets:
+                page = pdf.pages[p - 1]
+                if mode_norm == "text":
+                    per_page_text[p] = page.extract_text() or ""
+                elif mode_norm == "layout":
+                    per_page_text[p] = page.extract_text(layout=True) or ""
+                else:  # tables
+                    tables = page.extract_tables() or []
+                    if not tables:
+                        per_page_text[p] = ""
+                        continue
+                    parts: list[str] = []
+                    for ti, table in enumerate(tables, 1):
+                        parts.append(f"## Page {p} Table {ti}")
+                        for row in table:
+                            cells = [
+                                ("" if c is None else str(c)).replace(
+                                    "|", "\\|"
+                                )
+                                for c in row
+                            ]
+                            parts.append("| " + " | ".join(cells) + " |")
+                        parts.append("")
+                    per_page_text[p] = "\n".join(parts)
+
+    # Pick the pages OCR should cover.
+    if ocr_norm == "off":
+        ocr_targets: list[int] = []
+    elif ocr_norm == "auto":
+        ocr_targets = [
+            p
+            for p in sorted(per_page_text.keys())
+            if len(per_page_text[p].strip()) < OCR_AUTO_MIN_CHARS
+        ]
+    else:  # force / llm
+        ocr_targets = sorted(per_page_text.keys())
+
+    ocr_used = False
+    ocr_engine: str | None = None
+    ocr_error: str | None = None
+    if ocr_targets:
+        try:
+            ocr_text, ocr_engine = xberg_ocr_pages(
+                file_bytes,
+                ocr_targets,
+                vlm=(ocr_norm == "llm"),
+                concurrency=concurrency,
+            )
+            per_page_text.update(ocr_text)
+            ocr_used = True
+        except Exception as e:
+            # 'auto' is best-effort: a broken OCR stack must not take down
+            # plain text extraction — surface the failure in the result
+            # instead (the silent-failure trap this module replaces).
+            # An explicit 'force'/'llm' request propagates.
+            if ocr_norm != "auto":
+                raise
+            logger.warning("auto-mode OCR failed: %s", e)
+            ocr_error = f"{type(e).__name__}: {e}"
+
+    text_out, pages_included, truncated = assemble_pages(
+        per_page_text, max_bytes,
+    )
+
+    result = {
+        "text": text_out,
+        "page_count": page_count,
+        "pages_returned": pages_included,
+        "mode": mode_norm,
+        "truncated": truncated,
+    }
+    if ocr_used:
+        result["ocr_used"] = True
+        result["ocr_pages"] = ocr_targets
+        result["ocr_engine"] = ocr_engine
+    if ocr_error is not None:
+        result["ocr_error"] = ocr_error
+    return result

mcp_server_kit/serve.py

@@ -0,0 +1,31 @@
+"""Run a FastMCP server over stdio or bearer-gated Streamable HTTP."""
+
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from mcp_server_kit.auth import BearerAuthMiddleware
+
+
+def serve(mcp: FastMCP, *, port: int, bearer_token: str, host: str = "0.0.0.0",
+          argv: list[str] | None = None) -> None:
+    """`--stdio` in argv runs stdio (the client owns the process, so no auth). Otherwise
+    Streamable HTTP at /mcp behind BearerAuthMiddleware, and it refuses to start without
+    a token rather than serve unauthenticated.
+
+    Build the FastMCP with stateless_http=True, json_response=True, so a dropped
+    connection or a restart never strands a client session.
+    """
+    argv = sys.argv[1:] if argv is None else argv
+    if "--stdio" in argv:
+        mcp.run(transport="stdio")
+        return
+    if not bearer_token:
+        raise SystemExit(
+            "MCP_BEARER_TOKEN is not set. Refusing to start an unauthenticated "
+            "MCP server. Set it in .secrets.env and restart."
+        )
+    import uvicorn
+
+    app = BearerAuthMiddleware(mcp.streamable_http_app(), expected_token=bearer_token)
+    uvicorn.run(app, host=host, port=port)

mcp_server_kit/tools.py

@@ -0,0 +1,121 @@
+"""Tool registration: run sync handlers off the event loop, log one line per call.
+
+The MCP SDK runs a synchronous tool handler inline on the single asyncio event
+loop, so one blocking upstream call (httpx, httplib2, time.sleep) stalls every
+other request until it returns. `offload_sync_tools` rewires `mcp.tool` so each
+sync handler is registered as an async wrapper that runs the body in a worker
+thread. The tool's signature is preserved, so its input schema is unchanged.
+The decorator returns the original function, so module-level names stay
+directly callable (tool-to-tool calls, unit tests).
+
+Every call, sync or async, logs one line in the format audit tooling parses:
+
+    <asctime> INFO tool=<name> outcome=ok|error duration_ms=<n> rss_mib=<n>
+
+Guard non-thread-safe shared clients (e.g. cached httplib2 objects) with a lock
+in the server; thread-safe ones (httpx.Client, requests.Session) need none.
+"""
+
+import functools
+import inspect
+import logging
+import os
+import time
+from typing import Any
+
+import anyio
+from mcp.server.fastmcp import FastMCP
+
+_LOG_FORMAT = "%(asctime)s %(levelname)s %(message)s"
+
+
+def rss_mib() -> int:
+    """Current process RSS in MiB from /proc (Linux), or -1 where that isn't available."""
+    try:
+        with open("/proc/self/statm") as f:
+            pages = int(f.read().split()[1])
+        return pages * os.sysconf("SC_PAGE_SIZE") // (1024 * 1024)
+    except (OSError, ValueError, IndexError):
+        return -1
+
+
+def request_logger(name: str) -> logging.Logger:
+    """The per-call logger: its own stderr handler, so the line format doesn't depend on
+    how (or whether) the server configured root logging. stderr is safe under stdio."""
+    log = logging.getLogger(name)
+    if not log.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(_LOG_FORMAT))
+        log.addHandler(handler)
+        log.setLevel(logging.INFO)
+        log.propagate = False
+    return log
+
+
+def _signature(fn) -> inspect.Signature:
+    # Resolve string annotations (`from __future__ import annotations`): FastMCP/pydantic
+    # can't resolve forward refs like Optional[str] through the wrapper indirection.
+    try:
+        return inspect.signature(fn, eval_str=True)
+    except Exception:  # noqa: BLE001 - unresolvable name: fall back to the raw signature
+        return inspect.signature(fn)
+
+
+def offload_sync_tools(mcp: FastMCP, *, logger_name: str, default_annotations: Any = None) -> None:
+    """Rewire `mcp.tool` (call once, before the first @mcp.tool()).
+
+    logger_name: the per-call logger, conventionally "<package>.requests".
+    default_annotations: ToolAnnotations applied to tools that don't pass their own.
+    """
+    register_tool = mcp.tool
+    log = request_logger(logger_name)
+
+    def tool(*d_args, **d_kwargs):
+        if default_annotations is not None:
+            d_kwargs.setdefault("annotations", default_annotations)
+        register = register_tool(*d_args, **d_kwargs)
+
+        def decorator(fn):
+            name = d_kwargs.get("name") or fn.__name__
+
+            def done(start: float, outcome: str) -> None:
+                log.info("tool=%s outcome=%s duration_ms=%d rss_mib=%d",
+                         name, outcome, int((time.perf_counter() - start) * 1000), rss_mib())
+
+            if inspect.iscoroutinefunction(fn):
+                @functools.wraps(fn)
+                async def wrapper(*args, **kwargs):
+                    start, outcome = time.perf_counter(), "ok"
+                    try:
+                        return await fn(*args, **kwargs)
+                    except Exception:
+                        outcome = "error"
+                        raise
+                    finally:
+                        done(start, outcome)
+            else:
+                @functools.wraps(fn)
+                async def wrapper(*args, **kwargs):
+                    start, outcome = time.perf_counter(), "ok"
+                    try:
+                        return await anyio.to_thread.run_sync(functools.partial(fn, *args, **kwargs))
+                    except Exception:
+                        outcome = "error"
+                        raise
+                    finally:
+                        done(start, outcome)
+
+            sig = _signature(fn)
+            wrapper.__signature__ = sig
+            wrapper.__annotations__ = {
+                **{p.name: p.annotation for p in sig.parameters.values()
+                   if p.annotation is not inspect.Parameter.empty},
+                **({"return": sig.return_annotation}
+                   if sig.return_annotation is not inspect.Signature.empty else {}),
+            }
+            register(wrapper)
+            return fn
+
+        return decorator
+
+    mcp.tool = tool

mcp_server_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: mcp-server-kit
+Version: 0.1.0
+Summary: Shared plumbing for FastMCP servers: bearer auth, off-event-loop sync tools with per-call logging, stdio/HTTP serving, and a liveness probe
+Project-URL: Homepage, https://github.com/snickery/mcp-server-kit
+Project-URL: Issues, https://github.com/snickery/mcp-server-kit/issues
+Author-email: Nick Engel <nick@engel.au>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auth,fastmcp,mcp,model-context-protocol,server
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.0
+Requires-Dist: mcp[cli]<2,>=1.0.0
+Requires-Dist: uvicorn>=0.32.0
+Provides-Extra: pdf
+Requires-Dist: httpx>=0.27; extra == 'pdf'
+Requires-Dist: pdfplumber>=0.11; extra == 'pdf'
+Requires-Dist: pillow>=10.0; extra == 'pdf'
+Requires-Dist: pypdfium2>=4.30; extra == 'pdf'
+Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
+Requires-Dist: httpx>=0.27.0; extra == 'test'
+Requires-Dist: pdfplumber>=0.11; extra == 'test'
+Requires-Dist: pillow>=10.0; extra == 'test'
+Requires-Dist: pypdfium2>=4.30; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mcp-server-kit
+
+Shared plumbing for Python MCP servers built on the official SDK's FastMCP
+(`mcp.server.fastmcp`). It covers the parts every server ends up copying:
+
+| Module | What it does |
+|---|---|
+| `offload_sync_tools` | Registers each **sync** tool as an async wrapper that runs the body in a worker thread, so one blocking upstream call can't freeze every other request. The SDK runs sync handlers inline on the event loop. Signatures, and so input schemas, are unchanged. Every call, sync or async, logs one `tool=… outcome=… duration_ms=… rss_mib=…` line. |
+| `BearerAuthMiddleware` | Pure ASGI bearer-token gate (timing-safe compare, streaming-safe). Only `/.well-known/` discovery paths are exempt, matched by prefix, never by substring. |
+| `serve` | `--stdio` runs stdio. Otherwise it serves Streamable HTTP at `/mcp` behind the bearer gate, and **refuses to start without a token**. |
+| `healthcheck.probe` | A liveness probe for containers: a full HTTP round-trip to `/mcp`, where the 401 counts as alive. Pair it with restart-on-unhealthy so a wedged loop heals itself. |
+| `files` | Collision-safe staging for a directory several servers share: bare names only, never overwrite (`-2`, `-3`, … before the extension, `O_CREAT\|O_EXCL`), `sha256` of every transfer. `atomic_create` writes bytes; `exclusive_open` hands a streaming writer the fd. |
+| `pdf` (extra `[pdf]`) | PDF text extraction (pdfplumber text / layout / tables), page rendering (pypdfium2), and OCR through an [xberg](https://github.com/xberg-io/xberg) server (tesseract, or a vision model for hard pages). Configured by `XBERG_*` env vars; the PDF libraries load lazily. |
+
+## Install
+
+```bash
+uv add mcp-server-kit        # or: pip install mcp-server-kit
+```
+
+It pins `mcp>=1,<2`, so the SDK range lives in one place for every server built on the kit.
+
+## Use
+
+```python
+import logging
+import os
+
+from mcp.server.fastmcp import FastMCP
+from mcp_server_kit import offload_sync_tools, serve
+
+mcp = FastMCP("example", instructions="...", stateless_http=True, json_response=True)
+offload_sync_tools(mcp, logger_name="example_mcp.requests")   # before the first @mcp.tool()
+
+
+@mcp.tool()
+def lookup(query: str) -> str:
+    """A blocking call is fine here: it runs in a worker thread."""
+    ...
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO)
+    serve(mcp, port=8000, bearer_token=os.environ.get("MCP_BEARER_TOKEN", ""))
+```
+
+`lookup` stays a plain function, so tests and other tools can call it directly.
+
+To give every tool the same annotations unless it passes its own:
+`offload_sync_tools(mcp, logger_name=..., default_annotations=ToolAnnotations(readOnlyHint=True))`.
+
+Healthcheck module for a container (`HealthCmd=python -m example_mcp.healthcheck`):
+
+```python
+from mcp_server_kit.healthcheck import probe
+
+def main() -> None:
+    probe(8000)
+
+if __name__ == "__main__":
+    main()
+```
+
+Shared non-thread-safe clients (e.g. cached `httplib2` objects) need a lock in the
+server. Thread-safe ones (`httpx.Client`, `requests.Session`) don't.
+
+## Develop
+
+```bash
+uv sync --extra test
+uv run pytest -q
+```
+
+MIT licensed.

mcp_server_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mcp_server_kit/__init__.py,sha256=W6uj-aSN4t5XBIufiucfAU31zAcRKD1GqGv_1KTNmeU,460
+mcp_server_kit/auth.py,sha256=EjYGzINGxDn4MIX1vN8SiijABxpOURQV5SGU2Kwq_qQ,2112
+mcp_server_kit/files.py,sha256=eUYy8JLSrePCnkN6vnrEYmL6YcdkdjbFzDoa19zT2O4,2392
+mcp_server_kit/healthcheck.py,sha256=tB54y7cqSKRn36EEUogc5BYjl1baH90zM-Ufw-_2c6g,1021
+mcp_server_kit/pdf.py,sha256=iXLN5QTrPLkuOx_pj3wYqa5EjF4R4ZziQFBDHVmZgZM,21293
+mcp_server_kit/serve.py,sha256=vhuzGjLR-qpT3JwZ6W98YpKa7h3pMbUpovFMziBwipo,1164
+mcp_server_kit/tools.py,sha256=HhDS7PN6Io1wjIhz5VE_Zf_kyTaFNiP3uW0JHdjRl44,4741
+mcp_server_kit-0.1.0.dist-info/METADATA,sha256=Vg3SC_QiTsOBXCXNvMY63zqo25TA0EJdFskCaNCztqQ,4501
+mcp_server_kit-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mcp_server_kit-0.1.0.dist-info/licenses/LICENSE,sha256=UZKeFpV4SVVpWdGWdfHRZR5YmP82IP35IqH48YQdKLQ,1067
+mcp_server_kit-0.1.0.dist-info/RECORD,,

mcp_server_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_server_kit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Engel
+
+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.