exstruct 0.3.7__tar.gz → 0.4.1__tar.gz

{exstruct-0.3.7 → exstruct-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.3.7
+Version: 0.4.1
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -39,6 +39,14 @@ Requires-Dist: pandas>=2.3.3
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: scipy>=1.16.3
 Requires-Dist: xlwings>=0.33.16
+Requires-Dist: pyyaml>=6.0.3 ; extra == 'all'
+Requires-Dist: python-toon>=0.1.3 ; extra == 'all'
+Requires-Dist: pypdfium2>=5.1.0 ; extra == 'all'
+Requires-Dist: pillow>=12.0.0 ; extra == 'all'
+Requires-Dist: mcp>=1.6.0,<2.0.0 ; extra == 'all'
+Requires-Dist: httpx>=0.27,<1.0 ; extra == 'all'
+Requires-Dist: mcp>=1.6.0,<2.0.0 ; extra == 'mcp'
+Requires-Dist: httpx>=0.27,<1.0 ; extra == 'mcp'
 Requires-Dist: pypdfium2>=5.1.0 ; extra == 'render'
 Requires-Dist: pillow>=12.0.0 ; extra == 'render'
 Requires-Dist: python-toon>=0.1.3 ; extra == 'toon'
@@ -48,6 +56,8 @@ Project-URL: Documentation, https://harumiweb.github.io/exstruct/
 Project-URL: Homepage, https://harumiweb.github.io/exstruct/
 Project-URL: Issues, https://github.com/harumiWeb/exstruct/issues
 Project-URL: Repository, https://github.com/harumiWeb/exstruct
+Provides-Extra: all
+Provides-Extra: mcp
 Provides-Extra: render
 Provides-Extra: toon
 Provides-Extra: yaml
@@ -66,8 +76,8 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, smartart, table candidates, print areas/views, and auto page-break areas per sheet.
-- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
-- **Formula map extraction**: emits `formulas_map` (formula string -> cell coordinates) via openpyxl/COM; enabled by default in `verbose` or via `include_formulas_map`.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
+- **Formula map extraction**: emits `formulas_map` (formula string -> cell coordinates) via openpyxl/COM; enabled by default in `verbose` or via `include_formulas_map`.
 - **Auto page-break export (COM only)**: capture Excel-computed auto page breaks and write per-area JSON/YAML/TOON when requested (CLI option appears only when COM is available).
 - **Formats**: JSON (compact by default, `--pretty` available), YAML, TOON (optional dependencies).
 - **Table detection tuning**: adjust heuristics at runtime via API.
@@ -107,6 +117,30 @@ exstruct input.xlsx --pdf --image          # PDF and PNGs (Excel required)
 
 Auto page-break exports are available via API and CLI when Excel/COM is available; the CLI exposes `--auto-page-breaks-dir` only in COM-capable environments.
 
+## MCP Server (stdio)
+
+Install the MCP extras and run the stdio server:
+
+```bash
+pip install exstruct[mcp]
+exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
+```
+
+Available tools:
+
+- `exstruct.extract`
+- `exstruct.read_json_chunk`
+- `exstruct.validate_input`
+
+Notes:
+
+- Logs go to stderr (and optionally `--log-file`) to avoid contaminating stdio responses.
+- On Windows with Excel, standard/verbose can use COM for richer extraction. On non-Windows, COM is unavailable and extraction uses openpyxl-based fallbacks.
+
+MCP Setup Guide for Each AI Agent:
+
+[MCP Server](https://harumiweb.github.io/exstruct/mcp/)
+
 ## Quick Start (Python)
 
 ```python
@@ -392,7 +426,6 @@ flowchart TD
 ```
 ````
 
-
 ## Example 2: General Application Form
 
 ### Excel Sheet

{exstruct-0.3.7 → exstruct-0.4.1}/README.md

@@ -11,8 +11,8 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, smartart, table candidates, print areas/views, and auto page-break areas per sheet.
-- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
-- **Formula map extraction**: emits `formulas_map` (formula string -> cell coordinates) via openpyxl/COM; enabled by default in `verbose` or via `include_formulas_map`.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
+- **Formula map extraction**: emits `formulas_map` (formula string -> cell coordinates) via openpyxl/COM; enabled by default in `verbose` or via `include_formulas_map`.
 - **Auto page-break export (COM only)**: capture Excel-computed auto page breaks and write per-area JSON/YAML/TOON when requested (CLI option appears only when COM is available).
 - **Formats**: JSON (compact by default, `--pretty` available), YAML, TOON (optional dependencies).
 - **Table detection tuning**: adjust heuristics at runtime via API.
@@ -52,6 +52,30 @@ exstruct input.xlsx --pdf --image          # PDF and PNGs (Excel required)
 
 Auto page-break exports are available via API and CLI when Excel/COM is available; the CLI exposes `--auto-page-breaks-dir` only in COM-capable environments.
 
+## MCP Server (stdio)
+
+Install the MCP extras and run the stdio server:
+
+```bash
+pip install exstruct[mcp]
+exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
+```
+
+Available tools:
+
+- `exstruct.extract`
+- `exstruct.read_json_chunk`
+- `exstruct.validate_input`
+
+Notes:
+
+- Logs go to stderr (and optionally `--log-file`) to avoid contaminating stdio responses.
+- On Windows with Excel, standard/verbose can use COM for richer extraction. On non-Windows, COM is unavailable and extraction uses openpyxl-based fallbacks.
+
+MCP Setup Guide for Each AI Agent:
+
+[MCP Server](https://harumiweb.github.io/exstruct/mcp/)
+
 ## Quick Start (Python)
 
 ```python
@@ -337,7 +361,6 @@ flowchart TD
 ```
 ````
 
-
 ## Example 2: General Application Form
 
 ### Excel Sheet

{exstruct-0.3.7 → exstruct-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.3.7"
+version = "0.4.1"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -37,12 +37,25 @@ dev = [
 ]
 
 [project.optional-dependencies]
+all = [
+    "pyyaml>=6.0.3",
+    "python-toon>=0.1.3",
+    "pypdfium2>=5.1.0",
+    "Pillow>=12.0.0",
+    "mcp>=1.6.0,<2.0.0",
+    "httpx>=0.27,<1.0",
+]
 yaml = ["pyyaml>=6.0.3"]
 toon = ["python-toon>=0.1.3"]
 render = ["pypdfium2>=5.1.0", "Pillow>=12.0.0"]
+mcp = [
+    "mcp>=1.6.0,<2.0.0",
+    "httpx>=0.27,<1.0",
+]
 
 [project.scripts]
 exstruct = "exstruct.cli.main:main"
+exstruct-mcp = "exstruct.mcp.server:main"
 
 [project.urls]
 Homepage = "https://harumiweb.github.io/exstruct/"
@@ -120,6 +133,7 @@ markers = [
 ruff = "ruff check ."
 ruff-fix = "ruff check . --fix"
 mypy = "mypy src/exstruct --strict"
+precommit-run = "pre-commit run -a"
 test = "pytest -vv --cov=exstruct --cov-report=term-missing --cov-report=xml" # uv sync --extra render --extra toon
 test-unit = "pytest -vv -m \"not com and not render\" --cov=exstruct --cov-report=term-missing --cov-report=xml"
 test-com = "pytest -vv -m \"com\" --cov=exstruct --cov-report=term-missing --cov-report=xml"

{exstruct-0.3.7 → exstruct-0.4.1}/src/exstruct/core/backends/openpyxl_backend.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 import logging
 from pathlib import Path
+from typing import Literal
 
 from ...models import PrintArea
 from ..cells import (
@@ -116,18 +117,25 @@ class OpenpyxlBackend:
             )
             return None
 
-    def detect_tables(self, sheet_name: str) -> list[str]:
+    def detect_tables(
+        self,
+        sheet_name: str,
+        *,
+        mode: Literal["light", "standard", "verbose"] = "standard",
+    ) -> list[str]:
         """
         Detects table candidate ranges within the specified worksheet.
 
         Parameters:
             sheet_name (str): Name of the worksheet to analyze for table candidates.
+            mode (Literal["light", "standard", "verbose"]): Extraction mode, used to
+                adjust scan limits in openpyxl-based detection.
 
         Returns:
             list[str]: Detected table candidate ranges as A1-style range strings; empty list if none are found or detection fails.
         """
         try:
-            return detect_tables_openpyxl(self.file_path, sheet_name)
+            return detect_tables_openpyxl(self.file_path, sheet_name, mode=mode)
         except Exception:
             return []