modelcontextprotocol
diff --git a/‎examples/pdf-server/README.md‎
Lines changed: 147 additions & 18 deletions b/‎examples/pdf-server/README.md‎
Lines changed: 147 additions & 18 deletions
diff --git a/‎examples/pdf-server/grid-cell.png‎
-4.54 KB b/‎examples/pdf-server/grid-cell.png‎
-4.54 KB
diff --git a/‎examples/pdf-server/main.ts‎
Lines changed: 34 additions & 3 deletions b/‎examples/pdf-server/main.ts‎
Lines changed: 34 additions & 3 deletions
diff --git a/‎examples/pdf-server/mcp-app.html‎
Lines changed: 63 additions & 8 deletions b/‎examples/pdf-server/mcp-app.html‎
Lines changed: 63 additions & 8 deletions
@@ -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
@@ -20,8 +20,10 @@ import {
   pathToFileUrl,
   fileUrlToPath,
   allowedLocalFiles,
+  cliLocalFiles,
   DEFAULT_PDF,
   allowedLocalDirs,
+  writeFlags,
 } from "./server.js";
 
 /**
@@ -93,17 +95,33 @@ function parseArgs(): {
   urls: string[];
   stdio: boolean;
   useClientRoots: boolean;
+  enableInteract: boolean;
+  debug: boolean;
 } {
   const args = process.argv.slice(2);
   const urls: string[] = [];
   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") {
+      // Force-enable interact for HTTP mode. Only use when running a
+      // single long-lived server process (e.g. the e2e test harness) —
+      // the command queue is in-memory per-process, so stateless
+      // multi-instance deployments will drop commands.
+      enableInteract = true;
+    } else if (arg === "--debug") {
+      debug = true;
+    } else if (arg === "--writeable-uploads-root") {
+      // Claude Desktop mounts attachments under a dir root named "uploads";
+      // by default we refuse to write there. This flag opts back in.
+      writeFlags.allowUploadsRoot = true;
     } else if (!arg.startsWith("-")) {
       // Convert local paths to file:// URLs, normalize arxiv URLs
       let url = arg;
@@ -124,11 +142,13 @@ function parseArgs(): {
     urls: urls.length > 0 ? urls : [DEFAULT_PDF],
     stdio,
     useClientRoots,
+    enableInteract,
+    debug,
   };
 }
 
 async function main() {
-  const { urls, stdio, useClientRoots } = parseArgs();
+  const { urls, stdio, useClientRoots, enableInteract, debug } = parseArgs();
 
   // Register local files in whitelist
   for (const url of urls) {
@@ -138,6 +158,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);
@@ -153,10 +174,20 @@ async function main() {
 
   if (stdio) {
     // stdio → client is local (e.g. Claude Desktop), roots are safe
-    await startStdioServer(() => createServer({ useClientRoots: true }));
+    await startStdioServer(() =>
+      createServer({ enableInteract: true, useClientRoots: true, debug }),
+    );
   } else {
     // HTTP → client is remote, only honour roots with explicit opt-in
-    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 }),
+    );
   }
 }
 
 
@@ -19,6 +19,16 @@
         <p id="error-message">An error occurred</p>
       </div>
 
+      <!-- Confirmation Dialog Overlay -->
+      <div id="confirm-dialog" class="confirm-dialog" style="display: none">
+        <div class="confirm-box">
+          <div id="confirm-title" class="confirm-title"></div>
+          <div id="confirm-body" class="confirm-body"></div>
+          <div id="confirm-detail" class="confirm-detail"></div>
+          <div id="confirm-buttons" class="confirm-buttons"></div>
+        </div>
+      </div>
+
       <!-- PDF Viewer -->
       <div id="viewer" class="viewer" style="display: none">
         <!-- Toolbar -->
@@ -60,6 +70,31 @@
             <button id="zoom-in-btn" class="zoom-btn" title="Zoom in (+)">
               +
             </button>
+            <button
+              id="save-btn"
+              class="save-btn"
+              title="Save to file (overwrites original)"
+              style="display: none"
+            >
+              <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M13 14H3a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1h7l3 3v9a1 1 0 0 1-1 1z"/><path d="M11 14V9H5v5"/><path d="M5 2v3h5"/></svg>
+            </button>
+            <button
+              id="download-btn"
+              class="download-btn"
+              title="Download PDF"
+              style="display: none"
+            >
+              <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 2v8m0 0l-3-3m3 3l3-3"/><path d="M2 12v2h12v-2"/></svg>
+            </button>
+            <button
+              id="annotations-btn"
+              class="annotations-btn"
+              title="Toggle annotations panel"
+              style="display: none"
+            >
+              <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="1" y="1" width="14" height="14" rx="2"/><line x1="5" y1="5" x2="11" y2="5"/><line x1="5" y1="8" x2="11" y2="8"/><line x1="5" y1="11" x2="9" y2="11"/></svg>
+              <span id="annotations-badge" class="annotations-badge" style="display: none"></span>
+            </button>
             <button
               id="search-btn"
               class="search-btn"
@@ -68,9 +103,10 @@
             <button
               id="fullscreen-btn"
               class="fullscreen-btn"
-              title="Toggle fullscreen"
+              title="Toggle fullscreen (⌘Enter)"
             >
-              ⛶
+              <svg class="expand-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 3H5a2 2 0 0 0-2 2v3m18 0V5a2 2 0 0 0-2-2h-3m0 18h3a2 2 0 0 0 2-2v-3M3 16v3a2 2 0 0 0 2 2h3"/></svg>
+              <svg class="collapse-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:none"><path d="M8 3v3a2 2 0 0 1-2 2H3m18 0h-3a2 2 0 0 1-2-2V3m0 18v-3a2 2 0 0 1 2-2h3M3 16h3a2 2 0 0 1 2 2v3"/></svg>
             </button>
           </div>
         </div>
@@ -107,12 +143,31 @@
           </button>
         </div>
 
-        <!-- Single Page Canvas Container -->
-        <div class="canvas-container">
-          <div class="page-wrapper">
-            <canvas id="pdf-canvas"></canvas>
-            <div id="highlight-layer" class="highlight-layer"></div>
-            <div id="text-layer" class="text-layer"></div>
+        <!-- Canvas + Annotation Panel Row -->
+        <div class="viewer-body">
+          <!-- Single Page Canvas Container -->
+          <div class="canvas-container">
+            <div class="page-wrapper">
+              <canvas id="pdf-canvas"></canvas>
+              <div id="annotation-layer" class="annotation-layer"></div>
+              <div id="highlight-layer" class="highlight-layer"></div>
+              <div id="text-layer" class="text-layer"></div>
+              <div id="form-layer" class="annotationLayer"></div>
+            </div>
+          </div>
+
+          <!-- Annotation Side Panel -->
+          <div id="annotation-panel" class="annotation-panel" style="display: none">
+            <div id="annotation-panel-resize" class="annotation-panel-resize"></div>
+            <div class="annotation-panel-header">
+              <span class="annotation-panel-title">Annotations (<span id="annotation-panel-count">0</span>)</span>
+              <div class="annotation-panel-header-actions">
+                <button id="annotation-panel-reset" class="annotation-panel-reset" title="Revert to what's in the PDF file"><svg width="14" height="14" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2 6a4 4 0 1 1 1.2 2.85"/><path d="M2 9V6h3"/></svg></button>
+                <button id="annotation-panel-clear-all" class="annotation-panel-clear-all" title="Remove everything, including items from the PDF file"><svg width="14" height="14" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><path d="M2 3h8M4.5 3V2a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 .5.5v1M5 5.5v3M7 5.5v3M3 3l.5 7a1 1 0 0 0 1 1h3a1 1 0 0 0 1-1L9 3"/></svg></button>
+                <button id="annotation-panel-close" class="annotation-panel-close" title="Close panel">&#x2715;</button>
+              </div>
+            </div>
+            <div id="annotation-panel-list" class="annotation-panel-list"></div>
           </div>
         </div>
       </div>