Content
<!-- markdownlint-disable MD033 MD040 MD041 -->
<div align="center">
# Tool List
**No OCR!** Accurately and quickly parse CMB credit card statements in PDF format into structured data, with electronic signature verification.
[](https://www.python.org/) [](https://github.com/astral-sh/ruff) [](https://fastapi.tiangolo.com/) [](LICENSE)
</div>
<details>
<summary>CLI Example</summary>
</details>
[CSV Example](examples/transactions.example.csv)
## Installation
```bash
uv sync
```
## CLI Usage
```bash
# Statement summary (with signature verification)
uv run cmb-credit-parse examples/2026 July credit card statement.pdf
# Statement summary (skip signature verification)
uv run cmb-credit-parse --no-sig examples/2026 July credit card statement.pdf
# JSON output (with signature verification)
uv run cmb-credit-parse --json examples/2026 July credit card statement.pdf
# JSON output, skip signature verification
uv run cmb-credit-parse --json --no-sig examples/2026 July credit card statement.pdf
# CSV export
uv run cmb-credit-parse --csv transactions.csv examples/2026 July credit card statement.pdf
# CSV export, invert sign
uv run cmb-credit-parse --csv transactions.csv --invert-sign examples/2026 July credit card statement.pdf
```
## Options
| Option | Description |
| ---------------- | ------------------------------------------------------------ |
| `--json` | Output JSON format FullResponse (including statement + signature) |
| `--csv` | Export transactions as CSV file |
| `--invert-sign` | Invert income and expense signs in CSV |
| `--no-sig` | Skip signature verification |
## API Service
Start FastAPI + FastMCP server:
```bash
uv run uvicorn cmb_credit_parse.server:app --host 0.0.0.0 --port 8454
```
### Environment Variables
Create `.env` file to configure server address hint, which will be used for MCP service call hint:
```env
BASE_URL=http://localhost:8454
```
### FastAPI Endpoints
| Endpoint | Method | Parameters | Description |
| --------------- | ------ | --------------------------------- | --------------------------------------- |
| `/api/parse` | POST | `file` (form-data) | Upload PDF file, return FullResponse |
| `/api/parse/csv`| POST | `file` (form-data), `invert_sign` (query, optional) | Upload PDF file, return CSV download |
### FastMCP Tool
| Path | Description |
| ------ | -------------- |
| `/mcp` | MCP protocol endpoint |
MCP Tool:
- `parse_credit_statement(pdf_path: str)` — Guide to use HTTP API to upload PDF file
## Features
- **Statement Parsing**: Extract cardholder, address, billing date, due date, credit limit
- **Transaction Extraction**: Support 4 categories: consumption, refund, repayment, others
- **Statement Summary**: Previous balance, current repayment, new, adjustment, interest, current balance, minimum repayment
- **Signature Verification**: Verify PDF electronic signature, certificate chain validity
- **Rich Output**: Color panel and table display, unknown values highlighted in red
- **CSV Export**: One-click export transactions
## Project Structure
```
src/cmb_credit_parse/
├── __init__.py # empty file
├── models.py # Pydantic data models
├── parser.py # PDF statement parsing logic
├── signature.py # PDF electronic signature verification
├── cli.py # typer CLI entry
└── server.py # FastAPI + FastMCP server
```
## Tech Stack
- Python >=3.14
- pdfplumber (PDF extraction)
- pypdf + cryptography (signature parsing)
- Pydantic v2 (data models)
- typer + rich (CLI and output)
- FastAPI (HTTP API)
- FastMCP (MCP tool)
- pydantic-settings + dotenv (configuration management)
- Ruff (code inspection)
## Development
```bash
# Code inspection
uv run ruff check src/
# Auto-fix
uv run ruff check src/ --fix
# Run example
uv run python examples/usage.py
```
## Docker
```bash
# Build and start locally
docker compose up --build
# Or build manually
docker build -t cmb-credit-parse .
docker run -p 8454:8454 -e TZ=Asia/Shanghai cmb-credit-parse
```
Pre-built image: `ghcr.io/serinanya/cmb-credit-parse`
## TODO
- [ ] USD statement support (lack of example file)
