refigure 0.3.0__tar.gz → 0.3.2__tar.gz

{refigure-0.3.0 → refigure-0.3.2}/.gitignore

@@ -54,6 +54,7 @@ CLAUDE.local.md
 docs/*
 !docs/assets/
 CLAUDE.md
+BACKLOG.md
 
 # Real-document integration test fixtures (2026-08-05): 26/27 are checked
 # in — clean, well-documented redistribution licenses (see ATTRIBUTION.md

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

@@ -1,3 +1,43 @@
+Metadata-Version: 2.5
+Name: refigure
+Version: 0.3.2
+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: full
+Requires-Dist: anthropic<1,>=0.120; extra == 'full'
+Requires-Dist: mammoth<2,>=1.12; extra == 'full'
+Requires-Dist: markdownify<2,>=1.2; extra == 'full'
+Requires-Dist: mcp<3,>=2.0; extra == 'full'
+Requires-Dist: openai<4,>=3.1.0; extra == 'full'
+Requires-Dist: openpyxl<4,>=3.1; extra == 'full'
+Requires-Dist: pdfplumber<0.12,>=0.11; extra == 'full'
+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.**
@@ -7,6 +47,8 @@
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
 
+<!-- mcp-name: io.github.HelgDemidov/refigure -->
+
 DOCX / XLSX → Markdown converters that treat embedded charts, composite
 diagrams and infographics as single semantic objects instead of silently
 dropping or fragmenting them: native OOXML chart-data extraction (no
@@ -68,6 +110,12 @@ print(result.markdown)
 print(f"{result.charts_found} charts, {result.groups_found} composite figures")
 ```
 
+Or without a permanent install, via [uv](https://docs.astral.sh/uv/)/`uvx`:
+
+```bash
+uvx --from "refigure[docx,xlsx]" refigure report.docx
+```
+
 Optional VLM interpretation, for a composite figure the chart engine can't
 reconstruct on its own (see Features below):
 
@@ -103,6 +151,9 @@ refigure report.docx --vlm                    # needs the system soffice/LibreOf
 - **MCP server included** — `refigure-mcp` console command (`[mcp]` extra),
   stdio or Streamable HTTP, tools/resources/prompts, batch conversion with
   per-file isolation (see below).
+- **Docker image** — `ghcr.io/helgdemidov/refigure`, both console commands
+  on `PATH`, `soffice`/LibreOffice baked in — the VLM composite-figure
+  path works turnkey, no manual LibreOffice install (see below).
 
 ## CLI
 
@@ -156,6 +207,22 @@ refigure-mcp                              # stdio — the MCP client launches it
 }
 ```
 
+Or point the client at `uvx` instead, with no permanent install at all:
+
+```json
+{
+  "mcpServers": {
+    "refigure": {
+      "command": "uvx",
+      "args": ["--from", "refigure[mcp,docx,xlsx,vlm-direct]", "refigure-mcp"]
+    }
+  }
+}
+```
+
+`refigure[full]` is a shortcut for `refigure[mcp,docx,xlsx,vlm-direct]` —
+every tool, both formats, every VLM provider, one extras string.
+
 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.
@@ -179,6 +246,52 @@ fairness soft-cap once 2+ callers are configured; `refigure-mcp --help`
 covers every tuning flag (concurrency, timeouts, resource-store limits,
 batch size, VLM ceiling).
 
+## Docker
+
+One image, both surfaces — `refigure` and `refigure-mcp` are already on
+`PATH`, no separate CLI/MCP builds to choose between. The one thing this
+format buys over `pip`/`uvx` that neither can: the system `soffice`/
+LibreOffice binary the VLM composite-figure path needs is baked in, not a
+manual install.
+
+```bash
+docker pull ghcr.io/helgdemidov/refigure:0.3.1
+```
+
+CLI, via a bind mount (the image's working directory is already `/data`):
+
+```bash
+docker run --rm -v "$PWD:/data:ro" ghcr.io/helgdemidov/refigure:0.3.1 \
+  refigure /data/report.docx
+```
+
+MCP, stdio — the client launches the container itself:
+
+```json
+{
+  "mcpServers": {
+    "refigure": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/helgdemidov/refigure:0.3.1", "refigure-mcp"]
+    }
+  }
+}
+```
+
+MCP, Streamable HTTP — `--mcp-http-host 0.0.0.0` is required here, not
+optional: the default `127.0.0.1` bind is unreachable through `-p` port
+publishing (Docker's NAT reaches the container's external network
+interface, not its loopback), so the "obvious" invocation without this
+flag would silently never respond:
+
+```bash
+echo "sk-... = alice" > tokens.txt
+docker run --rm -p 8000:8000 -v "$PWD/tokens.txt:/data/tokens.txt:ro" \
+  ghcr.io/helgdemidov/refigure:0.3.1 \
+  refigure-mcp --transport http --mcp-http-host 0.0.0.0 \
+  --mcp-auth-token-file /data/tokens.txt
+```
+
 ## Real examples
 
 Full `convert()` output on real, openly-licensed documents — not
@@ -243,8 +356,11 @@ else:
     markdown = refigure.xlsx.convert(path).markdown
 ```
 
-`v0.1.0` published via trusted publishing (GitHub↔PyPI, no stored tokens).
-`refigure-md` is a reserved alternate name, not an active release.
+`v0.3.1` published via trusted publishing (GitHub↔PyPI, no stored tokens),
+also on GHCR as `ghcr.io/helgdemidov/refigure` and on the official
+[MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.HelgDemidov/refigure`. `refigure-md` is a reserved alternate
+name, not an active release.
 
 ## License
 

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

@@ -1,35 +1,3 @@
-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.**
@@ -39,6 +7,8 @@ Description-Content-Type: text/markdown
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
 
+<!-- mcp-name: io.github.HelgDemidov/refigure -->
+
 DOCX / XLSX → Markdown converters that treat embedded charts, composite
 diagrams and infographics as single semantic objects instead of silently
 dropping or fragmenting them: native OOXML chart-data extraction (no
@@ -100,6 +70,12 @@ print(result.markdown)
 print(f"{result.charts_found} charts, {result.groups_found} composite figures")
 ```
 
+Or without a permanent install, via [uv](https://docs.astral.sh/uv/)/`uvx`:
+
+```bash
+uvx --from "refigure[docx,xlsx]" refigure report.docx
+```
+
 Optional VLM interpretation, for a composite figure the chart engine can't
 reconstruct on its own (see Features below):
 
@@ -135,6 +111,9 @@ refigure report.docx --vlm                    # needs the system soffice/LibreOf
 - **MCP server included** — `refigure-mcp` console command (`[mcp]` extra),
   stdio or Streamable HTTP, tools/resources/prompts, batch conversion with
   per-file isolation (see below).
+- **Docker image** — `ghcr.io/helgdemidov/refigure`, both console commands
+  on `PATH`, `soffice`/LibreOffice baked in — the VLM composite-figure
+  path works turnkey, no manual LibreOffice install (see below).
 
 ## CLI
 
@@ -188,6 +167,22 @@ refigure-mcp                              # stdio — the MCP client launches it
 }
 ```
 
+Or point the client at `uvx` instead, with no permanent install at all:
+
+```json
+{
+  "mcpServers": {
+    "refigure": {
+      "command": "uvx",
+      "args": ["--from", "refigure[mcp,docx,xlsx,vlm-direct]", "refigure-mcp"]
+    }
+  }
+}
+```
+
+`refigure[full]` is a shortcut for `refigure[mcp,docx,xlsx,vlm-direct]` —
+every tool, both formats, every VLM provider, one extras string.
+
 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.
@@ -211,6 +206,52 @@ fairness soft-cap once 2+ callers are configured; `refigure-mcp --help`
 covers every tuning flag (concurrency, timeouts, resource-store limits,
 batch size, VLM ceiling).
 
+## Docker
+
+One image, both surfaces — `refigure` and `refigure-mcp` are already on
+`PATH`, no separate CLI/MCP builds to choose between. The one thing this
+format buys over `pip`/`uvx` that neither can: the system `soffice`/
+LibreOffice binary the VLM composite-figure path needs is baked in, not a
+manual install.
+
+```bash
+docker pull ghcr.io/helgdemidov/refigure:0.3.1
+```
+
+CLI, via a bind mount (the image's working directory is already `/data`):
+
+```bash
+docker run --rm -v "$PWD:/data:ro" ghcr.io/helgdemidov/refigure:0.3.1 \
+  refigure /data/report.docx
+```
+
+MCP, stdio — the client launches the container itself:
+
+```json
+{
+  "mcpServers": {
+    "refigure": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "ghcr.io/helgdemidov/refigure:0.3.1", "refigure-mcp"]
+    }
+  }
+}
+```
+
+MCP, Streamable HTTP — `--mcp-http-host 0.0.0.0` is required here, not
+optional: the default `127.0.0.1` bind is unreachable through `-p` port
+publishing (Docker's NAT reaches the container's external network
+interface, not its loopback), so the "obvious" invocation without this
+flag would silently never respond:
+
+```bash
+echo "sk-... = alice" > tokens.txt
+docker run --rm -p 8000:8000 -v "$PWD/tokens.txt:/data/tokens.txt:ro" \
+  ghcr.io/helgdemidov/refigure:0.3.1 \
+  refigure-mcp --transport http --mcp-http-host 0.0.0.0 \
+  --mcp-auth-token-file /data/tokens.txt
+```
+
 ## Real examples
 
 Full `convert()` output on real, openly-licensed documents — not
@@ -275,8 +316,11 @@ else:
     markdown = refigure.xlsx.convert(path).markdown
 ```
 
-`v0.1.0` published via trusted publishing (GitHub↔PyPI, no stored tokens).
-`refigure-md` is a reserved alternate name, not an active release.
+`v0.3.1` published via trusted publishing (GitHub↔PyPI, no stored tokens),
+also on GHCR as `ghcr.io/helgdemidov/refigure` and on the official
+[MCP Registry](https://registry.modelcontextprotocol.io) as
+`io.github.HelgDemidov/refigure`. `refigure-md` is a reserved alternate
+name, not an active release.
 
 ## License
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "refigure"
-version = "0.3.0"
+version = "0.3.2"
 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"
@@ -64,6 +64,14 @@ vlm-direct = ["refigure[vlm]", "openai>=3.1.0,<4", "anthropic>=0.120,<1"]
 # registered — see docs/mcp-server/mcp-server-architecture/
 # mcp-server-architecture.md §2.
 mcp = ["mcp>=2.0,<3"]
+# Convenience meta-extra for one-shot `uvx --from 'refigure[full]' ...`
+# invocations — union of every capability extra, nothing of its own. Carries
+# no independent isolation contract: if any component subset breaks, the
+# per-extra CI legs above catch it first. Exists specifically because [mcp]
+# alone registers 0 tools (see comment above) and [vlm-direct] alone has no
+# format to convert — a useful refigure-mcp needs all four together, and
+# spelling that out by hand in every doc/README invocation got repetitive.
+full = ["refigure[mcp,docx,xlsx,vlm-direct]"]
 
 [project.scripts]
 refigure = "refigure.cli:main"

{refigure-0.3.0 → refigure-0.3.2}/refigure/mcp/server.py

@@ -45,6 +45,7 @@ from mcp.types import (
 )
 from pydantic import AnyHttpUrl
 
+from .. import __version__
 from ..api import (
     Config,
     ConversionResult,
@@ -1221,6 +1222,7 @@ def build_server(
     if token_map is not None:
         mcp = MCPServer(
             "refigure",
+            version=__version__,
             token_verifier=_StaticTokenVerifier(token_map),
             auth=AuthSettings(
                 issuer_url=AnyHttpUrl("http://localhost/"),
@@ -1228,7 +1230,7 @@ def build_server(
             ),
         )
     else:
-        mcp = MCPServer("refigure")
+        mcp = MCPServer("refigure", version=__version__)
     server_ctx = _ServerContext(
         limiter=anyio.CapacityLimiter(max_concurrent),
         vlm_client=vlm_client,

{refigure-0.3.0 → refigure-0.3.2}/tests/unit/mcp/test_http.py

@@ -70,6 +70,35 @@ def _build_http_server(**kwargs):
     return build_server(transport="http", **kwargs)
 
 
+async def test_server_reports_its_own_version_over_http_too() -> None:
+    """Same regression as test_tools.py's stdio-side version, exercised
+    against the OTHER build_server() construction branch (token_map is
+    not None -> the token_verifier/AuthSettings path) — both branches
+    pass version=__version__ as a separate literal, line coverage alone
+    doesn't prove this one's value is right."""
+    import refigure
+
+    mcp_server = _build_http_server()
+    app = mcp_server.streamable_http_app()
+
+    async with app.router.lifespan_context(app):
+        http_client = httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app),
+            base_url=_BASE_URL,
+            headers={"Authorization": "Bearer tok-alice"},
+        )
+        async with http_client:
+            async with streamable_http_client(url=f"{_BASE_URL}/mcp", http_client=http_client) as (
+                read,
+                write,
+            ):
+                async with ClientSession(read, write) as session:
+                    init = await session.initialize()
+
+    assert init.server_info.version == refigure.__version__
+    assert init.server_info.version != ""
+
+
 async def test_valid_bearer_token_converts_successfully() -> None:
     mcp_server = _build_http_server()
     app = mcp_server.streamable_http_app()

{refigure-0.3.0 → refigure-0.3.2}/tests/unit/mcp/test_tools.py

@@ -182,6 +182,19 @@ async def test_list_tools_registers_both_convert_tools(client: Client) -> None:
         assert tool.annotations.read_only_hint is True
 
 
+async def test_server_reports_its_own_version_in_the_mcp_handshake(client: Client) -> None:
+    """Regression: MCPServer("refigure") was built with no version= kwarg
+    at all, so a real client's initialize() handshake saw an empty string
+    instead of refigure's actual version — found live via a real
+    subprocess stdio_client() round trip (this repo's first, every other
+    test here uses the in-memory Client), not by code review."""
+    import refigure
+
+    assert client.server_info is not None
+    assert client.server_info.version == refigure.__version__
+    assert client.server_info.version != ""
+
+
 async def test_corrupt_zip_bytes_are_rejected_as_corrupt_archive(client: Client) -> None:
     """A structurally-valid zip with no OOXML content still degrades to
     CorruptArchiveError, not something more exotic — belt-and-suspenders