feat(mcp): add Python MCP server for paperjam (#46)

* fix(publish): use manylinux_2_28 for aarch64 to fix aws-lc-sys C11 compile failure

manylinux2014 (auto) uses GCC 4.8 from CentOS 7 which lacks stdatomic.h,
causing aws-lc-sys bcm.c cross-compilation to fail on aarch64.
manylinux_2_28 uses AlmaLinux 8 with GCC 8.5 which has full C11 support.

* feat(mcp): add Python MCP server for paperjam document processing

FastMCP-based server exposing 48+ tools for AI agents to open, extract,
manipulate, convert, and analyze documents (PDF, DOCX, XLSX, PPTX, HTML,
EPUB) via the Model Context Protocol.

Flat src/ layout with tools organized by domain:
- document: session lifecycle (open, close, save, list, info)
- extraction: text, tables, structure, markdown, search, links, images
- page: page-level operations and layout analysis
- manipulation: split, merge, reorder, delete, insert, rotate, optimize
- annotation: watermark, annotations, stamp
- metadata: document metadata, bookmarks, TOC generation
- comparison: text diff and visual diff
- conversion: format conversion and detection
- render: page rendering to PNG/JPEG/BMP
- forms: AcroForm field operations
- security: sanitize, redact, encrypt
- signatures: digital signature operations
- validation: PDF/A and PDF/UA compliance
- pipeline: YAML/JSON workflow execution

Includes session management with TTL, MCP resources for document
browsing, prompt templates for common workflows, structured error
handling with logging, and setuptools package-dir mapping for clean
src/ → paperjam_mcp installation.

* docs(mcp): add README with installation, config, and tools reference

Installation via uvx/pip, MCP client configuration examples for
tools reference table covering all 48+ tools across 14 categories.

* ci(mcp): add PyPI publish workflow with trusted publishing

Triggers on mcp-* tags (e.g. mcp-0.1.0). Builds pure Python wheel
with uv and publishes via OIDC trusted publishing — no API tokens.

* fix(mcp): use SPDX license string to fix setuptools deprecation warning

* docs: update README — remove redundant title, center badges, update MCP section

* fix(mcp): resolve PR review comments — unused imports and mixed import style

- server.py: move side-effect imports out, use importlib in __main__
- security.py: replace mixed import styles with single from-import

* fix(mcp): harden for production — path sandboxing, resource leaks, memory limits

Security:
- resolve_path: reject paths that escape the working directory
- pipeline tools: disabled — they bypass server-side path sandboxing

Resource management:
- update_document: close old document before replacing (prevents native resource leak)
- _cleanup_expired: wrap close() in try/except so one failure doesn't orphan remaining sessions
- close_all: new method for clean shutdown, registered via atexit
- TTL now based on last access time, not creation time

Memory safety:
- render_page/render_pages: cap DPI at 600, limit to 50 pages per call
- visual_diff: cap DPI at 300

Error handling:
- Add @handle_errors to all 7 resource handlers (previously raw exceptions)

* docs(mcp): update docs site MCP guide for Python server

Replace Rust MCP server references with the new Python package
(paperjam-mcp via uvx/pip). Add Cursor config example, complete
tools reference across all 14 categories, document security
sandboxing and session TTL behavior.

* ci(mcp): add CI workflow for MCP server — lint, typecheck, build

Runs on mcp-server/** changes. Lint job: ruff check, ruff format,
mypy. Build job: wheel build + CLI smoke test on Python 3.12 and 3.13.

* fix(ci): let uv sync build paperjam from source, drop maturin develop step

maturin develop requires a pre-existing virtualenv. uv sync handles
building the paperjam path dependency (which uses maturin) automatically.

* fix(mcp): add str() casts to fix mypy no-any-return errors

paperjam's stubs type extract_text() and to_markdown() as returning
Any, which triggers no-any-return when returned from -> str functions.

Author: pratyush618

.github/workflows/ci-mcp.yml

@@ -0,0 +1,69 @@
+name: CI (MCP Server)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "mcp-server/**"
+      - ".github/workflows/ci-mcp.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "mcp-server/**"
+      - ".github/workflows/ci-mcp.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    working-directory: mcp-server
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2.9.1
+
+      - name: Install dependencies (builds paperjam from source)
+        run: uv sync
+
+      - name: Ruff check
+        run: uv run ruff check src/
+
+      - name: Ruff format
+        run: uv run ruff format --check src/
+
+      - name: Mypy
+        run: uv run mypy src/
+
+  build:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build wheel
+        run: uv build
+
+      - name: Verify CLI
+        run: |
+          uv run --no-project --with dist/*.whl paperjam-mcp --version
+          uv run --no-project --with dist/*.whl paperjam-mcp --help

.github/workflows/publish-mcp.yml

@@ -0,0 +1,31 @@
+name: Publish paperjam-mcp to PyPI
+
+on:
+  push:
+    tags:
+      - "mcp-[0-9]+.[0-9]+.[0-9]+*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build
+        run: uv build
+        working-directory: mcp-server
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: mcp-server/dist/
+          verbose: true
+          skip-existing: true

README.md

@@ -2,11 +2,11 @@
   <img src="docs-site/static/img/logo.jpeg" alt="paperjam logo" width="250">
 </p>
 
-# paperjam
-
-[![PyPI](https://img.shields.io/pypi/v/paperjam)](https://pypi.org/project/paperjam/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+<p align="center">
+  <a href="https://pypi.org/project/paperjam/"><img src="https://img.shields.io/pypi/v/paperjam" alt="PyPI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
+</p>
 
 Fast document processing powered by Rust. One API. Every document format.
 
@@ -93,14 +93,18 @@ paperjam info document.pdf
 
 ### MCP server
 
-Add to your MCP client configuration:
+```bash
+pip install paperjam-mcp
+```
+
+Add to your MCP client configuration (Claude Code, Claude Desktop, Cursor):
 
 ```json
 {
   "mcpServers": {
     "paperjam": {
-      "command": "paperjam",
-      "args": ["mcp", "serve"]
+      "command": "uvx",
+      "args": ["paperjam-mcp", "--working-dir", "."]
     }
   }
 }

docs-site/docs/guides/mcp.md

@@ -5,7 +5,7 @@ title: MCP Server
 
 # MCP Server
 
-paperjam ships with a built-in MCP (Model Context Protocol) server, making it the first document processing library with native AI-agent support. Any MCP-compatible client -- Claude Code, Claude Desktop, or custom agents -- can open, extract from, convert, and manipulate documents through a standard tool interface.
+paperjam ships with an MCP (Model Context Protocol) server, making it the first document processing library with native AI-agent support. Any MCP-compatible client -- Claude Code, Claude Desktop, Cursor, or custom agents -- can open, extract from, convert, and manipulate documents through a standard tool interface.
 
 ## What is MCP?
 
@@ -14,11 +14,11 @@ The Model Context Protocol is an open standard for connecting AI models to exter
 ## Installation
 
 ```bash
-# From crates.io
-cargo install paperjam-mcp
+# Run directly (no install needed)
+uvx paperjam-mcp
 
-# From source (in the paperjam repository)
-cargo install --path crates/paperjam-mcp
+# Or install globally
+pip install paperjam-mcp
 ```
 
 Verify the installation:
@@ -31,14 +31,14 @@ paperjam-mcp --version
 
 ### Claude Code
 
-Add the server to your project's `.mcp.json` or global MCP settings:
+Add the server to your project's `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "paperjam": {
-      "command": "paperjam-mcp",
-      "args": ["--working-dir", "/path/to/documents"]
+      "command": "uvx",
+      "args": ["paperjam-mcp", "--working-dir", "."]
     }
   }
 }
@@ -52,63 +52,162 @@ Add to your `claude_desktop_config.json`:
 {
   "mcpServers": {
     "paperjam": {
-      "command": "paperjam-mcp",
-      "args": ["--working-dir", "/Users/you/Documents"]
+      "command": "uvx",
+      "args": ["paperjam-mcp", "--working-dir", "/Users/you/Documents"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "paperjam": {
+      "command": "uvx",
+      "args": ["paperjam-mcp", "--working-dir", "."]
     }
   }
 }
 ```
 
 ### Server options
 
-| Flag | Description |
-|------|-------------|
-| `--working-dir <path>` | Base directory for resolving relative file paths |
-| `--max-sessions <n>` | Maximum concurrent document sessions (default: 16) |
-| `--log-level <level>` | Logging verbosity: `error`, `warn`, `info`, `debug` |
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--working-dir` | `.` | Base directory for resolving relative file paths. All file access is sandboxed to this directory. |
+| `--transport` | `stdio` | Transport: `stdio` or `sse` |
+| `--port` | `8080` | Port for SSE transport |
+| `--max-sessions` | `50` | Maximum concurrent document sessions |
+| `--session-ttl` | `3600` | Session time-to-live in seconds (resets on each access) |
+| `--log-level` | `warning` | Logging verbosity: `debug`, `info`, `warning`, `error` |
 
 ## Available tools
 
 Once connected, the AI model can call these tools through the MCP protocol.
 
-### Document tools
+### Document management
 
 | Tool | Description |
 |------|-------------|
-| `open_document` | Open a document by path or URL. Returns a session ID. |
+| `open_document` | Open a document by path. Returns a session ID. |
 | `get_document_info` | Get page count, metadata, format, and structural summary. |
 | `save_document` | Save the current document state to disk. |
 | `close_document` | Close a session and free resources. |
+| `list_sessions` | List all open document sessions. |
 
-### Extraction tools
+### Extraction
 
 | Tool | Description |
 |------|-------------|
-| `extract_text` | Extract plain text from all or specified pages. |
+| `extract_text` | Extract plain text from all pages. |
 | `extract_tables` | Extract tables as structured data (rows, headers, cells). |
 | `extract_structure` | Extract headings, paragraphs, and list items. |
 | `to_markdown` | Convert the document to Markdown. |
+| `search_document` | Full-text search with regex support (PDF only). |
+| `extract_links` | Extract all hyperlinks (PDF only). |
+| `extract_images` | Extract image metadata from a page (PDF only). |
+| `extract_bookmarks` | Extract bookmark/TOC tree. |
+
+### Page operations
+
+| Tool | Description |
+|------|-------------|
+| `page_get_info` | Page dimensions and rotation. |
+| `page_extract_text` | Text from a specific page. |
+| `page_extract_tables` | Tables from a specific page. |
+| `page_extract_structure` | Structure from a specific page. |
+| `page_analyze_layout` | Detect columns, headers, footers. |
+| `page_to_markdown` | Convert a page to Markdown. |
+
+### Manipulation
+
+| Tool | Description |
+|------|-------------|
+| `split_document` | Split by page ranges into multiple sessions. |
+| `merge_documents` | Merge multiple PDFs into one session. |
+| `reorder_pages` | Reorder, subset, or duplicate pages. |
+| `delete_pages` | Remove specific pages. |
+| `insert_blank_pages` | Add blank pages at positions. |
+| `rotate_pages` | Rotate specific pages. |
+| `optimize_document` | Compress and reduce file size. |
+
+### Annotations & stamps
+
+| Tool | Description |
+|------|-------------|
+| `add_watermark` | Apply a text watermark to pages. |
+| `add_annotation` | Add annotation (text, highlight, stamp, etc.). |
+| `remove_annotations` | Remove annotations by type or index. |
+| `stamp_pages` | Overlay a page from another PDF. |
+
+### Metadata & TOC
 
-### Conversion tools
+| Tool | Description |
+|------|-------------|
+| `set_metadata` | Update title, author, subject, keywords. |
+| `set_bookmarks` | Set/replace bookmarks. |
+| `generate_toc` | Auto-generate TOC from headings. |
+
+### Comparison
+
+| Tool | Description |
+|------|-------------|
+| `diff_documents` | Text-level diff between two PDFs. |
+| `visual_diff` | Pixel-level visual comparison. |
+
+### Conversion
 
 | Tool | Description |
 |------|-------------|
 | `convert_document` | Convert between formats (PDF, DOCX, XLSX, PPTX, HTML, EPUB, Markdown). |
+| `convert_file` | Direct file-to-file conversion. |
+| `detect_format` | Detect document format from path. |
+
+### Rendering
+
+| Tool | Description |
+|------|-------------|
+| `render_page` | Render a page to PNG/JPEG/BMP. Max 600 DPI. |
+| `render_pages` | Render multiple pages to images. Max 50 pages per call. |
+
+### Forms
+
+| Tool | Description |
+|------|-------------|
+| `has_form` | Check if document has a form. |
+| `get_form_fields` | List all form fields. |
+| `fill_form` | Fill form fields by name/value. |
+| `modify_form_field` | Modify field properties. |
+| `add_form_field` | Create a new form field. |
 
-### Manipulation tools
+### Security
 
 | Tool | Description |
 |------|-------------|
+| `sanitize_document` | Remove JavaScript, actions, embedded files, and links. |
 | `redact_text` | Find and permanently redact text by query or regex. |
-| `add_watermark` | Apply a text watermark to pages. |
+| `redact_regions` | Redact rectangular areas. |
 | `encrypt_document` | Password-protect a document with AES-128, AES-256, or RC4. |
-| `sanitize_document` | Remove JavaScript, actions, embedded files, and links. |
 
-### Pipeline tools
+### Digital signatures
 
 | Tool | Description |
 |------|-------------|
-| `run_pipeline` | Execute a multi-step processing pipeline from a YAML definition. |
+| `get_signatures` | Extract signature info. |
+| `verify_signatures` | Verify all signatures. |
+| `sign_document` | Digitally sign a PDF. |
+
+### Validation
+
+| Tool | Description |
+|------|-------------|
+| `validate_pdf_a` | Check PDF/A compliance. |
+| `validate_pdf_ua` | Check PDF/UA accessibility. |
+| `convert_to_pdf_a` | Convert to PDF/A. |
 
 ## Example interaction
 
@@ -131,7 +230,7 @@ The agent uses the extracted Markdown to write a summary, while the redacted PDF
 
 The MCP server maintains document sessions. When a client calls `open_document`, the server loads the file into memory and returns a session ID. Subsequent tool calls reference this ID to operate on the same document without re-reading from disk.
 
-Sessions are lightweight -- the document is loaded once and shared across all operations. The server enforces a maximum session count (`--max-sessions`) to bound memory usage. Sessions are released when the client calls `close_document` or when the MCP connection closes.
+Sessions are lightweight -- the document is loaded once and shared across all operations. The server enforces a maximum session count (`--max-sessions`) to bound memory usage. Sessions expire after the TTL (`--session-ttl`) of inactivity and are released when the client calls `close_document` or when the server shuts down.
 
 Multiple documents can be open simultaneously in separate sessions:
 
@@ -141,11 +240,22 @@ Multiple documents can be open simultaneously in separate sessions:
 4. `to_markdown` on `s2`
 5. `close_document` on `s1` and `s2`
 
+## Security
+
+The MCP server enforces a working directory sandbox:
+
+- All file paths are resolved relative to `--working-dir`
+- Paths that escape the working directory (e.g. `../../etc/passwd`) are rejected
+- Absolute paths outside the working directory are rejected
+
+Pipeline tools (`run_pipeline`, `validate_pipeline`) are disabled because they perform file I/O with their own path resolution that bypasses the sandbox. Use individual tools instead.
+
 ## Error handling
 
-Tool calls return structured errors when something goes wrong:
+Tool calls return structured JSON errors when something goes wrong:
 
 - **File not found** -- the path does not exist or is outside the working directory
+- **Path escapes working directory** -- the resolved path is outside the sandbox
 - **Invalid session** -- the session ID is expired or unrecognised
 - **Unsupported operation** -- e.g. calling `redact_text` on an XLSX document
 - **Conversion error** -- the requested format conversion is not supported