| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Olivier Chafik
|
3cf5b588a1 |
chore(pdf-server): switch pdf-lib to maintained @cantoo/pdf-lib fork (#651)
The original pdf-lib package has been unmaintained since Nov 2021. @cantoo/pdf-lib is an actively maintained, API-compatible fork with ongoing releases and accumulated bugfixes. Also updates test assertions from the deprecated PDFNumber.value() to PDFNumber.asNumber() per the fork's API guidance. |
||
|
Olivier Chafik
|
0008d3b78f |
chore: bump ext-apps to 1.7.1 (#643) | ||
|
Olivier Chafik
|
64b4fa16de |
chore: bump ext-apps to 1.7.0 (#628) | ||
|
Olivier Chafik
|
989ddc7568 |
chore: bump vite, hono, @hono/node-server to patched versions (#616)
Lockfile-only bumps to address npm audit findings: - vite 6.4.1 -> 6.4.2 (high) - hono 4.12.9 -> 4.12.14 (moderate) - @hono/node-server 1.19.11 -> 1.19.14 (moderate) All within existing semver ranges; no package.json changes needed. |
||
|
Olivier Chafik
|
3fb521b71f |
spec: Add tool registration for Apps, to be called by Host (WebMCP-style!) (#72)
* feat: Add tool registration and bidirectional tool support This PR adds comprehensive tool support for MCP Apps, enabling apps to register their own tools and handle tool calls from the host. - Add `registerTool()` method for registering tools with input/output schemas - Add `oncalltool` setter for handling tool call requests from host - Add `onlisttools` setter for handling tool list requests from host - Add `sendToolListChanged()` for notifying host of tool updates - Registered tools support enable/disable/update/remove operations - Add `sendCallTool()` method for calling tools on the app - Add `sendListTools()` method for listing available app tools - Fix: Use correct ListToolsResultSchema (was ListToolsRequestSchema) - Add comprehensive tests for tool registration lifecycle - Add tests for input/output schema validation - Add tests for bidirectional tool call communication - Add tests for tool list change notifications - All 27 tests passing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * nits * Update apps.mdx * feat: Add automatic request handlers for app tool registration Implement automatic `oncalltool` and `onlisttools` handlers that are initialized when apps register tools. This removes the need for manual handler setup and ensures tools work seamlessly out of the box. - Add automatic `oncalltool` handler that routes calls to registered tools - Add automatic `onlisttools` handler that returns full Tool objects with JSON schemas - Convert Zod schemas to MCP-compliant JSON Schema using `zod-to-json-schema` - Add 27 comprehensive tests covering automatic handlers and tool lifecycle - Test coverage includes error handling, schema validation, and multi-app isolation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * type updates * fix: Ensure tools/list returns valid JSON Schema for all tools - Always return inputSchema as object (never undefined) - Keep filter for enabled tools only in list - Update test to match behavior (only enabled tools in list) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * type updates * rm zod-to-json-schema * fix: Update RegisteredTool to use 'handler' instead of 'callback' (SDK API change) * refactor: Rename sendCallTool/sendListTools to callTool/listTools Avoid double-verb naming pattern for consistency with existing API. * feat: Add screenshot and click support to SDK - Add McpUiScreenshotRequest/Result and McpUiClickRequest/Result types - Add onscreenshot and onclick handlers to App class - Add screenshot() and click() methods to AppBridge class - Generate updated Zod schemas * feat(map-server): Enable registerTool with navigate-to and get-current-view - Uncomment and fix the navigate-to tool for animated navigation - Add get-current-view tool to query camera position and bounding box - Add flyToBoundingBox function for smooth camera animation - Add setLabel function for displaying location labels * feat(pdf-server): Add widget interaction tools - get-document-info: Get title, current page, total pages, zoom level - go-to-page: Navigate to a specific page - get-page-text: Extract text from a page - search-text: Search for text across the document - set-zoom: Adjust zoom level * feat(shadertoy-server): Add widget interaction tools * feat(examples): Add widget interaction tools to budget-allocator, shadertoy, wiki-explorer, and threejs budget-allocator: - get-allocations: Get current budget allocations - set-allocation: Set allocation for a category - set-total-budget: Adjust total budget - set-company-stage: Change stage for benchmarks - get-benchmark-comparison: Compare against benchmarks shadertoy: - set-shader-source: Update shader source code - get-shader-info: Get shader source and compilation status - Sends errors via updateModelContext wiki-explorer: - search-article: Search for Wikipedia articles - get-current-article: Get current article info - highlight-node: Highlight a graph node - get-visible-nodes: List visible nodes threejs: - set-scene-source: Update the Three.js scene source code - get-scene-info: Get current scene state and any errors - Sends syntax errors to model via updateModelContext * feat: Add expand-node tool to wiki-explorer and update tool descriptions Wiki Explorer: - Add expand-node tool - the critical missing tool for graph exploration - Claude can now programmatically expand nodes to discover linked articles Server descriptions updated to mention widget tools: - map-server: navigate-to, get-current-view - pdf-server: go-to-page, get-page-text, search-text, set-zoom, get-document-info - budget-allocator: get-allocations, set-allocation, set-total-budget, etc. - shadertoy: set-shader-source, get-shader-info - wiki-explorer: expand-node, search-article, highlight-node, etc. All descriptions now mention 'Use list_widget_tools to discover available actions.' * refactor: Simplify tool descriptions - remove client implementation details The server tool descriptions now just mention that widgets are interactive and can be controlled, without teaching the model about list_widget_tools (which is the client's responsibility to teach). Before: 'The widget exposes tools: X, Y, Z. Use list_widget_tools to discover...' After: 'The widget is interactive and exposes tools for X and Y.' * Remove ui/screenshot and ui/click protocol methods These will be proposed separately from the app tool registration changes. * fix(app): auto-register tools capability in registerTool When registerTool is called before connect() on an App created without explicit tools capability, setRequestHandler's capability assertion would throw, breaking app initialization at module load. Auto-register { tools: { listChanged: true } } on first registerTool call (pre-connect only), mirroring McpServer.registerTool behavior. Fixes pdf-annotations e2e failures where the PDF canvas never rendered because registerTool threw at module scope. * pdf-server: replace app-tools with 1:1 interact command mapping Converts the 5 placeholder app-registered tools into 12 tools that map directly to the server's interact commands (navigate, search, find, search_navigate, zoom, add_annotations, update_annotations, remove_annotations, highlight_text, fill_form, get_text, get_screenshot) plus the existing get-document-info. Implementation stays DRY by dispatching through the existing processCommands() handler — each tool callback constructs a PdfCommand and runs it via a small runCommand() wrapper. For get_text and get_screenshot, the page-data collection is extracted from handleGetPages into a shared collectPageData() helper so results can be returned directly instead of round-tripping through the server. Tool names and zod schemas mirror the interact command parameter shapes from server.ts so the model sees the same surface whether it goes through interact or app-tools. The server-side interact tool is unchanged and remains available for hosts without app-tool support. * chore: drop unused test vars and stale Request/Result imports * docs(spec): address review feedback on app tool registration - Add outputSchema to Tool struct (matches SDK + core MCP) - Reword "black box" bullets: drop stale screenshots reference, clarify no DOM access - Clarify push vs pull contrast with explicit setWidgetState + ui/update-model-context refs - Add Task-reference future-work bullet for tools outliving render lifecycle * docs(spec): clarify app DOM is not host-introspectable; frame tools as pull complementing update-model-context push * fix(app): emit title and omit absent outputSchema in tools/list * feat(app): accept Standard Schema in registerTool/registerAppTool App.registerTool and registerAppTool now accept any schema implementing the Standard Schema spec (Zod ≥3.25, ArkType, Valibot, …) instead of zod-only. Uses ~standard.validate / ~standard.jsonSchema directly, so app.ts no longer imports zod at runtime — zod is now an optional peer. Mirrors the StandardSchemaWithJSON type from modelcontextprotocol/typescript-sdk#1689 so bumping to SDK v2 is a drop-in import swap. Adds @standard-schema/spec (types-only) and a hand-rolled non-zod test. * docs(spec): reference core MCP Tasks for long-running app tools App tools/call MAY be task-augmented per the core MCP Tasks utility (spec 2025-11-25). Adds a Long-Running App Tools subsection: hosts proxy tasks/* while the app is mounted; apps SHOULD delegate long-lived work to the server so the task survives iframe teardown. Removes the stale 'future extension' bullet — Tasks is shipped. * docs(spec): note Schema Validation accepts any Standard Schema library * chore: clean unused-var and no-op-await diagnostics in app.ts and tests * refactor(app): fold error prefix into validateStandardSchema; clarify registerAppTool runtime caveat * chore(typedoc): mark RequestHandlerExtra as intentionally not exported AppToolCallback (introduced with the Standard Schema migration) references the local RequestHandlerExtra alias in its parameter type. The alias is a private Parameters<> derivation and isn't part of the public API surface, so add it to intentionallyNotExported alongside AppOptions/MethodSchema. * fix(app): restore zod v3.25 compat via lazy z.toJSONSchema fallback zod v3.25.x implements ~standard.validate but not ~standard.jsonSchema, so constraining to StandardSchemaWithJSON broke the ^3.25.0 peer range. Widen registerTool to StandardSchemaV1 and fall back to a lazy zod/v4 import for serialization when ~standard.jsonSchema is absent and vendor==='zod'. Non-zod schemas without jsonSchema get a clear error. * docs(spec): slim Long-Running App Tools to a pointer into core MCP Tasks * chore: add TODO(sdk-v2) marker in standard-schema.ts * fix(app): align registerTool runtime with declared types - Handler reads registeredTool.{input,output}Schema so update() takes effect - Call cb(extra) when no inputSchema, matching AppToolCallback<undefined> - Throw on duplicate name; guard list_changed pre-connect; notify on register - Drop misleading zod optional peer (still required by generated/schema.ts) - examples: fix pdf search/find stale match count; threejs set-scene-source re-render - spec: Zod → Standard Schema; clarify tools availability via tools/list after init * feat(app): type structuredContent from outputSchema in registerTool AppToolCallback gains an Out param: when outputSchema is provided, structuredContent is required and typed via StandardSchemaV1.InferOutput, with an `isError: true` escape hatch. Without outputSchema, return type is unchanged (CallToolResult). Uses intersection rather than Omit since CallToolResult's index signature swallows Omit's known keys. Also drops the `as any` casts on z.object(...) in tests — zod 4 satisfies StandardSchemaV1 directly. * fix(app): registerTool edge cases + example tool correctness App.registerTool: - Skip outputSchema validation when result.isError (matches AppToolResult type) - Pin callback arity to original config.inputSchema; only the validation schema is mutable via update() - Default missing tools/call arguments to {} - remove() is a no-op if the handle is stale (re-registered or already removed) - Gate list_changed notifications on the listChanged capability Examples: - threejs: propagate executeThreeCode failures to onSceneError/onSceneRendering; catch updateModelContext rejection - wiki-explorer: search-article preserves graph on no-match - budget-allocator: fix category/stage values in tool descriptions * feat(app,app-bridge): guard requests sent before handshake completes (#620) * feat(app,app-bridge): guard requests sent before handshake completes Calling host-bound methods before the ui/initialize → ui/notifications/initialized handshake completes can race the handshake on strict hosts and leave the iframe permanently hidden. App (View side): - All 8 host-bound methods (callServerTool, readServerResource, listServerResources, sendMessage, updateModelContext, openLink, downloadFile, requestDisplayMode) now check that connect() has sent the initialized notification. - New AppOptions.strict (default false): console.error when false, throw when true. AppOptions is now exported. - useApp() forwards strict to the App constructor. - Flag resets on reconnect. AppBridge (Host side): - replaceRequestHandler is overridden to wrap every host-bound handler with a console.warn if the request arrives before ui/notifications/initialized. Never throws. ui/initialize and ping use setRequestHandler directly and are exempt; notifications are unaffected. - Catches Views that hand-roll postMessage without the SDK. - Flag resets on reconnect. Refs anthropics/claude-ai-mcp#61, anthropics/claude-ai-mcp#149. * fix(docs): drop AppOptions from intentionallyNotExported now that it is exported --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Olivier Chafik
|
01d826aea0 |
chore: bump ext-apps to 1.6.0 (#613) | ||
|
Olivier Chafik
|
621a70a724 |
chore: bump ext-apps to 1.5.0 (#588)
* chore: bump ext-apps to 1.5.0 * style: auto-fix prettier formatting --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> |
||
|
Olivier Chafik
|
9da4a75ff6 |
chore: bump ext-apps to 1.4.0 (#582)
* chore: bump ext-apps to 1.4.0 Changes since 1.3.2: SDK - feat: add addEventListener/removeEventListener with DOM-model on* semantics (#573) pdf-server - feat: add save_as interact action (#580) - feat: fit-to-page on fullscreen + pinch-to-zoom (#583) - fix: npx DOMMatrix crash + broken MCPB bundle (#584) - fix: viewer liveness, 1:1 batch results, fullscreen jitter (#579) - fix: render page before O(numPages) annotation scans (#581) - fix: radio + dropdown in fill_form/save (#577) Dependencies - chore: npm audit fix — sdk 1.29.0, systeminformation 5.31.5, +13 transitives (#585, #586) - fix: bump path-to-regexp 8.3.0 → 8.4.1 to patch ReDoS CVEs (#576) * chore: update e2e snapshots [skip ci] --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> |
||
|
Olivier Chafik
|
9757f35fd1 |
chore: drop spurious root dependencies block from #585 (#586)
#585's `npm pkg set dependencies.@modelcontextprotocol/sdk` created a root `dependencies` block — root previously had only devDependencies + peerDependencies (it IS the published SDK, the upstream sdk is a peer). Harmless at runtime but pulls sdk into the published tarball's deps. The original 1.25.2 devDep pin (b9a459a6, Jan 26) was because sdk 1.25.3 depended on @hono/node-server@^1.19.9 which didn't exist on npm yet — long since resolved. |
||
|
Olivier Chafik
|
8e7206cb15 |
chore(deps): npm audit fix — sdk 1.29.0, systeminformation 5.31.5, +13 transitives (#585)
Clears all 15 npm audit findings (8 high / 6 moderate / 1 low): - @modelcontextprotocol/sdk 1.25.2 → 1.29.0 (GHSA-345p-7cg4-v4c7 cross-client data leak via shared transport reuse). Root had it pinned exact in devDependencies which blocked audit fix. - systeminformation 5.30.6 → 5.31.5 (GHSA-5vv4-hvf7-2h46, GHSA-9c88-49p5-5ggf command injection) - hono, undici, rollup, picomatch, minimatch, lodash-es, svelte, devalue, ajv, brace-expansion, markdown-it, yaml, qs — lockfile bumps via npm audit fix |
||
|
Olivier Chafik
|
f987bc43b2 |
fix(deps): bump path-to-regexp 8.3.0 → 8.4.1 to patch ReDoS CVEs (#576)
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. |
||
|
Olivier Chafik
|
14969c5da2 |
chore: bump ext-apps to 1.3.2 (#569)
Changes since 1.3.1: - Revert fullscreen size-changed skip (#570) - Fix auto-resize destroying horizontal scroll positions (#567) - Remove examples/pdf-server/plugin/ — canonical copy is upcoming in knowledge-work-plugins (#565) |
||
|
Olivier Chafik
|
e8ca859429 |
chore: bump ext-apps to 1.3.1 (#562)
Changes since 1.3.0: - fix(pdf-server): detached-buffer on range re-request + stale e2e assertion (#561) |
||
|
Olivier Chafik
|
6723c8ff10 |
chore: bump ext-apps to 1.3.0 (#560)
Changes since 1.2.2: - feat: add ui/notifications/request-teardown for view-initiated termination (#215) - feat(pdf-server): annotations, interact tool, page extraction & prompt engineering (#506) - fix(examples): improve mobile support for map, pdf, and threejs examples (#555) |
||
|
Olivier Chafik
|
296b5921fb |
pdf-server: annotations, interact tool, page extraction & prompt engineering (#506)
* 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>
|
||
|
Olivier Chafik
|
704b6e0af9 |
chore: bump ext-apps to 1.2.2 (#549)
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) |
||
|
Olivier Chafik
|
e13732ad38 |
chore: bump ext-apps to 1.2.1
Changes since 1.2.0: - fix: bundle SDK+zod in react-with-deps (was byte-identical to ./react) (#539) - fix(build): copy schema.json to dist and externalize zod (#534) - fix: skip debug log for high-frequency tool-input-partial notifications (#546) - fix(deps): drop @hono/node-server override to patch GHSA-wc8c-qw6v-h7f6 (#535) - fix(readme): use picture element for theme-aware logo (#545) - fix(ci): require maintainer association for /update-snapshots trigger (#532) - fix: pre-commit stages only originally-staged files; add .npmrc (#538) - ci: use npm ci with caching, validate typedoc links, align Node versions (#533) - test: exclude screenshot-gen from default E2E run; wire pdf-server tests (#537) |
||
|
Olivier Chafik
|
bf623f832d |
fix(deps): drop @hono/node-server override to patch GHSA-wc8c-qw6v-h7f6 (#535)
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). |
||
|
Olivier Chafik
|
6b12fff1d0 |
chore: bump ext-apps to 1.2.0 (#527)
* chore: bump ext-apps to 1.1.3 Changes since 1.1.2: - fix: autoResize reporting viewport height when content is taller (#525) - fix: remove duplicate --color-text-ghost from McpUiStyleVariableKey (#523) - fix: examples servers' npm run start:stdio (#507) - pdf-server: ignore client roots by default (#510) - docs: add Security documentation section and SEO improvements (#524) - docs: add MCP client configuration examples to CONTRIBUTING.md (#508, #526) - docs: use apps.extensions.modelcontextprotocol.io domain for docs URLs (#499) - docs: add SECURITY.md with GitHub Security Advisories guidance (#472) * chore: switch to minor bump 1.2.0 (new APIs in #470) |
||
Antoine Lévêque
|
62c75203b6 |
Replace platform-specific optionalDependencies with bun devDependency (#518)
* 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. |
||
|
Olivier Chafik
|
5373f01d6f |
chore: bump ext-apps to 1.1.2 (#503)
* chore: bump ext-apps to 1.1.2 Changes since 1.1.1: - feat: add ui/download-file method for host-mediated file downloads (#475) - pdf-server: robust path validation + folder/file root support (#497) - ci: auto-fix prettier formatting in pre-commit hook and CI (#498) * fix: sync local SDK build into node_modules for examples npm workspaces hoists example dependencies to the root node_modules, but installs the published registry copy of @modelcontextprotocol/ext-apps instead of linking to the local source. This causes type-check failures when examples use features not yet published to npm. Add scripts/link-self.mjs which copies the freshly-built dist/ and package.json into the hoisted node_modules copy after each SDK build, ensuring examples always type-check against the latest local types. See: https://github.com/npm/feedback/discussions/774 * Revert "fix: sync local SDK build into node_modules for examples" This reverts commit e3387e8434f3def030f5a223a70632092c929119. |
||
|
Olivier Chafik
|
ec389f473b |
chore: bump ext-apps to 1.1.1 (#496)
Bug fixes / improvements since 1.1.0: - fix: add audio/video support for basic-host (#460) - fix(pdf-server): remove page-loading overlay (#493) - pdf-server: remove domain allowlist, require HTTPS only (#487) - Set audioSession.type to playback in sheet music app (#489) - Add MCPB packaging and Claude Code plugin for pdf-server (#491) |
||
|
Olivier Chafik
|
219b4b1605 |
fix(pdf-server): remove page-loading overlay (#493)
* fix(pdf-server): remove page-loading overlay The overlay had multiple issues: - Hardcoded white background broke dark mode - Could get stuck visible, breaking sizing/layout - Added little value since previous page stays visible during render and the 150ms delay meant most renders completed before it showed * prettier:fix |
||
|
Olivier Chafik
|
5bbf277882 |
chore: bump ext-apps to 1.1.0 (#485)
* chore: bump ext-apps to 1.1.0 Features: - registerAppResource now returns the registered resource (#370) - Accept UIResourceMeta in both resources/list and resources/read (#410) - callServerTool throws helpful error when called with a string (#449) - Add double-connect guard to prevent protocol message handling errors (#450) Bug fixes: - Only ignore messages that lack jsonrpc 2.0 in message-transport (#448) - Align basic-host dark mode styles (#438) Spec: - Change Host <> Sandbox communication protocol to SHOULD (#435) - Clarify UIResourceMeta in both list and read responses (#410) * fix(debug-server): add missing npm package config (main, bin, types, exports) Align debug-server package.json with all other server examples: - main: dist/server.js (was server.ts) - types: dist/server.d.ts - bin: mcp-server-debug -> dist/index.js - exports with types - files: only dist (remove source server.ts) |
||
Jonathan Hefner
|
5c4000bafd |
Upgrade typedoc-github-theme to v0.4.0 and remove local CSS workaround
v0.4.0 includes the typography fixes from upstream PR
JulianWowra/typedoc-github-theme#7, so the local `customCss` override
(`scripts/typedoc-github-theme-fixes.css`) added in
|
||
Ido Salomon
|
0278af6a2a |
examples: remove arcade (#414) | ||
|
Ido Salomon
|
2187bd4498 |
examples: add MCP Apps arcade server (#346) | ||
|
Olivier Chafik
|
605e31b6c5 |
chore: bump ext-apps to 1.0.1 (#369)
* chore: bump ext-apps to 1.0.1 * chore: update examples to depend on ext-apps ^1.0.1 * fix: revert examples to ext-apps ^1.0.0 and fix cheerio version - Revert ext-apps dependency to ^1.0.0 (works with 1.0.1 once published) - Fix accidental cheerio bump in wiki-explorer-server - Remove broken override attempt * fix: allow compatible semver ranges in version check The check-versions script now accepts any compatible semver range, not just exact version matches. For example, ^1.0.0 is allowed when root version is 1.0.1, since semver compatibility is maintained. * style: fix indentation in package.json |
||
|
Olivier Chafik
|
ae9b96e1fd |
chore: bump to 1.0.1 - fix npm reference for ext-apps dependency in examples + update zod to 4.x (#368)
* fix(examples): use npm reference for ext-apps dependency Replace local path '../..' with '^1.0.0' npm reference in all example packages. The local path was accidentally published to npm, causing npm install to hang when installing server-* packages. Bump versions to 1.0.1 for all public packages to fix the published versions. Fixes npm install hanging issue in dependent projects like example-remote-server. Note: npm workspaces automatically resolves the dependency to the local package during development, so no overrides are needed. * fix: update zod to 4.x in transcript-server and fix update-lock:docker script - Update transcript-server to use zod ^4.1.13 for compatibility - Fix update-lock:docker script to properly clean workspace node_modules - Regenerate package-lock.json with clean npmjs.org URLs |
||
|
Olivier Chafik
|
298e884ec3 |
chore: stable spec release 2026-01-26 and SDK v1.0.0 (#362)
* chore: add stable spec release 2026-01-26 - Use git mv to copy specification from draft to specification/2026-01-26/apps.mdx (preserves history) - Update status from 'Draft' to 'Stable (2026-01-26)' - Add specification version table to README - Update Resources section with links to both stable and draft specs * chore: bump version to 1.0.0 - Update main package version from 0.4.2 to 1.0.0 - Update all example package versions to 1.0.0 - Regenerate package-lock.json * prettier * chore: align protocol version with spec release 2026-01-26 - Add 'Protocol Version: 2026-01-26' to spec header - Update LATEST_PROTOCOL_VERSION from '2025-11-21' to '2026-01-26' - Update spec examples to use '2026-01-26' protocol version - Add '2025-11-21' to SUPPORTED_PROTOCOL_VERSIONS for backwards compatibility * chore: update spec references to stable 2026-01-26 - Update typedoc.config.mjs navigation link - Update docs/overview.md spec links (10 occurrences) - Update plugins/mcp-apps/skills/create-mcp-app/SKILL.md spec link - Update src/spec.types.ts @see links - Update AGENTS.md spec path - Regenerate src/generated/schema.ts with updated links * chore: simplify versioning - first stable release - Remove backwards compatibility version (2025-11-21) - this is the first stable release - Remove redundant 'Protocol Version' header - spec version IS the protocol version * chore: add history reference comment to stable spec |
||
|
Olivier Chafik
|
2d4311a25d |
chore: bump version to 0.4.2 (#334)
* Adding a simple (bad) pdf icon for directory (#330) * chore: bump version to 0.4.2 - Update package version from 0.4.1 to 0.4.2 - Pin @types/node to 22.10.0 for dev compatibility - Override seroval to ^1.4.1 to fix security vulnerabilities - Use '*' for workspace SDK dependency (works with unpublished versions) * fix(e2e): update Map Server display name to CesiumJS Map Server (#324) * fix(test): update map-server test to expect 'CesiumJS Map Server' The server name was renamed but the E2E test config was not updated. * fix: change in another file --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Olivier Chafik <ochafik@anthropic.com> * feat(server): add getUiCapability helper for capability negotiation (#313) * feat(server): add hasUiSupport/getUiCapability for experimental+extensions Support double-tagging for MCP Apps capability negotiation: - Check both experimental and extensions fields in client capabilities - Add hasUiSupport() to easily check if client supports MCP Apps - Add getUiCapability() to retrieve the capability settings - Update spec to document both capability locations This enables forward compatibility as MCP transitions from experimental to the extensions field (SEP-1724). Claude-Generated-By: Claude Code (cli/claude-opus-4-5=100%) Claude-Steers: 0 Claude-Permission-Prompts: 0 Claude-Escapes: 0 * fix: update @types/node version in package-lock.json Replace invalid 22.19.5/22.19.6/22.19.7 versions with valid 22.19.3 * docs(spec): clarify hosts SHOULD double-tag, servers SHOULD check both - Hosts SHOULD advertise capabilities in both experimental and extensions - Servers SHOULD check both locations, preferring extensions when present - Updated example to show double-tagging pattern * chore: remove double-tagging recommendation, keep hasUiSupport helper Reverts the spec changes that recommended clients double-tag capabilities in both experimental and extensions fields. The helper functions remain as they're useful for checking capability in either location. * refactor(server): simplify to only getUiCapability, remove hasUiSupport - Remove hasUiSupport function (use getUiCapability directly) - Remove double-tagging logic (only check extensions field) - Add ClientCapabilitiesWithExtensions type using SDK's ClientCapabilities - Update spec to use getUiCapability - Simplify tests * fix: update @see link to getUiCapability * refactor(server): inline ClientCapabilitiesWithExtensions type in getUiCapability * refactor: move McpUiClientCapabilities to spec.types.ts * fix: update playwright docker image to v1.58.0 * fix: use -i instead of -it for docker commands (no TTY needed) * fix: Python server dependency resolution and Docker host validation (#333) * fix(say-server): add --index flag to uv run for PyPI resolution The pocket-tts dependency wasn't resolving without explicit --index flag when invoked via npm scripts. * fix(qr-server): allow Docker bridge IP in transport security Add 172.17.0.1:* to allowed_hosts to fix 421 Misdirected Request errors when the server is accessed from Docker containers. * feat(basic-host): Add theme toggle and MCP style variables (#336) * feat(basic-host): add theme toggle and MCP style variables Add theme support to basic-host example: - theme.ts: Global theme manager with light/dark toggle - host-styles.ts: Full set of MCP CSS variables using light-dark() - ThemeToggle component with sun/moon icons - Theme-aware CSS using CSS custom properties - Pass theme + styles to apps via hostContext - Notify apps when theme changes via sendHostContextChange Apps now receive: - hostContext.theme: 'light' | 'dark' - hostContext.styles.variables: All 60+ MCP CSS variables - onhostcontextchanged notifications when theme changes * test: update e2e goldens for theme changes * [MCP Apps] Add appCapabilities.availableDisplayModes documentation to spec (#331) * Add appCapabilities.availableDisplayModes documentation to spec Document the availableDisplayModes field in McpUiAppCapabilities that allows apps to declare which display modes they support. This enables hosts to compute the intersection of host and app capabilities and only offer appropriate display mode controls. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Address PR review feedback - Change "Guest UI" to "View" terminology - Add "View" prefix to availableDisplayModes heading for disambiguation - Remove intersection logic - host only checks its own supported modes - Remove assumption that apps must support inline mode - Simplify host behavior to honor/reject based on its own capabilities 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add appCapabilities.availableDisplayModes to types - Add `availableDisplayModes` field to `McpUiAppCapabilities` so apps can declare which display modes they support - Change `HostContext.availableDisplayModes` type from `string[]` to `McpUiDisplayMode[]` for type safety - Regenerate schemas 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Address Olivier's feedback - consolidate display mode docs - Remove separate "App Capabilities" section for availableDisplayModes - Add display mode requirements to existing ui/request-display-mode section: - Host MUST NOT switch View to mode not in appCapabilities.availableDisplayModes - Host MAY decline requests from Views that didn't declare modes - View MUST declare supported modes during initialization 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Restore McpUiAppCapabilities docs and fix display mode clause - Restore McpUiAppCapabilities interface documentation with availableDisplayModes - Restore "View MUST check if the requested mode is in availableDisplayModes from host context" clause that was accidentally removed 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Create unified Display Modes section Consolidate all display mode documentation into a single section: - Display mode types (inline, fullscreen, pip) - Declaring support from View (appCapabilities.availableDisplayModes) - Declaring support from Host (HostContext.availableDisplayModes) - Requesting changes (ui/request-display-mode) - Notifying changes (ui/notifications/host-context-changed) - All MUST/SHOULD requirements for View and Host behavior The ui/request-display-mode in Requests section now references the Display Modes section for behavior details. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Remove mode coercion clause from display modes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Regenerate schemas with correct version 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> * feat(say-server): add light/dark theme support (#338) - Add importmap entry for main SDK exports (applyDocumentTheme, etc.) - Import and apply host theme and styles on context changes - Apply initial host context theme/styles when app connects - Update CSS to use [data-theme="dark"] selector for host-provided themes - Keep @media prefers-color-scheme as fallback for standalone mode - Add color-scheme meta tag for native element theming * fix: followup app -> view terminology (#339) * chore: husky env fix, version pins, update-lock:docker script (#341) * fix(husky): load Node.js env for GUI apps + add update-lock:docker script Cherry-picked non-e2e changes from ochafik/fix-e2e-flaky-tests: - Load nvm/fnm/volta/homebrew paths in pre-commit for GitHub Desktop - Add update-lock:docker script to regenerate lockfile with public registry * pin package versions for dev compatibility - solid-js: 1.9.10 - caniuse-lite: 1.0.30001763 - cheerio: 1.1.2 - electron-to-chromium: 1.5.267 - @playwright/test: 1.57.0 - playwright: 1.57.0 - playwright-core: 1.57.0 * regen * fix: pin @types/node to existing version and regenerate lockfile - Fix @types/node 20.19.28 -> 20.19.27 (typo, version didn't exist) - Regenerate package-lock.json to resolve versions available on both public npm and Anthropic artifactory registries * fix(basic-server-solid): bump solid-js 1.9.10 -> 1.9.11 to fix seroval vulnerabilities * fix: pin seroval to 1.4.1 for dev compatibility * Refactor server startup functions Rename `startServer` to `startStreamableHTTPServer` and add a new `startStdioServer` helper to make the transport type explicit. Remove the `ServerOptions` interface in favor of reading `PORT` directly from the environment inside the function (defaulting to `3001`). Also update Python examples to default to port `3001` for consistency. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Support full-file inclusion in synced code snippets Previously, the script only supported extracting regions from `.ts/.tsx` files using the `#regionName` syntax. Now it also supports including entire files without a region specifier, enabling sync of any file type (JSON, YAML, shell scripts, etc.) into documentation. Changes: - Make `#regionName` optional in the `source=""` attribute - Accept any fence language (not just `ts`/`tsx`) - Simplify cache to flat map with composite keys - Add validation error for region extraction on non-TypeScript files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Rewrite Quickstart guide with type-checked code examples Rewrites the Quickstart tutorial to provide a more focused, step-by-step introduction to building MCP Apps. The guide now uses synced code fences that pull from `examples/quickstart/`, ensuring all code shown in the documentation is type-checked and tested. Key improvements: - Clearer project setup instructions with explicit commands - Streamlined explanations of the tool + resource registration pattern - Added screenshot showing the completed app - E2E test coverage validates the example works end-to-end Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Add MCP Apps Overview document Adds `docs/overview.md` covering the core concepts: architecture, lifecycle, UI resources, bidirectional communication, theming, display modes, and security. Includes mermaid flowchart and sequence diagrams. Also adds the `@boneskull/typedoc-plugin-mermaid` TypeDoc plugin for mermaid diagram support. However, the plugin handles HTML entities from TypeDoc incorrectly, so `scripts/typedoc-plugin-fix-mermaid-entities.mjs` decodes HTML entities before the plugin processes them. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Add Agent Skills installation guide Add `docs/agent-skills.md` with installation instructions for multiple AI coding agents including Claude Code, VS Code/Copilot, Gemini CLI, Cline, and Goose. The guide provides three installation methods: Claude Code plugin, Vercel Skills CLI (`npx skills add`), and manual installation. Update `README.md` to link to the new guide and reframe the plugin section around the broader "Agent Skills" concept. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Polish OpenAI migration reference for readability Add framing prose to the migration guide to improve navigation: - Expanded intro describing document purpose and how to use it - Added note about features marked "Not yet implemented" - Added brief transition sentences before Server-Side and Client-Side sections Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Fix mermaid diagram arrowheads not rendering The `@boneskull/typedoc-plugin-mermaid` creates both dark and light theme variants of each diagram, each with identical marker IDs (e.g., `#arrowhead`). When mermaid renders SVGs at runtime, lines reference `url(#arrowhead)`, but the browser resolves this to the first match in document order — the hidden dark-theme SVG — causing arrows to be invisible. The fix removes dark-theme `<div class="mermaid dark">` elements at build time, leaving only one SVG per diagram with unique marker IDs. A CSS filter (`filter: invert(1) hue-rotate(180deg)`) handles dark mode styling instead. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): improve OpenAI migration guide accuracy (#349) - Add missing setOpenInAppUrl API to 'Not Yet in MCP Apps' section - Clarify Event Handling table: specify exact OpenAI properties (toolInput/toolOutput) instead of vague 'window.openai.*' - Improve notes to distinguish sync property reads vs callbacks * Add Testing MCP Apps guide Document how to test MCP Apps using `basic-host` and MCP Apps-compatible hosts like Claude.ai and VS Code Copilot. Cover debugging features for `basic-host`, and using `cloudflared` to expose local servers for remote hosts. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Fix `onhostcontextchanged` handler invocation in examples `App.onhostcontextchanged` is a setter-only property with no getter. TypeScript doesn't prevent reading from setter-only properties, so `app.onhostcontextchanged?.(ctx)` compiles but silently returns `undefined` at runtime. Extract the handler into a named `handleHostContextChanged()` function and call it directly after `connect()`, matching the pattern used in `basic-server-vanillajs` and other examples. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Expand Agent Skills guide Add intro explaining what Agent Skills are and link to the two skill files (`create-mcp-app`, `migrate-oai-app`). Reorganize headings and add "Invoke a Skill" and "Test Your App" sections. Update `README.md` link text and add tip to quickstart suggesting agent skills as an alternative. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(e2e): improve test stability and developer experience (#337) * fix(e2e): add masks for dynamic content and increase timeouts for slow servers - Add HOST_MASKS for Tool Input/Result panels with dynamic timestamps - Add say-server to SLOW_SERVERS (10s) for TTS model download - Add say-server to EXTRA_WAIT_MS (30s) in generate-grid-screenshots * feat: add update-lock:docker script to regenerate lockfile with public registry * pin package versions for dev compatibility * feat(basic-host): add ?theme=hide query param to hide theme toggle in screenshots - Add hideThemeToggle param to getQueryParams() - Conditionally render ThemeToggle based on ?theme=hide - Update e2e tests to use ?theme=hide for consistent screenshots * update screenshots * update screenshots * fix(husky): load Node.js environment for GUI apps like GitHub Desktop * fix(e2e): increase map-server wait time to 15s for tile loading * fix(e2e): increase waitForAppLoad timeout to 30s for nested iframe loading * ci: add workflow to update e2e snapshots * ci: trigger snapshot update on push to this branch * chore: update e2e snapshots [skip ci] * ci: trigger CI after snapshot update * style: fix prettier formatting in update-snapshots workflow * fix: pin seroval, seroval-plugins, and solid-js for dev compatibility --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> * Improve README structure and clarity Add "Why MCP Apps?" section to explain the motivation upfront. Reorganize the "How It Works" section to lead with tool definition. Rename "Overview" to "Using the SDK" and add "For" prefix to audience headings. Restructure the Examples section with clearer subsections for running examples with `basic-host` vs MCP clients using stdio transport. Move the `qr` server note outside the collapsed details block. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Add Codex and Goose to documentation Add Codex to the list of agents supporting skills in `agent-skills.md`. Add Goose to the list of supported clients in `testing-mcp-apps.md` and rename "VS Code Copilot" to "VS Code (Insiders)" for accuracy. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: regenerate lockfile with public registry, use ^0.4.2 for ext-apps deps * fix: update quickstart example to use workspace reference * chore: remove internal registry references from lockfile * feat(ci): add /update-snapshots comment trigger for PRs - Comment '/update-snapshots' on any PR to update E2E snapshots - Adds rocket reaction to acknowledge the command - Comments back with result (updated or no changes needed) - Removes hardcoded branch trigger - Keeps workflow_dispatch for manual runs * docs: document /update-snapshots PR comment trigger * fix: pin @hono/node-server to 1.19.7 for dev compatibility SDK 1.25.3 requires @hono/node-server@^1.19.9 which doesn't exist on the public npm registry (latest is 1.19.7). * fix: pin @modelcontextprotocol/sdk to 1.25.2 SDK 1.25.3 has broken dependency on @hono/node-server@^1.19.9 which doesn't exist on public npm registry. * fix: restore flexible SDK peerDep range (^1.24.0) devDependencies stays pinned to 1.25.2 for our builds, but peerDependencies should allow users flexibility. * fix: pin @types/node to avoid unpublished versions - Pin quickstart @types/node to 22.19.5 (latest public 22.x) - Add @types/node override to root package.json - Regenerate lockfile with public registry only --------- Co-authored-by: Tobin South <tobin.south@gmail.com> Co-authored-by: Liad Yosef <liady@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: martinalong <martinalong10@gmail.com> Co-authored-by: Ido Salomon <idosalomon@gmail.com> Co-authored-by: Jonathan Hefner <jonathan@hefner.pro> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> |
||
|
Olivier Chafik
|
e479497371 |
fix(e2e): improve test stability and developer experience (#337)
* fix(e2e): add masks for dynamic content and increase timeouts for slow servers - Add HOST_MASKS for Tool Input/Result panels with dynamic timestamps - Add say-server to SLOW_SERVERS (10s) for TTS model download - Add say-server to EXTRA_WAIT_MS (30s) in generate-grid-screenshots * feat: add update-lock:docker script to regenerate lockfile with public registry * pin package versions for dev compatibility * feat(basic-host): add ?theme=hide query param to hide theme toggle in screenshots - Add hideThemeToggle param to getQueryParams() - Conditionally render ThemeToggle based on ?theme=hide - Update e2e tests to use ?theme=hide for consistent screenshots * update screenshots * update screenshots * fix(husky): load Node.js environment for GUI apps like GitHub Desktop * fix(e2e): increase map-server wait time to 15s for tile loading * fix(e2e): increase waitForAppLoad timeout to 30s for nested iframe loading * ci: add workflow to update e2e snapshots * ci: trigger snapshot update on push to this branch * chore: update e2e snapshots [skip ci] * ci: trigger CI after snapshot update * style: fix prettier formatting in update-snapshots workflow * fix: pin seroval, seroval-plugins, and solid-js for artifactory compatibility --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> |
||
|
Jonathan Hefner
|
d856b8bda6 |
Add MCP Apps Overview document
Adds `docs/overview.md` covering the core concepts: architecture, lifecycle, UI resources, bidirectional communication, theming, display modes, and security. Includes mermaid flowchart and sequence diagrams. Also adds the `@boneskull/typedoc-plugin-mermaid` TypeDoc plugin for mermaid diagram support. However, the plugin handles HTML entities from TypeDoc incorrectly, so `scripts/typedoc-plugin-fix-mermaid-entities.mjs` decodes HTML entities before the plugin processes them. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> |
||
|
Jonathan Hefner
|
2109dccadb |
Rewrite Quickstart guide with type-checked code examples
Rewrites the Quickstart tutorial to provide a more focused, step-by-step introduction to building MCP Apps. The guide now uses synced code fences that pull from `examples/quickstart/`, ensuring all code shown in the documentation is type-checked and tested. Key improvements: - Clearer project setup instructions with explicit commands - Streamlined explanations of the tool + resource registration pattern - Added screenshot showing the completed app - E2E test coverage validates the example works end-to-end Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> |
||
|
Olivier Chafik
|
9557d41ce7 |
chore: husky env fix, version pins, update-lock:docker script (#341)
* fix(husky): load Node.js env for GUI apps + add update-lock:docker script Cherry-picked non-e2e changes from ochafik/fix-e2e-flaky-tests: - Load nvm/fnm/volta/homebrew paths in pre-commit for GitHub Desktop - Add update-lock:docker script to regenerate lockfile with public registry * pin package versions for dev compatibility - solid-js: 1.9.10 - caniuse-lite: 1.0.30001763 - cheerio: 1.1.2 - electron-to-chromium: 1.5.267 - @playwright/test: 1.57.0 - playwright: 1.57.0 - playwright-core: 1.57.0 * regen * fix: pin @types/node to existing version and regenerate lockfile - Fix @types/node 20.19.28 -> 20.19.27 (typo, version didn't exist) - Regenerate package-lock.json to resolve versions available on both public npm and Anthropic artifactory registries * fix(basic-server-solid): bump solid-js 1.9.10 -> 1.9.11 to fix seroval vulnerabilities |
||
|
Olivier Chafik
|
cfcbc9605f |
feat(server): add getUiCapability helper for capability negotiation (#313)
* feat(server): add hasUiSupport/getUiCapability for experimental+extensions Support double-tagging for MCP Apps capability negotiation: - Check both experimental and extensions fields in client capabilities - Add hasUiSupport() to easily check if client supports MCP Apps - Add getUiCapability() to retrieve the capability settings - Update spec to document both capability locations This enables forward compatibility as MCP transitions from experimental to the extensions field (SEP-1724). Claude-Generated-By: Claude Code (cli/claude-opus-4-5=100%) Claude-Steers: 0 Claude-Permission-Prompts: 0 Claude-Escapes: 0 * fix: update @types/node version in package-lock.json Replace invalid 22.19.5/22.19.6/22.19.7 versions with valid 22.19.3 * docs(spec): clarify hosts SHOULD double-tag, servers SHOULD check both - Hosts SHOULD advertise capabilities in both experimental and extensions - Servers SHOULD check both locations, preferring extensions when present - Updated example to show double-tagging pattern * chore: remove double-tagging recommendation, keep hasUiSupport helper Reverts the spec changes that recommended clients double-tag capabilities in both experimental and extensions fields. The helper functions remain as they're useful for checking capability in either location. * refactor(server): simplify to only getUiCapability, remove hasUiSupport - Remove hasUiSupport function (use getUiCapability directly) - Remove double-tagging logic (only check extensions field) - Add ClientCapabilitiesWithExtensions type using SDK's ClientCapabilities - Update spec to use getUiCapability - Simplify tests * fix: update @see link to getUiCapability * refactor(server): inline ClientCapabilitiesWithExtensions type in getUiCapability * refactor: move McpUiClientCapabilities to spec.types.ts |
||
|
Olivier Chafik
|
8a877b36b4 |
feat(debug-server): add interactive debug server example (#321)
* feat(examples): add debug-server example A comprehensive debug/development server for testing MCP Apps SDK features: - Vanilla TypeScript UI with collapsible panels - Message visualization (sent, received, errors) - Server tool calling interface - Multiple tool endpoints for testing * refactor(debug-server): convert to React - Replace vanilla TypeScript with React components - Add comprehensive Host Styles panel showing all CSS variables grouped by category - Use React hooks (useApp, useHostStyles, useAutoResize) - Cleaner state management with useReducer for event log - Collapsible sections for better organization - CSS modules for scoped styling * fix(debug-server): correct server name in main.ts * Revert "refactor(debug-server): convert to React" This reverts commit 5d22d2daa9a98ba412892447202ef10fbdb62f5b. * fix(debug-server): update default values for multipleBlocks and includeMeta * fix(debug-server): correct serve script and server name - serve script now runs main.ts instead of server.ts - Updated server name to 'Debug Server' - Fixed npx command in comment * fix: increase maxHeight to 6000px and add tools capability to debug app - basic-host: Increase maxHeight from 600 to 6000px - debug-server: Add tools capability to enable oncalltool/onlisttools handlers * fix(debug-server): use consistent callback names for event tracking Event types now match callback names (ontoolinput, ontoolresult, etc.) so the Callback Status panel shows correct counts and payloads. * feat(debug-server): add Update (Image) button for model context * feat(debug-server): add expandable event log entries - Click on any event log row to expand/collapse - Arrow indicator rotates when expanded - Full JSON payload shown indented in pre block - Max height with scroll for large payloads * style(debug-server): format long line in fullPayload function * test(debug-server): add to E2E tests and screenshot specs * chore: regenerate package-lock.json for cross-platform compatibility * update dep |
||
|
Jonathan Hefner
|
eb803723ef |
Use typedoc-github-theme for API documentation
Configure TypeDoc to use the GitHub-styled theme for better visual consistency with the project's GitHub presence. Also reorganize the config options and enable group navigation for improved documentation structure. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> |
||
dependabot[bot]
|
43c30a7665 |
build(deps): bump the npm_and_yarn group across 1 directory with 2 updates (#284)
Bumps the npm_and_yarn group with 1 update in the / directory: [svelte](https://github.com/sveltejs/svelte/tree/HEAD/packages/svelte). Updates `svelte` from 5.46.3 to 5.46.4 - [Release notes](https://github.com/sveltejs/svelte/releases) - [Changelog](https://github.com/sveltejs/svelte/blob/main/packages/svelte/CHANGELOG.md) - [Commits](https://github.com/sveltejs/svelte/commits/svelte@5.46.4/packages/svelte) Updates `devalue` from 5.6.1 to 5.6.2 - [Release notes](https://github.com/sveltejs/devalue/releases) - [Changelog](https://github.com/sveltejs/devalue/blob/main/CHANGELOG.md) - [Commits](https://github.com/sveltejs/devalue/compare/v5.6.1...v5.6.2) --- updated-dependencies: - dependency-name: svelte dependency-version: 5.46.4 dependency-type: direct:production dependency-group: npm_and_yarn - dependency-name: devalue dependency-version: 5.6.2 dependency-type: indirect dependency-group: npm_and_yarn ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> |
||
|
Olivier Chafik
|
e6983b36d0 |
feat(examples): add say-server - streaming Pocket TTS with karaoke highlighting (#304)
* Add say-server: streaming TTS MCP App with karaoke UI - Streaming TTS MCP App with real-time word highlighting - React widget with pause/resume controls - Debounced model context updates - Self-contained server.py for standalone uv run Co-authored-by: Claude <noreply@anthropic.com> * Update server.py * fix(say-server): fix React/Zod version conflicts in widget - Pin Zod to v3.25.1 via esm.sh deps param (fixes .custom() error) - Add external=react,react-dom to prevent duplicate React instances - Update React from 19.1.0 to 19.2.0 - Import React for Babel's classic JSX transform - Consolidate imports: only use @modelcontextprotocol/ext-apps/react - Use Babel from unpkg.com instead of esm.sh - Simplify resource decorator with meta= parameter - Update CSP to allow both esm.sh and unpkg.com * fix(say-server): show play button when paused, restart when finished * feat(say-server): add fullscreen button, remove inline scroll - Add fullscreen toggle button (appears on hover when available) - Remove max-height/scroll in inline mode for cleaner display - Enable scrolling only in fullscreen mode - Track displayMode and fullscreenAvailable state - Handle onHostContextChanged to detect fullscreen support * fix(say-server): fix fullscreen button visibility and prevent multiple audio streams - Check initial host context for fullscreen availability (not just updates) - Add audioOperationInProgressRef guard to prevent concurrent audio operations - Prevents race conditions from rapid clicks/double-clicks * fix(qr-server): use meta parameter instead of manual handler patching Simplified CSP metadata handling to match say-server's approach: - Use meta parameter on @mcp.resource decorator directly - Removed custom _read_resource_with_meta handler and handler replacement * fix(say-server): simplify controls to prevent multiple audio streams - Remove onClick from text display (was conflicting with double-click) - Always show overlay button (with pause icon when playing) - Lower opacity (0.3) when playing, full on hover - Button shows: ▶️ (play), ⏸️ (pause), 🔄 (restart) - Double-click text to restart still works - Eliminates click/dblclick race condition * fix(say-server): only show pause button on hover - Play/restart buttons visible normally - Pause button hidden until hover (doesn't block karaoke text) * fix(say-server): fix partial input handling and session management - Add promise lock to initTTSQueue to prevent concurrent initialization - Reset queueIdRef and lastTextRef in ontoolresult for next tool call - Close existing AudioContext when starting new session - Reset all playback state (chunks, timings, position) on new session - Fixes: text deltas not sent when new tool call has shorter text * fix(say-server): detect new sessions by text comparison, not queueIdRef reset - Don't reset queueIdRef in ontoolresult - audio should keep playing - Detect new sessions in ontoolinputpartial/ontoolinput by checking if new text starts with lastTextRef (continuation) or not (new session) - Only reset and create new queue when genuinely new session detected - Fixes: pause/play was creating new streams because queueIdRef was reset * feat(say-server): add theming, floating button, and keyboard shortcuts Theming: - Use CSS variables (--font-sans, --color-text-primary/secondary) with fallbacks - Apply host fonts via applyHostFonts() on connect and context changes - Apply host style variables via applyHostStyleVariables() - Apply document theme via applyDocumentTheme() Floating button: - Button follows cursor position (below current line being spoken) - Uses invisible cursor marker element for accurate positioning - Shows ⏸️ when playing, ▶️ when paused, 🔄 when finished - Low opacity when playing, full on hover Keyboard shortcuts: - Space: toggle play/pause - Enter: toggle fullscreen (when available) UI changes: - Large overlay only shown for initial play (idle state) - Floating button used during playback for less intrusive controls * docs(say-server): add TODO items for future improvements * fix(say-server): simplify to fixed play button at top right - Remove floating cursor-following button (was too complex) - Fixed play button at top-right corner - Low opacity when playing, full on hover - Keep theming and keyboard shortcuts (Space/Enter) - Add say-server to E2E tests * test(e2e): add say-server to tests but skip in CI Say-server requires Pocket TTS model (~500MB) and GPU support, which isn't available in the Docker CI environment. Skip it for now. * test(e2e): add say-server and qr-server to screenshot generation - Remove say-server from SKIP_SERVERS (widget works without TTS model) - Add say-server masks for play buttons - Add both say-server and qr-server to grid screenshot generator * fix(say-server): restore working play/pause overlay, keep theming and keyboard shortcuts Reverted to working commit 413beca and carefully reapplied: - CSS variables for theming (--font-sans, --color-text-primary/secondary) - Dark mode support via @media (prefers-color-scheme) - Host theming via applyHostStyleVariables/applyHostFonts/applyDocumentTheme - Keyboard shortcuts: Space = play/pause, Enter = fullscreen Preserved working behavior: - Play overlay visible when not playing, hover to show when playing - Pause on click works correctly - Karaoke highlighting works * fix(say-server): minimal CSS-only theming, no JS changes from working version Only CSS changes from working commit 413beca: - Added CSS variables for theming foundation - No JavaScript changes (reverted theming calls and keyboard shortcuts) This isolates whether the issue is CSS or JS related. * feat(say-server): add autoPlay param and Reset button - Add autoPlay parameter (default: true) with Pydantic Field description - Description visible in MCP tool schema: 'browsers may block autoplay' - Add Reset button next to Fullscreen button (bottom right) - Both buttons share controlBtn base styles, shown on hover - Widget reads autoPlay from tool input params * fix(say-server): update FastMCP API for new SDK version Python SDK refactored transport params from constructor to run(): - Remove port, stateless_http from FastMCP() constructor - Pass stateless_http=True to streamable_http_app() instead * debug(say-server): add console logs to trace audio stream issue Logging added to: - togglePlayPause (all branches) - initTTSQueue (entry and AudioContext creation) - restartPlayback (entry) - ontoolinputpartial/ontoolinput (entry and new session detection) Open browser DevTools console and reproduce the issue - logs will show what's being called. * feat(say-server): add play/pause buttons in top-left and bottom-right corners - Top left: playPauseTopBtn for quick access - Bottom right: playPauseBtn alongside reset and fullscreen - Both show on hover with same styling as other control buttons - Icons: ▶️ (play), ⏸️ (pause), 🔄 (restart when finished) * fix(say-server): simplify UI and fix pause/resume audio duplication - Remove central play overlay, use single toolbar in top-right - Fix audio duplication on pause/resume (only defer to pendingChunks for initial autoplay) - Remove double-click to restart (use toolbar restart button) - Sync displayMode when host changes it externally - Click on text to play/pause * feat(say-server): add voice selection support - Add list_voices tool to show available voices - Add voice parameter to say tool (predefined names, HuggingFace URLs, or local paths) - Predefined voices: alba, marius, javert, jean, cosette, eponine, azelma, fantine - Update README with voice documentation * docs(say-server): improve tool description for better LLM triggering - Add English-only constraint prominently in first line and note - List common trigger patterns (say, speak, read aloud, etc.) - Update text parameter description to mention English - Keep description concise for quick LLM scanning * feat(say-server): add speak lock for multi-widget coordination When multiple TTS widgets exist, only one plays at a time: - Widget announces to localStorage when starting playback - Playing widgets poll localStorage every 200ms - If another widget starts, previous one pauses automatically - Lock is cleared on pause/finish/teardown Uses _meta.widgetUUID in tool result for widget identification. * update package.json of say * feat(say-server): add screenshots and update README gallery - Add say-server to demo gallery with 300x300 grid-cell.png - Fix qr-server grid-cell.png dimensions (was 672x668, now 300x300) - Add golden snapshot for say-server E2E tests - Add full screenshot and grid-cell thumbnail for say-server 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * style(say-server): apply prettier formatting - Add blank lines in README for better readability - Add trailing newline to package.json 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(say-server): add Escape key to exit fullscreen and update docs - Add onKeyDown handler to main element for Escape key - Update README with full list of MCP App features: - Model context updates - Native theming - Fullscreen mode - Multi-widget speak lock - Update server.py docstring with feature documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(say-server): add queue timeout to prevent infinite polling The TTS queue could hang forever if: - The LLM stops generating mid-stream (no end signal) - User cancels before tool completes - Network interruption prevents end_tts_queue call Changes: - Add last_activity timestamp to track queue activity - Add 30-second timeout (QUEUE_TIMEOUT_SECONDS) - Poll with 5-second timeout, checking for stale queues - Mark stale queues as "error" so widget stops polling - Return error message in poll_tts_audio response - Add error logging in widget polling loop This prevents tool calls from running forever when queues are abandoned. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * debug(say-server): add logging to track queue lifecycle Add console logging to debug why end_tts_queue might not be called: Widget-side: - Log queueId in ontoolinputpartial, ontoolinput, ontoolresult - Log when new session is detected (queue reset) - Log when initTTSQueue fails - Log when end_tts_queue is called/not called Server-side: - Log when end_tts_queue is called - Log warnings for unknown queues - Log info for already-ended queues This will help identify if the issue is: - User interruption (ontoolresult never called) - Session reset (queueId becomes null) - Host bug (callback dropped) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * perf(say-server): add initial delay before polling Add 150ms delay before first poll to give TTS model time to generate the first audio chunk. This reduces unnecessary polling and server load. Current backoff after that: - 30ms if chunks received (keep streaming fast) - 80ms if no chunks (wait longer for generation) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(say-server): use adaptive polling instead of fixed initial delay Previous approach: Always wait 150ms before first poll Problem: Even when chunks are ready, we wait unnecessarily New approach: Adaptive polling - Start polling immediately (no initial delay) - 20ms backoff when receiving chunks (fast streaming) - Exponential backoff when no chunks: 50ms → 100ms → 150ms max - Reset backoff when chunks start flowing This reduces latency when TTS is fast while being polite when it's slow. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(say-server): add speaker icon to server info Uses SVG data URI for a speaker with sound waves icon. * docs(say-server): add comprehensive third-party licensing information - Expand License section in README with component attribution table - Add voice collection license matrix with commercial use indicators - Add warning about non-commercial expresso/ears voice collections - Clarify NON-COMMERCIAL restriction in list_voices() output - Use consistent CC-BY formatting (hyphenated) * Update last activity to prevent timeout during active polling * feat(say-server): add info button, SVG icons, and UI fixes - Replace emoji play/pause buttons with neutral white SVG icons - Add (i) info button in bottom-right with attribution popup - Use app.openLink() API for external links in popup - Add dynamic padding to fit popup when shown - Make create_tts_queue async to fix AnyIO event loop error - Add better error logging for TTS queue initialization - Update README with openLink feature documentation - Remove unnecessary HuggingFace login prerequisites * docs(say-server): document multi-widget speak lock mechanism * prettier:fix --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Olivier Chafik
|
8c3b1daf7e |
chore: bump version to 0.4.1 (#282) | ||
Anton Pidkuiko
|
be8d725974 |
Merge pull request #272 from modelcontextprotocol/uv-qr-server
feat(qr-server): migrate to uv with PEP 723 inline dependencies |
||
Jerome
|
65a62a9fae |
feat: compile example servers to JavaScript for npm consumption (#259)
* feat: compile example servers to JavaScript for npm consumption
Add TypeScript compilation for server code so the example packages can be
imported and used by consumers without requiring TypeScript compilation.
Changes:
- Add tsconfig.server.json to each example for compiling server code
- Update package.json exports to point to compiled dist/server/server.js
- Add types field pointing to dist/server/server.d.ts
- Update build scripts to include server compilation step
- Fix .ts import extensions to .js in customer-segmentation-server
This enables importing the createServer function from published packages:
import { createServer } from '@modelcontextprotocol/server-basic-react';
* fix: add type assertion for Nominatim API response
* chore: regenerate schemas
* refactor: split server examples into library and binary entry points
- server.ts: exports createServer() only (library entry point)
- main.ts: entry point with main() that runs the server (binary)
- package.json: adds bin field for npx support, uses inline bun build
- tsconfig.server.json: emitDeclarationOnly, outputs to dist/
This allows:
1. Importing the server as a library: import { createServer } from '@modelcontextprotocol/server-basic-react'
2. Running with npx: npx @modelcontextprotocol/server-basic-react [--stdio]
Added migration script at scripts/migrate-server-examples.ts
* refactor: migrate remaining server examples to library/binary structure
Apply the same refactoring to all 13 remaining server examples:
- scenario-modeler-server, shadertoy-server, map-server
- cohort-heatmap-server, customer-segmentation-server, video-resource-server
- system-monitor-server, budget-allocator-server, sheet-music-server
- threejs-server, integration-server, transcript-server, wiki-explorer-server
Each now has:
- server.ts: exports createServer() (library)
- main.ts: runs the server (binary with shebang)
- bin field in package.json for npx support
* chore: remove unused server-utils.ts from video-resource-server/src
* update
* fix(build): make Windows-compatible by removing chmod and fixing bun externals
- Remove 'chmod +x dist/index.js' which doesn't exist on Windows
- Add '--external ./server.js' to prevent bun from treating the import as a second entry point
* fix(build): use .ts import for bun compatibility
- Change import from './server.js' to './server.ts' in main.ts files
- Remove --external flag since bun should inline everything
- Fixes Windows build where bun couldn't resolve .js to .ts properly
* fix(build): use --external for Windows bun compatibility
Bun on Windows incorrectly treats imported .ts files as entry points.
Use --external './server.js' to work around this, creating a runtime
dependency between index.js and server.js.
* style: fix prettier formatting in pdf-server/main.ts
* fix(build): remove quotes from --external for Windows cmd.exe compatibility
* fix(build): use glob pattern for --external to work on all platforms
The literal path --external ./server.js was not matching the import.
Using glob pattern --external "./server*" correctly externalizes the server module.
* fix(build): use */server.js pattern for --external
The "./server*" pattern was not matching on Windows.
Using "*/server.js" matches any path ending in /server.js which works cross-platform.
* fix(build): use *server.js pattern without slash for Windows compatibility
* update package-lock
* chore: regenerate package-lock.json for cross-platform compatibility
* fix(build): use ./server.js instead of glob pattern for Windows compatibility
* fix(build): use double quotes for banner to fix Windows cmd.exe compatibility
---------
Co-authored-by: Olivier Chafik <ochafik@anthropic.com>
|
||
Anton Pidkuiko MacBook
|
0927445025 |
feat(qr-server): migrate to uv with PEP 723 inline dependencies
- Replace requirements.txt with inline script dependencies in server.py - Add package.json with npm scripts for run-all.ts integration - Update CI workflow to install uv via astral-sh/setup-uv@v5 - Update Docker commands to install uv for e2e tests - Add Playwright golden screenshot for qr-server - Update README with uv installation and usage instructions |
||
|
Olivier Chafik
|
96daa46a1d |
examples: add PDF viewer w/ chunked data loading, full-screen, model context updates, private tool (#267)
* feat(pdf-server): Interactive PDF viewer example
PDF viewer with PDF.js featuring:
- Chunked binary loading with progress bar
- Text extraction for AI context
- arXiv paper support (fetch by ID)
- Page navigation with keyboard shortcuts
- Zoom controls (including Ctrl+0 reset)
- Fullscreen mode support
- Horizontal swipe for page changes (disabled when zoomed)
- Page persistence in localStorage
- Text selection via PDF.js TextLayer
- Clickable title link to source URL
- Rounded corners and subtle border styling
* chore: Add pdf-server to screenshot generation list
* refactor(pdf-server): Simplify and generalize PDF loading
- Accept any HTTP(s) URLs instead of ArXiv-only
- Use HTTP Range requests for chunked binary loading
- Remove ArXiv-specific code (arxiv.ts, metadata fetching)
- Remove CLAUDE.md index generation
- Flatten hierarchical folder structure to simple entries list
- Remove dead code: getPdfSummary, httpFileSizes
- Simplify base64 encoding using Buffer
- Simplify chunk extraction using slice()
- Consolidate DEFAULT_PDF_URL constant
The server now works with any PDF URL, not just arXiv papers.
HTTP Range requests stream chunks on-demand when supported.
* feat(pdf-server): Include title and selection in model context
- Add pdfTitle to updateModelContext structuredContent
- Include selection position (text, start, end) when text is selected
- Add debounced selectionchange listener to update context on selection
* fix(pdf-server): Restore default URL in view_pdf schema
The UI needs the default value in the schema to show it properly.
* refactor(pdf-server): Further simplifications
- Remove hard-coded test paths from main()
- Remove unused resources: pdfs://metadata/{pdfId}, pdfs://content/{pdfId}
- Remove unused metadata fields: subject, creator, producer, creationDate, modDate
- Remove unused entry fields: relativePath, estimatedTextSize
- Remove filterEntriesByFolder and folder filter from list_pdfs
- Remove redundant output schema validation (trust typed returns)
- Simplify scanDirectory and createLocalEntry signatures
Total: 1836 → 1666 lines (-170 lines, -9%)
* refactor(pdf-server): Major simplification for didactic focus
Simplified the example to focus on key MCP Apps SDK patterns:
- Chunked data through size-limited tool calls
- Model context updates (page text + selection)
- Display modes (fullscreen vs inline)
- External links (openLink)
Changes:
- Remove local file support (HTTP URLs only)
- Restrict dynamic URLs to arxiv.org for security
- Simplify types: url instead of sourcePath/sourceType
- Simplify indexer: 168 → 44 lines
- Simplify loader: 318 → 171 lines
- Simplify server: 337 → 233 lines
- Fix selection text normalization
- Rewrite README with didactic focus
Total: 1836 → 1236 lines (-33%)
* feat(pdf-server): Add file:// URL support for local files
- Local paths are converted to file:// URLs on startup
- file:// URLs must be in the initial list (strict validation)
- Dynamic URLs still restricted to arxiv.org only
- Updated README with local file examples
* fix(pdf-server): Improve selection detection with logging
- Add logging to selectionchange handler to verify it fires
- Add fallback matching without spaces (TextLayer spans may lack spaces)
- Log selection detection success/failure for debugging
The issue: PDF.js TextLayer renders text as positioned spans without
space characters between them. When selecting across spans:
- pageText has spaces (items joined with ' ')
- sel.toString() may not have spaces
- indexOf fails to match
The fix tries exact match first, then falls back to spaceless matching.
* feat(pdf-server): Format model context as markdown with front matter
Model context now looks like:
```markdown
---
url: https://arxiv.org/pdf/...
page: 5/144
---
Page text with <pdf-selection>selected text</pdf-selection> inline.
```
This is cleaner for the model to parse and includes the source URL.
* refactor(pdf-server): Extract smart truncation helpers
Added two well-designed helpers:
formatPageContent(text, maxLength, selection?)
- Centers truncation window around selection if present
- Adds <truncated-content/> markers at elision points
- Wraps selection in <pdf-selection> tags
- Allocates 60% context before, 40% after for readability
findSelectionInText(pageText, selectedText)
- Tries exact match first
- Falls back to spaceless match for TextLayer quirks
- Returns { start, end } or undefined
Example output with selection:
```
<truncated-content/>
...context before... <pdf-selection>selected text</pdf-selection> ...context after...
<truncated-content/>
```
* fix(pdf-server): Truncate inside selection tags when selection too long
When selection is too large for the budget:
<truncated-content/><pdf-selection><truncated-content/>start...end<truncated-content/></pdf-selection><truncated-content/>
This keeps the selection structure intact while showing beginning and end.
* refactor(pdf-server): Remove unused read_pdf_text, use Attention paper as default
- Remove read_pdf_text tool (viewer extracts text client-side with pdfjs)
- Remove PdfTextChunk and ReadPdfTextInput types
- Remove loadPdfTextChunk from pdf-loader
- Change default PDF to 'Attention Is All You Need' (1706.03762)
- Update README with modest language
* refactor(pdf-server): Simplify to use URL as ID, rename view_pdf to display_pdf
Major simplifications:
- Use URL directly as identifier (no hashing)
- Remove displayName - show elided URL with full URL as tooltip
- Rename view_pdf to display_pdf with better description
- Update all references from pdfId to url
- Simplify storage key and model context
The tool description now explains it displays an interactive viewer in the chat.
* feat(pdf-server): Normalize arxiv URLs to PDF format
arxiv.org/abs/... -> arxiv.org/pdf/...
Applied both at startup and when loading dynamic URLs.
* docs(pdf-server): Add prompt engineering to display_pdf description
* fix(pdf-server): Sharp rendering on retina displays
Account for devicePixelRatio when rendering canvas:
- Scale canvas dimensions by dpr
- Scale context by dpr
- Keep CSS size at logical pixels
* fix(pdf-server): Normalize arxiv URLs in read_pdf_bytes too
* add to e2e spec
* add to e2e spec
* add to e2e spec
* add to e2e spec
* regen
* chore: regenerate package-lock.json and fix hono vulnerability
* docs: add pdf-server screenshot to READMEs
* regen
* ci: add missing examples to pkg-pr-new publish
* ci: add pdf-server to npm publish examples
* Update README.md
* pdf-server: improve tool response text for better model context
* revert unrelated screenshot changes
* pdf-server: dynamically add arxiv URLs in read_pdf_bytes
Fixes 'PDF not found' error when server restarts between display_pdf
(which adds the entry) and read_pdf_bytes (which previously only looked
up existing entries). Now read_pdf_bytes mirrors display_pdf's logic
and dynamically adds arxiv URLs to the index.
|
||
|
dependabot[bot]
|
631090f41e |
build(deps): bump hono in the npm_and_yarn group across 1 directory (#268)
Bumps the npm_and_yarn group with 1 update in the / directory: [hono](https://github.com/honojs/hono). Updates `hono` from 4.11.3 to 4.11.4 - [Release notes](https://github.com/honojs/hono/releases) - [Commits](https://github.com/honojs/hono/compare/v4.11.3...v4.11.4) --- updated-dependencies: - dependency-name: hono dependency-version: 4.11.4 dependency-type: indirect dependency-group: npm_and_yarn ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> |
||
|
Olivier Chafik
|
574a768e09 |
feat: add example gallery with auto-generated screenshots (#253)
* feat: add script to generate 300x300 grid-cell.png screenshots for examples
- Add generate-grid-screenshots.spec.ts Playwright test to capture screenshots
- Add npm run generate:screenshots command (Docker-based for Santa compatibility)
- Add sharp dependency for image resizing with centered-fill mode
- Generate grid-cell.png for 14 example servers (only React for basic-server-* series)
The screenshots are 300x300 PNG images cropped with centered fill mode,
suitable for use in a grid layout showcasing the examples.
* docs: add example gallery grid to README
Add a 3-column visual grid showcasing 14 example MCP Apps with:
- Thumbnail screenshots (300x300 grid-cell.png)
- Clickable links to example directories
- Hover tooltips with brief descriptions
Organized by visual impact: 3D/WebGL examples first, then
visualizations, charts, monitoring, and starter templates.
* fix: use aspect-fit instead of crop for screenshots
Change from fit: 'cover' (crops) to fit: 'contain' (letterbox)
so the full app content is visible without cropping.
* feat: improve screenshot generation
- Constrain viewport to 500px width for consistent rendering
- Wait 5 seconds for full app load (tiles, animations, data)
- Screenshot just the inner iframe (no extra whitespace)
- Save both screenshot.png (full-size) and grid-cell.png (300x300 thumbnail)
- Use contain mode to preserve aspect ratio
* fix: use cover mode with top alignment for grid thumbnails
No letterboxing - crops to fill 300x300, aligned to top so headers
and important content are always visible.
* feat: improve screenshot gallery
- Remove integration-server from gallery (it's for E2E testing only)
- Add 30s extra wait for Map and Video servers to load fully
- Improve Three.js default scene: isometric rotation + better lighting
- Update README: Starter Templates row with links to all framework variants
(React, Vue, Svelte, Preact, Solid, Vanilla JS)
- Regenerate all screenshots with updated settings
* fix: improve README gallery layout
- Fix uneven column widths by using minimal separator
- Move Starter Templates to separate 2-cell table with description
- Add screenshot.png to top of each example README (13 examples)
- Shorten tooltips for cleaner table
* revert to document.write again; cesiumjs doesn't like srcdoc, period.
* fix: map-server screenshot now renders properly
- Merged ochafik/post-fixes which reverts sandbox from srcdoc to document.write
(CesiumJS doesn't work with srcdoc iframes)
- Fixed map-server name in screenshot test ('Map Server' not 'CesiumJS Map Server')
- Simplified screenshot generation script (removed complex debugging code)
- Increased map-server wait time to 45s for reliable tile loading
- Regenerated all 13 screenshots
* fix: remove redundant screenshots from READMEs
Remove the simple \ line from READMEs that
already had nicer HTML table screenshots. Keep it only for examples
that didn't have existing screenshots.
* docs: move gallery to Examples section
- Move screenshot gallery from top of README to Examples section
- Remove redundant list of basic examples (now shown visually in gallery)
- Clean up duplicate run instructions
* fix: remove empty header row from starter templates table
* fix: remove empty header rows from both tables
* fix: add prettier-ignore to prevent table header expansion
* feat: use custom screenshot for video-resource-server
- Use better screenshot from PR #253 comment showing actual video playback
- Skip video-resource-server in screenshot generation script
- Add SKIP_SERVERS set for manually maintained screenshots
* fix: revert unrelated map-server name change
* fix: use correct server name 'CesiumJS Map Server' in screenshot test
|
||
|
Olivier Chafik
|
231f23fd72 |
chore: release 0.4.0 (#249)
* chore: release 0.4.0 * chore: add new examples to npm publish workflow Add map-server, shadertoy-server, and transcript-server to the publish-examples matrix. |
||
|
Olivier Chafik
|
ba550f1aeb |
fix: follow-up to PR #234 (remove accidental file, revert from document.write to equiv. srcdoc) (#248)
* chore: remove tamper-detection.ts (not meant to be submitted) Follow-up to PR #234. This file was accidentally included. * revert to srcdoc Follow-up to PR #234 per domfarolino's review feedback. * regen * regen |
||
|
Olivier Chafik
|
6bb63c3bae |
examples: add transcript-server example with live speech transcription (#240)
* feat: add transcript-server example with live speech transcription - New example: transcript-server with Web Speech API transcription - Start/stop recording with timer display - Live transcript with interim results - Send button to send transcript as ui/message to host - Copy button to copy full transcript - Sent messages marked with divider, greyed out - Experimental ui/update-model-context for live context updates - Transparent background, respects host theme - Enable microphone and clipboard in basic-host sandbox iframes - Add allow="microphone; clipboard-write" to both outer and inner iframes - Required for Web Speech API, audio capture, and clipboard access - Add alert popup in basic-host for ui/message from apps 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * style: format transcript-server files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * test: add e2e test and golden for transcript-server 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor: use @types/dom-speech-recognition instead of hand-rolled types Removes ~50 lines of manually defined Web Speech API types in favor of the community-maintained type package. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: add newlines between transcript chunks when copying to clipboard * refactor: unify transcript formatting with timestamps - Add formatEntry() helper that includes [timestamp] prefix - Add formatEntries() helper that joins entries with newlines - Use same format for clipboard copy, send message, and model context - DRY up duplicate code in send button handler * fix: log model context update failures instead of silently swallowing * fix: log model context updates for debugging * refactor: pass permissions through loadSandboxProxy like csp - Add permissions parameter to loadSandboxProxy in implementation.ts - Build iframe allow attribute from permissions instead of hardcoding - Update sandbox.ts to not hardcode allow attribute (set via notification) - Add microphone + clipboardWrite permissions to transcript-server resource - Update README to reflect permission configuration via resource _meta.ui * fix(transcript-server): auto-expand instead of scroll - Remove min-height: 100vh and overflow-y: auto - Let content grow naturally with autoResize (default) - Remove unnecessary scrollTop calls * test: remove transcript timer mask (no longer dynamic) * refactor: pass permissions through loadSandboxProxy like csp * docs: document updateModelContext for transitional speech * test: update e2e screenshots * refactor: use app.updateModelContext() instead of raw request * package-lock.json * src/generated/schema.json * test: update e2e screenshots from CI --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> |
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
3cf5b588a1 |
||
|
|
0008d3b78f |
||
|
|
64b4fa16de |
||
|
|
989ddc7568 |
||
|
|
3fb521b71f |
||
|
|
01d826aea0 |
||
|
|
621a70a724 |
||
|
|
9da4a75ff6 |
||
|
|
9757f35fd1 |
||
|
|
8e7206cb15 |
||
|
|
f987bc43b2 |
||
|
|
14969c5da2 |
||
|
|
e8ca859429 |
||
|
|
6723c8ff10 |
||
|
|
296b5921fb |
||
|
|
704b6e0af9 |
||
|
|
e13732ad38 |
||
|
|
bf623f832d |
||
|
|
6b12fff1d0 |
||
|
|
62c75203b6 |
||
|
|
5373f01d6f |
||
|
|
ec389f473b |
||
|
|
219b4b1605 |
||
|
|
5bbf277882 |
||
|
|
5c4000bafd |
||
|
|
0278af6a2a |
||
|
|
2187bd4498 |
||
|
|
605e31b6c5 |
||
|
|
ae9b96e1fd |
||
|
|
298e884ec3 |
||
|
|
2d4311a25d |
||
|
|
e479497371 |
||
|
|
d856b8bda6 |
||
|
|
2109dccadb |
||
|
|
9557d41ce7 |
||
|
|
cfcbc9605f |
||
|
|
8a877b36b4 |
||
|
|
eb803723ef |
||
|
|
43c30a7665 |
||
|
|
e6983b36d0 |
||
|
|
8c3b1daf7e |
||
|
|
be8d725974 |
||
|
|
65a62a9fae |
||
|
|
0927445025 |
||
|
|
96daa46a1d |
||
|
|
631090f41e |
||
|
|
574a768e09 |
||
|
|
231f23fd72 |
||
|
|
ba550f1aeb |
||
|
|
6bb63c3bae |