- Switch npm install -> npm ci in ci.yml (build, build-wsl) and docs.yml
to fail on lockfile drift rather than silently tolerating it
- Add cache: npm to all setup-node steps that have a lockfile to hash
(skipped test-git-install which has no checkout, and WSL which has no
setup-node action)
- Add TypeDoc link validation step after build (Linux x64 only, matching
existing single-OS gate pattern for MCPB). Verified passing on main.
- Align all workflows on Node 22 (active LTS) — previously CI used 20
but publish workflows used 22, so releases were tested on a different
Node than PRs
- Add engines.node >=20 to package.json so consumers on Node 18 get a
warning
Two packaging bugs:
1. The './schema.json' export pointed to dist/src/generated/schema.json
but nothing copied it there (tsc is emitDeclarationOnly, Bun.build
doesn't emit JSON). Consumers got ERR_MODULE_NOT_FOUND.
Fix: cpSync after tsc runs.
2. zod is a peerDependency but was bundled into every entry point
(~270KB each). This causes dual-instance bugs where consumer-side
'instanceof ZodError' and schema.extend() break across boundaries.
Fix: add zod to external list for all non-with-deps entries.
Bundle size impact:
app.js 293952 -> 24561 (-91.6%)
app-bridge.js 299517 -> 30112 (-89.9%)
react/index.js 295558 -> 26153 (-91.2%)
server/index.js 291500 -> 22135 (-92.4%)
app-with-deps 321814 -> 321814 (unchanged, intentional)
Bug 1: generate-grid-screenshots.spec.ts was running on every CI E2E
invocation because playwright.config.ts had no testIgnore. This spec
writes examples/*/grid-cell.png as a side effect — it's meant to be
invoked only via npm run generate:screenshots.
Added testIgnore gated on GENERATE_SCREENSHOTS env var (Playwright's
testIgnore is stronger than explicit CLI file args, so a plain ignore
would break generate:screenshots). Passed the env var through the
docker invocation in generate:screenshots.
Before: npx playwright test --list → 82 tests in 3 files
After: npx playwright test --list → 65 tests in 2 files
GENERATE_SCREENSHOTS=1 ... --list → 17 tests in 1 file (still works)
Bug 2: examples/pdf-server/server.test.ts (448 LOC, 34 tests) was
never run — root script was 'bun test src'. Changed to 'bun test src
examples'. Only one .test. file exists in examples/ so no noise.
Before: npm test → 87 pass across 3 files
After: npm test → 121 pass across 4 files
Change `sandbox.ts` imports from relative paths into `dist/` to use the
proper `@modelcontextprotocol/ext-apps/app-bridge` package entry point.
This aligns the example with how external consumers would import from
the package.
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Move detailed implementation recipes (tool visibility, host styling, streaming,
fullscreen, etc.) out of the skill and point to `docs/patterns.md` instead.
This keeps the skill focused on essentials while the patterns doc provides
comprehensive examples.
Key changes:
- Fix protocol flow diagram: host renders UI before server returns result
- Update template file list to reflect actual contents (`main.ts`, `global.css`)
- Add critical CSP/CORS warnings to "Common Mistakes" section
- Replace "Advanced Examples" table with categorized patterns list
- Add note clarifying `basic-host` is for testing, not a host behavior guarantee
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
On Windows, `tsx watch` can hang when running under `concurrently` due
to stdin handling conflicts (see [privatenumber/tsx#623][]). Adding the
`--raw` flag to `concurrently` avoids this by preventing stdin
interception.
Since `--raw` mode disables concurrently's automatic output prefixing, a
custom Vite logger is added to prefix messages with `[vite]` so users
can still distinguish which process produced each line of output.
[privatenumber/tsx#623]: https://github.com/privatenumber/tsx/issues/623
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Follow-up to #470. Matches MCP SDK Client.listResources(params?) signature
so callers can omit the empty {} for the common case.
Also reflows a line in app-bridge.test.ts that prettier flagged.
* Replace platform-specific optionalDependencies with bun devDependency
Fixes#222. The bun meta-package handles platform detection internally.
Rollup resolves its own platform binaries transitively. Removes ~400MB
of bloat for SDK consumers. Simplifies setup-bun.mjs accordingly.
* Remove setup-bun.mjs, simplify prepare script
No longer needed since the bun npm package handles binary
installation and PATH registration automatically.
* Add Security docs section, SEO improvements, and doc site enhancements
- Add Authorization guide covering per-server and per-tool OAuth patterns
- Add CSP & CORS guide extracted from Patterns doc
- Group both under a new Security section in the documentation nav
- Replace CSP & CORS section in Patterns with cross-reference to new guide
- Rename doc site title from package name to 'MCP Apps'
- Rename 'Modules' nav section to 'API Documentation'
- Ensure Security section appears before API Documentation in TOC
- Add SEO plugin with JSON-LD structured data (TechArticle/WebPage)
- Add per-page meta descriptions from frontmatter
- Add description frontmatter to all documentation pages
- Add hostedBaseUrl for sitemap.xml generation and canonical URLs
- Normalize document page slugs to lowercase hyphenated format
- Update compressed navigation and search index data to match new slugs
* Add favicons with light/dark mode support
- Download favicons from modelcontextprotocol.io (light + dark variants)
- Inject favicon link tags into every page with correct relative paths
- Support prefers-color-scheme media queries for light/dark mode
- Include apple-touch-icon for iOS
- Copy favicon assets to output directory during doc build
* Fix HTML sanitization in SEO plugin with proper parser
Replace regex-based HTML tag stripping with htmlparser2 for
extracting plain-text descriptions from rendered pages.
* Add custom theme to align with modelcontextprotocol.io styling
- Import Inter and JetBrains Mono fonts (matching MCP site)
- Override light mode colors: pure white backgrounds, softer gray borders
- Override dark mode colors: match MCP site dark background (#0f1117)
- Taller header (3.5rem) with backdrop-blur frosted glass effect
- Sidebar: adjusted spacing, font size, and hover/active states
- Content: increased line-height (1.6), more heading breathing room
- Code blocks: JetBrains Mono, subtle border, more padding
- Fix CSS load order: custom.css now loads after theme stylesheets
* Align sidebar nav styling with modelcontextprotocol.io
- Active item: tinted blue background with blue text (matching MCP's
primary-color tinted active state)
- Non-active items: muted gray text, subtle hover background
- Larger border-radius (0.75rem/rounded-xl) matching MCP sidebar
- Group headers: semibold with slight letter spacing
- Proper dark mode variants for all states
* Fix sidebar active item: dark gray background with bold text
* Make sidebar active item more prominent: bolder weight, stronger background
* Highlight current page in sidebar nav, normalize code font size
Inject a small script via the SEO plugin that marks the active sidebar
link with a "current" class (TypeDoc doesn't do this natively for
document pages). Uses a MutationObserver since the sidebar is populated
asynchronously. Pathname comparison strips .html extensions to support
clean-URL servers.
Also bumps code/pre font-size from 0.85em to 1em so code snippets match
the surrounding body text size.
* Split styling into dedicated plugin, fix auth terminology, improve breadcrumbs
Extract CSS cascade fix, breadcrumb labels, and sidebar nav highlighting
from the SEO plugin into a new typedoc-plugin-mcpstyle.mjs to keep
concerns separated.
Fix authorization doc: use "authorization" consistently instead of mixing
with "authentication", link to MCP spec and RFC 9728 for Protected
Resource Metadata, remove redundant spec link paragraph.
Rename "Documents" nav section to "Getting Started" and add explicit
group frontmatter to all doc pages. Breadcrumbs now show the section
name instead of duplicating the page title.
Switch local development MCP server config from `npm --prefix` to
`bash -c "cd DIR && npm --silent run start:stdio"`. The --prefix form
caused connection instability in Claude Desktop (reconnect loops with
orphan builds competing on the same dist/).
Also updated example paths from ~/code/ext-apps to ~/src/ext-apps.
fit-content clamps to the containing block's available size. For <html>,
that's the iframe viewport, so when content exceeds the viewport height
the SDK reported the viewport height instead of the true content height,
causing internal scrolling instead of iframe growth.
max-content has no available-space constraint and correctly reports the
intrinsic content height in both directions (shrink and grow). Width
stays fit-content to preserve responsive wrapping.
* docs: restore full MCP client JSON configs to CONTRIBUTING.md
Reinstate the copy-pasteable JSON configurations for running all examples
with MCP clients (npx-based and local development), which were removed
from README.md in 2af02ba. Placed in CONTRIBUTING.md as a better home
for contributor-facing setup instructions.
https://claude.ai/code/session_014pjt7bE4ckHns5QFPkdWQp
* Use start:stdio in local dev config, add missing scripts to 9 examples
Update the local development JSON config in CONTRIBUTING.md to use
`npm --silent run start:stdio` instead of manual bash commands.
Add `serve:stdio` and `start:stdio` scripts to the 9 examples that
were missing them (basic-server-*, sheet-music, transcript,
video-resource, debug) to match the pattern already in place for the
other 11 showcase examples.
https://claude.ai/code/session_014pjt7bE4ckHns5QFPkdWQp
* style: auto-fix prettier formatting
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
* security: ignore client roots by default in pdf-server
When the pdf-server is started with --stdio, MCP clients may advertise
roots that refer to directories on the *client's* file system. Because
the server resolves those paths locally, accepting them by default would
give the remote client access to arbitrary directories on the server's
machine.
This commit makes client roots opt-in via the --use-client-roots flag.
Without the flag, the server logs a notice and skips roots setup
entirely. The createServer() function now accepts a CreateServerOptions
object with a `useClientRoots` boolean (defaults to false).
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* Enable client roots by default for HTTP, keep off for stdio
HTTP mode serves a local client so roots are safe. Stdio mode may
have a remote client whose roots would resolve against the server's
filesystem, so roots stay off unless --use-client-roots is passed.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* fix: correct transport-aware defaults for useClientRoots
stdio = local client (e.g. Claude Desktop) → auto-enable roots
HTTP = remote client → ignore roots unless --use-client-roots passed
The previous commit had the logic inverted.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* refactor: inline useClientRoots per transport branch
Remove the intermediate effectiveUseClientRoots variable — just pass
`true` in the stdio branch and the flag value in the HTTP branch.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* docs: update README to match transport-aware client roots defaults
Stdio always enables roots (client is local); HTTP ignores them by
default. The previous README text had these reversed.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
---------
Co-authored-by: Claude <noreply@anthropic.com>
* 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.
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
Pre-commit hook:
- Stage all files modified by prettier:fix, not just src/generated/
CI (GitHub Actions):
- Add prettier-fix job that runs on PRs from the same repo
- Auto-commits formatting fixes back to the PR branch
- Skips fork PRs (no write access to fork branches)
Co-authored-by: Claude <noreply@anthropic.com>
* pdf-server: support folders in cli + files in roots
* fix(pdf-server): use path.relative for robust ancestor dir matching
- Replace string prefix matching (startsWith) with path.relative-based
isAncestorDir() which correctly handles trailing slashes, path
normalization, and prevents both .. traversal and prefix attacks.
- Use path.resolve consistently when adding paths to allowedLocalFiles
and allowedLocalDirs (main.ts was missing this).
- Use resolved path for exact file match check in validateUrl.
- Improve error message formatting for easier debugging.
- Add tests for trailing slashes, grandparent dirs, and isAncestorDir.
* chore(pdf-server): remove JSONL interaction logging
Remove the withLogging transport wrapper, logInteraction helper,
InteractionLogger type, and all log parameter threading that were
added for debugging.
* fix(pdf-server): support computer:// URL scheme for local files
Some clients (e.g. Claude Code) use computer:// instead of file://
for local file references. Handle both schemes in isFileUrl and
fileUrlToPath.
* fix(pdf-server): add debug logging for rejected files, ignore .jsonl logs
* fix(pdf-server): accept bare file paths in addition to file:// URLs
Clients like Claude Desktop may pass raw absolute paths (e.g.
/Users/.../file.pdf) instead of file:// URLs. Handle these in
validateUrl and readPdfRange.
* debug(pdf-server): add hex char diagnostics for path mismatch
* fix(pdf-server): resolve symlinks to handle sandbox path remapping
Use fs.realpathSync to resolve symlinks/bind mounts when comparing
file paths against allowed directories. This fixes the path namespace
mismatch where Claude Desktop sends container paths (e.g. /sessions/...)
while MCP roots use host paths (e.g. /Users/...).
Both the file path and directory paths are resolved through symlinks
before comparison, so either side can be a symlink.
Also stores realpath of roots in allowedLocalDirs/Files so matching
works in both directions.
Removes verbose hex diagnostics (no longer needed).
* fix(pdf-server): decode percent-encoded bare paths (e.g. %20 for spaces)
Clients may send bare file paths with percent-encoded characters
(e.g., Application%20Support). Apply decodeURIComponent to bare paths
before resolving, matching the behavior already used for file:// URLs.
* fix(pdf-server): add full diagnostics to client-facing error message
Include url, resolved path, realpath, allowedFiles, and per-directory
path.relative results in the error returned to the client, so we can
diagnose why isAncestorDir fails when paths look identical.
* debug(pdf-server): add hex dump to diagnose invisible char differences
path.relative returns 10 levels of .. despite paths looking identical,
meaning they differ at the byte level. Add hex dump of first 30 chars
of both paths to catch invisible Unicode or encoding differences.
* fix(pdf-server): use inode comparison for bind-mount path matching
The cowork VM remaps paths via bind mounts: the tool input uses
VM-internal paths (/sessions/...) while MCP roots use host paths
(/Users/...). Since path.relative can't match across bind mounts,
compare directory inodes instead (dev+ino from fs.statSync).
Walks up the file's parent directories checking each against allowed
dirs by inode, which works regardless of path namespace differences.
* fix(pdf-server): resolve VM-internal paths via directory basename matching
When the MCP server runs on the host but receives unrewritten VM paths
(e.g., /sessions/name/mnt/uploads/file.pdf), the tool call url argument
isn't rewritten by the cowork VM proxy because it doesn't know which
arguments are file paths.
Fix: when path validation fails, try to match the file by finding the
directory basename (e.g., 'uploads') in the VM path and looking for
the relative path suffix under each allowed directory on the host.
Also returns the resolved host path so readPdfRange reads the correct
file on the host filesystem.
* revert(pdf-server): remove resolveVmPath hack
The VM path mismatch (VM-internal paths not rewritten in tool call
arguments) should be fixed in the cowork VM proxy layer, not worked
around in the MCP server.
Removes:
- resolveVmPath() function
- resolvedPath field from validateUrl return type
- effectiveUrl remapping in tool handlers
- VM path resolution test
* nit
Update all documentation links from `modelcontextprotocol.github.io/ext-apps`
to the new custom domain across README.md, docs/, and example READMEs.
Add `cname` to the `peaceiris/actions-gh-pages` deploy action in
`.github/workflows/docs.yml` so the CNAME file persists across deploys.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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)
Use the Audio Session API to declare audio as media playback so the
platform handles it correctly: background audio, lock screen controls,
Dynamic Island integration, and bypassing the iOS silent switch.
* Add MCPB packaging and Claude Code plugin for pdf-server
Two distribution paths for the pdf-server:
1. **MCPB bundle** (Claude Desktop MCP Directory):
- manifest.json: v0.3 manifest with tools, compatibility, privacy
- .mcpbignore: excludes source/tests from bundle
- icon.png: 64x64 PDF document icon
2. **Claude Code plugin** (plugin/):
- .mcp.json: declares local stdio server via npx
- commands: /pdf-research:read, /pdf-research:summarize
- skills: pdf-reading skill for document navigation
- Tested end-to-end: MCP server connects, all tools available
The plugin uses a local stdio MCP server pattern — the first known
instance in a knowledge-work plugin (all existing plugins use remote
HTTP connectors).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Run prettier:fix to satisfy CI formatting checks
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add basic-server-preact, basic-server-solid, basic-server-svelte,
basic-server-vue, and debug-server to the publish workflows so they
are included in pkg-pr-new and npm deployments.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Replace the hardcoded list of allowed remote origins with a simple
HTTPS protocol check. Any HTTPS URL is now accepted for remote PDFs.
Local file allowlisting remains unchanged.
* 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
* 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)
* lazy PDF loading w/ PDFDataRangeTransport
* lint
* feat: lazy PDF loading via range transport + eager background preloading
Replace full-file download with PDFDataRangeTransport so PDF.js fetches
byte ranges on demand. First page renders immediately; remaining pages
load in background for search.
**Range transport (server + client)**
- server.ts: add read_pdf_bytes tool returning base64 chunks with offset
- mcp-app.ts: AppRangeTransport feeds PDF.js via fetchRange/fetchChunk
with parallel sub-requests for large ranges, Promise-based dedup of
concurrent requests, and a persistent range cache
**Background preloader**
- Sequential page 1→N text extraction, pauses during interactive
navigation (preloadPaused flag set in goToPage, cleared in renderPage)
- Debounced live search refresh (500ms) as pages load
- Search UI shows '(loading…)' suffix until all pages processed
**Loading indicators**
- SVG pie in toolbar: fills as pages load, fades on completion,
turns red on errors with tooltip listing failed pages
- Debounced page-loading overlay (150ms) for uncached page navigation
**Cleanup**
- Remove old full-file chunked download and progress bar
- Remove extractAllPageText (replaced by preloader)
- Remove verbose debug logs (Coverage, RangeReq, cache hit)
Add padding: 0 !important to .main.fullscreen so that
safe area insets applied via inline styles are overridden,
making the PDF viewer truly fullscreen edge-to-edge.
Also add .build directories to .prettierignore to fix
pre-commit hook failures from Swift build artifacts.
When the client advertises roots capability, the server queries roots/list
on initialization and subscribes to roots/list_changed notifications.
Any file:// roots pointing to existing directories are added to an
allowedLocalDirs set, enabling access to all PDFs under those directories
without needing to enumerate them via CLI args.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
fix: revert unrelated changes from bad rebase
Restores files that were accidentally modified alongside the MCP roots
feature: README, pdf-server UI (search feature), threejs example,
SDK guards (app.ts, app-bridge.ts), typedoc theme, media assets,
and e2e snapshots.
