refigure 0.2.0__tar.gz → 0.3.0__tar.gz

refigure-0.2.0/README.md → refigure-0.3.0/PKG-INFO

@@ -1,3 +1,35 @@
+Metadata-Version: 2.5
+Name: refigure
+Version: 0.3.0
+Summary: DOCX/XLSX -> Markdown conversion with native OOXML chart-data extraction (no rasterize/OCR/VLM needed) + optional VLM interpretation for figures with no native chart data
+Project-URL: Homepage, https://github.com/HelgDemidov/refigure
+Project-URL: Repository, https://github.com/HelgDemidov/refigure
+Author-email: HelgDemidov <helg.demidov88@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: lxml<7,>=6.1
+Provides-Extra: docx
+Requires-Dist: mammoth<2,>=1.12; extra == 'docx'
+Requires-Dist: markdownify<2,>=1.2; extra == 'docx'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0; extra == 'mcp'
+Provides-Extra: vlm
+Requires-Dist: pdfplumber<0.12,>=0.11; extra == 'vlm'
+Provides-Extra: vlm-direct
+Requires-Dist: anthropic<1,>=0.120; extra == 'vlm-direct'
+Requires-Dist: openai<4,>=3.1.0; extra == 'vlm-direct'
+Requires-Dist: pdfplumber<0.12,>=0.11; extra == 'vlm-direct'
+Provides-Extra: xlsx
+Requires-Dist: openpyxl<4,>=3.1; extra == 'xlsx'
+Description-Content-Type: text/markdown
+
 # refigure
 
 **Converters where figures survive.**
@@ -100,6 +132,9 @@ refigure report.docx --vlm                    # needs the system soffice/LibreOf
   chart/group counts + `vlm_used`), not a bare string.
 - **CLI included** — `refigure` console command, stdin/stdout-first, native
   batch mode, typed exit codes (see below).
+- **MCP server included** — `refigure-mcp` console command (`[mcp]` extra),
+  stdio or Streamable HTTP, tools/resources/prompts, batch conversion with
+  per-file isolation (see below).
 
 ## CLI
 
@@ -133,6 +168,49 @@ Exit codes:
 | 5 | the format's extra (`[docx]`/`[xlsx]`) isn't installed |
 | 6 | unexpected internal error |
 
+## MCP server
+
+`refigure-mcp` — the same converters as an
+[MCP](https://modelcontextprotocol.io) server, for agents/IDEs that speak
+the protocol directly instead of shelling out to a CLI or importing the
+library:
+
+```bash
+pip install "refigure[mcp,docx,xlsx]"
+refigure-mcp                              # stdio — the MCP client launches it
+```
+
+```json
+{
+  "mcpServers": {
+    "refigure": { "command": "refigure-mcp" }
+  }
+}
+```
+
+Three tools — `convert_docx`, `convert_xlsx`, and `convert_batch` (multiple
+files in one call: one bad file reports its own error without aborting the
+rest) — each registered only if its format extra is actually installed.
+`use_vlm`/`--vlm-provider` and friends work the same as the CLI. A result
+too large to inline is stored and handed back as a
+`refigure://conversion/{id}` resource instead of inflating the tool
+response. Two prompts (`ingest_for_rag`, `explain_conversion_warnings`)
+help a client pick the right tool/VLM settings for the job.
+
+Streamable HTTP is opt-in, for a shared/remote deployment — bearer-token
+auth is required, not optional:
+
+```bash
+echo "sk-... = alice" > tokens.txt
+refigure-mcp --transport http --mcp-auth-token-file tokens.txt
+```
+
+Per-caller rate-limiting (protects the operator's own spend from a
+leaked/runaway token) applies automatically over HTTP, together with a
+fairness soft-cap once 2+ callers are configured; `refigure-mcp --help`
+covers every tuning flag (concurrency, timeouts, resource-store limits,
+batch size, VLM ceiling).
+
 ## Real examples
 
 Full `convert()` output on real, openly-licensed documents — not

refigure-0.2.0/PKG-INFO → refigure-0.3.0/README.md

@@ -1,33 +1,3 @@
-Metadata-Version: 2.5
-Name: refigure
-Version: 0.2.0
-Summary: DOCX/XLSX -> Markdown conversion with native OOXML chart-data extraction, no rasterize/OCR/VLM
-Project-URL: Homepage, https://github.com/HelgDemidov/refigure
-Project-URL: Repository, https://github.com/HelgDemidov/refigure
-Author-email: HelgDemidov <helg.demidov88@gmail.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Classifier: Development Status :: 2 - Pre-Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Text Processing :: Markup :: Markdown
-Requires-Python: >=3.10
-Requires-Dist: lxml<7,>=6.1
-Provides-Extra: docx
-Requires-Dist: mammoth<2,>=1.12; extra == 'docx'
-Requires-Dist: markdownify<2,>=1.2; extra == 'docx'
-Provides-Extra: vlm
-Requires-Dist: pdfplumber<0.12,>=0.11; extra == 'vlm'
-Provides-Extra: vlm-direct
-Requires-Dist: anthropic<1,>=0.120; extra == 'vlm-direct'
-Requires-Dist: openai<4,>=3.1.0; extra == 'vlm-direct'
-Requires-Dist: pdfplumber<0.12,>=0.11; extra == 'vlm-direct'
-Provides-Extra: xlsx
-Requires-Dist: openpyxl<4,>=3.1; extra == 'xlsx'
-Description-Content-Type: text/markdown
-
 # refigure
 
 **Converters where figures survive.**
@@ -130,6 +100,9 @@ refigure report.docx --vlm                    # needs the system soffice/LibreOf
   chart/group counts + `vlm_used`), not a bare string.
 - **CLI included** — `refigure` console command, stdin/stdout-first, native
   batch mode, typed exit codes (see below).
+- **MCP server included** — `refigure-mcp` console command (`[mcp]` extra),
+  stdio or Streamable HTTP, tools/resources/prompts, batch conversion with
+  per-file isolation (see below).
 
 ## CLI
 
@@ -163,6 +136,49 @@ Exit codes:
 | 5 | the format's extra (`[docx]`/`[xlsx]`) isn't installed |
 | 6 | unexpected internal error |
 
+## MCP server
+
+`refigure-mcp` — the same converters as an
+[MCP](https://modelcontextprotocol.io) server, for agents/IDEs that speak
+the protocol directly instead of shelling out to a CLI or importing the
+library:
+
+```bash
+pip install "refigure[mcp,docx,xlsx]"
+refigure-mcp                              # stdio — the MCP client launches it
+```
+
+```json
+{
+  "mcpServers": {
+    "refigure": { "command": "refigure-mcp" }
+  }
+}
+```
+
+Three tools — `convert_docx`, `convert_xlsx`, and `convert_batch` (multiple
+files in one call: one bad file reports its own error without aborting the
+rest) — each registered only if its format extra is actually installed.
+`use_vlm`/`--vlm-provider` and friends work the same as the CLI. A result
+too large to inline is stored and handed back as a
+`refigure://conversion/{id}` resource instead of inflating the tool
+response. Two prompts (`ingest_for_rag`, `explain_conversion_warnings`)
+help a client pick the right tool/VLM settings for the job.
+
+Streamable HTTP is opt-in, for a shared/remote deployment — bearer-token
+auth is required, not optional:
+
+```bash
+echo "sk-... = alice" > tokens.txt
+refigure-mcp --transport http --mcp-auth-token-file tokens.txt
+```
+
+Per-caller rate-limiting (protects the operator's own spend from a
+leaked/runaway token) applies automatically over HTTP, together with a
+fairness soft-cap once 2+ callers are configured; `refigure-mcp --help`
+covers every tuning flag (concurrency, timeouts, resource-store limits,
+batch size, VLM ceiling).
+
 ## Real examples
 
 Full `convert()` output on real, openly-licensed documents — not

{refigure-0.2.0 → refigure-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "refigure"
-version = "0.2.0"
-description = "DOCX/XLSX -> Markdown conversion with native OOXML chart-data extraction, no rasterize/OCR/VLM"
+version = "0.3.0"
+description = "DOCX/XLSX -> Markdown conversion with native OOXML chart-data extraction (no rasterize/OCR/VLM needed) + optional VLM interpretation for figures with no native chart data"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
@@ -57,9 +57,17 @@ vlm = ["pdfplumber>=0.11,<0.12"]
 # [vlm] here reflects a genuine dependency, not a bug to route around by
 # flattening client.py out of the package.
 vlm-direct = ["refigure[vlm]", "openai>=3.1.0,<4", "anthropic>=0.120,<1"]
+# MCP server (v2, stage 10) — thin protocol wrapper over docx.convert()/
+# xlsx.convert(), no self-referential coupling to [docx]/[xlsx]/[vlm]
+# (unlike vlm-direct above): refigure/mcp/__init__.py's guard is the only
+# module-level dependency, a bare `refigure[mcp]` is valid with 0 tools
+# registered — see docs/mcp-server/mcp-server-architecture/
+# mcp-server-architecture.md §2.
+mcp = ["mcp>=2.0,<3"]
 
 [project.scripts]
 refigure = "refigure.cli:main"
+refigure-mcp = "refigure.mcp.cli:main"
 
 [project.urls]
 Homepage = "https://github.com/HelgDemidov/refigure"

{refigure-0.2.0 → refigure-0.3.0}/refigure/__init__.py

@@ -6,6 +6,7 @@ from .api import (
     CorruptArchiveError,
     MissingOptionalDependencyError,
     UnsupportedFormatError,
+    VlmMarkerLimitExceededError,
 )
 
 try:
@@ -24,4 +25,5 @@ __all__ = [
     "CorruptArchiveError",
     "MissingOptionalDependencyError",
     "UnsupportedFormatError",
+    "VlmMarkerLimitExceededError",
 ]

{refigure-0.2.0 → refigure-0.3.0}/refigure/api.py

@@ -255,6 +255,35 @@ class Config:
     language-sensitivity — see ``vlm_verify``'s own docstring and
     ``witness_defects``'s."""
 
+    vlm_max_markers: int | None = None
+    """Maximum number of VLM markers this call may resolve with a PAID
+    call (docx-only — XLSX has no VLM path). ``None`` (default): no
+    ceiling, current behavior. A caller that sets this gets a pre-flight
+    check in ``vlm.enhance_docx_markdown``, before any paid call: every
+    marker that would incur at least one paid call — a cache-miss, OR (
+    when ``vlm_verify=True``) a cache-hit whose ``judge_verdict`` is still
+    unset (the judge-backfill pass is itself a paid call; without counting
+    it, a fully-cached document under ``vlm_verify=True`` would silently
+    bypass the ceiling) — is counted once, via a single memoized cache
+    probe reused by the main resolution loops (no doubled reads against a
+    networked ``VlmCacheBackend``, no TOCTOU window between the count and
+    the paid calls). Exceeding the count raises
+    ``VlmMarkerLimitExceededError`` immediately, before the first paid
+    call — no partial processing.
+
+    Motivation: input size alone does not bound the number of paid VLM
+    calls a document can trigger — a 1.46 MB real-world document carrying
+    9990 VLM-eligible markers was the concrete case that motivated this
+    field. This is the one lever specifically for VLM cost/latency
+    escalation; it is orthogonal to ``strict`` (which narrows exactly one
+    unrelated failure mode, a missing ``soffice`` binary) and to the
+    zero-loss-on-failure contract every other VLM failure path already
+    has (PR #16's security-audit contract) — an unavailable cache backend
+    still degrades every PROBE to "treat as a miss" (``vlm.
+    _cache_get_safely``'s existing behavior), which can trigger this
+    ceiling honestly (those calls really would have been paid), not a
+    weakening of that contract."""
+
 
 @dataclass
 class ConversionResult:
@@ -287,3 +316,9 @@ class MissingOptionalDependencyError(Exception):
     binary a pip extra can't provide (``soffice``/LibreOffice, needed to
     render a composite DOCX group under ``Config(use_vlm=True,
     strict=True)`` — see ``Config.strict``'s docstring)."""
+
+
+class VlmMarkerLimitExceededError(Exception):
+    """The document carries more VLM-eligible markers requiring a paid call
+    than ``Config.vlm_max_markers`` allows (see its docstring) — raised
+    before any paid call, not after partial processing."""

{refigure-0.2.0 → refigure-0.3.0}/refigure/cli.py

@@ -33,6 +33,7 @@ EXIT_UNSUPPORTED_FORMAT = 3
 EXIT_CORRUPT_ARCHIVE = 4
 EXIT_MISSING_DEPENDENCY = 5
 EXIT_INTERNAL_ERROR = 6
+EXIT_VLM_MARKER_LIMIT = 7
 
 _SUFFIX_TO_FORMAT = {".docx": "docx", ".xlsx": "xlsx"}
 
@@ -67,7 +68,12 @@ def _exit_code_for(exc: Exception) -> int:
     # Imported lazily too — importing refigure.api at module level is cheap
     # (lxml-only, see api.py), but the exception CLASSES only need to exist
     # once we actually have an exception to classify.
-    from .api import CorruptArchiveError, MissingOptionalDependencyError, UnsupportedFormatError
+    from .api import (
+        CorruptArchiveError,
+        MissingOptionalDependencyError,
+        UnsupportedFormatError,
+        VlmMarkerLimitExceededError,
+    )
 
     if isinstance(exc, UnsupportedFormatError):
         return EXIT_UNSUPPORTED_FORMAT
@@ -75,6 +81,8 @@ def _exit_code_for(exc: Exception) -> int:
         return EXIT_CORRUPT_ARCHIVE
     if isinstance(exc, MissingOptionalDependencyError):
         return EXIT_MISSING_DEPENDENCY
+    if isinstance(exc, VlmMarkerLimitExceededError):
+        return EXIT_VLM_MARKER_LIMIT
     return EXIT_INTERNAL_ERROR
 
 
@@ -200,6 +208,16 @@ def build_parser() -> argparse.ArgumentParser:
             "putting a secret in argv/shell history."
         ),
     )
+    vlm_group.add_argument(
+        "--vlm-max-markers",
+        metavar="N",
+        type=int,
+        help=(
+            "Cap on VLM markers requiring a paid call (Config(vlm_max_markers=...)). "
+            "Exceeding it exits with code 7 before any paid call. Unset: no cap "
+            "(the library default)."
+        ),
+    )
     verbosity = parser.add_mutually_exclusive_group()
     verbosity.add_argument(
         "-v",
@@ -271,6 +289,8 @@ def _build_config(args: argparse.Namespace, parser: argparse.ArgumentParser) ->
         kwargs["vlm_model"] = args.vlm_model
     if args.vlm_judge_mode is not None:
         kwargs["vlm_judge_mode"] = args.vlm_judge_mode
+    if args.vlm_max_markers is not None:
+        kwargs["vlm_max_markers"] = args.vlm_max_markers
     if args.vlm:
         # Provider/key-file resolution only matters when VLM is actually
         # enabled — otherwise --vlm-provider openai with no --vlm would

refigure-0.3.0/refigure/mcp/__init__.py

@@ -0,0 +1,30 @@
+"""MCP-server subpackage (v2, stage 10) — a thin protocol wrapper over
+``refigure.docx.convert()``/``refigure.xlsx.convert()``, not new
+conversion logic. See ``docs/mcp-server/mcp-server-architecture/
+mcp-server-architecture.md`` for the full design.
+
+Guard is the first same-package-import-adjacent statement in this file —
+same discipline as ``refigure/vlm/__init__.py``'s own guard docstring
+explains: a module-level ``try/except ImportError`` is only effective if
+it runs before any OTHER same-package import that could itself
+transitively raise an unguarded ``ImportError``. This subpackage currently
+has no such transitive risk (``server.py``/``cli.py`` only import
+``..api`` at module level, itself ``lxml``-only), but the ordering
+discipline holds regardless of today's safety being circumstantial.
+
+No self-referential coupling to ``[docx]``/``[xlsx]``/``[vlm]`` (unlike
+``vlm-direct``, see ``pyproject.toml``'s comment there) — a bare
+``refigure[mcp]`` install is valid, it just registers 0 tools (``docx``/
+``xlsx`` are imported lazily, per-tool, inside ``server.py``).
+"""
+
+from __future__ import annotations
+
+from ..api import MissingOptionalDependencyError
+
+try:
+    import mcp as _mcp_sdk  # noqa: F401 - import-for-guard, see module docstring
+except ImportError as exc:  # pragma: no cover - see tests/unit/test_optional_dependency_guards.py
+    raise MissingOptionalDependencyError(
+        "refigure[mcp] is required to use the refigure-mcp server"
+    ) from exc

refigure-0.3.0/refigure/mcp/_lru.py

@@ -0,0 +1,159 @@
+"""Generic bounded LRU + byte-budget store, shared by ``ServerState``
+(``state.py``) and ``BoundedLruVlmCache`` (``vlm_cache.py``) — architecture
+doc §7-bis: "the same LRU utility as the resource store", not two
+independent implementations of the same eviction policy.
+
+Byte-budget eviction is O(1) per operation: every entry carries its OWN
+precomputed size (this class never (re)computes it — the caller does, and
+is expected to do so OUTSIDE any lock it holds), and a running total is
+adjusted by plain addition/subtraction on insert/evict. Recomputing every
+remaining entry's size on each eviction (e.g. re-encoding/re-hashing the
+whole store under the lock) would reproduce the exact stall the
+architecture review measured for that approach: 34-60ms of event-loop
+blocking vs. <1ms for this incremental counter.
+
+Thread-safe via a plain ``threading.Lock`` — correct for both of this
+class's callers even though they run in different execution contexts:
+``ServerState`` is only ever touched from the event loop (architecture
+doc §4's "mutations only from the event loop" invariant), while
+``BoundedLruVlmCache`` is written from worker threads (core's
+``enhance_docx_markdown`` calls ``VlmCacheBackend.set()`` synchronously,
+inside the ``anyio.to_thread`` bridge). A plain lock protects either
+caller identically — no async-specific primitive needed here.
+
+Phase 3 (``docs/mcp-server/mcp-server-phase3-http-auth/
+mcp-server-phase3-http-auth-2026-08-21.md`` §1) adds two additive members —
+existing callers that don't pass ``on_evict``/don't call ``remove()`` see
+no behavior change: an optional ``on_evict`` callback, invoked for entries
+evicted by ``insert()``'s own count/byte-budget loop (``ServerState``'s
+per-caller soft-cap accounting needs to know which OTHER caller's entry a
+given ``insert()`` just evicted — this class has no other way to tell it),
+and ``remove()``, an explicit point-eviction the caller already knows
+about (deliberately NOT routed through ``on_evict`` — the caller doing the
+removing already updates its own bookkeeping at the call site, invoking
+the callback too would double-count).
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict
+from typing import Callable, Generic, TypeVar
+
+# Not PEP 695 generics (`class BoundedLru[T]`) — this repo's floor is
+# Python 3.10 (`pyproject.toml`'s `requires-python = ">=3.10"`), that
+# syntax is 3.12+.
+_T = TypeVar("_T")
+
+
+class BoundedLru(Generic[_T]):
+    """A dict-like LRU store bounded by BOTH entry count and total byte
+    size — whichever limit is hit first evicts the oldest entries until
+    neither is exceeded. Has no notion of time itself; a TTL (if the
+    caller wants one, as ``ServerState`` does) is layered on top by
+    storing a timestamp inside the value and checking it after ``get()``,
+    not something this class enforces.
+
+    A single entry larger than ``max_bytes`` on its own is kept, not
+    evicted-on-arrival: eviction never drops the store to zero entries
+    just because the one remaining entry is large — a caller calling
+    ``get()`` right after ``insert()`` must always find what it just
+    inserted. This only matters for a pathologically oversized single
+    entry; every real caller in this codebase keeps individual entries
+    well under their respective budgets (see ``state.py``/
+    ``vlm_cache.py``)."""
+
+    def __init__(
+        self,
+        *,
+        max_entries: int,
+        max_bytes: int,
+        on_evict: Callable[[str, _T, int], None] | None = None,
+    ) -> None:
+        self._max_entries = max_entries
+        self._max_bytes = max_bytes
+        self._on_evict = on_evict
+        self._lock = threading.Lock()
+        self._data: OrderedDict[str, tuple[_T, int]] = OrderedDict()
+        self._total_bytes = 0
+
+    def insert(self, key: str, value: _T, size_bytes: int) -> None:
+        """Insert (or replace) ``key``, then evict oldest entries while
+        over either limit. ``size_bytes`` must be precomputed by the
+        caller BEFORE calling this — see the module docstring; computing
+        it here (e.g. from ``value``) would put arbitrary caller-defined
+        serialization cost back under the lock, exactly what this class
+        exists to avoid.
+
+        ``on_evict`` (if set) is called once per entry evicted by THIS
+        call's own count/byte-budget loop — AFTER ``self._lock`` has
+        already been released (never while held: a lock this class
+        doesn't own must never be acquired while this one is, and
+        ``ServerState``'s own callback does exactly that with its own
+        ``self._lock`` — see the inline comment below for the full
+        lock-ordering rationale). A replacement of ``key`` itself
+        (already present, same key re-inserted) is NOT reported via
+        ``on_evict`` — that's a value update, not an eviction, and the
+        caller performing the ``insert()`` already knows about it
+        directly."""
+        evicted: list[tuple[str, _T, int]] = []
+        with self._lock:
+            if key in self._data:
+                _, old_size = self._data.pop(key)
+                self._total_bytes -= old_size
+            self._data[key] = (value, size_bytes)
+            self._total_bytes += size_bytes
+            while len(self._data) > 1 and (
+                len(self._data) > self._max_entries or self._total_bytes > self._max_bytes
+            ):
+                evicted_key, (evicted_value, evicted_size) = self._data.popitem(last=False)
+                self._total_bytes -= evicted_size
+                if self._on_evict is not None:
+                    evicted.append((evicted_key, evicted_value, evicted_size))
+        # Callbacks fire AFTER releasing the lock (not each iteration inside
+        # the loop above): a lock this class doesn't own must never be
+        # acquired while this one is held, and ServerState's own callback
+        # (§4 of the phase-3 spec) does exactly that (its own `self._lock`).
+        # Reporting collected evictions post-unlock avoids any risk of a
+        # lock-ordering cycle, at the cost of a caller theoretically
+        # observing `on_evict` fire slightly after `insert()`'s own state
+        # change is externally visible — irrelevant here, every real
+        # `on_evict` caller is on the same single-threaded event loop.
+        if self._on_evict is not None:
+            for evicted_key, evicted_value, evicted_size in evicted:
+                self._on_evict(evicted_key, evicted_value, evicted_size)
+
+    def remove(self, key: str) -> _T | None:
+        """Explicit point-eviction of ``key`` — the value it held, or
+        ``None`` if ``key`` wasn't present. Deliberately does NOT invoke
+        ``on_evict`` (see the module/class docstrings): the caller
+        removing a specific key already knows it's doing so and updates
+        its own bookkeeping at the call site — ``ServerState``'s soft-cap
+        self-eviction (phase-3 spec §4) is the one real caller."""
+        with self._lock:
+            entry = self._data.pop(key, None)
+            if entry is None:
+                return None
+            value, size_bytes = entry
+            self._total_bytes -= size_bytes
+            return value
+
+    def get(self, key: str) -> _T | None:
+        """The value for ``key``, or ``None`` on a miss. A hit touches the
+        entry as most-recently-used (moves it to the end) — a genuine LRU
+        read, not just a lookup."""
+        with self._lock:
+            if key not in self._data:
+                return None
+            self._data.move_to_end(key)
+            value, _ = self._data[key]
+            return value
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._data)
+
+    @property
+    def total_bytes(self) -> int:
+        with self._lock:
+            return self._total_bytes

refigure-0.3.0/refigure/mcp/auth.py

@@ -0,0 +1,102 @@
+"""Token-file loading + the static-token ``TokenVerifier`` implementation
+behind ``refigure-mcp --transport http``. See
+``docs/mcp-server/mcp-server-phase3-http-auth/
+mcp-server-phase3-http-auth-2026-08-21.md`` §2 for the design this module
+implements, and architecture doc §6 for the requirements it comes from.
+
+This module is a config-loading/auth-verification concern, not a
+conversion-tool concern — its own ``ValueError``s are handled at CLI
+startup (``cli.py``, before ``build_server()`` is even called), never
+routed through ``server.py``'s ``_TYPED_EXCEPTIONS``/``_call_and_wrap_errors``
+(that's for exceptions a live tool call can raise, which this isn't).
+"""
+
+from __future__ import annotations
+
+import hmac
+from pathlib import Path
+
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+
+from .state import _LOCAL_CALLER_ID
+
+
+def _normalize(value: str) -> str:
+    """The one normalization function used both when loading the token
+    file and (indirectly, via the tuples ``_StaticTokenVerifier`` is built
+    from) when verifying a request's bearer token — architecture doc §6:
+    "одна функция нормализации ... на стартовую дедупликацию и
+    рантайм-проверку". Case-sensitive, ``strip()`` only — no case-folding,
+    a bearer token is opaque data, not a human-typed identifier."""
+    return value.strip()
+
+
+def load_token_file(path: Path) -> dict[str, str]:
+    """Parse a ``--mcp-auth-token-file``: one ``token = caller_id`` pair
+    per non-blank line (exactly one ``=``; no comment syntax — the
+    architecture doc doesn't call for one, and this format doesn't need
+    it). Returns ``{token: caller_id}``.
+
+    Raises ``ValueError`` (line number included in the message) on: a
+    line with no ``=`` or more than one; an empty token or ``caller_id``
+    after normalization; ``caller_id == "__local__"`` (reserved for the
+    stdio/in-memory sentinel, architecture doc §6 — accepting it here
+    would let a configured HTTP caller collide with the unauthenticated
+    local identity); the SAME token value mapped to two DIFFERENT
+    ``caller_id``s (almost certainly a typo — silently letting the last
+    line win would hide a real misconfiguration). The same token mapped
+    to the SAME ``caller_id`` twice is a harmless idempotent duplicate,
+    not an error. DIFFERENT tokens mapped to the same ``caller_id`` is
+    the normal token-rotation case (architecture doc §6) and needs no
+    special handling at all — it's just two distinct dict keys."""
+    token_map: dict[str, str] = {}
+    for lineno, raw_line in enumerate(path.read_text().splitlines(), start=1):
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line.count("=") != 1:
+            raise ValueError(
+                f"{path}:{lineno}: expected exactly one 'token = caller_id' pair, got {raw_line!r}"
+            )
+        raw_token, raw_caller_id = line.split("=", 1)
+        token = _normalize(raw_token)
+        caller_id = _normalize(raw_caller_id)
+        if not token or not caller_id:
+            raise ValueError(f"{path}:{lineno}: token and caller_id must both be non-empty")
+        if caller_id == _LOCAL_CALLER_ID:
+            raise ValueError(
+                f"{path}:{lineno}: caller_id {_LOCAL_CALLER_ID!r} is reserved "
+                "for the stdio/unauthenticated identity, not usable in a token file"
+            )
+        existing = token_map.get(token)
+        if existing is not None and existing != caller_id:
+            raise ValueError(
+                f"{path}:{lineno}: token already maps to caller_id {existing!r}, "
+                f"got a second, different caller_id {caller_id!r} for the same token value"
+            )
+        token_map[token] = caller_id
+    return token_map
+
+
+class _StaticTokenVerifier(TokenVerifier):
+    """``TokenVerifier`` (SDK protocol, ``mcp.server.auth.provider``) over a
+    fixed ``{token: caller_id}`` map loaded once at server startup — no
+    live-reload (phase-3 spec, out of scope; architecture doc §6 phrases
+    it conditionally, "если появится").
+
+    Verification is a linear scan with ``hmac.compare_digest`` per
+    candidate, NOT a dict lookup by token value — architecture doc §6:
+    "сравнение — constant-time". A dict lookup is faster (O(1) vs. O(n))
+    but its timing depends on the incoming token's hash/equality path in
+    a way ``compare_digest`` is specifically designed to avoid; the token
+    list in a self-hosted deployment is small (single/low-double digits),
+    so the O(n) scan costs nothing that matters here."""
+
+    def __init__(self, token_map: dict[str, str]) -> None:
+        self._entries: tuple[tuple[str, str], ...] = tuple(token_map.items())
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        for configured_token, caller_id in self._entries:
+            if hmac.compare_digest(token, configured_token):
+                return AccessToken(token=token, client_id=caller_id, scopes=[])
+        return None