examples: add PDF viewer w/ chunked data loading, full-screen, model context updates, private tool #267

ochafik · 2026-01-13T20:46:44Z

Summary

A simple interactive PDF viewer that uses PDF.js. Launch it w/ a few PDF files and/or URLs as CLI args (+ support loading any additional pdf from arxiv.org).

MCP Apps Patterns Demonstrated

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:

// Server returns chunks with pagination metadata
{ bytes, offset, byteCount, totalBytes, hasMore }

// Client loads progressively
while (hasMore) {
  const chunk = await app.callServerTool("read_pdf_bytes", { url, offset });
  offset += chunk.byteCount;
  hasMore = chunk.hasMore;
  ...
}

2. Model Context Updates

The viewer keeps the model informed about what the user sees:

---
title: Attention Is All You Need
url: https://arxiv.org/pdf/1706.03762
current-page: 5/15
---

Page text with <pdf-selection>selected text</pdf-selection> inline.
<truncated-content/>

3. Display Modes

Inline mode: Viewer stays unscrolled, requests height changes via sendSizeChanged() to fit content
Fullscreen mode: Viewer fills the screen via requestDisplayMode(), with internal scrolling when zoomed

4. External Links

Opens source URLs via app.openLink()

5. App-Only Tools

read_pdf_bytes is hidden from the model (visibility: ["app"]), used only by the viewer UI.

Architecture

server.ts           # MCP server (~160 lines)
├── src/
│   ├── types.ts        # Zod schemas (~50 lines)
│   ├── pdf-indexer.ts  # Indexing (~50 lines)
│   ├── pdf-loader.ts   # Chunked loading (~130 lines)
│   └── mcp-app.ts      # Interactive viewer UI

Usage

# Default: "Attention Is All You Need" paper
bun examples/pdf-server/server.ts

# Local files (converted to file:// URLs)
bun examples/pdf-server/server.ts ./paper.pdf

# Any HTTP URL in initial args
bun examples/pdf-server/server.ts https://arxiv.org/pdf/2401.00001.pdf

Security: Dynamic URLs via display_pdf are restricted to arxiv.org. Local files must be in the initial list.

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

PDF viewer with PDF.js featuring: - Chunked binary loading with progress bar - Text extraction for AI context - arXiv paper support (fetch by ID) - Page navigation with keyboard shortcuts - Zoom controls (including Ctrl+0 reset) - Fullscreen mode support - Horizontal swipe for page changes (disabled when zoomed) - Page persistence in localStorage - Text selection via PDF.js TextLayer - Clickable title link to source URL - Rounded corners and subtle border styling

- Accept any HTTP(s) URLs instead of ArXiv-only - Use HTTP Range requests for chunked binary loading - Remove ArXiv-specific code (arxiv.ts, metadata fetching) - Remove CLAUDE.md index generation - Flatten hierarchical folder structure to simple entries list - Remove dead code: getPdfSummary, httpFileSizes - Simplify base64 encoding using Buffer - Simplify chunk extraction using slice() - Consolidate DEFAULT_PDF_URL constant The server now works with any PDF URL, not just arXiv papers. HTTP Range requests stream chunks on-demand when supported.

- Add pdfTitle to updateModelContext structuredContent - Include selection position (text, start, end) when text is selected - Add debounced selectionchange listener to update context on selection

The UI needs the default value in the schema to show it properly.

- Remove hard-coded test paths from main() - Remove unused resources: pdfs://metadata/{pdfId}, pdfs://content/{pdfId} - Remove unused metadata fields: subject, creator, producer, creationDate, modDate - Remove unused entry fields: relativePath, estimatedTextSize - Remove filterEntriesByFolder and folder filter from list_pdfs - Remove redundant output schema validation (trust typed returns) - Simplify scanDirectory and createLocalEntry signatures Total: 1836 → 1666 lines (-170 lines, -9%)

Simplified the example to focus on key MCP Apps SDK patterns: - Chunked data through size-limited tool calls - Model context updates (page text + selection) - Display modes (fullscreen vs inline) - External links (openLink) Changes: - Remove local file support (HTTP URLs only) - Restrict dynamic URLs to arxiv.org for security - Simplify types: url instead of sourcePath/sourceType - Simplify indexer: 168 → 44 lines - Simplify loader: 318 → 171 lines - Simplify server: 337 → 233 lines - Fix selection text normalization - Rewrite README with didactic focus Total: 1836 → 1236 lines (-33%)

- Local paths are converted to file:// URLs on startup - file:// URLs must be in the initial list (strict validation) - Dynamic URLs still restricted to arxiv.org only - Updated README with local file examples

- Add logging to selectionchange handler to verify it fires - Add fallback matching without spaces (TextLayer spans may lack spaces) - Log selection detection success/failure for debugging The issue: PDF.js TextLayer renders text as positioned spans without space characters between them. When selecting across spans: - pageText has spaces (items joined with ' ') - sel.toString() may not have spaces - indexOf fails to match The fix tries exact match first, then falls back to spaceless matching.

Model context now looks like: ```markdown --- url: https://arxiv.org/pdf/... page: 5/144 --- Page text with <pdf-selection>selected text</pdf-selection> inline. ``` This is cleaner for the model to parse and includes the source URL.

Added two well-designed helpers: formatPageContent(text, maxLength, selection?) - Centers truncation window around selection if present - Adds <truncated-content/> markers at elision points - Wraps selection in <pdf-selection> tags - Allocates 60% context before, 40% after for readability findSelectionInText(pageText, selectedText) - Tries exact match first - Falls back to spaceless match for TextLayer quirks - Returns { start, end } or undefined Example output with selection: ``` <truncated-content/> ...context before... <pdf-selection>selected text</pdf-selection> ...context after... <truncated-content/> ```

When selection is too large for the budget: <truncated-content/><pdf-selection><truncated-content/>start...end<truncated-content/></pdf-selection><truncated-content/> This keeps the selection structure intact while showing beginning and end.

…r as default - Remove read_pdf_text tool (viewer extracts text client-side with pdfjs) - Remove PdfTextChunk and ReadPdfTextInput types - Remove loadPdfTextChunk from pdf-loader - Change default PDF to 'Attention Is All You Need' (1706.03762) - Update README with modest language

…isplay_pdf Major simplifications: - Use URL directly as identifier (no hashing) - Remove displayName - show elided URL with full URL as tooltip - Rename view_pdf to display_pdf with better description - Update all references from pdfId to url - Simplify storage key and model context The tool description now explains it displays an interactive viewer in the chat.

arxiv.org/abs/... -> arxiv.org/pdf/... Applied both at startup and when loading dynamic URLs.

Account for devicePixelRatio when rendering canvas: - Scale canvas dimensions by dpr - Scale context by dpr - Keep CSS size at logical pixels

pkg-pr-new · 2026-01-13T23:26:27Z

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@267

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-react@267

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-vanillajs@267

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-budget-allocator@267

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-cohort-heatmap@267

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-customer-segmentation@267

@modelcontextprotocol/server-map

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-map@267

@modelcontextprotocol/server-pdf

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-pdf@267

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-scenario-modeler@267

@modelcontextprotocol/server-shadertoy

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-shadertoy@267

@modelcontextprotocol/server-sheet-music

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-sheet-music@267

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-system-monitor@267

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-threejs@267

@modelcontextprotocol/server-transcript

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-transcript@267

@modelcontextprotocol/server-video-resource

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-video-resource@267

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-wiki-explorer@267

commit: 70d360e

jonathanhefner

It looks like all the E2E screenshots are being regenerated without any masking. Is that issue particular to this branch, or coming from another base branch, or an existing issue in main?

ochafik · 2026-01-14T00:27:14Z

It looks like all the E2E screenshots are being regenerated without any masking. Is that issue particular to this branch, or coming from another base branch, or an existing issue in main?

@jonathanhefner The screenshots w/o masking (and their cropped / resized cell derivatives) are new (#253), used for the top-level gallery and the readmes of most servers. The e2e test goldens are still w/ masks

antonpk1 · 2026-01-14T11:52:22Z

examples/pdf-server/server.ts

+        content: [
+          {
+            type: "text",
+            text: `Viewing ${entry.url} (${entry.metadata.pageCount} pages)`,


maybe makes sense to expand this a bit to better explain situation to the agent (otherwise it may go :
"Displaying a widget with interactive PDF viewer to the user. Viewing ${entry.url} (${entry.metadata.pageCount} pages)"

Note the tool description already sets the stage for what's happening (Claude seems to understand) but I'll rework this too

text: `Displaying interactive PDF viewer${entry.metadata.title ? ` for "${entry.metadata.title}"` : ""} (${entry.url}, ${entry.metadata.pageCount} pages)`,

jonathanhefner · 2026-01-14T13:41:37Z

The screenshots w/o masking (and their cropped / resized cell derivatives) are new (#253), used for the top-level gallery and the readmes of most servers. The e2e test goldens are still w/ masks

Ah, I see. But why are they being replaced in this PR? Is that a side effect of adding a new screenshot (for a new example) to the gallery?

ochafik · 2026-01-14T13:59:42Z

The screenshots w/o masking (and their cropped / resized cell derivatives) are new (#253), used for the top-level gallery and the readmes of most servers. The e2e test goldens are still w/ masks

Ah, I see. But why are they being replaced in this PR? Is that a side effect of adding a new screenshot (for a new example) to the gallery?

@jonathanhefner No good reason (reverted all but pdf-server), the ones w/ masked date seem to vary in length (maybe day of week changes it?), I'll look at regularizing that in a follow up.

Fixes 'PDF not found' error when server restarts between display_pdf (which adds the entry) and read_pdf_bytes (which previously only looked up existing entries). Now read_pdf_bytes mirrors display_pdf's logic and dynamically adds arxiv URLs to the index.

ochafik marked this pull request as draft January 13, 2026 20:54

ochafik changed the title ~~feat(pdf-server): Interactive PDF viewer example~~ feat(pdf-server): Didactic PDF viewer demonstrating MCP Apps patterns Jan 13, 2026

ochafik changed the title ~~feat(pdf-server): Didactic PDF viewer demonstrating MCP Apps patterns~~ examples: add PDF viewer w/ chunked data loading, full-screen, model context updates, private tool Jan 13, 2026

ochafik force-pushed the ochafik/host-open branch from abca7ab to 4064f67 Compare January 13, 2026 22:38

ochafik marked this pull request as ready for review January 13, 2026 22:55

ochafik requested a review from jonathanhefner January 13, 2026 22:55

ochafik added 18 commits January 13, 2026 23:03

chore: Add pdf-server to screenshot generation list

0697d04

feat(pdf-server): Include title and selection in model context

311d058

- Add pdfTitle to updateModelContext structuredContent - Include selection position (text, start, end) when text is selected - Add debounced selectionchange listener to update context on selection

fix(pdf-server): Restore default URL in view_pdf schema

11fbda5

The UI needs the default value in the schema to show it properly.

feat(pdf-server): Add file:// URL support for local files

12b1213

- Local paths are converted to file:// URLs on startup - file:// URLs must be in the initial list (strict validation) - Dynamic URLs still restricted to arxiv.org only - Updated README with local file examples

feat(pdf-server): Normalize arxiv URLs to PDF format

7c154e2

arxiv.org/abs/... -> arxiv.org/pdf/... Applied both at startup and when loading dynamic URLs.

docs(pdf-server): Add prompt engineering to display_pdf description

19e364d

fix(pdf-server): Sharp rendering on retina displays

35a7e6d

Account for devicePixelRatio when rendering canvas: - Scale canvas dimensions by dpr - Scale context by dpr - Keep CSS size at logical pixels

fix(pdf-server): Normalize arxiv URLs in read_pdf_bytes too

6008f60

ochafik changed the base branch from ochafik/host-open to main January 13, 2026 23:05

ochafik force-pushed the ochafik/pdf-server2 branch from 9c5eb10 to 6008f60 Compare January 13, 2026 23:05

ochafik added 4 commits January 13, 2026 23:07

add to e2e spec

ab98f5f

add to e2e spec

12c0a26

add to e2e spec

31bd981

add to e2e spec

f51eeae

ochafik added 3 commits January 13, 2026 23:23

regen

fcec16a

chore: regenerate package-lock.json and fix hono vulnerability

ed89586

docs: add pdf-server screenshot to READMEs

4b84450

regen

69a5975

jonathanhefner reviewed Jan 13, 2026

View reviewed changes

Merge branch 'main' into ochafik/pdf-server2

6df8f40

ochafik requested a review from antonpk1 January 14, 2026 11:25

ochafik added 3 commits January 14, 2026 11:34

ci: add missing examples to pkg-pr-new publish

5c3e98b

ci: add pdf-server to npm publish examples

cc480b4

Update README.md

c02eef5

antonpk1 previously approved these changes Jan 14, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into ochafik/pdf-server2

0dc44a6

pdf-server: improve tool response text for better model context

b11153a

ochafik dismissed antonpk1’s stale review via b11153a January 14, 2026 13:56

revert unrelated screenshot changes

7347cf2

ochafik merged commit 96daa46 into main Jan 14, 2026
17 of 18 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

examples: add PDF viewer w/ chunked data loading, full-screen, model context updates, private tool #267

examples: add PDF viewer w/ chunked data loading, full-screen, model context updates, private tool #267

Uh oh!

ochafik commented Jan 13, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 13, 2026 •

edited

Loading

Uh oh!

jonathanhefner left a comment

Uh oh!

ochafik commented Jan 14, 2026

Uh oh!

antonpk1 Jan 14, 2026

Uh oh!

ochafik Jan 14, 2026

Uh oh!

ochafik Jan 14, 2026

Uh oh!

jonathanhefner commented Jan 14, 2026

Uh oh!

ochafik commented Jan 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

examples: add PDF viewer w/ chunked data loading, full-screen, model context updates, private tool #267

examples: add PDF viewer w/ chunked data loading, full-screen, model context updates, private tool #267

Uh oh!

Conversation

ochafik commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

MCP Apps Patterns Demonstrated

1. Chunked Data Through Size-Limited Tool Calls

2. Model Context Updates

3. Display Modes

4. External Links

5. App-Only Tools

Architecture

Usage

Tools

Uh oh!

pkg-pr-new bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonathanhefner left a comment

Choose a reason for hiding this comment

Uh oh!

ochafik commented Jan 14, 2026

Uh oh!

antonpk1 Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

ochafik Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

ochafik Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

jonathanhefner commented Jan 14, 2026

Uh oh!

ochafik commented Jan 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ochafik commented Jan 13, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 13, 2026 •

edited

Loading