@modelcontextprotocol/server-pdf 1.2.2 → 1.3.0

package/README.md

@@ -149,6 +149,20 @@ bun examples/pdf-server/main.ts ./local.pdf https://arxiv.org/pdf/2401.00001.pdf
 bun examples/pdf-server/main.ts --stdio ./papers/
 ```
 
+### Additional Flags
+
+- `--debug` — Enable verbose server-side logging.
+- `--enable-interact` — Enable the `interact` tool in HTTP mode (see [Deployment](#deployment)). Not needed for stdio.
+- `--writeable-uploads-root` — Allow saving annotated PDFs back to files under client roots named `uploads` (Claude Desktop mounts attachments there; writes are refused by default).
+
+## Deployment
+
+The `interact` tool relies on an in-memory command queue (server enqueues → viewer polls). This constrains how the server can be deployed:
+
+- **stdio** (Claude Desktop) — `interact` is always enabled. The server runs as a single long-lived process, so the in-memory queue works.
+- **HTTP, single instance** — Pass `--enable-interact` to opt in. Works as long as all requests land on the same process.
+- **HTTP, stateless / multi-instance** — `interact` will not work. Commands enqueued on one instance are invisible to viewers polling another. Leave the flag off; the tool will not be registered.
+
 ## Security: Client Roots
 
 MCP clients may advertise **roots** — `file://` URIs pointing to directories on the client's file system. The server uses these to allow access to local files under those directories.
@@ -174,34 +188,149 @@ When roots are ignored the server logs:
 
 ## Tools
 
-| Tool             | Visibility | Purpose                                |
-| ---------------- | ---------- | -------------------------------------- |
-| `list_pdfs`      | Model      | List available local files and origins |
-| `display_pdf`    | Model + UI | Display interactive viewer             |
-| `read_pdf_bytes` | App only   | Stream PDF data in chunks              |
+| Tool             | Visibility | Purpose                                               |
+| ---------------- | ---------- | ----------------------------------------------------- |
+| `list_pdfs`      | Model      | List available local files and origins                |
+| `display_pdf`    | Model + UI | Display interactive viewer                            |
+| `interact`¹      | Model      | Navigate, annotate, search, extract pages, fill forms |
+| `read_pdf_bytes` | App only   | Stream PDF data in chunks                             |
+| `save_pdf`       | App only   | Save annotated PDF back to local file                 |
+
+¹ stdio only by default; in HTTP mode requires `--enable-interact` — see [Deployment](#deployment).
+
+## Example Prompts
+
+After the model calls `display_pdf`, it receives the `viewUUID` and a description of all capabilities. Here are example prompts and follow-ups that exercise annotation features:
+
+### Annotating
+
+> **User:** Show me the Attention Is All You Need paper
+>
+> _Model calls `display_pdf` → viewer opens_
+>
+> **User:** Highlight the title and add an APPROVED stamp on the first page.
+>
+> _Model calls `interact` with `highlight_text` for the title and `add_annotations` with a stamp_
+
+> **User:** Can you annotate this PDF? Mark important sections for me.
+>
+> _Model calls `interact` with `get_text` to read content first, then `add_annotations` with highlights/notes_
+
+> **User:** Add a note on page 1 saying "Key contribution" at position (200, 500), and highlight the abstract.
+>
+> _Model calls `interact` with `add_annotations` containing a `note` and either `highlight_text` or a `highlight` annotation_
+
+### Navigation & Search
+
+> **User:** Search for "self-attention" in the paper.
+>
+> _Model calls `interact` with action `search`, query `"self-attention"`_
+
+> **User:** Go to page 5.
+>
+> _Model calls `interact` with action `navigate`, page `5`_
+
+### Page Extraction
+
+> **User:** Give me the text of pages 1–3.
+>
+> _Model calls `interact` with action `get_text`, intervals `[{start:1, end:3}]`_
+
+> **User:** Take a screenshot of the first page.
+>
+> _Model calls `interact` with action `get_screenshot`, page `1`_
+
+### Stamps & Form Filling
+
+> **User:** Stamp this document as CONFIDENTIAL on every page.
+>
+> _Model calls `interact` with `add_annotations` containing `stamp` annotations on each page_
+
+> **User:** Fill in the "Name" field with "Alice" and "Date" with "2026-02-26".
+>
+> _Model calls `interact` with action `fill_form`, fields `[{name:"Name", value:"Alice"}, {name:"Date", value:"2026-02-26"}]`_
+
+## Testing
+
+### E2E Tests (Playwright)
+
+```bash
+# Run annotation E2E tests (renders annotations in a real browser)
+npx playwright test tests/e2e/pdf-annotations.spec.ts
+
+# Run all PDF server tests
+npx playwright test -g "PDF Server"
+```
+
+### API Prompt Discovery Tests
+
+These tests verify that Claude can discover and use annotation capabilities by calling the Anthropic Messages API with the tool schemas. They are **disabled by default** — skipped unless `ANTHROPIC_API_KEY` is set:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-... npx playwright test tests/e2e/pdf-annotations-api.spec.ts
+```
+
+The API tests simulate a conversation where `display_pdf` has already been called, then send a follow-up user message and verify the model uses annotation actions (or at least the `interact` tool). Three scenarios are tested:
+
+| Scenario             | User prompt                                                       | Expected model behavior                    |
+| -------------------- | ----------------------------------------------------------------- | ------------------------------------------ |
+| Direct annotation    | "Highlight the title and add an APPROVED stamp"                   | Uses `highlight_text` or `add_annotations` |
+| Capability discovery | "Can you annotate this PDF?"                                      | Uses interact or mentions annotations      |
+| Specific notes       | "Add a note saying 'Key contribution' and highlight the abstract" | Uses `interact` tool                       |
 
 ## Architecture
 
 ```
-server.ts      # MCP server + tools
-main.ts        # CLI entry point
+server.ts                  # MCP server + tools
+main.ts                    # CLI entry point
 src/
-└── mcp-app.ts # Interactive viewer UI (PDF.js)
+├── mcp-app.ts             # Interactive viewer UI (PDF.js)
+├── pdf-annotations.ts     # Annotation types, diff model, PDF import/export
+└── pdf-annotations.test.ts # Unit tests for annotation module
 ```
 
 ## Key Patterns Shown
 
-| Pattern           | Implementation                              |
-| ----------------- | ------------------------------------------- |
-| App-only tools    | `_meta: { ui: { visibility: ["app"] } }`    |
-| Chunked responses | `hasMore` + `offset` pagination             |
-| Model context     | `app.updateModelContext()`                  |
-| Display modes     | `app.requestDisplayMode()`                  |
-| External links    | `app.openLink()`                            |
-| View persistence  | `viewUUID` + localStorage                   |
-| Theming           | `applyDocumentTheme()` + CSS `light-dark()` |
+| Pattern                       | Implementation                                                 |
+| ----------------------------- | -------------------------------------------------------------- |
+| App-only tools                | `_meta: { ui: { visibility: ["app"] } }`                       |
+| Chunked responses             | `hasMore` + `offset` pagination                                |
+| Model context                 | `app.updateModelContext()`                                     |
+| Display modes                 | `app.requestDisplayMode()`                                     |
+| External links                | `app.openLink()`                                               |
+| View persistence              | `viewUUID` + localStorage                                      |
+| Theming                       | `applyDocumentTheme()` + CSS `light-dark()`                    |
+| Annotations                   | DOM overlays synced with proper PDF annotation dicts           |
+| Annotation import             | Load existing PDF annotations via PDF.js `getAnnotations()`    |
+| Diff-based persistence        | localStorage stores only additions/removals vs PDF baseline    |
+| Proper PDF export             | pdf-lib low-level API creates real `/Type /Annot` dictionaries |
+| Save to file                  | App-only `save_pdf` tool writes annotated bytes back to disk   |
+| Dirty flag                    | `*` prefix on title when unsaved local changes exist           |
+| Command queue                 | Server enqueues → client polls + processes                     |
+| File download                 | `app.downloadFile()` for annotated PDF                         |
+| Floating panel with anchoring | Magnetic corner-snapping panel for annotation list             |
+| Drag, resize, rotate          | Interactive annotation handles with undo/redo                  |
+| Keyboard shortcuts            | Ctrl+Z/Y (undo/redo), Ctrl+S (save), Ctrl+F (search), ⌘Enter   |
+
+### Annotation Types
+
+Supported annotation types (synced with PDF.js):
+
+| Type            | Properties                                                         | PDF Subtype  |
+| --------------- | ------------------------------------------------------------------ | ------------ |
+| `highlight`     | `rects`, `color?`, `content?`                                      | `/Highlight` |
+| `underline`     | `rects`, `color?`                                                  | `/Underline` |
+| `strikethrough` | `rects`, `color?`                                                  | `/StrikeOut` |
+| `note`          | `x`, `y`, `content`, `color?`                                      | `/Text`      |
+| `rectangle`     | `x`, `y`, `width`, `height`, `color?`, etc.                        | `/Square`    |
+| `circle`        | `x`, `y`, `width`, `height`, `color?`, etc.                        | `/Circle`    |
+| `line`          | `x1`, `y1`, `x2`, `y2`, `color?`                                   | `/Line`      |
+| `freetext`      | `x`, `y`, `content`, `fontSize?`, `color?`                         | `/FreeText`  |
+| `stamp`         | `x`, `y`, `label`, `color?`, `rotation?`                           | `/Stamp`     |
+| `image`         | `x`, `y`, `width`, `height`, `imageData?`/`imageUrl?`, `rotation?` | `/Stamp`     |
 
 ## Dependencies
 
-- `pdfjs-dist`: PDF rendering (frontend only)
+- `pdfjs-dist`: PDF rendering and annotation import (frontend only)
+- `pdf-lib`: Client-side PDF modification — creates proper PDF annotation dictionaries for export
 - `@modelcontextprotocol/ext-apps`: MCP Apps SDK

package/dist/index.js

@@ -34135,8 +34135,10 @@ import {
   pathToFileUrl,
   fileUrlToPath,
   allowedLocalFiles,
+  cliLocalFiles,
   DEFAULT_PDF,
-  allowedLocalDirs
+  allowedLocalDirs,
+  writeFlags
 } from "./server.js";
 async function startStreamableHTTPServer(createServer2) {
   const port = parseInt(process.env.PORT ?? "3001", 10);
@@ -34188,11 +34190,19 @@ function parseArgs() {
   const urls = [];
   let stdio = false;
   let useClientRoots = false;
+  let enableInteract = false;
+  let debug = false;
   for (const arg of args) {
     if (arg === "--stdio") {
       stdio = true;
     } else if (arg === "--use-client-roots") {
       useClientRoots = true;
+    } else if (arg === "--enable-interact") {
+      enableInteract = true;
+    } else if (arg === "--debug") {
+      debug = true;
+    } else if (arg === "--writeable-uploads-root") {
+      writeFlags.allowUploadsRoot = true;
     } else if (!arg.startsWith("-")) {
       let url = arg;
       if (!arg.startsWith("http://") && !arg.startsWith("https://") && !arg.startsWith("file://")) {
@@ -34206,11 +34216,13 @@ function parseArgs() {
   return {
     urls: urls.length > 0 ? urls : [DEFAULT_PDF],
     stdio,
-    useClientRoots
+    useClientRoots,
+    enableInteract,
+    debug
   };
 }
 async function main() {
-  const { urls, stdio, useClientRoots } = parseArgs();
+  const { urls, stdio, useClientRoots, enableInteract, debug } = parseArgs();
   for (const url of urls) {
     if (isFileUrl(url)) {
       const filePath = path.resolve(fileUrlToPath(url));
@@ -34218,6 +34230,7 @@ async function main() {
         const s = fs.statSync(filePath);
         if (s.isFile()) {
           allowedLocalFiles.add(filePath);
+          cliLocalFiles.add(filePath);
           console.error(`[pdf-server] Registered local file: ${filePath}`);
         } else if (s.isDirectory()) {
           allowedLocalDirs.add(filePath);
@@ -34230,9 +34243,12 @@ async function main() {
   }
   console.error(`[pdf-server] Ready (${urls.length} URL(s) configured)`);
   if (stdio) {
-    await startStdioServer(() => createServer({ useClientRoots: true }));
+    await startStdioServer(() => createServer({ enableInteract: true, useClientRoots: true, debug }));
   } else {
-    await startStreamableHTTPServer(() => createServer({ useClientRoots }));
+    if (!useClientRoots) {
+      console.error("[pdf-server] Client roots are ignored (default for remote transports). " + "Pass --use-client-roots to allow the client to expose local directories.");
+    }
+    await startStreamableHTTPServer(() => createServer({ useClientRoots, enableInteract, debug }));
   }
 }
 main().catch((e) => {