@modelcontextprotocol/server-pdf 0.4.1 → 1.0.0

package/README.md

@@ -2,26 +2,59 @@
 
 ![Screenshot](screenshot.png)
 
-A simple interactive PDF viewer that uses [PDF.js](https://mozilla.github.io/pdf.js/). Launch it w/ a few PDF files and/or URLs as CLI args (+ support loading any additional pdf from arxiv.org).
+An interactive PDF viewer using [PDF.js](https://mozilla.github.io/pdf.js/). Supports local files and remote URLs from academic sources (arxiv, biorxiv, zenodo, etc).
+
+## MCP Client Configuration
+
+Add to your MCP client configuration (stdio transport):
+
+```json
+{
+  "mcpServers": {
+    "pdf": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-pdf",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+
+### Local Development
+
+To test local modifications, use this configuration (replace `~/code/ext-apps` with your clone path):
+
+```json
+{
+  "mcpServers": {
+    "pdf": {
+      "command": "bash",
+      "args": [
+        "-c",
+        "cd ~/code/ext-apps/examples/pdf-server && npm run build >&2 && node dist/index.js --stdio"
+      ]
+    }
+  }
+}
+```
 
 ## What This Example Demonstrates
 
 ### 1. Chunked Data Through Size-Limited Tool Calls
 
-On some host platforms, tool calls have size limits, so large PDFs cannot be sent in a single response. This example shows a possible workaround:
+On some host platforms, tool calls have size limits, so large PDFs cannot be sent in a single response. This example streams PDFs in chunks using HTTP Range requests:
 
-**Server side** (`pdf-loader.ts`):
+**Server side** (`server.ts`):
 
 ```typescript
 // Returns chunks with pagination metadata
-async function loadPdfBytesChunk(entry, offset, byteCount) {
-  return {
-    bytes: base64Chunk,
-    offset,
-    byteCount,
-    totalBytes,
-    hasMore: offset + byteCount < totalBytes,
-  };
+{
+  (bytes, offset, byteCount, totalBytes, hasMore);
 }
 ```
 
@@ -30,7 +63,7 @@ async function loadPdfBytesChunk(entry, offset, byteCount) {
 ```typescript
 // Load in chunks with progress
 while (hasMore) {
-  const chunk = await app.callServerTool("read_pdf_bytes", { pdfId, offset });
+  const chunk = await app.callServerTool("read_pdf_bytes", { url, offset });
   chunks.push(base64ToBytes(chunk.bytes));
   offset += chunk.byteCount;
   hasMore = chunk.hasMore;
@@ -44,13 +77,12 @@ The viewer keeps the model informed about what the user is seeing:
 
 ```typescript
 app.updateModelContext({
-  structuredContent: {
-    title: pdfTitle,
-    currentPage,
-    totalPages,
-    pageText: pageText.slice(0, 5000),
-    selection: selectedText ? { text, start, end } : undefined,
-  },
+  content: [
+    {
+      type: "text",
+      text: `PDF viewer | "${title}" | Current Page: ${page}/${total}\n\nPage content:\n${pageText}`,
+    },
+  ],
 });
 ```
 
@@ -80,58 +112,75 @@ The viewer demonstrates opening external links (e.g., to the original arxiv page
 titleEl.onclick = () => app.openLink(sourceUrl);
 ```
 
+### 5. View Persistence
+
+Page position is saved per-view using `viewUUID` and localStorage.
+
+### 6. Dark Mode / Theming
+
+The viewer syncs with the host's theme using CSS `light-dark()` and the SDK's theming APIs:
+
+```typescript
+app.onhostcontextchanged = (ctx) => {
+  if (ctx.theme) applyDocumentTheme(ctx.theme);
+  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
+};
+```
+
 ## Usage
 
 ```bash
 # Default: loads a sample arxiv paper
-bun examples/pdf-server/server.ts
+bun examples/pdf-server/main.ts
 
 # Load local files (converted to file:// URLs)
-bun examples/pdf-server/server.ts ./docs/paper.pdf /path/to/thesis.pdf
+bun examples/pdf-server/main.ts ./docs/paper.pdf /path/to/thesis.pdf
 
 # Load from URLs
-bun examples/pdf-server/server.ts https://arxiv.org/pdf/2401.00001.pdf
+bun examples/pdf-server/main.ts https://arxiv.org/pdf/2401.00001.pdf
 
 # Mix local and remote
-bun examples/pdf-server/server.ts ./local.pdf https://arxiv.org/pdf/2401.00001.pdf
+bun examples/pdf-server/main.ts ./local.pdf https://arxiv.org/pdf/2401.00001.pdf
 
 # stdio mode for MCP clients
-bun examples/pdf-server/server.ts --stdio ./papers/
+bun examples/pdf-server/main.ts --stdio ./papers/
 ```
 
-**Security**: Dynamic URLs (via `view_pdf` tool) are restricted to arxiv.org. Local files must be in the initial list.
+## Allowed Sources
+
+- **Local files**: Must be passed as CLI arguments
+- **Remote URLs**: arxiv.org, biorxiv.org, medrxiv.org, chemrxiv.org, zenodo.org, osf.io, hal.science, ssrn.com, and more
 
 ## Tools
 
-| Tool             | Visibility | Purpose                            |
-| ---------------- | ---------- | ---------------------------------- |
-| `list_pdfs`      | Model      | List indexed PDFs                  |
-| `display_pdf`    | Model + UI | Display interactive viewer in chat |
-| `read_pdf_bytes` | App only   | Chunked binary loading             |
+| 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              |
 
 ## Architecture
 
 ```
-server.ts           # MCP server (233 lines)
-├── src/
-│   ├── types.ts        # Zod schemas (75 lines)
-│   ├── pdf-indexer.ts  # URL-based indexing (44 lines)
-│   ├── pdf-loader.ts   # Chunked loading (171 lines)
-│   └── mcp-app.ts      # Interactive viewer UI
+server.ts      # MCP server + tools
+main.ts        # CLI entry point
+src/
+└── mcp-app.ts # Interactive viewer UI (PDF.js)
 ```
 
 ## 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()`                         |
-| Size negotiation  | `app.sendSizeChanged()`                  |
+| 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()` |
 
 ## Dependencies
 
-- `pdfjs-dist`: PDF rendering
+- `pdfjs-dist`: PDF rendering (frontend only)
 - `@modelcontextprotocol/ext-apps`: MCP Apps SDK