pdf-porter 0.1.0__tar.gz

pdf_porter-0.1.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tail:*)",
+      "Bash(head:*)",
+      "Bash(source:*)",
+      "Bash(zsh:*)"
+    ]
+  }
+}

pdf_porter-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

pdf_porter-0.1.0/.gitignore

@@ -0,0 +1,181 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor  
+#  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to 
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

pdf_porter-0.1.0/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+`pdf-porter`: a minimal MCP server exposing one tool — `pdf_to_markdown(path, save_output)` — for layout-aware PDF→Markdown conversion via Docling. Pitch: one tool, zero config, five minutes.
+
+**Note:** `docling-mcp` (the obvious name) is taken by IBM Research Zurich, the Docling authors themselves, at v1.3.2. This package is intentionally minimal — one tool, no config. The README should reference IBM's `docling-mcp` as the full-featured alternative: "if you want the full Docling toolset, see docling-mcp."
+
+## Stack
+- Python 3.11+
+- `mcp[cli]` (FastMCP)
+- `docling`
+- `uv` for packaging and running
+- `reportlab` (dev only, for generating test fixtures)
+
+## Structure
+```
+pdf_porter/
+  __init__.py       # __version__ = "0.1.0"
+  server.py         # FastMCP app, tool definitions, module-level converter singleton
+tests/
+  test_server.py    # integration tests (no mocking)
+  fixtures/         # simple.pdf, two_column.pdf, table.pdf (generated by generate_fixtures.py)
+generate_fixtures.py  # standalone script to regenerate test PDFs via reportlab
+pyproject.toml
+README.md
+```
+
+## Commands
+```bash
+uv run python -m pdf_porter          # start server
+uv run pytest                        # run tests
+uv run mcp dev pdf_porter/server.py  # MCP inspector
+uv run pytest tests/test_server.py::test_table_pdf  # run a single test
+python generate_fixtures.py          # regenerate test fixture PDFs
+uv build                             # build wheel + sdist into dist/
+```
+
+## Publishing to PyPI
+
+`PYPI_TOKEN` must be set in the environment before publishing. Claude Code's Bash tool does **not** inherit variables exported in the user's interactive shell — the user must publish manually from their own terminal:
+
+```bash
+# In your terminal (not via Claude Code):
+uv build
+uv publish --token $PYPI_TOKEN
+```
+
+After publishing, verify the release:
+```bash
+curl -s https://pypi.org/pypi/pdf-porter/json | python -m json.tool | grep '"version"'
+uvx pdf-porter &   # should start cleanly; kill with Ctrl-C
+```
+
+## Architecture
+
+`server.py` holds a module-level `DocumentConverter` singleton (instantiated once, not per-call) and a boolean flag to log "Loading Docling models..." to stderr on the first conversion only. The `pdf_to_markdown` tool validates path existence and `.pdf` extension before calling Docling, and wraps all exceptions as `"Error: {e}"` strings — never raw tracebacks.
+
+Entry point: `pdf_porter.server:main` → calls `mcp.run()`. Also handles `if __name__ == "__main__"`.
+
+## Tool signature
+```python
+pdf_to_markdown(path: str, save_output: bool = False) -> str
+```
+- Returns markdown string directly, or `"Saved to: {output_path}"` when `save_output=True`
+- Returns `"Error: ..."` on any failure (bad path, wrong extension, conversion error)
+
+## Rules
+- No global state beyond the converter singleton and the first-run flag — document both in server.py.
+- All errors surface as readable strings, never raw tracebacks to the LLM.
+- Tests are integration tests — do not mock `DocumentConverter`.
+- Tests must cover: simple PDF, two-column PDF, table PDF (asserts `|` present), bad path, non-PDF extension, `save_output=True`.
+- Do not add dependencies beyond `mcp`, `docling`, `pytest`, and `reportlab` (dev).
+- README must include a working `claude_desktop_config.json` snippet.
+
+## Known limitations (inform users)
+- First run downloads Docling model weights (~500MB); subsequent runs are fast.
+- OCR mode not enabled in v0.1 — scanned/image-only PDFs will return empty text.
+- Windows path handling not validated.
+
+
+## PATHS
+
+NEVER HARD CODE PATHS. /path/to/repo should NEVER APPEAR in the codebase.

pdf_porter-0.1.0/CLAUDE_CODE_PROMPTS.md

@@ -0,0 +1,212 @@
+# Claude Code Prompt Sequence
+## mcp-docling — Autonomous Build Session
+
+Run these prompts in order in Claude Code. Each phase should complete fully before the next begins. If a phase fails its acceptance criteria, fix before proceeding.
+
+---
+
+## Prompt 0 — Bootstrap
+
+```
+Initialize a new Python project called mcp-docling.
+
+Create this directory structure:
+  mcp_docling/__init__.py
+  mcp_docling/server.py
+  tests/__init__.py
+  tests/test_server.py
+  tests/fixtures/   (empty for now)
+  pyproject.toml
+  README.md
+  CLAUDE.md
+  LICENSE
+
+pyproject.toml requirements:
+  - name: mcp-docling
+  - version: 0.1.0
+  - description: "MCP server for layout-aware PDF to Markdown conversion via Docling"
+  - requires-python: ">=3.11"
+  - dependencies: ["mcp[cli]", "docling"]
+  - optional-dependencies.dev: ["pytest"]
+  - [project.scripts] mcp-docling = "mcp_docling.server:main"
+  - [project.urls] homepage = "https://github.com/benmazzotta/mcp-docling"
+
+In mcp_docling/__init__.py, just set __version__ = "0.1.0".
+
+Do not write server.py or tests yet. Confirm the scaffold is in place.
+```
+
+---
+
+## Prompt 1 — Server
+
+```
+Write mcp_docling/server.py.
+
+Use FastMCP from the mcp package. Create a module-level DocumentConverter singleton 
+from docling.document_converter. Do not reinstantiate it on every call.
+
+Expose one tool:
+
+  pdf_to_markdown(path: str, save_output: bool = False) -> str
+
+Behavior:
+- If path does not exist: return "Error: file not found: {path}"
+- If path does not end in .pdf (case-insensitive): return "Error: not a PDF file: {path}"
+- Convert using DocumentConverter().convert(path), then export_to_markdown()
+- If save_output is True: write markdown to same directory, same stem, .md extension.
+  Return "Saved to: {output_path}"
+- If save_output is False: return the markdown string directly
+- Wrap everything in try/except Exception as e and return f"Error: {e}" on failure
+
+Add a main() function:
+  def main():
+      mcp.run()
+
+Add if __name__ == "__main__": main() at the bottom.
+
+Log "Loading Docling models..." to stderr before the first conversion (not at import time — 
+use a module-level flag).
+```
+
+---
+
+## Prompt 2 — Fixtures and Tests
+
+```
+Generate test fixture PDFs in tests/fixtures/ using reportlab.
+Add reportlab as a dev dependency if not present.
+
+Generate three PDFs:
+
+1. tests/fixtures/simple.pdf
+   - Single column
+   - Three paragraphs of Lorem Ipsum
+   - One H1 heading
+
+2. tests/fixtures/two_column.pdf
+   - Two-column layout
+   - Different text in each column, clearly labeled "Column A" and "Column B"
+
+3. tests/fixtures/table.pdf
+   - A table with 3 columns and 5 rows
+   - Headers: Name, Value, Notes
+   - Fill with sample data
+
+Write a standalone script generate_fixtures.py at the project root that generates 
+all three. Run it. Confirm all three files exist and are valid PDFs.
+
+Then write tests/test_server.py:
+
+Import pdf_to_markdown directly from mcp_docling.server (not through MCP).
+
+Tests:
+- test_simple_pdf: result is str, len > 100, no "Error:" prefix
+- test_two_column_pdf: result is str, len > 100, no "Error:" prefix
+- test_table_pdf: result contains "|" character
+- test_bad_path: result starts with "Error:"
+- test_non_pdf: create a temp .txt file, result starts with "Error:"
+- test_save_output: copy simple.pdf to tmp_path, call with save_output=True,
+  assert .md file exists and is non-empty
+
+Run pytest. All tests must pass before proceeding.
+```
+
+---
+
+## Prompt 3 — README and Packaging
+
+```
+Write README.md with these exact sections:
+
+# mcp-docling
+
+One sentence: what it does and why it's better than pypdf.
+
+## Installation
+
+### Use with Claude Desktop (recommended)
+Add to claude_desktop_config.json:
+
+{
+  "mcpServers": {
+    "pdf-tools": {
+      "command": "uvx",
+      "args": ["mcp-docling"]
+    }
+  }
+}
+
+Then restart Claude Desktop.
+
+### Development
+git clone https://github.com/benmazzotta/mcp-docling
+cd mcp-docling
+uv sync --dev
+uv run pytest
+
+## Tool Reference
+
+### pdf_to_markdown
+- path (str): absolute or relative path to a PDF file
+- save_output (bool, default False): if True, writes .md file next to the PDF and returns the path
+
+## Known Limitations
+- First run downloads Docling model weights (~500MB). Subsequent runs are fast.
+- Scanned PDFs: OCR mode is not enabled in v0.1. Text in image-only PDFs will be empty.
+- Tested on macOS and Linux. Windows path handling not validated.
+
+## License
+MIT. See LICENSE.
+
+---
+
+Write LICENSE as MIT, author Ben Mazzotta, year 2025.
+
+Then run:
+  uv build
+
+Confirm dist/ contains a .whl and a .tar.gz. Report the filenames.
+```
+
+---
+
+## Prompt 4 — Publish
+
+```
+Publish to PyPI.
+
+First, check whether PYPI_TOKEN is set in the environment.
+If not set: print the following and stop:
+
+  "To publish, set your PyPI API token:
+   export PYPI_TOKEN=pypi-...
+   Then re-run this prompt."
+
+If set, run:
+  uv publish --token $PYPI_TOKEN
+
+After publishing, wait 60 seconds, then verify:
+  curl -s https://pypi.org/pypi/mcp-docling/json | python -m json.tool | grep '"version"'
+
+Then test the live package in a temporary directory:
+  cd /tmp
+  uvx mcp-docling &
+  sleep 5
+  kill %1
+
+Confirm it starts without error. Report success or failure clearly.
+```
+
+---
+
+## Final Checklist
+
+After all four prompts complete, verify:
+
+- [ ] `uv run pytest` — all tests green
+- [ ] `uv build` — dist/ has wheel and sdist  
+- [ ] `uvx mcp-docling` — server starts
+- [ ] Package visible at pypi.org/project/mcp-docling
+- [ ] README on PyPI renders correctly
+- [ ] claude_desktop_config.json snippet in README is accurate

pdf_porter-0.1.0/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,181 @@
+# mcp-docling: Concept Note & Implementation Plan
+
+## Problem
+
+Claude's native PDF ingestion is shallow. It reads text streams, not document structure. Tables become noise. Two-column papers read in the wrong order. Scanned PDFs return nothing. The result is that users paste PDFs into Claude and get confused or degraded responses — not because Claude is weak, but because the input is scrambled before Claude ever sees it.
+
+## Solution
+
+A local MCP server that wraps Docling — a layout-aware document converter — and exposes a single tool to Claude Desktop: `pdf_to_markdown(path)`. Claude calls it, gets clean structured markdown back, and reasons over that instead.
+
+No upload. No cloud dependency. No background service. The server process lives only during a Claude Desktop session.
+
+## Scope
+
+**In:** PDF to markdown. Local file paths. Optional output-to-file.  
+**Out:** Other document formats, cloud storage integration, batch processing, GUI. These are v2 concerns.
+
+---
+
+## Phase 1: Build
+
+### Goal
+A working MCP server that converts a local PDF to markdown and returns it to Claude.
+
+### Prompt for Claude Code
+```
+Create a Python MCP server using FastMCP (mcp[cli] package) in mcp_docling/server.py.
+
+Expose one tool: pdf_to_markdown(path: str, save_output: bool = False) -> str
+
+Behavior:
+- Validate that path exists and is a .pdf file. Return a clear error string if not.
+- Use DocumentConverter from docling to convert the PDF.
+- Call result.document.export_to_markdown().
+- If save_output is True, write the markdown to the same directory as the PDF, 
+  with the same filename and .md extension. Return the output path as a string.
+- If save_output is False, return the markdown content directly.
+- Catch all exceptions and return them as readable error strings prefixed with "Error: ".
+- Cache the DocumentConverter as a module-level singleton to avoid reloading weights on every call.
+
+Set up pyproject.toml with:
+- name: mcp-docling
+- version: 0.1.0
+- dependencies: mcp[cli], docling
+- dev dependencies: pytest
+- entry point: mcp_docling.server:mcp (as mcp script)
+- Python >= 3.11
+
+Do not add any other dependencies.
+```
+
+### Acceptance Criteria
+- [ ] `uv run python -m mcp_docling` starts without error
+- [ ] `uv run mcp dev mcp_docling/server.py` opens MCP inspector
+- [ ] Tool appears in inspector with correct signature
+- [ ] Calling with a valid PDF path returns non-empty markdown string
+- [ ] Calling with a bad path returns a readable error string, not a traceback
+- [ ] `save_output=True` writes a `.md` file next to the PDF
+
+---
+
+## Phase 2: Test
+
+### Goal
+Confidence across the real-world PDF types that matter. This is where pypdf fails and docling earns its keep.
+
+### Prompt for Claude Code
+```
+Create tests/test_server.py using pytest.
+
+Download or generate four fixture PDFs into tests/fixtures/:
+1. simple.pdf — single column, clean text (generate with reportlab if needed)
+2. two_column.pdf — two-column layout (generate with reportlab)
+3. table.pdf — PDF containing a markdown-renderable table (generate with reportlab)
+4. scanned.pdf — use any freely licensed scanned PDF sample from a public URL, 
+   or skip if download is unreliable and note it
+
+For each fixture, write a test that:
+- Calls pdf_to_markdown(path) directly (import the function, don't go through MCP)
+- Asserts the result is a non-empty string
+- Asserts no "Error:" prefix in result
+
+Additional tests:
+- Bad path returns string starting with "Error:"
+- Non-PDF extension returns string starting with "Error:"
+- save_output=True creates the expected .md file (use tmp_path fixture, copy a fixture there first)
+
+Do not mock DocumentConverter. These are integration tests. They should call docling for real.
+```
+
+### Acceptance Criteria
+- [ ] `uv run pytest` passes all tests
+- [ ] Two-column test returns markdown where paragraphs are not interleaved
+- [ ] Table test returns output containing a markdown table (`|` characters)
+- [ ] Error path tests pass
+- [ ] save_output test confirms file exists and is non-empty
+
+---
+
+## Phase 3: Package
+
+### Goal
+Anyone can run this with a single `uvx` command. No cloning required.
+
+### Prompt for Claude Code
+```
+Prepare mcp-docling for PyPI publication.
+
+1. Verify pyproject.toml is complete:
+   - name, version, description, license (MIT), author, homepage, readme
+   - Correct entry point so `uvx mcp-docling` starts the server
+
+2. Write README.md with these sections:
+   - One-sentence description
+   - Installation (two methods: uvx one-liner, and uv add for development)
+   - claude_desktop_config.json snippet showing exact configuration
+   - Tool reference: pdf_to_markdown parameters and return values
+   - Known limitations: large files, scanned PDFs need OCR mode, first-run weight download
+   - License
+
+3. Add LICENSE (MIT, author: Ben Mazzotta, year 2025)
+
+4. Build the package:
+   uv build
+
+5. Confirm dist/ contains a .whl and .tar.gz
+
+6. Dry-run install from the wheel locally to confirm the entry point works:
+   uv run --with dist/mcp_docling-*.whl mcp-docling --help
+   (adjust if FastMCP handles --help differently)
+```
+
+### Acceptance Criteria
+- [ ] `uv build` completes without error
+- [ ] `dist/` contains both wheel and sdist
+- [ ] README contains working config snippet (verified by reading it)
+- [ ] LICENSE file present
+- [ ] Entry point is callable from the wheel
+
+---
+
+## Phase 4: Publish
+
+### Goal
+Package is live on PyPI. Users can configure it in two lines.
+
+### Prompt for Claude Code
+```
+Publish mcp-docling to PyPI using uv.
+
+Steps:
+1. Ensure PYPI_TOKEN is available as environment variable (do not hardcode it)
+2. Run: uv publish --token $PYPI_TOKEN
+3. Wait ~60 seconds, then verify publication:
+   curl https://pypi.org/pypi/mcp-docling/json | python -m json.tool | grep version
+4. Test the live package:
+   uvx mcp-docling
+   (confirm it starts and prints MCP server startup message)
+5. Update README if the PyPI badge URL or install command needs adjusting.
+
+If PYPI_TOKEN is not set, stop and print instructions for the user to set it.
+Do not attempt to publish without a token.
+```
+
+### Acceptance Criteria
+- [ ] Package appears at pypi.org/project/mcp-docling
+- [ ] `uvx mcp-docling` works in a clean environment (test in a new uv venv)
+- [ ] Version on PyPI matches pyproject.toml
+- [ ] README on PyPI renders correctly (check the PyPI project page)
+
+---
+
+## Risk Notes
+
+**Docling weight download on first run.** Users will see a pause of 30–90 seconds the first time `pdf_to_markdown` is called. The README must warn them. Consider printing a log message from the server: `"Loading Docling models (first run only)..."`.
+
+**Scanned PDFs.** Docling handles these but OCR mode must be enabled explicitly. v0.1 can document this as a known limitation and expose it as a future `ocr=True` parameter.
+
+**Path handling on Windows.** Docling and MCP both support Windows but path separators can bite. Test on the platform you care about.
+
+**PyPI name collision.** Check that `mcp-docling` is unclaimed before Phase 3. If taken, `mcp-pdf-docling` or `docling-mcp` are reasonable alternatives.

pdf_porter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Mazzotta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.