examples: add PDF viewer w/ chunked data loading, full-screen, model context updates, private tool (#267)
* feat(pdf-server): Interactive PDF viewer example
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
* chore: Add pdf-server to screenshot generation list
* refactor(pdf-server): Simplify and generalize PDF loading
- 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.
* feat(pdf-server): Include title and selection in model context
- 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
The UI needs the default value in the schema to show it properly.
* refactor(pdf-server): Further simplifications
- 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%)
* refactor(pdf-server): Major simplification for didactic focus
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%)
* feat(pdf-server): Add file:// URL support for local files
- 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
* fix(pdf-server): Improve selection detection with logging
- 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.
* feat(pdf-server): Format model context as markdown with front matter
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.
* refactor(pdf-server): Extract smart truncation helpers
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/>
```
* fix(pdf-server): Truncate inside selection tags when selection too long
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.
* refactor(pdf-server): Remove unused read_pdf_text, use Attention paper 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
* refactor(pdf-server): Simplify to use URL as ID, rename view_pdf to display_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.
* feat(pdf-server): Normalize arxiv URLs to PDF format
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
* fix(pdf-server): Sharp rendering on retina displays
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
* add to e2e spec
* add to e2e spec
* add to e2e spec
* add to e2e spec
* regen
* chore: regenerate package-lock.json and fix hono vulnerability
* docs: add pdf-server screenshot to READMEs
* regen
* ci: add missing examples to pkg-pr-new publish
* ci: add pdf-server to npm publish examples
* Update README.md
* pdf-server: improve tool response text for better model context
* revert unrelated screenshot changes
* pdf-server: dynamically add arxiv URLs in read_pdf_bytes
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.
This commit is contained in:
Olivier Chafik
GitHub
parent
63b05b4fdd
commit
96daa46a1d
1 changed files with 2358 additions and 29 deletions
250
examples/pdf-server/server.ts
Normal file
250
examples/pdf-server/server.ts
Normal file
|
|
@ -0,0 +1,250 @@
|
|||
/**
|
||||
* PDF MCP Server - Didactic Example
|
||||
*
|
||||
* Demonstrates:
|
||||
* - Chunked data through size-limited tool responses
|
||||
* - Model context updates (current page text + selection)
|
||||
* - Display modes: fullscreen with scrolling vs inline with resize
|
||||
* - External link opening (openLink)
|
||||
*/
|
||||
import {
|
||||
registerAppResource,
|
||||
registerAppTool,
|
||||
RESOURCE_MIME_TYPE,
|
||||
} from "@modelcontextprotocol/ext-apps/server";
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
||||
import type {
|
||||
CallToolResult,
|
||||
ReadResourceResult,
|
||||
} from "@modelcontextprotocol/sdk/types.js";
|
||||
import fs from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
buildPdfIndex,
|
||||
findEntryByUrl,
|
||||
createEntry,
|
||||
isArxivUrl,
|
||||
isFileUrl,
|
||||
toFileUrl,
|
||||
normalizeArxivUrl,
|
||||
} from "./src/pdf-indexer.js";
|
||||
import { loadPdfBytesChunk, populatePdfMetadata } from "./src/pdf-loader.js";
|
||||
import {
|
||||
ReadPdfBytesInputSchema,
|
||||
PdfBytesChunkSchema,
|
||||
type PdfIndex,
|
||||
} from "./src/types.js";
|
||||
import { startServer } from "./server-utils.js";
|
||||
|
||||
const DIST_DIR = path.join(import.meta.dirname, "dist");
|
||||
const RESOURCE_URI = "ui://pdf-viewer/mcp-app.html";
|
||||
const DEFAULT_PDF = "https://arxiv.org/pdf/1706.03762"; // Attention Is All You Need
|
||||
|
||||
let pdfIndex: PdfIndex | null = null;
|
||||
|
||||
export function createServer(): McpServer {
|
||||
const server = new McpServer({ name: "PDF Server", version: "1.0.0" });
|
||||
|
||||
// Tool: list_pdfs
|
||||
server.tool(
|
||||
"list_pdfs",
|
||||
"List indexed PDFs",
|
||||
{},
|
||||
async (): Promise<CallToolResult> => {
|
||||
if (!pdfIndex) throw new Error("Not initialized");
|
||||
return {
|
||||
content: [
|
||||
{ type: "text", text: JSON.stringify(pdfIndex.entries, null, 2) },
|
||||
],
|
||||
structuredContent: { entries: pdfIndex.entries },
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
// Tool: read_pdf_bytes (app-only) - Chunked binary loading
|
||||
registerAppTool(
|
||||
server,
|
||||
"read_pdf_bytes",
|
||||
{
|
||||
title: "Read PDF Bytes",
|
||||
description: "Load binary data in chunks",
|
||||
inputSchema: ReadPdfBytesInputSchema.shape,
|
||||
outputSchema: PdfBytesChunkSchema,
|
||||
_meta: { ui: { visibility: ["app"] } },
|
||||
},
|
||||
async (args: unknown): Promise<CallToolResult> => {
|
||||
if (!pdfIndex) throw new Error("Not initialized");
|
||||
const {
|
||||
url: rawUrl,
|
||||
offset,
|
||||
byteCount,
|
||||
} = ReadPdfBytesInputSchema.parse(args);
|
||||
const url = isArxivUrl(rawUrl) ? normalizeArxivUrl(rawUrl) : rawUrl;
|
||||
let entry = findEntryByUrl(pdfIndex, url);
|
||||
|
||||
// Dynamically add arxiv URLs (handles server restart between display_pdf and read_pdf_bytes)
|
||||
if (!entry) {
|
||||
if (isFileUrl(url)) {
|
||||
throw new Error("File URLs must be in the initial list");
|
||||
}
|
||||
if (!isArxivUrl(url)) {
|
||||
throw new Error(`PDF not found: ${url}`);
|
||||
}
|
||||
entry = createEntry(url);
|
||||
await populatePdfMetadata(entry);
|
||||
pdfIndex.entries.push(entry);
|
||||
}
|
||||
|
||||
const chunk = await loadPdfBytesChunk(entry, offset, byteCount);
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: `${chunk.byteCount} bytes at ${chunk.offset}/${chunk.totalBytes}`,
|
||||
},
|
||||
],
|
||||
structuredContent: chunk,
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
// Tool: display_pdf - Interactive viewer with UI
|
||||
registerAppTool(
|
||||
server,
|
||||
"display_pdf",
|
||||
{
|
||||
title: "Display PDF",
|
||||
description: `Display an interactive PDF viewer in the chat.
|
||||
|
||||
Use this tool when the user asks to view, display, read, or open a PDF. Accepts:
|
||||
- URLs from list_pdfs (preloaded PDFs)
|
||||
- Any arxiv.org URL (loaded dynamically)
|
||||
|
||||
The viewer supports zoom, navigation, text selection, and fullscreen mode.`,
|
||||
inputSchema: {
|
||||
url: z
|
||||
.string()
|
||||
.default(DEFAULT_PDF)
|
||||
.describe("PDF URL (arxiv.org for dynamic loading)"),
|
||||
page: z.number().min(1).default(1).describe("Initial page"),
|
||||
},
|
||||
outputSchema: z.object({
|
||||
url: z.string(),
|
||||
title: z.string().optional(),
|
||||
pageCount: z.number(),
|
||||
initialPage: z.number(),
|
||||
}),
|
||||
_meta: { ui: { resourceUri: RESOURCE_URI } },
|
||||
},
|
||||
async ({ url: rawUrl, page }): Promise<CallToolResult> => {
|
||||
if (!pdfIndex) throw new Error("Not initialized");
|
||||
|
||||
// Normalize arxiv URLs to PDF format
|
||||
const url = isArxivUrl(rawUrl) ? normalizeArxivUrl(rawUrl) : rawUrl;
|
||||
|
||||
let entry = findEntryByUrl(pdfIndex, url);
|
||||
|
||||
if (!entry) {
|
||||
if (isFileUrl(url)) {
|
||||
throw new Error("File URLs must be in the initial list");
|
||||
}
|
||||
if (!isArxivUrl(url)) {
|
||||
throw new Error(`Only arxiv.org URLs can be loaded dynamically`);
|
||||
}
|
||||
|
||||
entry = createEntry(url);
|
||||
await populatePdfMetadata(entry);
|
||||
pdfIndex.entries.push(entry);
|
||||
}
|
||||
|
||||
const result = {
|
||||
url: entry.url,
|
||||
title: entry.metadata.title,
|
||||
pageCount: entry.metadata.pageCount,
|
||||
initialPage: Math.min(page, entry.metadata.pageCount),
|
||||
};
|
||||
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: `Displaying interactive PDF viewer${entry.metadata.title ? ` for "${entry.metadata.title}"` : ""} (${entry.url}, ${entry.metadata.pageCount} pages)`,
|
||||
},
|
||||
],
|
||||
structuredContent: result,
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
// Resource: UI HTML
|
||||
registerAppResource(
|
||||
server,
|
||||
RESOURCE_URI,
|
||||
RESOURCE_URI,
|
||||
{ mimeType: RESOURCE_MIME_TYPE },
|
||||
async (): Promise<ReadResourceResult> => {
|
||||
const html = await fs.readFile(
|
||||
path.join(DIST_DIR, "mcp-app.html"),
|
||||
"utf-8",
|
||||
);
|
||||
return {
|
||||
contents: [
|
||||
{ uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },
|
||||
],
|
||||
};
|
||||
},
|
||||
);
|
||||
|
||||
return server;
|
||||
}
|
||||
|
||||
// CLI
|
||||
function parseArgs(): { urls: string[]; stdio: boolean } {
|
||||
const args = process.argv.slice(2);
|
||||
const urls: string[] = [];
|
||||
let stdio = false;
|
||||
|
||||
for (const arg of args) {
|
||||
if (arg === "--stdio") {
|
||||
stdio = true;
|
||||
} else if (!arg.startsWith("-")) {
|
||||
// Convert local paths to file:// URLs, normalize arxiv URLs
|
||||
let url = arg;
|
||||
if (
|
||||
!arg.startsWith("http://") &&
|
||||
!arg.startsWith("https://") &&
|
||||
!arg.startsWith("file://")
|
||||
) {
|
||||
url = toFileUrl(arg);
|
||||
} else if (isArxivUrl(arg)) {
|
||||
url = normalizeArxivUrl(arg);
|
||||
}
|
||||
urls.push(url);
|
||||
}
|
||||
}
|
||||
|
||||
return { urls: urls.length > 0 ? urls : [DEFAULT_PDF], stdio };
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const { urls, stdio } = parseArgs();
|
||||
|
||||
console.error(`[pdf-server] Initializing with ${urls.length} PDF(s)...`);
|
||||
pdfIndex = await buildPdfIndex(urls);
|
||||
console.error(`[pdf-server] Ready`);
|
||||
|
||||
if (stdio) {
|
||||
await createServer().connect(new StdioServerTransport());
|
||||
} else {
|
||||
const port = parseInt(process.env.PORT ?? "3001", 10);
|
||||
await startServer(createServer, { port, name: "PDF Server" });
|
||||
}
|
||||
}
|
||||
|
||||
main().catch((e) => {
|
||||
console.error(e);
|
||||
process.exit(1);
|
||||
});
|
||||
Loading…
Reference in a new issue