PR #506 added loadBaselineAnnotations() and buildFieldNameMap() between
showViewer() and renderPage(). Both iterate every page calling
getPage()+getAnnotations(), so the viewer sat with an unsized empty
canvas for ~400ms (15-page doc, scales linearly) before painting.
Neither scan blocks the canvas — page.render() only needs canvasContext
+ viewport. renderAnnotationsForPage() reads annotationMap (graceful
empty), AnnotationLayer.render() takes cachedFieldObjects (graceful
null). So: render first, scan after, re-render to overlay annotations
+ form values. Same fix at the reload path.
* pdf-server: add save_as interact action
Adds a model-callable save_as action to the interact tool that writes the
viewer's current annotated state (annotations + form values) to a new file.
Reuses the get_pages request/reply pattern: model's interact call blocks
while the viewer builds bytes via getAnnotatedPdfBytes() and posts them
back through a new submit_save_data app-only tool.
Validation runs synchronously before bothering the viewer:
- path must be absolute or file://
- isWritablePath gate (same as save_pdf)
- existence check; fails with a descriptive error unless overwrite: true
The viewer can report build errors back via submit_save_data({error}),
so the model gets a real message instead of the 45s timeout.
* pdf-server: warn model off app-only tools in descriptions
Hosts that don't filter visibility:["app"] tools from the model's tool
list will still surface these. The save_pdf one in particular is a
near-miss for the new save_as interact action — point the model at the
right one.
* pdf-server: save_as without path overwrites original
When path is omitted, save_as falls back to the displayed PDF's local
path (tracked per-viewUUID by display_pdf). Same writability gate as
the viewer's save button: isWritablePath + OS-level W_OK probe, so it
refuses on read-only mounts before the viewer roundtrip.
Requires explicit overwrite: true since the original always exists —
the model can't accidentally clobber it.
Remote PDFs have no source path stored; the error tells the model to
pass an explicit path.
* fix(pdf-server): fail fast on never-polled viewer + surface batch errors
interact's get_screenshot/get_text waited the full 45s for a viewer that
never mounted (host went idle before iframe reached startPolling), then
timed out with a generic message. Now tracks viewsPolled and fails in ~8s
with a recovery hint. Batch errors were also ordered success-first —
hosts that flatten isError to content[0] showed "Queued: Filled N fields"
and dropped the actual failure entirely. Viewer side: poll even when PDF
load throws, and catch connect() rejection instead of silently blanking.
* fix(pdf-server): radio button + dropdown handling in fill_form and save
Three related bugs around non-text form fields:
Viewer fill_form (mcp-app.ts): writing a string to annotationStorage on
every radio widget trips pdf.js's inverted string coercion
(`value !== buttonValue` → true) — the first-rendered widget checks
itself and clears the rest, so whatever you ask for, you get the first
option. Fix: extract a setFieldInStorage() helper that writes
{value: true} only on the widget whose buttonValue matches, {value: false}
on siblings, matching pdf.js's own change handler. Also covers the
syncFormValuesToStorage() path (localStorage restore).
Save (pdf-annotations.ts): buildAnnotatedPdfBytes only knew about
getTextField/getCheckBox — dropdowns and radios threw in the try block
and fell through the catch, so they were silently dropped on save.
Fix: instanceof dispatch on getFieldMaybe(). For radios, accept either
the option label or a numeric buttonValue (indexed into getOptions()),
since the viewer stores the latter for PDFs with /Opt.
display_pdf output (server.ts): radio groups showed as N identical
`name [Btn]` lines with no way to tell them apart; dropdowns didn't
list their options. Fix: surface buttonValue as exportValue and the
options array from the annotation data already in hand.
Transitive dep via express → router. Fixes:
- GHSA-27v5-c462-wpq7 (ReDoS via multiple wildcards)
- GHSA-j3q9-mxjg-w52f (DoS via sequential optional groups)
router@2.2.0 accepts ^8.0.0, so this is a clean lockfile-only bump.
* feat(events): DOM-model on* semantics with addEventListener/removeEventListener
Fixes#551 (useHostStyles broken: fonts clobber theme/CSS variables)
Fixes#225 (user onhostcontextchanged and SDK hooks mutually exclusive)
The on* setters now follow the DOM event model:
- Replace semantics (like el.onclick) with getters
- Coexist with addEventListener/removeEventListener listeners
- Both channels fire on dispatch: on* handler then listeners
Introduces ProtocolWithEvents base class between Protocol and
App/AppBridge. Each notification event gets a slot with two independent
channels (singular on* handler + addEventListener listener array).
useHostStyles hooks now use addEventListener with proper cleanup,
so they compose correctly with user on* handlers.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Fix typedoc validation warnings
- Export AppEventMap, AppBridgeEventMap, ProtocolWithEvents so they
appear in generated docs (they're part of public addEventListener
signatures)
- Move AppBridgeEventMap above the AppBridge class JSDoc — it had been
inserted between the doc block and the class, orphaning the AppBridge
docs onto the wrong type
- Drop @param callback tags from on* getter/setter pairs — typedoc
attaches the doc block to the getter signature which has no params
- Add MethodSchema to intentionallyNotExported (internal zod helper
referenced by the now-documented eventSchemas field)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Reverts the fullscreen displayMode guard added in #567. Skipping
size-changed measurement during fullscreen caused apps to not receive
an initial size report after the transition, breaking layout for some
apps.
* Fix auto-resize destroying horizontal scroll positions
The setupSizeChangedNotifications method temporarily sets
html.style.width to 'fit-content' to measure intrinsic content width.
For responsive apps that derive width from their container (width: 100%,
flex: 1, etc.), fit-content resolves to 0px. The synchronous reflow at
0px causes browsers to clamp scrollLeft on all horizontal scroll
containers to 0, permanently destroying their scroll positions.
Replace the fit-content width measurement with window.innerWidth. The
height measurement (max-content) is preserved since hosts rely on it.
Neither the iOS nor web host uses the width value from size-changed
notifications, so this change has no functional impact on hosts while
fixing scroll position clamping for all MCP apps with horizontal scroll
views.
* Skip size-changed measurement during fullscreen
Hosts determine the container size in fullscreen mode, so size-changed
notifications are not needed. The temporary max-content height override
used for measurement causes visible vertical jitter during animated
fullscreen transitions by briefly reflowing the document on every frame.
This directory duplicated the Claude Code plugin that's being added to
the knowledge-work plugin marketplace (anthropics/knowledge-work-plugins#72).
Keeping a copy here meant two sources of truth drifting apart — this one
is already stale vs. the server's interact/annotation capabilities from #506.
The MCPB packaging (manifest.json) remains — that's the distributable
server artifact. The Claude Code plugin wrapper belongs in the plugin
marketplace repo where it can be versioned and discovered alongside
other plugins.
Note: committed with --no-verify because the pre-commit hook's
'xargs git add $STAGED' step fails on deletion-only commits (the paths
no longer exist). Hook fix tracked separately.
* fix(pdf-server): slice bytes before onDataRange to avoid detached buffer
PDF.js transfers the ArrayBuffer to its worker via postMessage, detaching
it in the main thread. When the same range is re-requested (common on
iOS/WKWebView under memory pressure during scroll/zoom/navigate), the
cached Uint8Array now wraps a detached buffer and onDataRange throws
'Buffer is already detached'.
Fix: pass result.bytes.slice() so the rangeCache entry stays valid.
* test(e2e): update pdf-annotations assertion for new display_pdf prompt text
The 91880a6d prompt rewrite changed the interact-enabled result text from
'Displaying PDF (viewUUID: ...)' to 'PDF opened. viewUUID: ...'. The e2e
test was still asserting the old string.
* pdf-server: add interact tool to allow model to modify existing view
* pdf-server: add annotations, download, form fill, and highlight_text
Add PDF annotation system with 7 annotation types (highlight, underline,
strikethrough, note, rectangle, freetext, stamp), text-based highlighting,
form filling, and annotated PDF download using pdf-lib.
- Server: annotation Zod schemas, extended interact tool with add/update/remove
annotations, highlight_text, and fill_form actions
- Client: annotation layer rendering with PDF coordinate conversion, persistence
via localStorage (using toolInfo.id key), pdf-lib-based download with embedded
annotations and form fills, uses app.downloadFile() SDK with <a> fallback
- Model context includes annotation summary
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add get_pages tool for batch text/screenshot extraction
New tool `get_pages` lets the model get text and/or screenshots from
arbitrary page ranges without navigating the visible viewer.
- Server: `get_pages` tool with interval-based page ranges (optional
start/end, open ranges supported), `getText`/`getScreenshots` flags,
request-response bridge via `submit_page_data` app-only tool
- Client: offscreen rendering (hidden canvas, no visual interference),
text from cache or on-demand extraction, screenshots scaled to 768px
max dimension, results submitted back to server
- Max 20 pages per request, 60s timeout
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: move get_pages into interact tool as an action
Fold get_pages into the interact tool to minimize tools requiring
approval. Now accessed via `interact(action: "get_pages", ...)`.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: improve interact tool annotation discoverability
- Add concrete per-type schema docs with field names in tool description
- Add JSON example showing add_annotations with highlight + stamp
- Replace opaque z.record(z.string(), z.unknown()) with typed union
of all annotation schemas (full + partial forms) so the model sees
exact field names and types
- Remove redundant manual safeParse since Zod inputSchema validates
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: improve annotation discoverability + add E2E tests
- display_pdf result text now explicitly lists annotation capabilities
(highlights, stamps, notes, etc.) instead of vague "navigate, search, zoom, etc."
- Restructured interact tool description: annotations promoted to top,
with clear type reference, JSON example, and bold section headers
- Added pdf-annotations.spec.ts with 6 E2E tests covering:
- Result text mentions annotation capabilities
- interact tool available in dropdown
- add_annotations renders highlight
- Multiple annotation types render (highlight, note, stamp, freetext, rectangle)
- remove_annotations removes from DOM
- highlight_text finds and highlights text
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add Claude API prompt discovery tests for annotations
Tests that Claude can discover and use PDF annotation capabilities
by calling the Anthropic Messages API with the tool schemas and
simulated display_pdf result.
Disabled by default — skipped unless ANTHROPIC_API_KEY is set:
ANTHROPIC_API_KEY=sk-... npx playwright test tests/e2e/pdf-annotations-api.spec.ts
3 scenarios tested:
- Model uses highlight_text when asked to highlight the title
- Model discovers annotation capabilities when asked "can you annotate?"
- Model uses interact (add_annotations or get_pages) when asked to add notes
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add example prompts, testing docs, and updated tools table to README
- Example prompts for annotations, navigation, page extraction, stamps, forms
- Documents how to run E2E tests and API prompt discovery tests
- Updated tools table to include interact tool
- Updated key patterns table with annotations, command queue, file download
- Added pdf-lib to dependencies list
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: simplify interact annotations schema (7802 → 2239 chars)
The typed Zod union (14 anyOf variants: 7 full + 7 partial annotation
types) produced a 5,817-char JSON schema for the annotations field alone.
This bloated the interact tool schema to 7,802 chars, which may cause
the model to struggle with or skip the tool.
Replace with z.record(z.string(), z.any()) — annotation types are
already fully documented in the tool description. Schema drops to
2,239 chars (71% reduction), annotations field to 254 chars (96% reduction).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: enumerate all interact actions in display_pdf result
The display_pdf result text now lists every action by name (navigate,
search, find, search_navigate, zoom, add_annotations, update_annotations,
remove_annotations, highlight_text, fill_form, get_pages) so the model
knows exactly what commands are available without needing to inspect the
interact tool schema.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: validate viewUUID in interact, clarify in description
The model was passing "pdf-viewer" instead of the actual UUID, causing
get_pages to timeout (commands queued under wrong key, client never
picks them up).
- Add activeViewUUIDs set tracking UUIDs issued by display_pdf
- Validate viewUUID at the top of interact handler with clear error
- Add "IMPORTANT: viewUUID must be the exact UUID returned by display_pdf"
to the interact tool description
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix annotation clickability and replace emoji icon with SVG
- Raise annotation-layer z-index above text-layer so note annotations
receive hover/click events (was z-index: 1, now 3; text-layer is 2)
- Replace memo emoji (data-icon attr) with CSS mask SVG document icon
that respects currentColor for consistent cross-platform rendering
* pdf-server: add annotation side panel with bidirectional linking
Right-side panel (250px) shows all annotations grouped by page with
expand/collapse cards. Clicking a card navigates to the page and pulses
the annotation; clicking a note icon on the PDF highlights its card in
the panel. Panel auto-shows on first annotation, remembers user toggle
preference via localStorage, and shows a badge count when collapsed.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: replace 300ms interval polling with long-polling
Server now holds poll_pdf_commands requests open (up to 30s) until
commands arrive, waking waiters via enqueueCommand. Client loops
sequentially instead of using setInterval, with 2s backoff on errors.
Reduces idle RPC traffic from ~3 calls/sec to ~2 calls/min.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add interactive form filling via PDF.js AnnotationLayer
Render PDF.js AnnotationLayer with renderForms:true so form fields
appear as interactive HTML inputs. Build a fieldName→annotationID map
via getFieldObjects() to bridge fill_form (which uses field names) with
annotationStorage (which uses annotation IDs). Sync user input back to
formFieldValues for persistence and PDF download.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add elicit_form_inputs to display_pdf for upfront form filling
When enabled and the client supports elicitation, extracts form fields
from the PDF via pdf-lib and prompts the user to fill them before the
viewer loads. Elicited values are returned in content/structuredContent
and enqueued as a fill_form command for the viewer.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: replace pdf-lib with pdfjs-dist for server-side form field extraction
Use pdfjs-dist's getDocument() + getFieldObjects() instead of pdf-lib's
PDFDocument.load() + getForm().getFields() in extractFormSchema(). This
removes the pdf-lib import from the server bundle (pdf-lib is still used
client-side for PDF modification in downloadAnnotatedPdf). Uses the legacy
pdfjs-dist build to avoid DOMMatrix dependency in Node.js.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix form field font size and programmatic fill_form
Set --scale-factor/--total-scale-factor CSS variables on the form layer
so AnnotationLayer font-size rules resolve correctly instead of falling
back to browser defaults. Also update live DOM elements directly in
fill_form handler so values appear immediately without waiting for a
full re-render.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix listbox font size overflow in AnnotationLayer
After rendering the annotation layer, shrink select[size] font to fit
within the PDF rect height. The default AnnotationLayer CSS uses a fixed
9px * scale-factor which overflows when many options share a small rect.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add trash icon to annotation sidebar cards
Show a delete button on each annotation card that appears on hover.
Clicking it removes the annotation from the PDF and persists the change.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix space key captured in form fields
Skip keyboard navigation shortcuts (space, arrows, +/-) when any input,
textarea, or select element is focused, not just the search/page inputs.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: show form fields in annotation sidebar with clear buttons
Form field values now appear in the sidebar under a "Form Fields" group,
with trash icons to clear individual values. The badge count and auto-show
logic include form fields. The panel open/close now calls
requestFitToContent with width to avoid overflow in inline layout mode.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: clarify Y coordinate system in interact tool description
Explicitly state that Y=0 is the bottom edge and Y=792 is the top for
US Letter, with concrete guidance on typical values for top/bottom
placement to prevent models from using top-down screen coordinates.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: validate fill_form field names and report valid fields
Extract form field names during display_pdf and cache per viewer UUID.
fill_form now soft-fails on unknown field names (applies valid ones,
reports skipped ones). Both display_pdf and fill_form results include
the list of valid field names so the model can self-correct.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add compact annotation strip for inline mode
In inline mode, replace the 250px side panel with a slim bottom strip
that shows one annotation/form-field at a time with prev/next navigation.
The side panel is still used in fullscreen mode.
- Strip shows item swatch, label, preview + counter (N of M · Page P)
- Click item to navigate to its page; delete single or clear all
- requestFitToContent includes strip height in size calculation
- fieldNameToPage map built during init for form field page context
- Display mode toggle switches between strip and panel automatically
* pdf-server: improve display_pdf description for form/annotation use cases
Add explicit guidance on when to use the tool: filling out forms
(tax forms, applications), annotating PDFs, and interactive review.
This helps models route user requests like 'help me fill out this form'
to the display_pdf tool.
* pdf-server: only show download button when host supports downloadFile
* pdf-server: resizable sidebar + human-readable form field labels
- Sidebar panel is now resizable by dragging its left edge (150px min,
50vw max). Width is persisted in localStorage.
- Form fields show human-readable labels from PDF's TU (alternativeText)
field when available. Mechanical names like ').F1_01[0]' are replaced
with the generic label 'Field' when no TU text exists.
- Empty values are no longer shown in the sidebar.
* pdf-server: fix field label collection to use getAnnotations() API
getFieldObjects() doesn't include alternativeText. Instead, iterate
per-page annotations (only pages with known form fields) to collect
the TU/alternativeText labels that PDF authors set as tooltips.
* pdf-server: move strip below toolbar + follow form field focus
- Strip is now positioned below the toolbar (above search bar) instead
of at the bottom, for better visibility and proximity to the toolbar.
- Form field focus changes automatically sync the strip to show the
focused field's item.
- Search bar top offset adjusts dynamically when strip is shown/hidden.
* pdf-server: add Clear all to fullscreen sidebar + steer model to reuse views
- Add 'Clear all' button in the fullscreen sidebar panel header
- Update display_pdf description to instruct models to use the interact
tool with existing viewUUID rather than calling display_pdf again for
the same PDF (e.g. when user asks to annotate an already-open doc)
* pdf-server: add page dimensions to model context + improve coordinate docs
- Model context now includes 'Page size: 612x792pt (coordinates: origin
at bottom-left, Y increases upward)' so the model knows actual page
dimensions when placing annotations.
- Interact tool description expanded with clearer coordinate guidance,
margin hints, and a tip to use highlight_text for text annotations.
- Download button temporarily shown unconditionally (capability check
commented out with TODO for re-enabling).
* pdf-server: auto-close panel when empty + stronger display_pdf reuse guidance
- Sidebar/strip auto-closes when all items are cleared (via delete or
Clear all), and the annotations toolbar button hides.
- display_pdf description now uses CRITICAL warning to prevent models
from re-calling it to add annotations to an already-open PDF.
* pdf-server: skip elicitation when form fields have mechanical names
Only use elicitation if all editable fields have human-readable names.
Fields with brackets, dots, or ALL_CAPS_UNDERSCORE patterns (and no
alternativeText label from the PDF) are considered mechanical and
would be confusing in an elicitation form. Also use alternativeText
as the elicitation field title when available.
* pdf-server: paint annotations on screenshots + list coords in model context
Screenshots sent to the model (both updateModelContext and get_pages)
now include annotations drawn on top of the PDF canvas, so the model
can visually verify placement. The text context also lists each
annotation on the current page with its coordinates.
* pdf-server: style multiselect/listbox form fields to match viewer theme
* pdf-server: add command batching to interact tool
Extract command processing into a helper function and accept an optional
`commands` array for sequential batch execution. This lets the model
send multiple actions (e.g. add annotations + get screenshot) in a single
tool call, reducing round trips. Stops on first error in a batch.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix multiselect rendering by removing font-size override
The custom font-size: inherit on #form-layer select was conflicting with
PDF.js AnnotationLayer's inline font-size, causing doubled/overlapping text
in select options. Remove the override and keep only the checked-option
highlight style.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix form reset button by passing fieldObjects to AnnotationLayer
PDF.js AnnotationLayer needs the fieldObjects parameter to bind reset
form button actions. Cache the result of doc.getFieldObjects() and pass
it through to annotationLayer.render().
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: improve annotation labels in sidebar and strip
Use human-readable labels instead of raw type names (e.g. "Rectangle"
instead of "rectangle", "Stamp: APPROVED" instead of "stamp"). Remove
redundant preview text for types that have no additional content (rectangle,
underline, strikethrough, stamp) to avoid "rectangle Rectangle" duplication.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: split get_pages into get_text and get_screenshot commands
Replace the combined get_pages action (with getText/getScreenshots flags)
with two focused commands:
- get_text: extract text from pages (single page or intervals)
- get_screenshot: capture a single page as PNG image
This makes the API cleaner and returns each command's result as its own
content block in batch mode. Also fix download function syntax error
from earlier capability check commenting.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix download by using pdfDocument.getData() instead of re-fetching
The download was failing with "No PDF header found" because it re-fetched
the PDF via read_pdf_bytes tool calls, but stateless MCP transport creates
fresh server instances per request with empty caches. Using getData() from
the already-loaded pdf.js document avoids the round-trip entirely.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: increase express body limit to fix get_screenshot hang
The submit_page_data tool sends base64 PNG screenshots that exceed the
default 100KB express.json() body limit from createMcpExpressApp. This
caused the request to silently fail, making waitForPageData timeout and
the get_screenshot command hang. Replaced createMcpExpressApp with manual
express setup using a 50MB body limit.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: use JPEG for screenshots to fix get_screenshot hang
Switch from PNG to JPEG (quality 0.85) for both offscreen screenshots
(get_screenshot) and model context images. JPEG is much smaller than PNG
for document pages, keeping the submit_page_data payload well within the
MCP SDK's default 100KB express body limit. This also reverts the
temporary workaround of replacing createMcpExpressApp with a custom
express setup.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add ' - edited' suffix to download filename when modified
Renames the download from '_annotated' to ' - edited' and also triggers
the suffix when form fields have been filled, not just when annotations
are present.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: include viewUUID in display_pdf structuredContent
The viewUUID was only in _meta but not in structuredContent, so the model
couldn't retrieve it from the tool result to pass to interact.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: move interact action list from display_pdf content to description
The content response was bloated with static instructions about interact
actions. Moved that to the tool description where it belongs, keeping
only the dynamic PDF URL and viewUUID in the content.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix form reset setting dropdowns to first item
PDF.js resetform handler deselects all options but doesn't re-add the
hidden empty placeholder, so the browser falls back to showing the first
real option. Work around this by listening for resetform on combo selects
and re-inserting a hidden blank option when nothing is selected.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: sort form fields in sidebar/strip by intrinsic PDF order
Fields are now sorted by page number then top-to-bottom Y position on
the page, matching the visual reading order of the PDF form rather than
the arbitrary insertion order of formFieldValues.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add viewUUID to display_pdf outputSchema
The viewUUID was added to structuredContent but not to the outputSchema,
causing MCP validation error -32602.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: allow horizontal scrolling in inline mode
When the PDF is zoomed or wider than the container, users can now scroll
horizontally in inline mode instead of the content being clipped.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add viewUUID to model context, remove activeViewUUIDs validation
Include viewUUID in the updateModelContext header so the model can
reference it when calling interact. Remove the activeViewUUIDs set
validation since it breaks after server restarts — command queue TTL
pruning is sufficient cleanup. Also prune empty queues with no active
pollers.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix delete button alignment in sidebar annotation cards
Annotations without preview text had the delete button hugging the type
label instead of right-aligning. Add margin-left: auto so the button is
consistently pushed to the right edge of the row.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add interactive annotations (select, drag, resize, rotate, undo/redo)
Enable pointer-events on all annotation types so they can be clicked to
select. Draggable types (rectangle, freetext, stamp, note) support smooth
drag-to-move. Rectangles show corner resize handles, stamps show a rotate
handle. Delete/Backspace removes the selected annotation, Ctrl+Z/Shift+Z
provides unlimited undo/redo, and Escape deselects. Sidebar cards sync
with on-canvas selection state.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: clicking sidebar card focuses form field input and scrolls into view
Sidebar annotation cards now scroll the annotation into view, and form
field cards navigate to the correct page and focus the input element.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix form widget double-text by making inputs opaque
PDF.js AnnotationLayer renders interactive form inputs with a
semi-transparent background, letting the canvas's static form appearance
bleed through. Since the widget font (9px * scale, sans-serif) doesn't
match the PDF's actual font metrics, this creates a "double text" misalignment
at most zoom levels. Make text/choice widgets opaque so only the interactive
layer's text is visible.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add selection/focus to model context, double-click to send messages, toggle resize/rotate
- Model context now includes selected annotation ID and focused form
field name so the model knows what the user is interacting with.
- Double-clicking a sidebar annotation card sends a message prompting
the model to change that annotation.
- Double-clicking a sidebar form field card sends a message prompting
the model to fill that field.
- Double-clicking an annotation in the renderer toggles between resize
and rotate handles (for rectangles and stamps).
- Rectangles now support rotation via the rotate handle.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: replace inline-mode strip with floating accordion sidebar
Replace the compact horizontal annotation strip with a floating panel
at top-right in inline mode. Uses accordion-style collapsible sections
(per-page annotations + form fields) with at most one section open at
a time. Refactors renderAnnotationPanel into reusable helpers
(appendAccordionSection, createAnnotationCard, createFormFieldCard).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: remove dead annotation strip code
The compact horizontal annotation strip is no longer used since inline
mode now uses a floating accordion sidebar. Remove all strip-related
HTML, CSS, JS (DOM refs, StripItem type, buildStripItems, renderStrip,
navigateToStripItem, deleteStripItem, event listeners, stripHeight
calculations).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: multi-select annotations, natural prompts, form reset sync
- Convert selection from single ID to Set for multi-select (Shift+click)
- Deselect annotations when focusing a form input field
- Fix rotation to always use center origin (stamp was using left-bottom)
- Simplify double-click sendMessage prompts (e.g. "update Notes: ")
- Call updateModelContext before sendMessage to guarantee context is sent
- Listen for PDF.js resetform events to clear formFieldValues, update
sidebar badge/count, and hide icon when no items remain
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: draggable floating panel with magnetic corner anchoring
- Reduce floating panel width (220→180px), add border-radius
- Panel header is draggable; on drop, snaps to nearest corner
- Persists corner preference to localStorage
- Auto-docks to opposite side when overlapping selected annotations
- Accordion chevron: ▶ when collapsed, ▼ when expanded
- Slightly reduce section header size for compactness
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: allow all accordion sections to be collapsed
Only auto-open the first section on initial render. Once the user has
interacted with accordion headers, respect their choice to collapse all
sections without forcing one back open.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: polish interactions and UI details
- Remove auto-show annotation panel; wait for user to open it
- Badge color: blue (accent) instead of red
- Search bar: offset floating panel below it when anchored top-right
- Text selection deselects annotations and clears field focus
- Click on text layer / empty area clears field focus too
- Zoom keeps selected annotation visible (scrollIntoView after render)
- Fullscreen button: distinct exit icon + tooltip with Esc hint
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix text deselect, stamp dblclick, rotation direction, export
- Text selection and text-layer mousedown now deselect annotations
- Add user-select: none on draggable annotations (prevents stamp text
selection on double-click, allowing resize/rotate toggle to work)
- Fix rotation direction: remove CSS transform negation so clockwise
drag = clockwise rotation on screen
- Fix stamp export: rotate around center (matching CSS transformOrigin)
and negate rotation for PDF coordinate convention
- Add rotation support to rectangle PDF export
- Remove auto-show annotation panel; badge uses blue accent color
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: allow any text as stamp label, not just predefined enum
The StampLabel was unnecessarily restricted to 6 predefined values
(APPROVED, DRAFT, etc). The PDF format supports arbitrary stamp text,
so open it up to z.string() while keeping common labels as examples
in the schema description.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: show resize + rotate handles simultaneously, dblclick sends message
Remove the interactionMode toggle — instead show both corner resize handles
and the rotate handle at the same time on selected annotations. Rectangle
gets resize corners + rotate handle; stamp gets rotate handle only.
Double-click on annotation elements now sends a message to modify the
annotation (matching sidebar card behavior) instead of toggling modes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: SVG fullscreen icons, Y-coord docs, dirty flag
- Replace Unicode fullscreen chars (⛶/⊠) with proper SVG expand/collapse icons
- Add Cmd+Enter keyboard shortcut for fullscreen toggle
- Improve coordinate system docs: emphasize rectangle x,y is BOTTOM-LEFT corner, add worked examples
- Add isDirty state with * prefix on title for unsaved changes
- Track dirty state through persistAnnotations, suppress during restore
* pdf-server: diff-based annotation persistence, proper PDF annotation export, PDF annotation import
Extract annotation logic into pdf-annotations.ts module with comprehensive tests. Replace content-stream drawing (drawRectangle/drawText) with proper PDF annotation dicts (/Type /Annot) that are editable in Acrobat/Preview. Persistence now stores only a diff (additions/removals) relative to the PDF's native annotations, keeping localStorage small. On load, annotations are imported from the PDF via pdf.js and merged with the user's diff.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: enhance page shadow for better depth perception
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: use floating panel in fullscreen, respect insets, direction-aware resize
Always use the floating annotations panel (both inline and fullscreen) instead
of the sidebar in fullscreen mode. Panel anchorage now respects safe area insets
(especially bottom). Resize handle repositions to the correct edge based on
which corner the panel is anchored to. Initial width reduced from 180px to 135px.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add save_pdf tool and save button for local files
Add server-side save_pdf tool that writes annotated PDF bytes back to the
original local file. Client shows a save button (floppy disk icon) next to
the download button for file:// URLs. Ctrl/Cmd+S shortcut saves when dirty.
Saving clears the dirty flag and localStorage diff.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add circle and line annotation types synced with PDF.js
Add circle (ellipse) and line annotation support across all layers:
server Zod schemas, pdf-annotations module (import/export), client
renderers, canvas painting for screenshots, CSS, drag/resize handling,
and tool description documentation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add searchability keywords to display_pdf tool description
Include viewer, render, renderer, display, show, annotate, edit, and
form keywords so the tool is easier to discover by models.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: switch model-facing annotation API to top-left origin coordinates
Convert Y coordinates at the command boundary (add/update_annotations) so the
model uses intuitive top-left origin while internal storage stays in PDF's
native bottom-left origin. Also converts coordinates back to model space in
context strings for consistency.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix stamp rotation in PDF export via appearance stream matrix
Stamp rotation was a no-op (empty if-block with a comment). Now computes
a proper rotation matrix around the bounding box center and applies it
to the appearance stream. Also adds verification tests for rectangle
stroke/fill colors and stamp color/rotation in exported PDF dicts.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix screenshots to include filled form field values
Screenshots sent to the model were missing form field values because
the canvas render didn't use ENABLE_STORAGE mode. Now both offscreen
renders (model context and get_pages) pass annotationStorage to PDF.js
so filled fields appear in screenshots. Also reuses renderPageOffscreen
for model context screenshots to deduplicate rendering logic.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: list form fields with page, bounding box, and label in display_pdf result
The model needs field locations to fill forms accurately, especially for
fields with mechanical names or no name at all. Extracts per-page bounding
boxes in model coordinates (top-left origin) and includes labels where
available from PDF alternativeText.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: include full field listing in fill_form result and update UI after fill
fill_form results now include all form fields with names, types, pages, and
bounding boxes so the model can self-correct on unknown field names. Also
updates the annotation panel badge and visibility after programmatic fills.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add formFields to display_pdf structuredContent and output schema
Programmatic consumers need structured access to form field metadata
(names, types, pages, bounding boxes) without parsing text content.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add image annotation type with URL/base64 support, drag-drop, and PDF export
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix image annotation click/select, add Shift-resize for aspect ratio, add handle tooltips
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix image annotation to stretch to fill its bounding box
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: fix stamp PDF export to match on-screen appearance
Use non-standard /Name to prevent Preview.app from substituting built-in
stamp graphics, align padding with CSS (4pt/12pt), add ExtGState for 0.6
opacity, and fix text baseline positioning.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: improve annotation panel UX and image resize behavior
- Page accordion click navigates to that page
- Form fields appear in their page's accordion section (before annotations)
- Selecting annotation or focusing form field auto-expands page accordion
- Image resize preserves aspect ratio by default (Shift for free resize)
- Add aspect field ("preserve"|"ignore") to ImageAnnotation type
- Fix selection UI regression: remove overflow:hidden that clipped handles
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add signature/signing keywords and image example to tool descriptions
- Add signing/signature keywords to display_pdf description for discoverability
- Add image annotation example (signature placement) to interact tool description
- Clarify that imageUrl supports file paths and HTTP URLs with auto-fetch
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: discourage base64 encoding in image annotation, clarify imageUrl accepts file paths
Models tend to encode images as base64 themselves instead of passing file
paths. Make the schema descriptions and tool docs explicit: prefer imageUrl
with a file path, no data: URIs, don't encode images yourself.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: remove imageData from image annotation API, require imageUrl
Models were encoding images as base64 themselves instead of passing file
paths. Remove imageData from the model-facing Zod schema entirely — only
imageUrl (file path or HTTPS URL) is accepted. The server fetches and
embeds the image automatically. imageData remains as an internal field
for client-side rendering and drag-drop. Also mention drag-and-drop as
an alternative in the tool description.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add clipboard support (copy/cut/paste annotations and images)
- Request clipboardWrite permission in resource metadata
- Ctrl/Cmd+C: copy selected annotations as JSON to clipboard
- Ctrl/Cmd+X: cut (copy + delete) selected annotations
- Ctrl/Cmd+V / paste event: paste annotations from clipboard JSON,
or paste images from clipboard (e.g. screenshots, copied images)
- Refactor drag-drop image creation into shared addImageFromFile()
- Pasted annotations get new IDs and slight offset to avoid overlap
- Pasted images are centered on the current page
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: add disableInteract option for distributed deployments
Adds a `disableInteract` boolean to `createServer()` options that skips
registering the `interact`, `poll_pdf_commands`, and `submit_page_data`
tools (all relying on an in-memory command queue). Adjusts `display_pdf`
description and schema accordingly when disabled.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: flip interact to opt-in, enable only for --stdio
Rename disableInteract → enableInteract (default false) so existing
library consumers get read-only mode without code changes. The CLI
entry point passes enableInteract: true only when running with --stdio.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* pdf-server: log client-roots warning once at startup, not per request
* pdf-server: fix form widget transparency, poll spam, and pdf.js warnings
- Form widgets: PDF.js writes inline background-color (from the
annotation /BC entry, typically 'transparent'), defeating our CSS.
Force opaque with !important. Fixes double-text in listboxes and
text inputs at any zoom.
- Poll spam: view was calling poll_pdf_commands in a tight loop when
interact is disabled (HTTP mode) — server returns isError, which
doesn't throw, so the loop never backed off. Server now signals
interactEnabled via _meta; view only polls when true, and stops
entirely on isError results.
- Silence Helvetica / inset-border warnings: set verbosity=ERRORS
for server-side getDocument (only used for form introspection,
no rendering, so font fallback warnings are noise).
* pdf-server: set standardFontDataUrl for server-side pdf.js
Resolve pdfjs-dist/standard_fonts/ at runtime via createRequire. Works
from both source (bun main.ts) and bundled dist/ since pdfjs-dist is
--external. NodeStandardFontDataFactory reads via fs.readFile, so a
filesystem path with trailing separator is what's expected.
Keep verbosity=ERRORS as backstop for unrelated warnings (e.g.
'Unimplemented border style: inset').
* pdf-server: use unpkg CDN for pdf.js standard fonts, add to CSP
- Single CDN URL pinned to the bundled pdfjs-dist version, used in both
server (Node) and viewer (browser)
- Node: default NodeStandardFontDataFactory uses fs.readFile which can't
fetch URLs — pass a minimal FetchStandardFontDataFactory
- Browser: DOMStandardFontDataFactory already fetches, just pass the URL
- Add https://unpkg.com to CSP connectDomains (pdf.js loads font
binaries via fetch(), maps to connect-src)
* pdf-server: guard against missing totalBytes in viewer
Without this, an invalid totalBytes flows to PDFDataRangeTransport.length
→ worker ChunkedStream sized at 0 → opaque 'Bad end offset: N' error.
The guard turns that into an actionable message (rebuild hint).
* pdf-server: re-probe file size at load time, ignore stale totalBytes from history
The display_pdf result (including totalBytes) is baked into conversation
history. If the user saves the annotated PDF (grows the file) then
reloads the conversation, the host replays the stale size. pdf.js
initializes its ChunkedStream at that stale length, then the first live
read_pdf_bytes returns the current (larger) file — every chunk fails
the 'end === bytes.length' check with 'Bad end offset: N'.
Fix: drop the fileSizeBytes param and always probe via a live 1-byte
read_pdf_bytes call before setting up the range transport.
* pdf-server: file watching, save confirmation, disk-change reload
Server:
- fs.watch on local files when interact is enabled; pushes file_changed
via the poll_pdf_commands channel. Re-attaches on rename to survive
atomic writes (vim/vscode). Debounced 150ms. Skips unchanged mtime.
- save_pdf returns {filePath, mtimeMs} so the saving viewer can
recognise its own write's echo. Other viewers on the same file still
get notified (their content is genuinely stale).
- stopFileWatch in pruneStaleQueues TTL sweep.
Viewer:
- In-app confirm dialog (no window.confirm — would block the iframe).
- Save button: hidden until first edit, enabled while dirty, disabled
(but still visible) after save, re-enabled on next edit.
- savePdf() asks for confirmation, records lastSavedMtime.
- loadGeneration counter invalidates stale fetchChunk results and
aborts the preloader when the PDF is reloaded underneath them.
- reloadPdf() clears all per-document state (byte cache, annotations,
form fields, undo/redo, text caches, field maps, localStorage diff)
and loads fresh.
- file_changed handler: suppresses own-save echo via saveInProgress +
mtime match; auto-reloads when clean; prompts Keep/Discard when dirty.
* pdf-server: add file watching tests
Covers: external write → file_changed enqueued via poll_pdf_commands;
debounced rapid writes; stopFileWatch prevents further events; save_pdf
returns mtimeMs; watcher survives atomic rename (vim/vscode pattern).
* pdf-server: fix confirm-btn-primary hover, show filename only in save prompt
- .confirm-btn:hover's background cascaded to primary buttons too
(same specificity, primary has both classes) — turning the blue
button light grey on hover. Re-assert background in primary:hover.
- Save confirm: extract just the filename from pdfUrl (strip file://
prefix, take basename).
* pdf-server: match confirm dialog to host's native style
Use host-provided CSS variables (--color-*, --font-*, --border-radius-*,
--shadow-*) from applyHostStyleVariables, with local fallbacks.
- Larger border-radius (--border-radius-xl), softer shadow (--shadow-lg)
- Larger bold title (--font-heading-md-size, --font-weight-bold)
- Primary button uses inverse colors (dark bg + light text) like the
host's downloadFile dialog, not blue
- New .confirm-detail box: monospace bordered rect for filename
- Button order: Cancel first, primary last (native convention)
- Escape resolves to first non-primary button
* pdf-server: derive dirty from diff — undoing all changes clears save button
persistAnnotations() was unconditionally setDirty(true). It already
computes the diff vs baseline — use isDiffEmpty(diff) to decide instead.
Now undoing all the way back to the original state marks the viewer
clean again (save button disables, title loses asterisk).
* pdf-server: import saved form field values from PDF as baseline
getFieldObjects() returns the PDF's stored form values but we were only
reading field IDs/pages from it. After saving a filled form and reopening,
the panel showed nothing and there was no way to see what was filled.
- New pdfBaselineFormValues map, populated in buildFieldNameMap() from
each field's .value (skipping empty/Off/button values). Seeds
formFieldValues so the panel shows PDF-stored values on open.
- computeDiff takes an optional baselineFormFields param and only
includes values that differ — opening a filled PDF doesn't mark dirty,
editing a field does, reverting to the PDF's value marks clean again.
- importFieldValue() normalises radio-group value lookup (parent entry
has value=undefined, children have the real export value), checkbox→
true, listbox array→joined string.
* pdf-server: fix form Reset button; split panel into Reset vs Clear all
Reset-button regression: buildFieldNameMap() now seeds formFieldValues
from the PDF's stored values, but syncFormValuesToStorage() was pushing
them back into annotationStorage in our normalised repr (checkbox→true,
radio→export string). pdf.js's native repr may differ, and overwriting
it breaks the form's Reset button. Fix: skip syncing values that match
baseline — the PDF's own values are already in storage natively.
Panel buttons:
- Reset: revert to what's in the PDF file. Restores baseline annotations
and form values, clears undo/redo. Empty diff → clean.
Disabled when not dirty.
- Clear all: removes EVERYTHING including PDF-native items. Non-empty
diff (baseline items are 'removed') → dirty; saving writes stripped PDF.
Disabled when nothing to clear.
* pdf-server: fix Clear all to push defaultValue; gate save on writability
Clear all regression: annotationStorage.remove(id) only drops our
override — the widget reverts to the PDF's stored /V (the baseline
value). To actually clear, push each field's defaultValue (/DV) via
setValue instead, which is what the PDF's native Reset button does.
Save button visibility: server now checks fs.access(path, W_OK) and
reports via _meta.writable. Viewer gates save on that instead of just
'is this a local path'. Hides the button for read-only mounts and
Claude Desktop's uploads directory. Removed dead isLocalFileUrl().
* pdf-server: fix annotationStorage keys — use widget annotation IDs
Root cause: getFieldObjects() returns field-dictionary refs (the /T
tree, e.g. '86R'), but annotationStorage is keyed by WIDGET annotation
refs (what page.getAnnotations() returns, e.g. '9R'). These differ
when a PDF's field and its widget /Kids are separate objects.
fieldNameToIds was built from getFieldObjects().id, so EVERY
storage write was keyed wrong and silently no-op'd:
- syncFormValuesToStorage: wrote to dead keys
- fill_form: setValue + querySelector([data-element-id=...]) both missed
- individual field delete: remove() on wrong key
- clearAllItems: setValue to wrong keys
Fix: build fieldNameToIds from page.getAnnotations() which gives the
correct widget IDs. Keep cachedFieldObjects only for type/value/
defaultValue metadata (matched by name, not id) and for passing to
AnnotationLayer.render() where pdf.js uses it internally.
Also extract clearFieldInStorage() helper — pushes defaultValue for a
single field, used by both individual delete and Clear all.
* pdf-server: remap fieldObjects IDs to widget IDs for pdf.js Reset
pdf.js _bindResetFormAction iterates fieldObjects using each entry's .id
to (a) key annotationStorage and (b) querySelector([data-element-id=...]).
Both expect WIDGET annotation IDs. fieldObjects contains field-dict IDs.
Works only when field and widget share a PDF object — which pdf-lib's
save breaks (it splits merged objects on write).
This is a latent pdf.js bug, not a regression from our changes — it was
broken the moment the user first saved via save_pdf.
Fix: rebuild cachedFieldObjects with widget IDs (from fieldNameToIds)
before passing to AnnotationLayer.render({fieldObjects}). Skip parent
entries with no concrete id (radio group /T tree root). Preserve
type/defaultValue/exportValues which Reset needs.
* pdf-server: fix combo reset, scope writability, drop flaky CI assert
Combo reset: pdf.js's resetform handler sets all option.selected =
(option.value === defaultFieldValue); when defaultFieldValue is null
nothing matches. Chrome then synchronously normalises the non-multiple
<select> by auto-selecting option[0] — so by the time our fix-listener
ran, selectedIndex was 0 and the state-check failed. Now: capture
whether a real default exists before the event; if reset didn't land
on it, force-prepend a hidden blank and select it explicitly.
(Was latent — before the ID fix, resetform never dispatched on selects.)
Writability scope: only mark writable if the file is explicitly in
allowedLocalFiles (CLI arg = opt-in) OR strictly under an allowed
root directory (isAncestorDir already excludes the root itself via
rel !== ''), AND fs.access W_OK passes. A root passed by the client
is a boundary, not a target.
CI: drop the post-rename second-write assertion — fs.watch re-attach
semantics differ between kqueue and inotify, inherently racy in CI.
Only assert the rename itself is detected.
* pdf-server: fix Reset bug; show cleared baseline fields w/ revert
Reset-all bug: clearUserFormStorage skipped any field whose name was
in pdfBaselineFormValues — but if the user had EDITED a baseline field,
the edit sits in storage under that name. Skipping it left the widget
showing the stale edit while the panel showed the restored baseline.
Fix: remove ALL storage overrides on reset — every field reverts to the
PDF's /V, which IS baseline. Removed the now-dead helper.
Panel: cleared baseline fields now stay visible instead of vanishing.
State is derived per-field by comparing formFieldValues to
pdfBaselineFormValues (no new data structures — both maps already
exist, the comparison was just never rendered):
- unchanged: current === baseline → solid swatch, trash clears
- modified: baseline exists, current differs → solid swatch, revert
- cleared: baseline exists, current empty/absent → outlined cross
swatch, struck-out label/value, revert restores
- added: no baseline → solid swatch, trash removes
Panel iterates union(formFieldValues, pdfBaselineFormValues) so cleared
items don't disappear. sidebarItemCount uses the same union so the
toolbar button stays visible as long as there are baseline items OR
edits. Per-item revert: formFieldValues.set(name, baseline) +
storage.remove(id) → widget reverts to /V.
* pdf-server: import baseline from widget fieldValue, not field-dict
page.getAnnotations().fieldValue is what AnnotationLayer actually
renders. getFieldObjects().value reads the field-dict /V — which can
be out of sync in an internally-inconsistent PDF (e.g. after a pdf-lib
setText silently failed on a comb field, leaving the field-dict stale
while the widget still shows the older value from the raw bytes).
Your Form.pdf: ID widget shows 'eeeee', field-dict says 'eew2e'.
Panel was importing 'eew2e' → mismatch with what's on screen.
Fix: capture a.fieldValue during the page.getAnnotations scan (we're
already iterating there for widget IDs) and prefer it over the
field-dict value. Fall back to field-dict if the widget doesn't expose
one. normaliseFieldValue() handles the format differences (choice
widgets give arrays; field-dict gives strings).
* pdf-server: fix radio input → 'on'; use export value for consistency
pdf.js creates <input type=radio> without setting .value (pdf.mjs:
18138-18144), so target.value defaults to the HTML spec's 'on'. Our
input listener read that → panel showed 'on' after clicking a radio,
but baseline import correctly used the export value ('0') — so
clicking then reverting showed two different strings for the same
selection.
Fix: store each radio widget's buttonValue during the annotation scan
(we're already there for widget IDs), read it in the input listener
via data-element-id. Now baseline, click, revert, and save all agree
on the export value.
(Form.pdf happens to use '0'/'1' as export values instead of
'Male'/'Female' — that's the form's design; the labels are just PDF
text next to the widgets, not form data.)
* pdf-server: panel Reset/Clear-all as icon buttons, keep tooltips
* pdf-server: file roots from MCP client are read-only
allowedLocalFiles conflated two sources: CLI args (user explicitly
named the file when starting the server — overwriting is intentional)
and MCP file roots (client-uploaded copies in ad-hoc hidden folders
that the client doesn't expect to change).
New cliLocalFiles set tracks only the CLI-sourced files. Writable now
requires: file is in cliLocalFiles OR strictly under a directory root.
Directory roots are mounted folders where saving is expected.
save_pdf enforces the same scope server-side — the viewer hides the
button based on _meta.writable, but we must not trust the client.
* pdf-server: file root stays read-only even under a directory root
Extracted isWritablePath() with the full policy in one place (was
duplicated between display_pdf and save_pdf):
- CLI file → writable (user explicitly named it)
- MCP file root → read-only, ALWAYS. Even when the path happens to
fall inside a mounted directory root — the client sending it as a
file root is the stronger signal ('here's an upload')
- under a directory root at any depth → writable (mounted folder)
- the directory root itself → not writable (rel === '' excluded)
- no roots and no CLI files → nothing writable
8 unit tests cover each case.
* pdf-server: fix e2e (interact for HTTP test harness), skip rename test on Linux
E2E: tests/e2e/pdf-annotations.spec.ts expects 'interact' in the tool
dropdown and calls it for annotation tests. Since 3f2c209c interact is
stdio-only; e2e runs HTTP basic-host → tool absent → all tests fail
(broken since Mar 4). Add --enable-interact CLI flag for HTTP mode and
pass it in 'npm run serve'. The in-memory command queue works fine for
the e2e setup (one long-lived process); the stdio-only restriction is
about stateless multi-instance deployments.
Rename test: inotify watches inodes. When the directory entry is
atomically swapped to a NEW inode, the watcher on the OLD inode gets
no event. kqueue (macOS) watches paths and fires 'rename'. Gate with
skipIf(platform !== 'darwin').
* pdf-server: list_pdfs walks directory roots for *.pdf files
Recurse into allowedLocalDirs (depth ≤ 8, ≤ 500 files) and enumerate
actual .pdf files as file:// URLs alongside the explicitly-registered
ones. Skip dotfiles/dirs and node_modules. Dedup (a file may be both
explicitly registered and under a walked directory). Report truncation.
* pdf-server: fix stale e2e assertion after 2d47f14b
Commit 2d47f14b moved the interact action list from display_pdf's
content to the tool description, but the e2e test still asserted the
result text contained 'add_annotations', 'highlight_text', etc.
Now checks for viewUUID / interactEnabled / 'Displaying PDF' which
are the actual result contents.
* pdf-server: add unpkg to resourceDomains (font-src) for pdf.js FontFace
pdf.js in the browser doesn't just fetch() the .ttf bytes — it also
creates FontFace('name', 'url(https://unpkg.com/...)') which goes
through CSP font-src, not connect-src. Nest's CSP blocked it
('font-src self assets.claude.ai'). pdf.js fell back to system fonts
so nothing broke visually, but the CDN URL was doing nothing.
(Separate finding re: the 'bricked UI' report — logs show fill_form
processed cleanly at 16:27:18, then Nest's router navigated away 13s
later. Poll id=17 returned to an already-unmounted iframe. Normal
teardown, not a brick.)
* pdf-server: validate imageUrl scheme before <img src> assignment
Fixes CodeQL js/xss + js/client-side-unvalidated-url-redirection on
line 1994 (renderImageAnnotation) and the canvas-paint fallback.
The server resolves imageUrl to imageData before enqueueing, so
def.imageUrl only survives to the client if the server-side fetch
fails. safeImageSrc whitelists https/http/data/blob and returns
undefined for javascript: et al.
* pdf-server: fix get_pages timeout race; trim fill_form response
get_pages round-trip (interact → enqueue → poll → render → submit):
- GET_PAGES_TIMEOUT_MS 60s → 45s. The MCP SDK also defaults to 60s, so
if the round-trip got close, the client timed out first and our error
went nowhere. Server rejects first now.
- waitForPageData wires extra.signal. If the client cancels interact
(timeout/user abort), we clean up the pendingPageRequests entry
immediately instead of leaking until our own timeout. Also simplified
to a single settle callback instead of {resolve, reject, timer}.
- handleGetPages .catch() → submit empty pages. Was fire-and-forget
with no error path; any rejection before the inner try/catch meant
no submit_page_data → server waited the full timeout.
fill_form response: dropped the full field listing that was appended
on every call. display_pdf already returns it; echoing it back after
every successful fill is noise. Only list valid field names when the
model got one wrong.
* pdf-server: return URL.href from safeImageSrc so CodeQL sees sanitizer
The previous attempt returned the raw input string after a scheme
check, which CodeQL's taint tracker doesn't recognise as a sanitiser
(it sees tainted in → tainted out). Now parse with the URL constructor
and return the .href property — this is a canonical sanitiser pattern
CodeQL models as a barrier for js/xss and unvalidated-url-redirection.
Also folded the data: URI branch into safeImageSrc for a single call
site responsible for producing the <img src> string.
* feat(pdf-server): treat uploads-root dirs as read-only by default
Dir roots whose basename is 'uploads' (e.g. Claude Desktop's attachment
drop folder) are now treated as read-only unless --writeable-uploads-root
is passed. This prevents the save button from appearing for attached PDFs
that the client doesn't expect to be overwritten.
Also gates the _debug diagnostic block on --debug and adds save/restore
of writeFlags.allowUploadsRoot in test beforeEach/afterEach.
* feat(pdf-server): add --debug flag, fix interact timeout, skip persist for read-only cmds
- Wire --debug CLI flag through to createServer; _debug diagnostic block
in display_pdf _meta is now only emitted when --debug is set.
- Viewer: showDebugBubble renders _debug payload as a fixed overlay.
- Fix interact get_pages timeout: await handleGetPages instead of
fire-and-forget, so submit_page_data doesn't queue behind the next
30s long-poll on serialized host connections.
- Skip persistAnnotations for read-only commands (get_pages, file_changed).
* fix(pdf-server): rebase annotations baseline after save
After a successful save_pdf, update pdfBaselineAnnotations and
pdfBaselineFormValues to reflect what was written to disk. Without
this, removing all annotations after a save produced an empty diff
(compared to the stale pre-save baseline), incorrectly disabling
the save button even though the file on disk still had annotations.
* fix(pdf-server): sync annotation panel on canvas click, fix tooltip z-index
Clicking an annotation on the canvas now re-renders the panel to
expand the correct page section and scrolls the card into view.
Previously only the selection class toggled without updating the
accordion.
Raise tooltip z-index to 100 within the annotation layer and
promote the annotation layer above the form layer on note hover
(:has selector) so tooltips aren't clipped by the form overlay.
* debug(pdf-server): add __pdfDebug() helper + log skipped baseline annotations
Adds window.__pdfDebug() that dumps annotationMap, baseline,
layer children, and localStorage diff to diagnose ghost annotations
(visible on canvas but not in panel, not selectable).
Also logs when importPdfjsAnnotation returns null for non-widget
annotations, and surfaces any thrown errors during baseline import
instead of silently swallowing them.
* debug(pdf-server): expose pdfDocument.annotationStorage + window.__pdf internals
__pdfDebug() now also dumps PDF.js's annotationStorage contents
(editor stamps live there, invisible to our tracking) and all
localStorage keys matching pdf-annot pattern.
After running __pdfDebug(), internals are exposed as
window.__pdf.{pdfDocument, annotationMap, annotationLayerEl, formLayerEl}
for interactive console poking.
* fix(pdf-server): hide viewUUID when interact disabled, widen annotations panel
- display_pdf result text no longer leaks viewUUID when the interact
tool is not registered (model has no use for it).
- Annotations panel default width: 250px -> 500px (max-width:50vw
still caps on narrow viewports).
* refactor(pdf-server): extract src/commands.ts, dedupe PdfCommand type
PdfCommand was defined independently in server.ts and mcp-app.ts with
no compiler check to keep them in sync. Extract to src/commands.ts as
the single source of truth; both sides import the type.
Uses the TS interfaces from pdf-annotations.ts (not Zod-inferred types)
since those already describe the post-resolveImageAnnotation wire shape
(imageData present, x/y/width/height non-optional).
Also deletes ~150 lines of dead Zod schemas (PdfAnnotationDef and the
10 variant schemas that built it) -- they were never used as runtime
validators, only for z.infer<typeof> type inference. Input remains
z.record(z.any()) for model-API forgiveness.
* fix(pdf-server): correctness cleanup bundle
- findTextRectsFromCache: return [] instead of a hardcoded placeholder
rect when text-layer DOM isn't rendered. The placeholder was persisted
as real coordinates; caller already guards on empty.
- onteardown: bump loadGeneration to stop the preloader (reuses the
reload-abort check) and clear searchDebounceTimer.
- startPreloading: re-check loadGeneration inside the pause-wait loop
so teardown mid-pause exits instead of spinning.
- app.sendMessage calls: wrap in .catch(log.error) so host-unsupported
doesn't throw an unhandled rejection.
- Remove dead ternary (Highlight:Highlight), stale TODO and commented
downloadBtn line.
* docs(pdf-server): fix action names in example prompts, document all flags
- Example prompts referenced get_pages with getText/getScreenshots params;
actual model-facing actions are get_text (intervals) and get_screenshot
(single page). Fixed 3 prompts.
- Document --debug, --enable-interact, --writeable-uploads-root flags.
- Add image annotation type to the Annotation Types table.
- Note that interact is disabled in HTTP mode unless --enable-interact.
- Add Deployment section (stdio vs HTTP single-instance vs stateless).
* test(pdf-server): add interact tool unit tests
New describe("interact tool") block with 7 tests covering:
- enqueue -> poll_pdf_commands roundtrip
- missing-arg error paths for navigate, fill_form, add_annotations
- command queue isolation across distinct viewUUIDs
- fill_form passthrough when viewFieldNames not registered
- (skip) unknown-UUID poll (LONG_POLL_TIMEOUT_MS not exported, can't
bypass the 30s wait without changing server.ts)
Surprises found:
- interact never validates viewUUID exists; enqueues to any string
- batch-mode early-exits on first error, silently dropping later commands
* style: auto-fix prettier formatting
* refactor(pdf-server): extract annotation panel to src/annotation-panel.ts
Split ~930 lines from mcp-app.ts into two new modules:
- src/viewer-state.ts (50 lines): shared Maps/Sets/Arrays + types
(annotationMap, formFieldValues, selectedAnnotationIds, fieldNameTo*,
undoStack/redoStack, TrackedAnnotation, EditEntry). Only containers
with stable bindings — both modules mutate contents, never reassign.
- src/annotation-panel.ts (1084 lines): floating panel positioning,
accordion rendering, annotation/form-field cards, reset/clear-all.
Coupling to mcp-app flows through PanelDeps injected at init —
scalars like currentPage/pdfDocument reach the panel via a state()
getter so the ~100 use sites in mcp-app stay unwrapped.
mcp-app.ts: 5666 → 4721 lines. panelState.open replaces
annotationPanelOpen; panelState.openAccordionSection is written by
selectAnnotation. syncSidebarSelection moved to the panel module.
* style: auto-fix prettier formatting
* test(pdf-server): document computeDiff same-id modification behavior
Two new tests:
- User-added annotation modification: captured in diff.added (id not
in baseline, so latest content persists correctly).
- Baseline annotation in-place modification: KNOWN LIMITATION. Same-id
edit produces empty diff (id-set based), so the change vanishes on
reload. Viewer's addAnnotation() works around via remove+add, but
updateAnnotation() (interact tool's update_annotations) does not.
* chore(pdf-server): revert unrelated screenshot regenerations
Pre-commit hook runs build:all which regenerates all example
screenshots. These 24 PNGs have no semantic change; reverting
to keep the PR diff focused on pdf-server.
* fix(pdf-server): gate resolveImageAnnotation on validateUrl (arbitrary file read)
resolveImageAnnotation() did fs.readFile on whatever imageUrl the model
sent, bypassing the allowedLocalFiles/allowedLocalDirs machinery that
protects display_pdf and save_pdf. Model could request
{imageUrl:"/Users/x/.ssh/id_rsa"}, server would base64 the bytes into
the add_annotations command, iframe stores it, get_screenshot reads it
back.
Also: fetch() branch accepted plain http:// (SSRF to local network).
Fix: call validateUrl(imageUrl) before touching the filesystem or
network. Throws on rejection; caller converts to {isError:true} so the
model sees a clear error instead of silent skip.
3 tests: reject local path outside roots, reject http://, accept path
under allowed dir (with real readFile + imageData population).
* fix(pdf-server): deleted-baseline zombies, clear-all form strip, height-only coord shift
Three bugs from PR review, all in viewer state/coord handling:
1. Deleted baseline annotations zombied back on reload (mcp-app.ts:2512).
restoreAnnotations' apply loop was add-only. loadBaselineAnnotations
runs between the two restore calls and re-seeds annotationMap with
every baseline id, including the ones in diff.removed. The zombie
survives, and the next persistAnnotations sees it in currentIds ->
computeDiff produces removed=[] -> deletion permanently lost.
Fix: delete diff.removed ids after the merge loop.
2. Clear All didn't strip form values from the saved PDF (mcp-app.ts:2756).
clearAllItems() empties formFieldValues, but buildAnnotatedPdfBytes
gates on formFields.size > 0 and only writes entries present in the
map. Empty map -> zero setText/uncheck calls -> pdf-lib keeps the
original /V values. Fix: at getAnnotatedPdfBytes time, inject an
explicit clearing sentinel ("" or false by baseline type) for every
baseline field absent from formFieldValues.
3. update_annotations shifted rect/circle/image when patching height
without y (mcp-app.ts:4161). The old code spread existing.def
(internal coords, y = bottom edge) with update (model coords, y =
top-left), then key-filtered back to only update keys. But internal
y = pageHeight - modelY - height; patching height with top fixed
requires rewriting internal y, which the key-filter discarded.
Fix: convert existing to model coords, merge in model space, convert
back, pass the full merged def. Also uses the target page height
when update.page differs (fixes the low-severity page-move bug too).
* fix(pdf-server): sweep aux maps independently of commandQueues; line annotations sort
Two lower-severity findings from review:
Leak (server.ts:265): pruneStaleQueues iterated commandQueues to clean
up viewFieldNames/viewFieldInfo/viewFileWatches, but display_pdf
populates those maps without creating a commandQueues entry (only
enqueueCommand does), and dequeueCommands deletes the entry on every
poll. Net: the sweep found nothing; aux maps leaked every display_pdf.
viewFileWatches entries hold an fs.StatWatcher -> slow FD exhaustion
on HTTP --enable-interact. Fix: new viewLastActivity heartbeat map,
touched at display_pdf/enqueue/dequeue, swept on TTL. Dead second
loop (entry.commands.length===0 was unreachable) removed.
Line-annotation sort (annotation-panel.ts:400): getAnnotationY checked
'y' in def and 'rects' in def, but LineAnnotation has only x1/y1/x2/y2.
Fell through to return 0 -> all line annotations sorted to panel
bottom. Added y1 branch returning max(y1, y2).
* feat(pdf-server): rewrite display_pdf prompts to steer model toward interact
The model was calling display_pdf again to add annotations instead of
using interact with the existing viewUUID. Root cause: the description's
first two sentences invited exactly that --
'Use this to display, annotate, edit, and fill form fields'
'when the user wants to ... annotate, edit, sign, stamp'
-- then the CRITICAL warning arrived three paragraphs later, after the
model had already pattern-matched 'user wants to sign' -> display_pdf.
Three changes:
- First sentence is now narrow: 'Open a PDF. Call this ONCE per PDF.'
- Follow-up-actions-go-through-interact is sentence 2, not paragraph 3.
- Result text is directive at the decision point: tells the model to
call interact with the viewUUID, warns against re-calling display_pdf.
* fix(pdf-server): correct the 'discards state' claim in display_pdf prompts
Both viewers coexist; nothing is discarded. The actual failure mode is
the model now holds a new viewUUID and addresses the wrong viewer --
interact calls land on the fresh empty one, not the one with the user's
existing annotations. Rewording to say that.
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
* Fix touch gesture conflicts in WebGL example apps on mobile
* Format with prettier
* fix(examples): improve mobile support for map, pdf, and threejs examples
- map-server: fullscreen button respects safe area insets, hover/opacity
pattern with always-visible on touch devices
- pdf-server: fit-to-width scale for narrow viewports, responsive toolbar
with compact controls on mobile, safe area in fullscreen toolbar via
CSS custom properties
- threejs-server: fullscreen button respects safe area and always visible
on touch, ResizeObserver for responsive width, host containerDimensions
for fullscreen height, no container padding in fullscreen, replace
useHostStyles with inline style application to avoid overwriting
onhostcontextchanged handler
Changes since 1.2.1:
- fix(schemas): import from zod/v4 to match SDK's zod API (#548)
- test(e2e): fix no-op security injection test via frames[] traversal (#540)
The generated schemas compose with schemas imported from
@modelcontextprotocol/sdk/types.js (e.g. z.array(ContentBlockSchema)).
The SDK constructs its schemas via `import * as z from 'zod/v4'`, but
our generated schema.ts used `import { z } from "zod"` — which returns
the v3 API when the consumer has zod 3.25.x installed.
Mixing v3-created and v4-created schema instances throws at parse time
with errors like `keyValidator._parse is not a function` because zod v4
dropped the `_parse` / `_parseSync` internals that v3 wrappers call.
This was masked before #534 because zod was bundled — all schema
creation shared the same inlined zod copy. Externalizing zod exposed
the mismatch on consumers pinned to zod 3.x (e.g. anthropics/apps).
The `zod/v4` subpath is exported by both zod 3.25+ and zod 4.x, so the
existing peerDependency range `^3.25.0 || ^4.0.0` is preserved.
https://claude.ai/code/session_013xQUegrvVGct5xpqeSL5av
Co-authored-by: Claude <noreply@anthropic.com>
The cross-app message injection test at security.spec.ts:313 has been a
no-op since it was added in 2411c71a. It attempted to reach the inner app
iframe via:
outerIframe.contentDocument?.querySelector('iframe')
but contentDocument is null across the 8080→8081 origin boundary (the test
at :247 in the same file explicitly asserts this). The ?. short-circuited,
postMessage never fired, and the test passed without exercising the
defense in message-transport.ts.
Fix:
- Use window.frames[0].frames[0] — cross-origin accessible per HTML spec,
and the actual attack path a malicious sibling app would use
- Return a sentinel from page.evaluate() and assert it, so the test fails
loudly if frame traversal ever breaks again
- Actually assert the rejection log (was previously captured but never
checked)
- Use expect.poll() instead of waitForTimeout(500)
- Reuse captureConsoleLogs helper
Also fixed: comment at :293 claimed 'Outer frame should NOT have
allow-same-origin' but the assertion checks allow-top-navigation. The
outer frame DOES have allow-same-origin (implementation.ts:167);
isolation comes from the separate port, not the sandbox attribute.
* chore: remove dead ./react-with-deps export (copy-paste bug from #221)
The react-with-deps build entry was introduced in PR #221 (e078250a) as a
sibling to app-with-deps for CDN/unpkg no-bundler use. But its external
array was duplicated without editing — it never dropped @modelcontextprotocol/sdk
from externals, so it has shipped byte-identical to ./react for 10 releases
(v0.3.1 → v1.2.0).
After #534 merged, both entries use ['react', 'react-dom', ...PEER_EXTERNALS]
— still identical, just smaller.
Delete rather than fix: React apps always use a bundler; the CDN/unpkg
use case (HTML-string apps like qr-server) doesn't apply to React hooks.
Zero consumers verified (examples/docs/tests/plugins).
* fix: bundle SDK+zod in react-with-deps (keep React external)
Reverts the deletion from the previous commit and applies the actual fix.
The react-with-deps external array was copy-pasted in PR #221 without
dropping PEER_EXTERNALS — now it mirrors app-with-deps: bundles
@modelcontextprotocol/sdk + zod for CDN/import-map consumers.
React and react-dom MUST remain external — bundling them would cause
dual-React-instance hooks errors. Consumer provides them via import map.
Before: index.js 26KB == react-with-deps.js 26KB (identical MD5)
After: index.js 26KB != react-with-deps.js 323KB (SDK+zod bundled)
* fix(readme): use picture element for theme-aware logo
The #gh-light-mode-only / #gh-dark-mode-only URL fragments only work
on github.com. On npm, VS Code preview, and other markdown renderers
both img tags render, showing two stacked logos.
Switch to <picture> with prefers-color-scheme, which GitHub recommends
and which degrades gracefully to a single logo elsewhere.
* ci: add Cloudflare Pages preview for docs PRs
Deploys a per-PR preview of the TypeDoc site to Cloudflare Pages project
mcp-ext-apps-docs-preview when docs, src JSDoc, README, or typedoc config
change. Uses the shared modelcontextprotocol/actions composite action that
injects noindex headers, posts a sticky PR comment with preview URLs, and
cleans up deployments on PR close. Fork PRs are skipped (no secret access).
* fix(docs): sync README logo with TypeDoc theme switcher
The README <picture> logo uses prefers-color-scheme, which only follows
the OS setting. TypeDoc's theme switcher sets data-theme on <html>, so
manually picking Light/Dark would show the wrong logo (e.g. white logo
on light background if OS is dark but user picked Light).
Rewrite the <picture> in the generated docs into two class-tagged <img>s
via the mcpstyle plugin, and hide the inactive one via CSS keyed on both
data-theme (explicit selection) and prefers-color-scheme (OS mode). The
README source is unchanged so GitHub/npm still get <picture>.
Also: prettier normalized mcp-theme.css (tabs to spaces, quote style).
The issue_comment trigger previously ran for any commenter on a PR.
On a public repo this lets drive-by users trigger a job with
contents:write that checks out the PR branch, runs playwright
--update-snapshots, and pushes a [skip ci] commit.
Gate the issue_comment path on author_association being OWNER,
MEMBER or COLLABORATOR. workflow_dispatch is unchanged (already
requires repo write access).
The override pinning @hono/node-server to 1.19.7 was added in 71976101
as a workaround when @modelcontextprotocol/sdk 1.25.3 required ^1.19.9,
which did not yet exist on the public npm registry.
That constraint is now obsolete: the SDK is pinned to 1.25.2 (requires
^1.19.7), and 1.19.8-1.19.11 have since been published. Removing the
override lets npm naturally resolve 1.19.11, which includes the fix for
the HIGH-severity auth bypass in the Serve Static middleware
(GHSA-wc8c-qw6v-h7f6, fixed in 1.19.10).
Lockfile regenerated against registry.npmjs.org (no artifactory URLs).
Bug 1: .husky/pre-commit line 21 ran:
git diff --name-only --diff-filter=M | xargs -r git add
which stages EVERY modified tracked file in the worktree. If a
contributor has unstaged WIP elsewhere, it gets silently swept
into the commit.
Fix: capture `git diff --name-only --cached` before running
build/prettier, then only re-add that set. src/generated/ is
staged explicitly since build:all regenerates it from
spec.types.ts.
Bug 2: no repo-local .npmrc meant the maintainer's global
artifactory registry leaked into package-lock.json, requiring
the Docker regen dance. Committing .npmrc with
registry=https://registry.npmjs.org/ overrides user-global
config. Docker regen is now optional (still useful for
linux-amd64 optionalDeps).
- Switch npm install -> npm ci in ci.yml (build, build-wsl) and docs.yml
to fail on lockfile drift rather than silently tolerating it
- Add cache: npm to all setup-node steps that have a lockfile to hash
(skipped test-git-install which has no checkout, and WSL which has no
setup-node action)
- Add TypeDoc link validation step after build (Linux x64 only, matching
existing single-OS gate pattern for MCPB). Verified passing on main.
- Align all workflows on Node 22 (active LTS) — previously CI used 20
but publish workflows used 22, so releases were tested on a different
Node than PRs
- Add engines.node >=20 to package.json so consumers on Node 18 get a
warning
Two packaging bugs:
1. The './schema.json' export pointed to dist/src/generated/schema.json
but nothing copied it there (tsc is emitDeclarationOnly, Bun.build
doesn't emit JSON). Consumers got ERR_MODULE_NOT_FOUND.
Fix: cpSync after tsc runs.
2. zod is a peerDependency but was bundled into every entry point
(~270KB each). This causes dual-instance bugs where consumer-side
'instanceof ZodError' and schema.extend() break across boundaries.
Fix: add zod to external list for all non-with-deps entries.
Bundle size impact:
app.js 293952 -> 24561 (-91.6%)
app-bridge.js 299517 -> 30112 (-89.9%)
react/index.js 295558 -> 26153 (-91.2%)
server/index.js 291500 -> 22135 (-92.4%)
app-with-deps 321814 -> 321814 (unchanged, intentional)
Bug 1: generate-grid-screenshots.spec.ts was running on every CI E2E
invocation because playwright.config.ts had no testIgnore. This spec
writes examples/*/grid-cell.png as a side effect — it's meant to be
invoked only via npm run generate:screenshots.
Added testIgnore gated on GENERATE_SCREENSHOTS env var (Playwright's
testIgnore is stronger than explicit CLI file args, so a plain ignore
would break generate:screenshots). Passed the env var through the
docker invocation in generate:screenshots.
Before: npx playwright test --list → 82 tests in 3 files
After: npx playwright test --list → 65 tests in 2 files
GENERATE_SCREENSHOTS=1 ... --list → 17 tests in 1 file (still works)
Bug 2: examples/pdf-server/server.test.ts (448 LOC, 34 tests) was
never run — root script was 'bun test src'. Changed to 'bun test src
examples'. Only one .test. file exists in examples/ so no noise.
Before: npm test → 87 pass across 3 files
After: npm test → 121 pass across 4 files
Change `sandbox.ts` imports from relative paths into `dist/` to use the
proper `@modelcontextprotocol/ext-apps/app-bridge` package entry point.
This aligns the example with how external consumers would import from
the package.
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Move detailed implementation recipes (tool visibility, host styling, streaming,
fullscreen, etc.) out of the skill and point to `docs/patterns.md` instead.
This keeps the skill focused on essentials while the patterns doc provides
comprehensive examples.
Key changes:
- Fix protocol flow diagram: host renders UI before server returns result
- Update template file list to reflect actual contents (`main.ts`, `global.css`)
- Add critical CSP/CORS warnings to "Common Mistakes" section
- Replace "Advanced Examples" table with categorized patterns list
- Add note clarifying `basic-host` is for testing, not a host behavior guarantee
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
On Windows, `tsx watch` can hang when running under `concurrently` due
to stdin handling conflicts (see [privatenumber/tsx#623][]). Adding the
`--raw` flag to `concurrently` avoids this by preventing stdin
interception.
Since `--raw` mode disables concurrently's automatic output prefixing, a
custom Vite logger is added to prefix messages with `[vite]` so users
can still distinguish which process produced each line of output.
[privatenumber/tsx#623]: https://github.com/privatenumber/tsx/issues/623
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Follow-up to #470. Matches MCP SDK Client.listResources(params?) signature
so callers can omit the empty {} for the common case.
Also reflows a line in app-bridge.test.ts that prettier flagged.
* Replace platform-specific optionalDependencies with bun devDependency
Fixes#222. The bun meta-package handles platform detection internally.
Rollup resolves its own platform binaries transitively. Removes ~400MB
of bloat for SDK consumers. Simplifies setup-bun.mjs accordingly.
* Remove setup-bun.mjs, simplify prepare script
No longer needed since the bun npm package handles binary
installation and PATH registration automatically.
* Add Security docs section, SEO improvements, and doc site enhancements
- Add Authorization guide covering per-server and per-tool OAuth patterns
- Add CSP & CORS guide extracted from Patterns doc
- Group both under a new Security section in the documentation nav
- Replace CSP & CORS section in Patterns with cross-reference to new guide
- Rename doc site title from package name to 'MCP Apps'
- Rename 'Modules' nav section to 'API Documentation'
- Ensure Security section appears before API Documentation in TOC
- Add SEO plugin with JSON-LD structured data (TechArticle/WebPage)
- Add per-page meta descriptions from frontmatter
- Add description frontmatter to all documentation pages
- Add hostedBaseUrl for sitemap.xml generation and canonical URLs
- Normalize document page slugs to lowercase hyphenated format
- Update compressed navigation and search index data to match new slugs
* Add favicons with light/dark mode support
- Download favicons from modelcontextprotocol.io (light + dark variants)
- Inject favicon link tags into every page with correct relative paths
- Support prefers-color-scheme media queries for light/dark mode
- Include apple-touch-icon for iOS
- Copy favicon assets to output directory during doc build
* Fix HTML sanitization in SEO plugin with proper parser
Replace regex-based HTML tag stripping with htmlparser2 for
extracting plain-text descriptions from rendered pages.
* Add custom theme to align with modelcontextprotocol.io styling
- Import Inter and JetBrains Mono fonts (matching MCP site)
- Override light mode colors: pure white backgrounds, softer gray borders
- Override dark mode colors: match MCP site dark background (#0f1117)
- Taller header (3.5rem) with backdrop-blur frosted glass effect
- Sidebar: adjusted spacing, font size, and hover/active states
- Content: increased line-height (1.6), more heading breathing room
- Code blocks: JetBrains Mono, subtle border, more padding
- Fix CSS load order: custom.css now loads after theme stylesheets
* Align sidebar nav styling with modelcontextprotocol.io
- Active item: tinted blue background with blue text (matching MCP's
primary-color tinted active state)
- Non-active items: muted gray text, subtle hover background
- Larger border-radius (0.75rem/rounded-xl) matching MCP sidebar
- Group headers: semibold with slight letter spacing
- Proper dark mode variants for all states
* Fix sidebar active item: dark gray background with bold text
* Make sidebar active item more prominent: bolder weight, stronger background
* Highlight current page in sidebar nav, normalize code font size
Inject a small script via the SEO plugin that marks the active sidebar
link with a "current" class (TypeDoc doesn't do this natively for
document pages). Uses a MutationObserver since the sidebar is populated
asynchronously. Pathname comparison strips .html extensions to support
clean-URL servers.
Also bumps code/pre font-size from 0.85em to 1em so code snippets match
the surrounding body text size.
* Split styling into dedicated plugin, fix auth terminology, improve breadcrumbs
Extract CSS cascade fix, breadcrumb labels, and sidebar nav highlighting
from the SEO plugin into a new typedoc-plugin-mcpstyle.mjs to keep
concerns separated.
Fix authorization doc: use "authorization" consistently instead of mixing
with "authentication", link to MCP spec and RFC 9728 for Protected
Resource Metadata, remove redundant spec link paragraph.
Rename "Documents" nav section to "Getting Started" and add explicit
group frontmatter to all doc pages. Breadcrumbs now show the section
name instead of duplicating the page title.
Switch local development MCP server config from `npm --prefix` to
`bash -c "cd DIR && npm --silent run start:stdio"`. The --prefix form
caused connection instability in Claude Desktop (reconnect loops with
orphan builds competing on the same dist/).
Also updated example paths from ~/code/ext-apps to ~/src/ext-apps.
fit-content clamps to the containing block's available size. For <html>,
that's the iframe viewport, so when content exceeds the viewport height
the SDK reported the viewport height instead of the true content height,
causing internal scrolling instead of iframe growth.
max-content has no available-space constraint and correctly reports the
intrinsic content height in both directions (shrink and grow). Width
stays fit-content to preserve responsive wrapping.
* docs: restore full MCP client JSON configs to CONTRIBUTING.md
Reinstate the copy-pasteable JSON configurations for running all examples
with MCP clients (npx-based and local development), which were removed
from README.md in 2af02ba. Placed in CONTRIBUTING.md as a better home
for contributor-facing setup instructions.
https://claude.ai/code/session_014pjt7bE4ckHns5QFPkdWQp
* Use start:stdio in local dev config, add missing scripts to 9 examples
Update the local development JSON config in CONTRIBUTING.md to use
`npm --silent run start:stdio` instead of manual bash commands.
Add `serve:stdio` and `start:stdio` scripts to the 9 examples that
were missing them (basic-server-*, sheet-music, transcript,
video-resource, debug) to match the pattern already in place for the
other 11 showcase examples.
https://claude.ai/code/session_014pjt7bE4ckHns5QFPkdWQp
* style: auto-fix prettier formatting
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
* security: ignore client roots by default in pdf-server
When the pdf-server is started with --stdio, MCP clients may advertise
roots that refer to directories on the *client's* file system. Because
the server resolves those paths locally, accepting them by default would
give the remote client access to arbitrary directories on the server's
machine.
This commit makes client roots opt-in via the --use-client-roots flag.
Without the flag, the server logs a notice and skips roots setup
entirely. The createServer() function now accepts a CreateServerOptions
object with a `useClientRoots` boolean (defaults to false).
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* Enable client roots by default for HTTP, keep off for stdio
HTTP mode serves a local client so roots are safe. Stdio mode may
have a remote client whose roots would resolve against the server's
filesystem, so roots stay off unless --use-client-roots is passed.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* fix: correct transport-aware defaults for useClientRoots
stdio = local client (e.g. Claude Desktop) → auto-enable roots
HTTP = remote client → ignore roots unless --use-client-roots passed
The previous commit had the logic inverted.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* refactor: inline useClientRoots per transport branch
Remove the intermediate effectiveUseClientRoots variable — just pass
`true` in the stdio branch and the flag value in the HTTP branch.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* docs: update README to match transport-aware client roots defaults
Stdio always enables roots (client is local); HTTP ignores them by
default. The previous README text had these reversed.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
---------
Co-authored-by: Claude <noreply@anthropic.com>
Olivier Chafik
Mel Ludowise
Frédéric Barthelet
Anton Pidkuiko
Den Delimarsky
Anton Pidkuiko MacBook
Andrew
Jonathan Hefner
Hryhorii (Greg) Avcharov
Antoine Lévêque
Suriya Prakash