fcp-pdf 0.1.0__tar.gz

fcp_pdf-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: uv sync
+      - run: uv run pytest
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

fcp_pdf-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+uv.lock
+.python-version

fcp_pdf-0.1.0/CLAUDE.md

@@ -0,0 +1,35 @@
+# fcp-pdf
+
+PDF driver for the File Context Protocol (FCP). Provides semantic PDF operations as an MCP server.
+
+## Architecture
+
+- `src/fcp_pdf/main.py` — MCP server entry point via `create_fcp_server()`
+- `src/fcp_pdf/adapter.py` — `PdfAdapter` implementing `FcpDomainAdapter` protocol
+- `src/fcp_pdf/model/snapshot.py` — `PdfModel` wrapper around `fitz.Document` with byte-snapshot undo/redo
+- `src/fcp_pdf/server/ops_*.py` — verb handlers (pages, text, annotate, bookmark, merge, meta, watermark, image, redact, link)
+- `src/fcp_pdf/server/queries.py` — read-only query handlers (plan, status, describe, find, toc, fonts, annots)
+- `src/fcp_pdf/server/resolvers.py` — page resolution, range parsing, color parsing
+- `src/fcp_pdf/server/verb_registry.py` — verb specs for all operations
+- `src/fcp_pdf/server/reference_card.py` — help content
+
+## Key dependencies
+
+- **PyMuPDF** (`pymupdf`/`fitz`) — PDF engine
+- **fcp-core** — shared FCP server framework
+- **fastmcp** — MCP server transport
+
+## Commands
+
+```bash
+uv sync --dev        # install deps
+uv run pytest        # run tests
+uv run fcp-pdf       # start MCP server
+```
+
+## MCP tools exposed
+
+- `pdf(ops)` — execute operations (page, text, insert-text, annotate, bookmark, merge, split, meta, watermark, image, redact, link)
+- `pdf_query(q)` — query document state (plan, status, describe, find, toc, fonts, annots)
+- `pdf_session(action)` — session lifecycle (new, open, save, checkpoint, undo, redo)
+- `pdf_help()` — reference card

fcp_pdf-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: fcp-pdf
+Version: 0.1.0
+Summary: PDF File Context Protocol — semantic PDF operations for LLMs
+Requires-Python: <3.14,>=3.11
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: fcp-core>=0.1.18
+Requires-Dist: pymupdf>=1.25

fcp_pdf-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "fcp-pdf"
+version = "0.1.0"
+description = "PDF File Context Protocol — semantic PDF operations for LLMs"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "fcp-core>=0.1.18",
+    "fastmcp>=3.0",
+    "pymupdf>=1.25",
+]
+
+# [tool.uv.sources]
+# For local development, use `make link-py` instead of uncommenting:
+# fcp-core = { path = "../fcp-core/python", editable = true }
+
+[project.scripts]
+fcp-pdf = "fcp_pdf.main:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4",
+    "pyright>=1.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fcp_pdf"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+src = ["src"]

fcp_pdf-0.1.0/src/fcp_pdf/__main__.py

@@ -0,0 +1,3 @@
+from fcp_pdf.main import main
+
+main()

fcp_pdf-0.1.0/src/fcp_pdf/adapter.py

@@ -0,0 +1,153 @@
+"""PdfAdapter — FcpDomainAdapter implementation for PyMuPDF documents.
+
+Bridges fcp-core to PyMuPDF via PdfModel. Handles batch atomicity
+and snapshot-based undo/redo.
+"""
+
+from __future__ import annotations
+
+import fitz
+
+from fcp_core import EventLog, OpResult, ParsedOp
+
+from fcp_pdf.model.snapshot import PdfModel, SnapshotEvent
+from fcp_pdf.server.queries import dispatch_query
+from fcp_pdf.server.resolvers import PdfOpContext
+
+# Import all handler dicts
+from fcp_pdf.server.ops_pages import HANDLERS as PAGE_HANDLERS
+from fcp_pdf.server.ops_text import HANDLERS as TEXT_HANDLERS
+from fcp_pdf.server.ops_annotate import HANDLERS as ANNOTATE_HANDLERS
+from fcp_pdf.server.ops_bookmark import HANDLERS as BOOKMARK_HANDLERS
+from fcp_pdf.server.ops_merge import HANDLERS as MERGE_HANDLERS
+from fcp_pdf.server.ops_meta import HANDLERS as META_HANDLERS
+from fcp_pdf.server.ops_watermark import HANDLERS as WATERMARK_HANDLERS
+from fcp_pdf.server.ops_image import HANDLERS as IMAGE_HANDLERS
+from fcp_pdf.server.ops_redact import HANDLERS as REDACT_HANDLERS
+from fcp_pdf.server.ops_link import HANDLERS as LINK_HANDLERS
+from fcp_pdf.server.ops_compose import HANDLERS as COMPOSE_HANDLERS
+
+
+class PdfAdapter:
+    """FcpDomainAdapter[PdfModel, SnapshotEvent] for PDF operations."""
+
+    def __init__(self) -> None:
+        # Merge all verb handlers
+        self._handlers: dict[str, callable] = {}
+        for h in (
+            PAGE_HANDLERS, TEXT_HANDLERS, ANNOTATE_HANDLERS,
+            BOOKMARK_HANDLERS, MERGE_HANDLERS, META_HANDLERS,
+            WATERMARK_HANDLERS, IMAGE_HANDLERS, REDACT_HANDLERS,
+            LINK_HANDLERS, COMPOSE_HANDLERS,
+        ):
+            self._handlers.update(h)
+
+    # -- FcpDomainAdapter protocol --
+
+    def create_empty(self, title: str, params: dict[str, str]) -> PdfModel:
+        """Create a new empty PDF document."""
+        doc = fitz.open()
+        model = PdfModel(title=title, doc=doc)
+        return model
+
+    def serialize(self, model: PdfModel, path: str) -> None:
+        """Save PDF to file."""
+        model.doc.save(path, garbage=3, deflate=True)
+        model.file_path = path
+
+    def deserialize(self, path: str) -> PdfModel:
+        """Load PDF from file."""
+        doc = fitz.open(path)
+        title = path.rsplit("/", 1)[-1]
+        model = PdfModel(title=title, doc=doc)
+        model.file_path = path
+        return model
+
+    def rebuild_indices(self, model: PdfModel) -> None:
+        """Rebuild index after undo/redo. Clamp active page."""
+        if len(model.doc) == 0:
+            model.active_page = 0
+        elif model.active_page >= len(model.doc):
+            model.active_page = len(model.doc) - 1
+
+    def get_digest(self, model: PdfModel) -> str:
+        """Return a compact state fingerprint."""
+        doc = model.doc
+        page_count = len(doc)
+        active = model.active_page + 1
+
+        # Quick stats
+        total_images = 0
+        total_annots = 0
+        for i in range(page_count):
+            page = doc[i]
+            total_images += len(page.get_images())
+            for _ in page.annots():
+                total_annots += 1
+
+        parts = [f"Active: page {active}", f"Pages: {page_count}"]
+        if total_images:
+            parts.append(f"Images: {total_images}")
+        if total_annots:
+            parts.append(f"Annotations: {total_annots}")
+
+        return ", ".join(parts)
+
+    def dispatch_op(
+        self, op: ParsedOp, model: PdfModel, log: EventLog
+    ) -> OpResult:
+        """Execute a parsed operation on the model."""
+        handler = self._handlers.get(op.verb)
+        if handler is None:
+            from fcp_core import suggest
+            s = suggest(op.verb, list(self._handlers.keys()))
+            msg = f"Unknown verb: {op.verb!r}"
+            if s:
+                msg += f"\n  try: {s}"
+            return OpResult(success=False, message=msg)
+
+        # Take pre-op snapshot
+        before = model.snapshot()
+
+        # Build context
+        ctx = PdfOpContext(doc=model.doc, model=model)
+
+        # Dispatch
+        try:
+            result = handler(op, ctx)
+        except NotImplementedError as exc:
+            return OpResult(success=False, message=str(exc))
+        except (ValueError, KeyError, TypeError, AttributeError) as exc:
+            return OpResult(success=False, message=f"Error: {exc}")
+
+        if not result.success:
+            return result
+
+        # Log snapshot for undo
+        after = model.snapshot()
+        log.append(SnapshotEvent(before=before, after=after, summary=op.raw))
+
+        return result
+
+    def take_snapshot(self, model: PdfModel) -> bytes:
+        """Return byte snapshot for batch rollback."""
+        return model.snapshot()
+
+    def restore_snapshot(self, model: PdfModel, snapshot: bytes) -> None:
+        """Restore model from snapshot and rebuild indices."""
+        model.restore(snapshot)
+        self.rebuild_indices(model)
+
+    def dispatch_query(self, query: str, model: PdfModel) -> str:
+        """Execute a query against the model."""
+        return dispatch_query(query, model)
+
+    def reverse_event(self, event: SnapshotEvent, model: PdfModel) -> None:
+        """Undo — restore from before-snapshot."""
+        model.restore(event.before)
+        self.rebuild_indices(model)
+
+    def replay_event(self, event: SnapshotEvent, model: PdfModel) -> None:
+        """Redo — restore from after-snapshot."""
+        model.restore(event.after)
+        self.rebuild_indices(model)

fcp_pdf-0.1.0/src/fcp_pdf/lib/themes.py

@@ -0,0 +1,213 @@
+"""Named color themes for professional documents.
+
+Each theme defines a coordinated palette that the compose engine
+uses for headings, table headers, accents, callouts, and body text.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Theme:
+    """A coordinated color palette for document styling."""
+    name: str
+    # Core
+    heading: str        # H1/H2 color
+    subheading: str     # H3/H4 color
+    body: str           # body text
+    muted: str          # captions, footnotes
+    # Accents
+    accent: str         # primary accent (links, highlights)
+    accent_bg: str      # accent background (light tint)
+    # Table
+    table_header_bg: str
+    table_header_fg: str
+    table_border: str
+    table_stripe: str   # alternating row background
+    # Callouts
+    info_bg: str
+    info_border: str
+    info_fg: str
+    warning_bg: str
+    warning_border: str
+    warning_fg: str
+    success_bg: str
+    success_border: str
+    success_fg: str
+    error_bg: str
+    error_border: str
+    error_fg: str
+    # Structural
+    rule: str           # horizontal rule color
+    blockquote_border: str
+    code_bg: str
+
+
+# -- Built-in themes --
+
+CORPORATE = Theme(
+    name="corporate",
+    heading="#1a1a2e",
+    subheading="#16213e",
+    body="#2d2d2d",
+    muted="#6c757d",
+    accent="#0066cc",
+    accent_bg="#e8f0fe",
+    table_header_bg="#1a1a2e",
+    table_header_fg="#ffffff",
+    table_border="#d0d0d0",
+    table_stripe="#f8f9fa",
+    info_bg="#e8f4fd",
+    info_border="#0288d1",
+    info_fg="#01579b",
+    warning_bg="#fff8e1",
+    warning_border="#f9a825",
+    warning_fg="#e65100",
+    success_bg="#e8f5e9",
+    success_border="#43a047",
+    success_fg="#1b5e20",
+    error_bg="#fce4ec",
+    error_border="#e53935",
+    error_fg="#b71c1c",
+    rule="#d0d0d0",
+    blockquote_border="#0066cc",
+    code_bg="#f5f5f5",
+)
+
+MODERN = Theme(
+    name="modern",
+    heading="#0f172a",
+    subheading="#334155",
+    body="#374151",
+    muted="#9ca3af",
+    accent="#6366f1",
+    accent_bg="#eef2ff",
+    table_header_bg="#6366f1",
+    table_header_fg="#ffffff",
+    table_border="#e5e7eb",
+    table_stripe="#f9fafb",
+    info_bg="#eff6ff",
+    info_border="#3b82f6",
+    info_fg="#1e40af",
+    warning_bg="#fffbeb",
+    warning_border="#f59e0b",
+    warning_fg="#92400e",
+    success_bg="#f0fdf4",
+    success_border="#22c55e",
+    success_fg="#166534",
+    error_bg="#fef2f2",
+    error_border="#ef4444",
+    error_fg="#991b1b",
+    rule="#e5e7eb",
+    blockquote_border="#6366f1",
+    code_bg="#f1f5f9",
+)
+
+MINIMAL = Theme(
+    name="minimal",
+    heading="#111111",
+    subheading="#333333",
+    body="#222222",
+    muted="#888888",
+    accent="#111111",
+    accent_bg="#f5f5f5",
+    table_header_bg="#f0f0f0",
+    table_header_fg="#111111",
+    table_border="#e0e0e0",
+    table_stripe="#fafafa",
+    info_bg="#f5f5f5",
+    info_border="#999999",
+    info_fg="#333333",
+    warning_bg="#f5f5f5",
+    warning_border="#999999",
+    warning_fg="#333333",
+    success_bg="#f5f5f5",
+    success_border="#999999",
+    success_fg="#333333",
+    error_bg="#f5f5f5",
+    error_border="#999999",
+    error_fg="#333333",
+    rule="#cccccc",
+    blockquote_border="#cccccc",
+    code_bg="#f5f5f5",
+)
+
+EXECUTIVE = Theme(
+    name="executive",
+    heading="#1b2838",
+    subheading="#2c3e50",
+    body="#2c3e50",
+    muted="#7f8c8d",
+    accent="#c0392b",
+    accent_bg="#fdedec",
+    table_header_bg="#2c3e50",
+    table_header_fg="#ecf0f1",
+    table_border="#bdc3c7",
+    table_stripe="#f8f9f9",
+    info_bg="#eaf2f8",
+    info_border="#2980b9",
+    info_fg="#1a5276",
+    warning_bg="#fef9e7",
+    warning_border="#f39c12",
+    warning_fg="#7d6608",
+    success_bg="#eafaf1",
+    success_border="#27ae60",
+    success_fg="#1e8449",
+    error_bg="#fdedec",
+    error_border="#c0392b",
+    error_fg="#922b21",
+    rule="#bdc3c7",
+    blockquote_border="#c0392b",
+    code_bg="#f4f6f7",
+)
+
+OCEAN = Theme(
+    name="ocean",
+    heading="#023e8a",
+    subheading="#0077b6",
+    body="#264653",
+    muted="#8ecae6",
+    accent="#0096c7",
+    accent_bg="#caf0f8",
+    table_header_bg="#023e8a",
+    table_header_fg="#ffffff",
+    table_border="#90e0ef",
+    table_stripe="#caf0f8",
+    info_bg="#caf0f8",
+    info_border="#0077b6",
+    info_fg="#023e8a",
+    warning_bg="#fff3cd",
+    warning_border="#e9c46a",
+    warning_fg="#795548",
+    success_bg="#d1fae5",
+    success_border="#2a9d8f",
+    success_fg="#264653",
+    error_bg="#fee2e2",
+    error_border="#e76f51",
+    error_fg="#9b2226",
+    rule="#90e0ef",
+    blockquote_border="#0077b6",
+    code_bg="#edf6f9",
+)
+
+THEMES: dict[str, Theme] = {
+    "corporate": CORPORATE,
+    "modern": MODERN,
+    "minimal": MINIMAL,
+    "executive": EXECUTIVE,
+    "ocean": OCEAN,
+}
+
+DEFAULT_THEME = CORPORATE
+
+
+def get_theme(name: str) -> Theme | None:
+    """Look up a theme by name (case-insensitive)."""
+    return THEMES.get(name.lower())
+
+
+def list_themes() -> list[str]:
+    """Return available theme names."""
+    return sorted(THEMES.keys())

fcp_pdf-0.1.0/src/fcp_pdf/main.py

@@ -0,0 +1,36 @@
+"""fcp-pdf — PDF File Context Protocol MCP server."""
+
+from __future__ import annotations
+
+from fcp_core.server import create_fcp_server
+
+from fcp_pdf.adapter import PdfAdapter
+from fcp_pdf.server.reference_card import EXTRA_SECTIONS
+from fcp_pdf.server.verb_registry import VERBS
+
+adapter = PdfAdapter()
+
+mcp = create_fcp_server(
+    domain="pdf",
+    adapter=adapter,
+    verbs=VERBS,
+    extra_sections=EXTRA_SECTIONS,
+    extensions=["pdf"],
+    name="fcp-pdf",
+    instructions=(
+        "FCP PDF server for reading, manipulating, and creating PDF files. "
+        "Use pdf_session to open an existing PDF or create a new one, "
+        "pdf to execute operations (page, text, annotate, bookmark, merge, split, meta, watermark, image, redact), "
+        "pdf_query to inspect document structure and search content, "
+        "and pdf_help for the full verb reference. "
+        "Start every interaction with pdf_session."
+    ),
+)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

fcp_pdf-0.1.0/src/fcp_pdf/model/snapshot.py

@@ -0,0 +1,52 @@
+"""Byte-snapshot undo/redo for PyMuPDF documents.
+
+SnapshotEvent captures before/after states as bytes.
+fitz documents serialize/deserialize via doc.tobytes()/fitz.open(stream=...).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import fitz
+
+
+@dataclass
+class SnapshotEvent:
+    """Event type for byte-snapshot undo/redo."""
+
+    type: str = "snapshot"
+    before: bytes = field(default=b"", repr=False)
+    after: bytes = field(default=b"", repr=False)
+    summary: str = ""
+
+
+class PdfModel:
+    """Thin wrapper around fitz.Document for in-place undo/redo.
+
+    The session dispatcher holds a reference to this object.
+    reverse_event/replay_event replace self.doc in place so
+    the session reference stays valid.
+    """
+
+    def __init__(self, title: str = "Untitled", doc: fitz.Document | None = None):
+        self.title = title
+        self.doc: fitz.Document = doc or fitz.open()
+        self.file_path: str | None = None
+        self.active_page: int = 0
+
+    def snapshot(self) -> bytes:
+        """Take a byte snapshot of the current document state."""
+        if len(self.doc) == 0:
+            # PyMuPDF can't serialize zero-page docs — return sentinel
+            return b""
+        return self.doc.tobytes(deflate=True, garbage=3)
+
+    def restore(self, data: bytes) -> None:
+        """Replace the document from snapshot bytes (in-place for undo/redo)."""
+        self.doc.close()
+        if data == b"":
+            # Restore to empty doc
+            self.doc = fitz.open()
+        else:
+            self.doc = fitz.open(stream=data, filetype="pdf")