ofdkit 0.1.0__py3-none-any.whl

ofdkit/mcp_server.py

@@ -0,0 +1,125 @@
+"""MCP server: lets AI tools (Claude, Codex, Cursor and others) read OFD files.
+
+Run it with ``ofdkit mcp`` after ``pip install "ofdkit[mcp]"``, or without installing
+anything: ``uvx --from "ofdkit[mcp]" ofdkit mcp``. Every tool only reads files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
+
+from . import __version__
+from .batch import find_ofd_files, invoice_rows, summary
+from .cli import file_info
+from .document import OFDDocument
+from .errors import OFDError
+from .markdown import document_markdown
+
+#: Most files list_ofd_invoices reads in one call.
+MAX_BATCH_FILES = 500
+
+INSTRUCTIONS = """\
+Reads OFD files (GB/T 33190), the Chinese fixed-layout format used for e-invoices
+(电子发票, 数电票) and official documents. Pass absolute file paths.
+Use read_ofd_invoice for invoice fields, read_ofd_text for any document's text, and
+list_ofd_invoices to summarise a folder of invoices. Values are what the file
+contains; they are not checked against the tax authority."""
+
+_READ_ONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False)
+
+
+def create_server(root: str | Path | None = None) -> MCPServer:
+    """Build the server. With ``root`` set, only files inside that folder can be read."""
+    allowed = Path(root).expanduser().resolve() if root else None
+    server = MCPServer(name="ofdkit", version=__version__, instructions=INSTRUCTIONS)
+
+    def check(path: str) -> Path:
+        resolved = Path(path).expanduser().resolve()
+        if allowed is not None and not resolved.is_relative_to(allowed):
+            raise ToolError(f"{path} is outside the allowed folder {allowed}")
+        if not resolved.exists():
+            raise ToolError(f"{path} does not exist")
+        return resolved
+
+    def open_document(path: str) -> OFDDocument:
+        try:
+            return OFDDocument(check(path))
+        except OFDError as exc:
+            raise ToolError(f"cannot read {path}: {exc}") from exc
+
+    @server.tool(title="Read OFD text", annotations=_READ_ONLY)
+    def read_ofd_text(path: str, markdown: bool = False, first_page: int = 1, last_page: int | None = None) -> str:
+        """Extract the text of an OFD file in reading order.
+
+        Args:
+            path: Absolute path to the .ofd file.
+            markdown: Return Markdown; e-invoices then start with a table of their fields.
+            first_page: First page to include, counting from 1.
+            last_page: Last page to include; all remaining pages if omitted.
+        """
+        with open_document(path) as document:
+            if markdown and first_page == 1 and last_page is None:
+                return document_markdown(document)
+            pages = document.pages[max(first_page, 1) - 1 : last_page]
+            if not pages:
+                raise ToolError(f"no pages in range {first_page}-{last_page}; the file has {len(document.pages)} pages")
+            texts = []
+            for page in pages:
+                try:
+                    text = page.text()
+                except OFDError as exc:
+                    text = f"[page {page.index + 1} could not be read: {exc}]"
+                texts.append(f"## 第 {page.index + 1} 页\n\n{text}" if markdown else text)
+            return "\n\n".join(texts)
+
+    @server.tool(title="Read OFD invoice", annotations=_READ_ONLY)
+    def read_ofd_invoice(path: str) -> dict[str, Any]:
+        """Read the fields of a Chinese e-invoice (数电票 or 增值税电子发票) in OFD format.
+
+        Returns invoice number and code, issue date (YYYY-MM-DD), buyer and seller, amounts
+        as decimal strings, line items, and warnings such as totals that do not add up.
+
+        Args:
+            path: Absolute path to the .ofd file.
+        """
+        with open_document(path) as document:
+            invoice = document.invoice()
+        if invoice is None:
+            raise ToolError(f"no invoice data in {path}; use read_ofd_text to read its text")
+        return invoice.to_dict()
+
+    @server.tool(title="OFD file info", annotations=_READ_ONLY)
+    def ofd_info(path: str) -> dict[str, Any]:
+        """Pages (with sizes in millimetres), metadata, and whether an OFD file is an invoice.
+
+        Args:
+            path: Absolute path to the .ofd file.
+        """
+        with open_document(path) as document:
+            return file_info(document, path)
+
+    @server.tool(title="List OFD invoices in a folder", annotations=_READ_ONLY)
+    def list_ofd_invoices(folder: str, recursive: bool = False) -> dict[str, Any]:
+        """Summarise every invoice in a folder of .ofd files.
+
+        Returns one row per file (number, date, buyer, seller, amounts, or the reason it
+        could not be read), duplicate invoice numbers flagged, and totals.
+
+        Args:
+            folder: Absolute path to a folder.
+            recursive: Also look in subfolders.
+        """
+        directory = check(folder)
+        if not directory.is_dir():
+            raise ToolError(f"{folder} is not a folder")
+        files, _ = find_ofd_files([directory], recursive)
+        truncated = len(files) > MAX_BATCH_FILES
+        rows = invoice_rows(files[:MAX_BATCH_FILES])
+        return {"summary": summary(rows), "truncated": truncated, "rows": rows}
+
+    return server

ofdkit/package.py

@@ -0,0 +1,145 @@
+"""The ZIP container of an OFD file: entry lookup, path resolution and safety limits."""
+
+from __future__ import annotations
+
+import io
+import os
+import posixpath
+import xml.etree.ElementTree as ET
+import zipfile
+import zlib
+from typing import BinaryIO, Union
+
+from ._xml import parse_xml
+from .errors import OFDFormatError, OFDLimitError
+
+Source = Union[str, "os.PathLike[str]", bytes, bytearray, BinaryIO]
+
+#: Most entries a package may contain.
+MAX_ENTRIES = 50_000
+#: Largest single part, uncompressed, that ofdkit will read into memory.
+MAX_PART_SIZE = 64 * 1024 * 1024
+
+_UTF8_FLAG = 0x800
+
+
+class Package:
+    """Read-only view of the parts inside an OFD file."""
+
+    def __init__(self, source: Source) -> None:
+        try:
+            if isinstance(source, (bytes, bytearray)):
+                self._zip = zipfile.ZipFile(io.BytesIO(bytes(source)))
+            else:
+                self._zip = zipfile.ZipFile(source)
+        except (zipfile.BadZipFile, ValueError, EOFError) as exc:
+            raise OFDFormatError(f"not an OFD file (not a ZIP container): {exc}") from exc
+
+        infos = self._zip.infolist()
+        if len(infos) > MAX_ENTRIES:
+            self.close()
+            raise OFDLimitError(f"too many entries in the package ({len(infos)} > {MAX_ENTRIES})")
+
+        self._entries: dict[str, zipfile.ZipInfo] = {}
+        for info in infos:
+            if info.is_dir():
+                continue
+            self._entries.setdefault(_normalize(_entry_name(info)), info)
+        self._casefolded: dict[str, str] = {}
+        for name in self._entries:
+            self._casefolded.setdefault(name.casefold(), name)
+
+    @property
+    def names(self) -> list[str]:
+        """Names of all files in the package."""
+        return list(self._entries)
+
+    def find(self, path: str) -> str | None:
+        """Return the entry name for ``path``, matching case-insensitively as a fallback."""
+        path = _normalize(path)
+        if path in self._entries:
+            return path
+        return self._casefolded.get(path.casefold())
+
+    def resolve(self, base: str | None, location: str | None) -> str | None:
+        """Resolve a location written inside ``base`` to an entry name, or None.
+
+        The standard says relative locations are relative to the referencing file and
+        absolute ones start at the package root. Producers get this wrong often enough
+        that a location is also tried relative to the root, and matched without case.
+        """
+        location = (location or "").strip().replace("\\", "/")
+        if not location:
+            return None
+        if location.startswith("/"):
+            candidates = [location]
+        else:
+            base_dir = posixpath.dirname(_normalize(base)) if base else ""
+            candidates = [posixpath.join(base_dir, location), location]
+        for candidate in candidates:
+            candidate = posixpath.normpath(_normalize(candidate))
+            if candidate == ".." or candidate.startswith("../"):
+                continue
+            found = self.find(candidate)
+            if found is not None:
+                return found
+        return None
+
+    def read(self, name: str) -> bytes:
+        """Read one entry, refusing entries larger than MAX_PART_SIZE."""
+        info = self._entries.get(name)
+        if info is None:
+            raise OFDFormatError(f"missing part: {name}")
+        if info.file_size > MAX_PART_SIZE:
+            raise OFDLimitError(f"{name} is too large ({info.file_size} bytes)")
+        try:
+            with self._zip.open(info) as stream:
+                data = stream.read(MAX_PART_SIZE + 1)
+        except (zipfile.BadZipFile, zlib.error, RuntimeError, NotImplementedError, EOFError, OSError) as exc:
+            # RuntimeError: encrypted entry; NotImplementedError: unsupported compression.
+            raise OFDFormatError(f"cannot read {name}: {exc}") from exc
+        if len(data) > MAX_PART_SIZE:
+            raise OFDLimitError(f"{name} is too large when decompressed")
+        return data
+
+    def read_xml(self, name: str) -> ET.Element:
+        """Read and parse one XML entry."""
+        return parse_xml(self.read(name), name)
+
+    def close(self) -> None:
+        self._zip.close()
+
+    def __enter__(self) -> Package:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+def _normalize(name: str) -> str:
+    name = name.replace("\\", "/")
+    while name.startswith(("/", "./")):
+        name = name[1:] if name.startswith("/") else name[2:]
+    return name
+
+
+def _entry_name(info: zipfile.ZipInfo) -> str:
+    """Decode an entry name the way its producer most likely wrote it.
+
+    Without the UTF-8 flag, zipfile decodes names as CP437, but Chinese tools usually
+    stored UTF-8 or GBK bytes there.
+    """
+    if info.flag_bits & _UTF8_FLAG:
+        return info.filename
+    try:
+        raw = info.filename.encode("cp437")
+    except UnicodeEncodeError:
+        return info.filename
+    if raw.isascii():
+        return info.filename
+    for encoding in ("utf-8", "gb18030"):
+        try:
+            return raw.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+    return info.filename

ofdkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: ofdkit
+Version: 0.1.0
+Summary: Read OFD documents (GB/T 33190) and Chinese e-invoices: text, invoice fields, and AI tool integrations.
+Keywords: ofd,gb/t 33190,e-invoice,fapiao,电子发票,数电票,mcp
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Text Processing
+Requires-Dist: markitdown>=0.1,<0.2 ; extra == 'markitdown'
+Requires-Dist: mcp>=2.3,<3 ; extra == 'mcp'
+Maintainer: Edgar-311
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/Edgar-311/ofdkit
+Project-URL: Issues, https://github.com/Edgar-311/ofdkit/issues
+Project-URL: Changelog, https://github.com/Edgar-311/ofdkit/blob/main/CHANGELOG.md
+Provides-Extra: markitdown
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+# ofdkit
+
+轻量的 Python 工具，用来读取 OFD 文件，提取里面的文字和发票字段，并能接入 AI 工具。OFD 是中国的国家标准版式文档格式（GB/T 33190），常见于电子发票和公文。
+
+A lightweight Python toolkit for reading OFD documents (GB/T 33190, the Chinese fixed-layout format used for e-invoices and official documents): extract text and invoice fields, and use them from AI tools.
+
+> 状态：0.1 版，接口以后可能还会调整。更新记录见 [CHANGELOG](https://github.com/Edgar-311/ofdkit/blob/main/CHANGELOG.md)。
+> Status: 0.1, the API may still change. See the [CHANGELOG](https://github.com/Edgar-311/ofdkit/blob/main/CHANGELOG.md).
+
+## 能做什么 / What it does
+
+- 按阅读顺序提取文字，包括模板和复合对象里的文字。
+  Text in reading order, including text in templates and composite objects.
+- 读取电子发票字段（数电票和增值税电子发票），输出 JSON：发票号码、开票日期、购买方、销售方、金额、税额、价税合计、明细。
+  Invoice fields from e-invoices as JSON: number, date, buyer, seller, amounts, tax, total, line items.
+- 把一个文件夹里的发票汇总成 CSV，Excel 可以直接打开，并提示重复的发票号码。
+  A folder of invoices summarised as CSV (opens in Excel), with duplicate invoice numbers flagged.
+- 只用 Python 标准库，没有任何第三方依赖；能读很多不规范的文件（路径写法不对、编码不对、XML 前缀错误等）。
+  Standard library only, no dependencies; reads many non-conforming files (bad paths, encodings, XML prefixes).
+
+## 安装 / Install
+
+需要 Python 3.10 或更新版本。Requires Python 3.10+.
+
+```bash
+pip install ofdkit
+```
+
+## 命令行 / Command line
+
+```bash
+ofdkit text 文件.ofd                         # 提取文字 / print text
+ofdkit invoice 发票.ofd                      # 发票字段（JSON）/ invoice fields as JSON
+ofdkit batch 发票文件夹/ -o 发票汇总.csv      # 批量汇总 / summarise a folder as CSV
+ofdkit info 文件.ofd                         # 页数、作者等信息 / pages and metadata
+```
+
+`ofdkit invoice` 的输出示例（数据是虚构的）/ Example output (fictional data):
+
+```json
+{
+  "invoice_number": "00000000000000000001",
+  "invoice_code": null,
+  "issue_date": "2026-01-02",
+  "check_code": null,
+  "machine_number": null,
+  "buyer": {"name": "测试单位甲", "tax_id": "TESTBUYER0001", "address_phone": null, "bank_account": null},
+  "seller": {"name": "测试单位乙", "tax_id": "TESTSELLER0002", "address_phone": null, "bank_account": null},
+  "amount_without_tax": "100.00",
+  "tax_amount": "6.00",
+  "total_amount": "106.00",
+  "issuer": "测试人员",
+  "payee": null,
+  "reviewer": null,
+  "note": null,
+  "items": [
+    {"name": "*测试*服务项目", "specification": null, "unit": null, "quantity": null,
+     "unit_price": null, "amount": "100.00", "tax_rate": "6%", "tax_amount": "6.00"}
+  ],
+  "sources": ["custom_tags"],
+  "warnings": []
+}
+```
+
+金额是字符串，不会丢失精度。如果"合计金额 + 合计税额"不等于"价税合计"，`warnings` 里会提示。
+Amounts are decimal strings, so no precision is lost. `warnings` notes totals that do not add up.
+
+## 在 AI 工具里使用 / Use from AI tools
+
+### MCP 服务器 / MCP server
+
+让 Claude、Codex、Cursor 等 AI 工具直接读取 OFD 文件。需要先安装 [uv](https://docs.astral.sh/uv/)。所有工具都是只读的。
+Lets Claude, Codex, Cursor and other AI tools read OFD files. Requires [uv](https://docs.astral.sh/uv/). All tools are read-only.
+
+| 工具 / Tool | 作用 / What it does |
+| --- | --- |
+| `read_ofd_text` | 按阅读顺序提取文字，可选 Markdown 和页码范围 / text in reading order, optional Markdown and page range |
+| `read_ofd_invoice` | 发票字段 / invoice fields |
+| `ofd_info` | 页数、尺寸、元数据 / pages, sizes, metadata |
+| `list_ofd_invoices` | 汇总一个文件夹里的发票 / summarise a folder of invoices |
+
+Claude Code:
+
+```bash
+claude mcp add ofdkit -- uvx --from "ofdkit[mcp]" ofdkit mcp
+```
+
+Claude Desktop、Cursor 等使用 JSON 配置的工具 / tools with a JSON config:
+
+```json
+{
+  "mcpServers": {
+    "ofdkit": {
+      "command": "uvx",
+      "args": ["--from", "ofdkit[mcp]", "ofdkit", "mcp"]
+    }
+  }
+}
+```
+
+Codex（`~/.codex/config.toml`）:
+
+```toml
+[mcp_servers.ofdkit]
+command = "uvx"
+args = ["--from", "ofdkit[mcp]", "ofdkit", "mcp"]
+```
+
+加上 `--root 文件夹` 可以只允许读取这个文件夹里的文件。
+Add `--root FOLDER` to allow only files inside that folder.
+
+### Agent Skill
+
+[`skills/ofd-reader`](https://github.com/Edgar-311/ofdkit/tree/main/skills/ofd-reader) 告诉 AI 什么时候、怎么用 ofdkit 命令行，适用于支持 [Agent Skills](https://agentskills.io) 的工具。把这个文件夹复制到：
+[`skills/ofd-reader`](https://github.com/Edgar-311/ofdkit/tree/main/skills/ofd-reader) tells an AI agent when and how to use the ofdkit command line. Copy the folder to:
+
+- Claude Code: `~/.claude/skills/ofd-reader/`
+- Codex: `~/.codex/skills/ofd-reader/`
+
+### MarkItDown 插件 / MarkItDown plugin
+
+[MarkItDown](https://github.com/microsoft/markitdown) 是把各种文件转成 Markdown 给 AI 读的工具。安装插件后它就能读 OFD：
+[MarkItDown](https://github.com/microsoft/markitdown) converts files to Markdown for AI. With this plugin it reads OFD too:
+
+```bash
+pip install "ofdkit[markitdown]"
+markitdown --use-plugins 发票.ofd
+```
+
+## Python
+
+```python
+import ofdkit
+
+with ofdkit.open("发票.ofd") as doc:
+    print(doc.text())
+    invoice = doc.invoice()        # 不是发票时返回 None / None if not an invoice
+    if invoice:
+        print(invoice.invoice_number, invoice.total_amount)
+```
+
+## 注意 / Notes
+
+- ofdkit 只读取文件里写了什么，不验证发票真伪。查验真伪请使用国家税务总局的发票查验平台。
+  ofdkit reports what a file contains. It does not verify that an invoice is genuine.
+- 文字如果是画成图形或图片的，就读不出来（需要 OCR，不在本项目范围内）。
+  Text drawn as shapes or images cannot be extracted (that needs OCR, which is out of scope).
+- 多栏排版的页面，目前两栏的文字会出现在同一行，用三个空格隔开。
+  On multi-column pages, both columns currently share each line, separated by three spaces.
+
+## 原则 / Principles
+
+- 只读取 OFD，不生成、不修改发票。
+  Reads OFD only. It never creates or modifies invoices.
+- 本项目大部分代码由 AI（Claude）编写，维护者负责决定方向和批准发布。
+  Most code is written with AI assistance (Claude). The maintainer sets the direction and approves releases.
+
+## 许可证 / License
+
+[Apache-2.0](https://github.com/Edgar-311/ofdkit/blob/main/LICENSE)

ofdkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+ofdkit/__init__.py,sha256=kiU9yXbFbWRJmRUSY8dNuxBWmPBVQibZzkKghxx_X0c,1553
+ofdkit/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+ofdkit/_xml.py,sha256=zCSoRTbQ2trxakf5Ey_P_4xcqyxh1Hzlz1ZaEdzh4lY,4722
+ofdkit/batch.py,sha256=_tSoe2x6upEiWi8HXewWj6WyQtSJF566Rgm9LdVSrWo,3675
+ofdkit/cli.py,sha256=n4myDBXi9eK-KcpNWYbqbBdH5kj623BaYA9jLnVdR9A,7156
+ofdkit/document.py,sha256=kd1h3dbFtSkPYGhc5-gRUp3VFde1OEX7viNNBaVegt4,19217
+ofdkit/errors.py,sha256=JKVhg36Lu6DVLXkfCBDJPAy4xrgXvVaNGgup38ehNL0,356
+ofdkit/invoice.py,sha256=vWvdAYFH_d1UTZhwIzAf6n5ruqohC9NeP7tp7iI9DUc,16176
+ofdkit/layout.py,sha256=3bSYGM9ytZ_FaiRj1a1c6oY0ukQR8OGUUXHn01CK_bU,2775
+ofdkit/markdown.py,sha256=A4smJ-Upxc3EyDKnVfgVsoDXvFP4gJlDzGp35f3FxuA,3943
+ofdkit/markitdown_plugin.py,sha256=vL78_98f0l4KMYy3tfeq8dU1qGpLXf0NhnC8bYN-zIM,2099
+ofdkit/mcp_server.py,sha256=essaiq2xpBd8XZSk2zo3XRu5MNFj9ZVRD9NW20YwRfk,5437
+ofdkit/package.py,sha256=6-HJyYvERTjQs70Z1KzEKTmMO1AvfyAkJ3WAGXCGjBg,5205
+ofdkit-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+ofdkit-0.1.0.dist-info/WHEEL,sha256=a0ta4TK7UKMB0EbDesmi2mn0Djkly7aj_7Tu2R7SseE,81
+ofdkit-0.1.0.dist-info/entry_points.txt,sha256=rRjw7GvihBgFe8na-kXxK-AT3taKYvFdYWNlJ891ANc,99
+ofdkit-0.1.0.dist-info/METADATA,sha256=0HA2gsXWQJAP9si4eh0KmiDCRRPK5rydK63FVdsXsso,7997
+ofdkit-0.1.0.dist-info/RECORD,,

ofdkit-0.1.0.dist-info/WHEEL

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

ofdkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+ofdkit = ofdkit.cli:main
+
+[markitdown.plugin]
+ofdkit = ofdkit.markitdown_plugin
+