MarkSentry

Secure, local-first document-to-Markdown conversion.
Zero cloud dependencies. Zero-trust input sanitization. Correct multi-column layout. Full LaTeX math support.

Built to address the layout bugs, mathematical omissions, and critical security vulnerabilities (SSRF, path traversal, cloud-API lock-in) found in existing conversion utilities.

Table of Contents

• Why MarkSentry?
• Live Demo
• Architecture
• Installation
• Quick Start
  • CLI
  • Python SDK
• Claude Code MCP Integration
• Feature Deep Dives
  • Zero-Trust Input Sanitizer
  • Multi-Column Layout Processor
  • Table Reconstruction
  • LaTeX Math Output
  • PII Masking
• CLI Reference
• Development
• Contributing
• License
• Citation
• Author

Why MarkSentry?

MarkSentry isn't trying to out-fidelity GPU-accelerated converters like Marker
or IBM's layout-model-driven Docling -- it's the option for pipelines
where the document might be untrusted (a user upload, an email attachment, a scraped file) and the security
properties of the conversion step matter as much as the Markdown quality.

If you need the highest-fidelity extraction on trusted, GPU-available infrastructure, Docling or Marker will likely
out-perform MarkSentry on layout accuracy. If the file is coming from outside your trust boundary, or you need to
run entirely offline on modest hardware, that's what MarkSentry is for.

Live Demo

A hosted demo isn't up yet -- run it locally in under a minute instead:

git clone https://github.com/sunilgentyala/marksentry
cd marksentry
pip install -e ".[demo]"
streamlit run demo/streamlit_app.py

Upload a PDF, DOCX, or ZIP and see the sanitized Markdown, security warnings, and PII scan results update live. Nothing is uploaded anywhere outside your own machine or your own Streamlit deployment.

Architecture

                  User-supplied file
                        |
              ┌─────────▼──────────┐
              │  Zero-Trust        │  sanitizer.py
              │  Input Sanitizer   │  - path traversal jail
              │                    │  - SSRF URI scan
              │                    │  - macro stripping
              │                    │  - zip-bomb detection
              └─────────┬──────────┘
                        |
          ┌─────────────┼─────────────┐
          |             |             |
   ┌──────▼──────┐ ┌────▼────┐ ┌─────▼──────┐
   │  PDF Parser │ │  DOCX   │ │  ZIP       │
   │             │ │  Parser │ │  Dispatcher│
   │ pdfminer    │ │ python- │ └─────┬──────┘
   │ + BBox grid │ │ docx    │       | recurse
   └──────┬──────┘ └────┬────┘       |
          |             |            |
          └──────┬───────────────────┘
                 |
     ┌───────────▼──────────────┐
     │  Multi-Column Layout     │  layout.py
     │  Processor               │  - gap analysis
     │                          │  - column assignment
     │                          │  - reading-order sort
     └───────────┬──────────────┘
                 |
     ┌───────────▼──────────────┐
     │  Table + Math Core       │  pdf_parser.py / math_converter.py
     │                          │  - GFM table reconstruction
     │                          │  - OMML → LaTeX (DOCX)
     │                          │  - Unicode → LaTeX (PDF)
     └───────────┬──────────────┘
                 |
     ┌───────────▼──────────────┐
     │  PII Masking Filter      │  pii_filter.py  (optional)
     │                          │  - SSN, email, credit card
     │                          │  - private keys, JWT, AWS keys
     └───────────┬──────────────┘
                 |
          Markdown output

Installation

Requirements: Python 3.10+

# From source
git clone https://github.com/sunilgentyala/marksentry
cd marksentry
pip install -e .

# From PyPI (once published)
pip install marksentry

Optional OCR support (for scanned PDFs):

pip install marksentry[ocr]
# Also requires: sudo apt install tesseract-ocr  (or brew install tesseract)

Docker (GitHub Packages)

A prebuilt container image is published to the GitHub Container Registry:

docker pull ghcr.io/sunilgentyala/marksentry:latest
docker run --rm -v "$PWD:/work" ghcr.io/sunilgentyala/marksentry convert paper.pdf

Quick Start

CLI

# Convert a PDF, output to file
marksentry convert paper.pdf --output paper.md

# Convert with PII masking enabled
marksentry convert hr_report.pdf --mask-pii --output clean.md

# Convert multiple files into an output directory
marksentry convert *.pdf --output-dir ./converted/

# Convert a DOCX with LaTeX math, no table detection
marksentry convert thesis.docx --no-tables --output thesis.md

# Convert a ZIP archive containing mixed documents
marksentry convert bundle.zip --output-dir ./extracted/

# Dry-run PII audit (no output written)
marksentry audit-pii confidential.pdf

# Show document metadata and security scan results
marksentry info suspicious.docx

Python SDK

from marksentry import convert

# Simple conversion
result = convert("research_paper.pdf")
print(result.markdown)

# With all security + compliance features
result = convert(
    "internal_report.pdf",
    mask_pii=True,
    pii_patterns=["SSN", "EMAIL", "CREDIT_CARD"],
    multi_column=True,
    detect_math=True,
    allowed_base="/safe/data/directory",   # path jail
    strip_macros=True,
    check_ssrf=True,
)

for warning in result.warnings:
    print(f"[WARNING] {warning}")

with open("output.md", "w") as f:
    f.write(result.markdown)

Claude Code MCP Integration

MarkSentry ships a Model Context Protocol (MCP) server so
Claude Code can convert documents before sending their content to the model. This eliminates
the token cost of reading raw binary files: a 20-page IEEE paper that would consume 15,000+
tokens as raw bytes arrives as ~2,000 tokens of clean Markdown.

Why it saves tokens

Setup

1. Install MarkSentry and the MCP package:

git clone https://github.com/sunilgentyala/marksentry
cd marksentry
pip install -e .
pip install mcp

2. Register with Claude Code:

# macOS / Linux
claude mcp add --scope user marksentry python /path/to/marksentry/marksentry_mcp.py

# Windows — use the full path to your Python executable to avoid shell stubs
claude mcp add --scope user marksentry "C:\Python\python.exe" "C:\path\to\marksentry\marksentry_mcp.py"

Windows note: Using just python can resolve to the Windows Store stub that has no
packages installed. Run where python and pass the full path returned.

3. Verify:

claude mcp get marksentry
# Status: Connected

Restart Claude Code after registration for the tools to load into the session.

MCP Tools

Parameters for convert_to_markdown

Usage examples

Once the MCP server is connected, just share a file path in your prompt:

"Summarise this paper: /home/user/papers/research.pdf"
  → Claude calls convert_to_markdown, receives Markdown, answers from text

"Does this DOCX contain any PII? /home/user/docs/report.docx"
  → Claude calls audit_pii first, reports findings before converting

"What type of file is this and is it safe to convert? /tmp/unknown.zip"
  → Claude calls document_info for a fast preflight check

Feature Deep Dives

Zero-Trust Input Sanitizer

Every file passes through the sanitizer before reaching any parser:

Multi-Column Layout Processor

Academic papers commonly use 2- or 3-column layouts. Naive parsers read text horizontally,
producing garbled output:

Introduction  Methodology  Results
We studied...  We applied...  Our findings...

MarkSentry uses a gap-analysis algorithm:

1. Build a 1-point-resolution coverage histogram across the page width
2. Identify contiguous uncovered regions wider than the minimum gap threshold (default 18pt)
3. Declare each gap a column separator
4. Assign every text block to the column it overlaps most
5. Sort within each column top-to-bottom
6. Interleave full-width blocks (titles, section headers, captions) at their correct vertical position

The result is correct sequential flow through each column before moving to the next.

Table Reconstruction

The TableDetector clusters text blocks by shared y-bands (rows) and x-positions (columns),
identifies grid regions where at least 3 rows each contain 2+ aligned cells, and emits
standard GitHub-Flavored Markdown pipe tables:

| Method     | Precision | Recall | F1   |
|------------|-----------|--------|------|
| Baseline   | 0.82      | 0.79   | 0.80 |
| MarkSentry | 0.94      | 0.91   | 0.92 |

LaTeX Math Output

PDF documents: Unicode mathematical symbols (Greek letters, operators, set notation,
integrals, sums) are mapped to LaTeX equivalents. Inline-length formulas use $...$;
display-length formulas use $$...$$.

DOCX documents: Office Math Markup Language (OMML) equations are converted via a
recursive XML descent parser:

PII Masking

Ten pattern categories, all with validation (credit cards are Luhn-checked to eliminate
false positives):

Use marksentry audit-pii for a dry run that reports findings without modifying any output.

CLI Reference

Usage: marksentry [OPTIONS] COMMAND [ARGS]...

Commands:
  convert    Convert one or more documents to Markdown.
  audit-pii  Scan for PII without modifying output (dry run).
  info       Display document metadata and security scan summary.

marksentry convert [OPTIONS] FILES...

Options:
  -o, --output PATH          Output file (single input only)
  --output-dir DIR           Output directory for batch conversion
  --mask-pii                 Enable PII masking
  --pii-patterns TEXT        Comma-separated pattern names (default: all)
  --no-tables                Disable table reconstruction
  --no-math                  Disable LaTeX math conversion
  --no-multi-column          Disable column layout reconstruction
  --column-gap FLOAT         Column gap threshold in points (default: 18.0)
  --page-breaks              Emit --- between PDF pages
  --no-strip-macros          Skip macro stripping
  --no-ssrf-check            Skip embedded URL scanning
  --allowed-base DIR         Restrict file access to this directory
  -v, --verbose              Enable debug logging

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests with coverage
pytest

# Type checking
mypy marksentry/

# Linting
ruff check marksentry/

Contributing

Issues and pull requests are welcome — new PII pattern categories, additional parsers (PPTX, RTF, EPUB), multi-column edge cases, and new MCP tools are all open areas. See CONTRIBUTING.md for setup and PR guidelines, or use the issue templates to report a bug or propose a feature. General questions and ideas belong in Discussions.

License

MIT License. See LICENSE for details.

Citation

If MarkSentry is useful in your research or pipeline, please cite it — see CITATION.cff or use GitHub's "Cite this repository" button in the sidebar.

Author and Attribution

MarkSentry was designed and built by Sunil Gentyala.

Sunil Gentyala is a principal software architect and cybersecurity researcher at HCL America
Inc., with expertise in secure systems design, document intelligence pipelines, and adversarial
robustness. MarkSentry was created to solve real security gaps in existing document conversion
tooling -- in particular the complete absence of input sanitization, SSRF defenses, and correct
multi-column layout handling in tools like Microsoft MarkItDown -- and to provide a
production-grade, offline-first foundation for RAG data pipelines that must handle sensitive
documents safely.

Contact: [email protected]
GitHub: github.com/sunilgentyala