ext-apps/examples/pdf-server

PDF Server

An interactive PDF viewer using 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):

{
  "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):

{
  "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 streams PDFs in chunks using HTTP Range requests:

Server side (server.ts):

// Returns chunks with pagination metadata
{
  (bytes, offset, byteCount, totalBytes, hasMore);
}

Client side (mcp-app.ts):

// Load in chunks with progress
while (hasMore) {
  const chunk = await app.callServerTool({
    name: "read_pdf_bytes",
    arguments: { url, offset },
  });
  chunks.push(base64ToBytes(chunk.bytes));
  offset += chunk.byteCount;
  hasMore = chunk.hasMore;
  updateProgress(offset, chunk.totalBytes);
}

2. Model Context Updates

The viewer keeps the model informed about what the user is seeing:

app.updateModelContext({
  content: [
    {
      type: "text",
      text: `PDF viewer | "${title}" | Current Page: ${page}/${total}\n\nPage content:\n${pageText}`,
    },
  ],
});

This enables the model to answer questions about the current page or selected text.

3. Display Modes: Fullscreen vs Inline

• Inline mode: App requests height changes to fit content
• Fullscreen mode: App fills the screen with internal scrolling

// Request fullscreen
app.requestDisplayMode({ mode: "fullscreen" });

// Listen for mode changes
app.ondisplaymodechange = (mode) => {
  if (mode === "fullscreen") enableScrolling();
  else disableScrolling();
};

4. External Links (openLink)

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:

app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) applyDocumentTheme(ctx.theme);
  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
};

Usage

# Default: loads a sample arxiv paper
bun examples/pdf-server/main.ts

# Load local files (converted to file:// URLs)
bun examples/pdf-server/main.ts ./docs/paper.pdf /path/to/thesis.pdf

# Load from URLs
bun examples/pdf-server/main.ts https://arxiv.org/pdf/2401.00001.pdf

# Mix local and remote
bun examples/pdf-server/main.ts ./local.pdf https://arxiv.org/pdf/2401.00001.pdf

# stdio mode for MCP clients
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). 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.

• Stdio mode (--stdio): Client roots are always enabled — the client is typically on the same machine (e.g. Claude Desktop), so the roots are safe.
• HTTP mode (default): Client roots are ignored by default — the client may be remote, and its roots would be resolved against the server's filesystem. To opt in, pass --use-client-roots:

# Trust that the HTTP client is local and its roots are safe
bun examples/pdf-server/main.ts --use-client-roots

When roots are ignored the server logs:

[pdf-server] Client roots are ignored (default for remote transports). Pass --use-client-roots to allow the client to expose local directories.

Allowed Sources

• Local files: Must be passed as CLI arguments (or via client roots when enabled)
• 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 available local files and origins
display_pdf	Model + UI	Display interactive viewer
interact¹	Model	Navigate, annotate, search, extract pages, fill forms, save to file
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.

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"}]

Saving

User: Save the annotated version as /docs/contract-signed.pdf.

Model calls interact with action save_as, path /docs/contract-signed.pdf. Fails if the file exists; pass overwrite: true to replace. The target path must be under a mounted directory root.

User: Save my changes back to the file.

Model calls interact with action save_as, overwrite: true (no path). Overwrites the original — same writability gate as the viewer's save button. Only works for local files; remote PDFs need an explicit path.

Testing

E2E Tests (Playwright)

# 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:

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
src/
├── 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()
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 and annotation import (frontend only)
• pdf-lib: Client-side PDF modification — creates proper PDF annotation dictionaries for export
• @modelcontextprotocol/ext-apps: MCP Apps SDK