Commit graph

380 commits

Author SHA1 Message Date
Tobin South
c76f827368
fix(example qr server): Embed widget HTML in QR server (#317)
* feat(qr-server): embed widget HTML for self-contained usage

Embed the widget HTML directly in server.py following the same pattern
as the say-server. This allows the QR server to be run without any
local file dependencies using `uv run <url>`.

The get_widget_html() function prefers the built version from dist/
for local development but falls back to the embedded HTML for unbundled
usage.

* refactor(qr-server): remove widget.html and simplify embedded HTML

Address PR review feedback:
- Remove separate widget.html file (no longer needed)
- Remove get_widget_html() function and dist/mcp-app.html reference
- Inline EMBEDDED_WIDGET_HTML directly in widget() resource
- Remove unused Path import

The server is now fully self-contained in a single file.

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-21 16:51:23 +00:00
Olivier Chafik
17813898c0
docs(spec): clarify ui.domain is host-dependent (#309)
Update the spec to clarify that:
- ui.domain format and validation rules are host-dependent
- Servers must consult host-specific documentation for expected format
- Common patterns: hash-based subdomains, URL-derived subdomains
- Updated examples to reflect realistic host-controlled domains

This addresses the gap between the spec's previous implied flexibility
(arbitrary domains like weather-widget.example.com) and real-world
constraints where hosts must control sandbox domains for security.
2026-01-21 14:09:38 +00:00
Jonathan Hefner
26ae13df0f
Merge pull request #302 from jonathanhefner/checked-examples
Move JSDoc examples to type-checked `.examples.ts` files
2026-01-20 13:30:01 -06:00
Jonathan Hefner
121034709e
Merge pull request #306 from jonathanhefner/top-level-plugin-marketplace
Add `.claude-plugin/marketplace.json` for plugin distribution
2026-01-20 12:32:44 -06:00
Maurizio Albari
b594fc2dbd
fix: update serve:http to run main.ts instead of server.ts (#315)
After commit 65a62a9f, the server startup code was moved from server.ts
to main.ts, but the serve:http script was not updated accordingly.

This caused 9 example servers to fail to start when running npm start:
- budget-allocator-server
- cohort-heatmap-server
- customer-segmentation-server
- integration-server
- map-server
- scenario-modeler-server
- system-monitor-server
- threejs-server
- wiki-explorer-server

The server.ts file now only exports createServer(), while main.ts
contains the actual server startup logic.
2026-01-20 17:57:08 +00:00
Jonathan Hefner
7078f81ceb Add .claude-plugin/marketplace.json for plugin distribution
This enables users to install the `mcp-apps` plugin via:

    /plugin marketplace add modelcontextprotocol/ext-apps
    /plugin install mcp-apps@modelcontextprotocol-ext-apps

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-20 11:38:14 -06:00
Anton Pidkuiko
f6ee5d5bdc
Merge pull request #286 from modelcontextprotocol/ochafik/readme-mcp-config
docs: add MCP client configuration to READMEs
2026-01-20 11:11:51 +00:00
Olivier Chafik
864bb6dc2d
docs: clarify that npm start runs examples in dev mode 2026-01-20 10:54:04 +00:00
Olivier Chafik
24f43927e5
Merge remote-tracking branch 'origin/ochafik/fix-say-server-readme' into ochafik/readme-mcp-config
# Conflicts:
#	examples/say-server/README.md
2026-01-20 10:51:14 +00:00
Olivier Chafik
198a1be034
fix(say-server): use isolated HuggingFace cache for Docker
Avoid sharing host's HF cache with Docker container since
downloaded models may contain unsafe pickled files or code.
2026-01-20 10:46:21 +00:00
Olivier Chafik
cba7b71e2b
docs(say-server): use raw GitHub URL for direct uv run 2026-01-20 10:42:31 +00:00
Olivier Chafik
ccd41ac721
docs: add MCP client config for say-server
- Add MCP client configuration section to say-server README
- Add say-server to combined config in top-level README
2026-01-20 10:18:19 +00:00
Olivier Chafik
5ef3120e0c
Merge remote-tracking branch 'origin/main' into ochafik/readme-mcp-config 2026-01-20 10:17:45 +00:00
Olivier Chafik
ad67b3e4bb
Merge remote-tracking branch 'origin/main' into ochafik/fix-say-server-readme 2026-01-20 10:16:59 +00:00
Jonathan Hefner
f0c7cc1b14 Refine JSDoc examples for consistency and type safety
Follow-up to the examples extraction: pass dependencies as function
parameters instead of using global stub declarations, rename region
names to match method names (e.g., `AppBridge_guestCapabilities_*` →
`AppBridge_getAppCapabilities_*`), and simplify examples using optional
chaining.

Also clarifies `RESOURCE_URI_META_KEY` documentation to indicate it's
for tool definition metadata (from `tools/list`), not tool result
metadata, and removes the redundant `setNotificationHandler` example
in favor of the simpler event setter approach.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-19 20:43:47 -06:00
Jonathan Hefner
ad04e89745 Move JSDoc examples to type-checked .examples.ts files
Extract inline code examples from JSDoc comments into companion
`.examples.ts`/`.examples.tsx` files. Examples are now:

- Type-checked by wrapping them in functions
- Referenced via `{@includeCode ./file.examples.ts#regionName}` tags
- Organized using `//#region` and `//#endregion` markers

This keeps the main source files cleaner while ensuring examples
compile correctly. Updated TypeDoc config with `exampleTag: false`
to support title text on `@example` tags.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-19 20:41:19 -06:00
Jonathan Hefner
e5c90c7385 Use absolute GitHub URLs for example links in README
Relative directory links like `](examples/map-server)` caused TypeDoc
warnings ("relative path is not a file") and resulted in broken links
in the generated API documentation. Converted all 20 example directory
links to full GitHub URLs while keeping image paths relative.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-19 20:36:28 -06:00
Jonathan Hefner
cac214f2cf
Merge pull request #290 from jonathanhefner/migrate-oai-app-skill
Add "Migrate from OpenAI App" skill to Claude Code plugin
2026-01-19 20:17:14 -06:00
Olivier Chafik
def51a70ad
fix(say-server): clean up README
- Add screenshot reference
- Remove GPU prerequisite (not needed, wasn't requested)
- Use GitHub raw URLs instead of local file paths
- Simplify Docker section
- Fix Claude Desktop config to use remote URL
2026-01-20 01:08:01 +00:00
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>
2026-01-20 00:41:50 +00:00
Jonathan Hefner
f3b3c48a83
Merge pull request #289 from jonathanhefner/basic-host-sse-transport
Add SSE transport fallback to `basic-host`
2026-01-19 16:26:53 -06:00
Olivier Chafik
801e1b043a
add EXAMPLE=folder-name support for tests & basic-host (#292)
* add EXAMPLE=folder-name support for tests & basic-host

* style: format e2e test files

* style: format threejs-server files
2026-01-19 20:16:37 +00:00
Olivier Chafik
6c5aa52c95
feat(shadertoy): add proper mouse/touch interaction support (#293)
* feat(shadertoy): add proper mouse/touch interaction support

- Fix iMouse uniform to match official Shadertoy specification:
  - iMouse.xy only updates while button/touch is held down
  - iMouse.zw uses positive values when down, negative when released
  - Enables proper click detection via iMouse.z > 0

- Add touch event support for mobile devices:
  - touchstart/touchmove/touchend/touchcancel handlers
  - Same behavior as mouse events

- Update tool description with mouse interaction documentation
- Update README with:
  - Mouse & Touch Interaction feature
  - Improved Julia Set example with click detection
  - iMouse specification table and usage examples

The iMouse uniform is a core Shadertoy feature used by popular shaders
like Star Nest, raymarching examples, and particle systems.

* style: fix Prettier formatting in shadertoy README
2026-01-19 19:11:53 +00:00
Olivier Chafik
de8048cb6d
feat(qr-server): use Python SDK meta parameter for resource CSP metadata (#303)
* update qr-server w/ python sdk fix

* feat(qr-server): use Python SDK meta parameter for resource CSP metadata

- Update qr-server to use the new meta parameter on @mcp.resource decorator
  instead of manually overriding the read_resource handler
- Add ui.resourceUri to tool meta alongside legacy ui/resourceUri for forward compatibility
- Simplify server.py by removing the custom _read_resource_with_meta handler
- Add qr-server to grid screenshot generation tests
- Update grid-cell.png screenshot

This leverages the Python SDK's native support for resource metadata,
eliminating the need for low-level handler manipulation.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-19 19:11:42 +00:00
Anton Pidkuiko
73ab853dc5
Merge pull request #297 from modelcontextprotocol/feat/shadertoy-streaming-visibility
feat(shadertoy): add streaming partial input, visibility optimization, host styling
2026-01-19 18:36:43 +00:00
Anton Pidkuiko
f71155ac7c
Merge pull request #299 from modelcontextprotocol/feat/threejs-perf-styling
feat(threejs): add visibility optimization, host styling, transparent background
2026-01-19 18:36:33 +00:00
Anton Pidkuiko
a9d8e40fe6
Merge pull request #305 from modelcontextprotocol/fix/spec-permissions-type
fix(spec): align permissions type with SDK implementation
2026-01-19 18:26:05 +00:00
Anton Pidkuiko MacBook
8c87715628
fix(spec): align permissions type with SDK implementation
The spec document incorrectly defined permission fields (camera, microphone,
geolocation, clipboardWrite) as boolean types, but the SDK implementation
uses empty object types ({}).

This caused validation errors for MCP servers (like Hex) that followed
the spec and sent boolean values like `clipboardWrite: true`, when the
Zod schema expects `clipboardWrite: {}`.

The empty object design was intentional to allow future extensibility
(e.g., adding options like `{ required: true }`). This commit aligns
the spec documentation with the actual TypeScript types in spec.types.ts.

Fixes validation error:
`{ code: 'invalid_type', expected: 'object', received: 'boolean',
   path: ['permissions', 'clipboardWrite'] }`
2026-01-19 17:26:13 +00:00
Olivier Chafik
fcd243a6f3
fix(e2e): make server-time element fill width for consistent mask (#283)
* fix(e2e): make server-time element fill width for consistent mask

- Add flex layout to .action p to make server-time stretch
- Add #server-time flex: 1 rule across all basic-server variants
- Update golden screenshots with full-width masked time field

This ensures the Playwright mask covers a consistent width regardless
of the timestamp content, fixing screenshot comparison flakiness.

* fix(e2e): wait for select to be enabled in screenshot generator

Match the logic in servers.spec.ts - wait for select to be enabled
(servers connected) instead of just visible.

* chore: trigger CI re-run
2026-01-19 17:01:55 +00:00
Jonathan Hefner
90dad1a86b Add "Migrate from OpenAI App" skill to Claude Code plugin
Adds a new skill (`plugins/mcp-apps/skills/migrate-oai-app/SKILL.md`)
that guides developers through migrating OpenAI Apps SDK applications
to the MCP Apps SDK. Includes API mapping tables, CSP configuration
guidance, and a "Before Finishing" checklist.

Also fixes the `registerAppResource()` JSDoc example in `src/server/index.ts`
to show CSP configuration in the correct location (on the content item,
not the resource config).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-19 07:59:41 -06:00
Anton Pidkuiko MacBook
d60224f363
feat(threejs): add visibility optimization, host styling, transparent background
- Add visibility-based animation pause (IntersectionObserver + wrapped rAF)
- Zero CPU usage when widget scrolls out of view
- Apply host style variables via useHostStyles
- Support transparent WebGL background (alpha: true)
- Use light-dark() for theme-aware fallback colors
- Tool no longer echoes code back in result
- Document performance features in README
2026-01-17 23:19:34 +00:00
Anton Pidkuiko MacBook
f1a00f9e15
feat(shadertoy): add streaming partial input, visibility optimization, host styling
Shadertoy server improvements:
- Add ontoolinputpartial handler to show code preview during generation
- Add IntersectionObserver to pause/play shader based on visibility
- Apply host style variables (theme, colors, fonts)
- Add border-radius with fullscreen mode support
- Use gradient background and ghost text color for code preview

Skill documentation updates:
- Add streaming partial input section with use cases
- Add visibility-based resource management pattern
- Add fullscreen mode API and CSS patterns
- Expand host styling with CSS variable usage examples
2026-01-17 22:29:57 +00:00
Jonathan Hefner
7ce5504f9f Add SSE transport fallback to basic-host
Implement the conventional MCP pattern for transport backward compatibility:
try `StreamableHTTPClientTransport` first (modern), then fall back to
`SSEClientTransport` (deprecated but needed for older servers).

This follows the approach documented in the MCP TypeScript SDK's
`streamableHttpWithSseFallbackClient.ts` example.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-16 10:23:07 -06:00
Olivier Chafik
ac1130cda4
style: format JSON in READMEs with prettier 2026-01-16 15:14:48 +00:00
Olivier Chafik
ed51361511
docs: add combined MCP client config to top-level README
Add a collapsible details section with configuration for all example
servers in the Examples section of the main README.
2026-01-16 14:31:42 +00:00
Olivier Chafik
94c5dff983
docs(qr-server): clarify that repo clone is required 2026-01-16 14:03:46 +00:00
Olivier Chafik
cce8d5c7a3
docs: add MCP client configuration to example READMEs
Add stdio transport configuration snippets near the top of each example
README to help users quickly set up the servers in their MCP clients.

- Node.js examples use npx with the published npm packages
- Python qr-server uses uv with local path
- Removed Claude Desktop-specific references from qr-server
2026-01-16 14:00:57 +00:00
Olivier Chafik
8c3b1daf7e
chore: bump version to 0.4.1 (#282) v0.4.1 2026-01-15 16:11:53 +00:00
Anton Pidkuiko
be8d725974
Merge pull request #272 from modelcontextprotocol/uv-qr-server
feat(qr-server): migrate to uv with PEP 723 inline dependencies
2026-01-15 14:29:33 +00:00
Olivier Chafik
0936d52d0a
feat(shadertoy): show fullscreen button only on widget hover, add min-height (#281) 2026-01-15 14:15:17 +00:00
Olivier Chafik
b78cd74c1b
feat(shadertoy): add fullscreen support + ditch insets for max visual effect (#278)
* feat(shadertoy): add fullscreen support

Add fullscreen toggle button that appears when the host supports fullscreen
display mode. Uses the same pattern as pdf-server:
- Check availableDisplayModes in host context
- Show/hide button based on capability
- Toggle between inline and fullscreen via requestDisplayMode()
- Update UI state on host context changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(shadertoy): button visibility after exiting fullscreen + Escape key

- Only update button visibility when availableDisplayModes is present
  in context (partial updates don't include all fields)
- Add Escape key handler to exit fullscreen mode

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-15 13:01:55 +00:00
Olivier Chafik
89a684546b
fix(examples): resolve DIST_DIR path for npm package execution (#277)
* fix(examples): resolve DIST_DIR path for npm package execution

When servers are compiled to dist/server.js and published to npm,
`import.meta.dirname` already points to dist/, so joining with "dist"
results in dist/dist/ which doesn't exist.

This fix detects whether we're running from TypeScript source or
compiled JavaScript and adjusts the path accordingly:
- From source (server.ts): use dist/ subdirectory
- From compiled (dist/server.js): use current directory

Fixes ENOENT errors like:
"ENOENT: no such file or directory, open '.../dist/dist/mcp-app.html'"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(pdf-server): mark pdfjs-dist as external in bundle

The pdf.worker.mjs file wasn't being found when running from npm
because bun bundled pdfjs-dist but didn't include the worker file.

By marking pdfjs-dist as external, it uses the installed package
from node_modules at runtime where the worker is available.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-15 12:23:13 +00:00
Olivier Chafik
847427aeef
pdf-server: fix scrolling gap in inline mode (#280)
* map-server: fix async/await in ontoolresult, remove unused getViewStorageKey

* pdf-server: fix scrolling gap in inline mode

- Set html/body background to match .main background color
  This hides any gap between .main and iframe border
- Change .main from height:100% to min-height:100%
  Ensures .main fills container properly
2026-01-15 12:22:58 +00:00
Olivier Chafik
b94982cc35
fix[examples/transcript]: fix transitional deltas (#275)
* fix transcript deltas

* Update mcp-app.css
2026-01-15 12:06:02 +00:00
Anton Pidkuiko MacBook
489d28b6da
fix: increase webServer timeout for uv dependency download
uv needs extra time on first run to download Python dependencies
2026-01-15 11:53:27 +00:00
Copilot
c73d36343b
fix: change unknown source message log from error to debug level (#239)
* Initial plan

* Change console.error to console.debug for unknown message sources

Co-authored-by: liady <7003853+liady@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: liady <7003853+liady@users.noreply.github.com>
2026-01-15 11:51:27 +00:00
Anton Pidkuiko
dbc7a41550
Merge pull request #274 from matteo8p/use-tool-type-from-official-sdk
Use `Tool` as the input type in `getToolUiResourceUri`
2026-01-15 11:45:46 +00:00
Anton Pidkuiko MacBook
656a0292ae
feat: add QR Code to README gallery + rename to QR Code Server
- Add grid-cell.png screenshot for README gallery
- Rename 'QR Server' to 'QR Code Server' everywhere
- Add QR Code (Python) entry to examples table in README
2026-01-15 11:36:21 +00:00
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>
2026-01-14 23:46:17 +00:00
Olivier Chafik
75cbf8612c
feat(basic-host): URL params, fullscreen mode, unified layout (#266)
* basic-host: handle containerDimensions

* feat(basic-host): Unified tool call layout with shared collapsible panels

* snapshots

* format
2026-01-14 22:09:41 +00:00