From cce8d5c7a31d2a05a99dfb9c08923d91414e587b Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Fri, 16 Jan 2026 13:59:19 +0000 Subject: [PATCH 1/9] 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 --- examples/basic-server-preact/README.md | 21 ++++++++++++ examples/basic-server-react/README.md | 21 ++++++++++++ examples/basic-server-solid/README.md | 21 ++++++++++++ examples/basic-server-svelte/README.md | 21 ++++++++++++ examples/basic-server-vanillajs/README.md | 21 ++++++++++++ examples/basic-server-vue/README.md | 21 ++++++++++++ examples/budget-allocator-server/README.md | 21 ++++++++++++ examples/cohort-heatmap-server/README.md | 21 ++++++++++++ .../customer-segmentation-server/README.md | 21 ++++++++++++ examples/map-server/README.md | 21 ++++++++++++ examples/pdf-server/README.md | 21 ++++++++++++ examples/qr-server/README.md | 32 +++++++++++-------- examples/scenario-modeler-server/README.md | 21 ++++++++++++ examples/shadertoy-server/README.md | 21 ++++++++++++ examples/sheet-music-server/README.md | 21 ++++++++++++ examples/system-monitor-server/README.md | 21 ++++++++++++ examples/threejs-server/README.md | 21 ++++++++++++ examples/transcript-server/README.md | 21 ++++++++++++ examples/video-resource-server/README.md | 21 ++++++++++++ examples/wiki-explorer-server/README.md | 21 ++++++++++++ 20 files changed, 417 insertions(+), 14 deletions(-) diff --git a/examples/basic-server-preact/README.md b/examples/basic-server-preact/README.md index 8091ad87..b85fb907 100644 --- a/examples/basic-server-preact/README.md +++ b/examples/basic-server-preact/README.md @@ -5,6 +5,27 @@ An MCP App example with a Preact UI. > [!TIP] > Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)! +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "basic-preact": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-preact", + "--stdio" + ] + } + } +} +``` + ## Overview - Tool registration with a linked UI resource diff --git a/examples/basic-server-react/README.md b/examples/basic-server-react/README.md index d29073d7..4b3f26c1 100644 --- a/examples/basic-server-react/README.md +++ b/examples/basic-server-react/README.md @@ -7,6 +7,27 @@ An MCP App example with a React UI. > [!TIP] > Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)! +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "basic-react": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-react", + "--stdio" + ] + } + } +} +``` + ## Overview - Tool registration with a linked UI resource diff --git a/examples/basic-server-solid/README.md b/examples/basic-server-solid/README.md index e0e7584d..693fec33 100644 --- a/examples/basic-server-solid/README.md +++ b/examples/basic-server-solid/README.md @@ -5,6 +5,27 @@ An MCP App example with a Solid UI. > [!TIP] > Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)! +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "basic-solid": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-solid", + "--stdio" + ] + } + } +} +``` + ## Overview - Tool registration with a linked UI resource diff --git a/examples/basic-server-svelte/README.md b/examples/basic-server-svelte/README.md index 22505c8a..ff599af6 100644 --- a/examples/basic-server-svelte/README.md +++ b/examples/basic-server-svelte/README.md @@ -5,6 +5,27 @@ An MCP App example with a Svelte 5 UI using runes for reactivity. > [!TIP] > Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)! +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "basic-svelte": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-svelte", + "--stdio" + ] + } + } +} +``` + ## Overview - Tool registration with a linked UI resource diff --git a/examples/basic-server-vanillajs/README.md b/examples/basic-server-vanillajs/README.md index 41e23e3c..e3fabc9b 100644 --- a/examples/basic-server-vanillajs/README.md +++ b/examples/basic-server-vanillajs/README.md @@ -5,6 +5,27 @@ An MCP App example with a vanilla JavaScript UI (no framework). > [!TIP] > Looking for a React-based example? See [`basic-server-react`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react)! +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "basic-vanillajs": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-vanillajs", + "--stdio" + ] + } + } +} +``` + ## Overview - Tool registration with a linked UI resource diff --git a/examples/basic-server-vue/README.md b/examples/basic-server-vue/README.md index 2090973e..84a0b0ed 100644 --- a/examples/basic-server-vue/README.md +++ b/examples/basic-server-vue/README.md @@ -5,6 +5,27 @@ An MCP App example with a Vue 3 UI using the Composition API. > [!TIP] > Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)! +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "basic-vue": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-vue", + "--stdio" + ] + } + } +} +``` + ## Overview - Tool registration with a linked UI resource diff --git a/examples/budget-allocator-server/README.md b/examples/budget-allocator-server/README.md index b81d2e18..917abd60 100644 --- a/examples/budget-allocator-server/README.md +++ b/examples/budget-allocator-server/README.md @@ -10,6 +10,27 @@ An interactive budget allocation tool demonstrating real-time data visualization +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "budget-allocator": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-budget-allocator", + "--stdio" + ] + } + } +} +``` + ## Features - **Interactive Sliders**: Adjust budget allocation across 5 categories (Marketing, Engineering, Operations, Sales, R&D) diff --git a/examples/cohort-heatmap-server/README.md b/examples/cohort-heatmap-server/README.md index 322a116f..31a0f4ae 100644 --- a/examples/cohort-heatmap-server/README.md +++ b/examples/cohort-heatmap-server/README.md @@ -10,6 +10,27 @@ A demo MCP App that displays cohort retention data as an interactive heatmap, sh +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "cohort-heatmap": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-cohort-heatmap", + "--stdio" + ] + } + } +} +``` + ## Features - **Cohort Retention Heatmap**: Color-coded grid showing retention percentages across cohorts and time periods diff --git a/examples/customer-segmentation-server/README.md b/examples/customer-segmentation-server/README.md index 76a453e2..6e118e90 100644 --- a/examples/customer-segmentation-server/README.md +++ b/examples/customer-segmentation-server/README.md @@ -10,6 +10,27 @@ A demo MCP App that displays customer data as an interactive scatter/bubble char +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "customer-segmentation": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-customer-segmentation", + "--stdio" + ] + } + } +} +``` + ## Features - **Interactive Scatter Plot**: Bubble chart visualization using Chart.js with configurable X/Y axes diff --git a/examples/map-server/README.md b/examples/map-server/README.md index ad9223dc..38a4f383 100644 --- a/examples/map-server/README.md +++ b/examples/map-server/README.md @@ -4,6 +4,27 @@ Interactive 3D globe viewer using CesiumJS with OpenStreetMap tiles. Demonstrates geocoding integration and full MCP App capabilities. +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "map": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-map", + "--stdio" + ] + } + } +} +``` + ## Features - **3D Globe Rendering**: Interactive CesiumJS globe with rotation, zoom, and 3D perspective diff --git a/examples/pdf-server/README.md b/examples/pdf-server/README.md index 48964a8f..bdc83bec 100644 --- a/examples/pdf-server/README.md +++ b/examples/pdf-server/README.md @@ -4,6 +4,27 @@ A simple interactive PDF viewer that uses [PDF.js](https://mozilla.github.io/pdf.js/). Launch it w/ a few PDF files and/or URLs as CLI args (+ support loading any additional pdf from arxiv.org). +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "pdf": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-pdf", + "--stdio" + ] + } + } +} +``` + ## What This Example Demonstrates ### 1. Chunked Data Through Size-Limited Tool Calls diff --git a/examples/qr-server/README.md b/examples/qr-server/README.md index e98016ec..0dbb54f8 100644 --- a/examples/qr-server/README.md +++ b/examples/qr-server/README.md @@ -4,12 +4,27 @@ A minimal Python MCP server that generates customizable QR codes with an interac ![Screenshot](https://modelcontextprotocol.github.io/ext-apps/screenshots/qr-server/screenshot.png) +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "qr": { + "command": "uv", + "args": ["run", "/path/to/qr-server/server.py", "--stdio"] + } + } +} +``` + ## Features - Generate QR codes from any text or URL - Customizable colors, size, and error correction - Interactive widget that displays in MCP-UI enabled clients -- Supports both HTTP (for web clients) and stdio (for Claude Desktop) +- Supports both HTTP (for web clients) and stdio (for MCP clients) ## Prerequisites @@ -41,24 +56,13 @@ Connect from basic-host: SERVERS='["http://localhost:3108/mcp"]' bun serve.ts ``` -### Stdio Mode (for Claude Desktop) +### Stdio Mode (for MCP clients) ```bash uv run server.py --stdio ``` -Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): - -```json -{ - "mcpServers": { - "qr": { - "command": "uv", - "args": ["run", "/path/to/qr-server/server.py", "--stdio"] - } - } -} -``` +See [MCP Client Configuration](#mcp-client-configuration) above for how to add this server to your MCP client. ### Docker (accessing host server from container) diff --git a/examples/scenario-modeler-server/README.md b/examples/scenario-modeler-server/README.md index c5252a73..8d3e1001 100644 --- a/examples/scenario-modeler-server/README.md +++ b/examples/scenario-modeler-server/README.md @@ -10,6 +10,27 @@ A React-based demo MCP App that lets users adjust SaaS business parameters and s +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "scenario-modeler": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-scenario-modeler", + "--stdio" + ] + } + } +} +``` + ## Features - **Interactive Parameters**: 5 sliders for Starting MRR, Growth Rate, Churn Rate, Gross Margin, and Fixed Costs diff --git a/examples/shadertoy-server/README.md b/examples/shadertoy-server/README.md index 5f965cb8..58dc6397 100644 --- a/examples/shadertoy-server/README.md +++ b/examples/shadertoy-server/README.md @@ -10,6 +10,27 @@ A demo MCP App that renders [ShaderToy](https://www.shadertoy.com/)-compatible G +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "shadertoy": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-shadertoy", + "--stdio" + ] + } + } +} +``` + ## Features - **Real-time Rendering**: Renders GLSL shaders using WebGL 2.0 diff --git a/examples/sheet-music-server/README.md b/examples/sheet-music-server/README.md index 8f2f990c..cdcf869b 100644 --- a/examples/sheet-music-server/README.md +++ b/examples/sheet-music-server/README.md @@ -9,6 +9,27 @@ A demo MCP App that renders [ABC notation](https://en.wikipedia.org/wiki/ABC_not +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "sheet-music": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-sheet-music", + "--stdio" + ] + } + } +} +``` + ## Features - **Audio Playback**: Built-in audio player with play/pause and loop controls diff --git a/examples/system-monitor-server/README.md b/examples/system-monitor-server/README.md index 6e343866..7330572a 100644 --- a/examples/system-monitor-server/README.md +++ b/examples/system-monitor-server/README.md @@ -10,6 +10,27 @@ A demo MCP App that displays real-time OS metrics with a stacked area chart for +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "system-monitor": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-system-monitor", + "--stdio" + ] + } + } +} +``` + ## Features - **Per-Core CPU Monitoring**: Stacked area chart showing individual CPU core utilization over a 1-minute sliding window diff --git a/examples/threejs-server/README.md b/examples/threejs-server/README.md index 41e6d2f0..2b58fee8 100644 --- a/examples/threejs-server/README.md +++ b/examples/threejs-server/README.md @@ -4,6 +4,27 @@ Interactive 3D scene renderer using Three.js. Demonstrates streaming code preview and full MCP App integration. +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "threejs": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-threejs", + "--stdio" + ] + } + } +} +``` + ## Features - **Interactive 3D Rendering**: Execute JavaScript code to create and animate Three.js scenes diff --git a/examples/transcript-server/README.md b/examples/transcript-server/README.md index dae22280..4ae89ee4 100644 --- a/examples/transcript-server/README.md +++ b/examples/transcript-server/README.md @@ -4,6 +4,27 @@ An MCP App Server for live speech transcription using the Web Speech API. +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "transcript": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-transcript", + "--stdio" + ] + } + } +} +``` + ## Features - **Live Transcription**: Real-time speech-to-text using browser's Web Speech API diff --git a/examples/video-resource-server/README.md b/examples/video-resource-server/README.md index 252e6bbf..01d89e63 100644 --- a/examples/video-resource-server/README.md +++ b/examples/video-resource-server/README.md @@ -4,6 +4,27 @@ Demonstrates serving binary content (video) via MCP resources using the base64 blob pattern. +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "video-resource": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-video-resource", + "--stdio" + ] + } + } +} +``` + ## Quick Start ```bash diff --git a/examples/wiki-explorer-server/README.md b/examples/wiki-explorer-server/README.md index bd827e37..70ac6d9a 100644 --- a/examples/wiki-explorer-server/README.md +++ b/examples/wiki-explorer-server/README.md @@ -10,6 +10,27 @@ Visualizes Wikipedia link graphs using a force-directed layout. Explore how Wiki +## MCP Client Configuration + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "wiki-explorer": { + "command": "npx", + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-wiki-explorer", + "--stdio" + ] + } + } +} +``` + ## Features - **Force-directed graph visualization**: Interactive graph powered by [`force-graph`](https://github.com/vasturiano/force-graph) From 94c5dff98384fbabdc0b5c8495dcfe91f5cb8329 Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Fri, 16 Jan 2026 14:03:46 +0000 Subject: [PATCH 2/9] docs(qr-server): clarify that repo clone is required --- examples/qr-server/README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/examples/qr-server/README.md b/examples/qr-server/README.md index 0dbb54f8..36ae4d17 100644 --- a/examples/qr-server/README.md +++ b/examples/qr-server/README.md @@ -6,14 +6,20 @@ A minimal Python MCP server that generates customizable QR codes with an interac ## MCP Client Configuration -Add to your MCP client configuration (stdio transport): +First, clone the repository: + +```bash +git clone https://github.com/modelcontextprotocol/ext-apps.git +``` + +Then add to your MCP client configuration (stdio transport), replacing the path with your clone location: ```json { "mcpServers": { "qr": { "command": "uv", - "args": ["run", "/path/to/qr-server/server.py", "--stdio"] + "args": ["run", "/path/to/ext-apps/examples/qr-server/server.py", "--stdio"] } } } From ed51361511b6210b2c62c7254bba413dc1073b8c Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Fri, 16 Jan 2026 14:31:42 +0000 Subject: [PATCH 3/9] 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. --- README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/README.md b/README.md index 6057fe10..5be1f129 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,102 @@ Or edit your `package.json` manually: The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains additional demo apps showcasing real-world use cases. +
+MCP client configuration for all examples + +Add to your MCP client configuration (stdio transport): + +```json +{ + "mcpServers": { + "basic-react": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-react", "--stdio"] + }, + "basic-vanillajs": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-vanillajs", "--stdio"] + }, + "basic-vue": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-vue", "--stdio"] + }, + "basic-svelte": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-svelte", "--stdio"] + }, + "basic-preact": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-preact", "--stdio"] + }, + "basic-solid": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-solid", "--stdio"] + }, + "budget-allocator": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-budget-allocator", "--stdio"] + }, + "cohort-heatmap": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-cohort-heatmap", "--stdio"] + }, + "customer-segmentation": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-customer-segmentation", "--stdio"] + }, + "map": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-map", "--stdio"] + }, + "pdf": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-pdf", "--stdio"] + }, + "scenario-modeler": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-scenario-modeler", "--stdio"] + }, + "shadertoy": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-shadertoy", "--stdio"] + }, + "sheet-music": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-sheet-music", "--stdio"] + }, + "system-monitor": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-system-monitor", "--stdio"] + }, + "threejs": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-threejs", "--stdio"] + }, + "transcript": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-transcript", "--stdio"] + }, + "video-resource": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-video-resource", "--stdio"] + }, + "wiki-explorer": { + "command": "npx", + "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-wiki-explorer", "--stdio"] + }, + "qr": { + "command": "uv", + "args": ["run", "/path/to/ext-apps/examples/qr-server/server.py", "--stdio"] + } + } +} +``` + +> **Note:** The `qr` server requires cloning the repository first. See [qr-server README](examples/qr-server) for details. + +
+ To run all examples: ```bash From ac1130cda4c7de945c0245c1d58e919c477f649c Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Fri, 16 Jan 2026 15:14:48 +0000 Subject: [PATCH 4/9] style: format JSON in READMEs with prettier --- README.md | 158 ++++++++++++++++++++++++++++++----- examples/qr-server/README.md | 6 +- 2 files changed, 143 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 5be1f129..4ac41a5c 100644 --- a/README.md +++ b/README.md @@ -89,83 +89,201 @@ Add to your MCP client configuration (stdio transport): "mcpServers": { "basic-react": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-react", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-react", + "--stdio" + ] }, "basic-vanillajs": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-vanillajs", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-vanillajs", + "--stdio" + ] }, "basic-vue": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-vue", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-vue", + "--stdio" + ] }, "basic-svelte": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-svelte", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-svelte", + "--stdio" + ] }, "basic-preact": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-preact", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-preact", + "--stdio" + ] }, "basic-solid": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-basic-solid", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-basic-solid", + "--stdio" + ] }, "budget-allocator": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-budget-allocator", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-budget-allocator", + "--stdio" + ] }, "cohort-heatmap": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-cohort-heatmap", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-cohort-heatmap", + "--stdio" + ] }, "customer-segmentation": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-customer-segmentation", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-customer-segmentation", + "--stdio" + ] }, "map": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-map", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-map", + "--stdio" + ] }, "pdf": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-pdf", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-pdf", + "--stdio" + ] }, "scenario-modeler": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-scenario-modeler", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-scenario-modeler", + "--stdio" + ] }, "shadertoy": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-shadertoy", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-shadertoy", + "--stdio" + ] }, "sheet-music": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-sheet-music", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-sheet-music", + "--stdio" + ] }, "system-monitor": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-system-monitor", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-system-monitor", + "--stdio" + ] }, "threejs": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-threejs", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-threejs", + "--stdio" + ] }, "transcript": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-transcript", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-transcript", + "--stdio" + ] }, "video-resource": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-video-resource", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-video-resource", + "--stdio" + ] }, "wiki-explorer": { "command": "npx", - "args": ["-y", "--silent", "--registry=https://registry.npmjs.org/", "@modelcontextprotocol/server-wiki-explorer", "--stdio"] + "args": [ + "-y", + "--silent", + "--registry=https://registry.npmjs.org/", + "@modelcontextprotocol/server-wiki-explorer", + "--stdio" + ] }, "qr": { "command": "uv", - "args": ["run", "/path/to/ext-apps/examples/qr-server/server.py", "--stdio"] + "args": [ + "run", + "/path/to/ext-apps/examples/qr-server/server.py", + "--stdio" + ] } } } diff --git a/examples/qr-server/README.md b/examples/qr-server/README.md index 36ae4d17..9ad3da6f 100644 --- a/examples/qr-server/README.md +++ b/examples/qr-server/README.md @@ -19,7 +19,11 @@ Then add to your MCP client configuration (stdio transport), replacing the path "mcpServers": { "qr": { "command": "uv", - "args": ["run", "/path/to/ext-apps/examples/qr-server/server.py", "--stdio"] + "args": [ + "run", + "/path/to/ext-apps/examples/qr-server/server.py", + "--stdio" + ] } } } From def51a70adea777f4b53c1c13338a85a7802bebd Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Tue, 20 Jan 2026 01:08:01 +0000 Subject: [PATCH 5/9] 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 --- examples/say-server/README.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/examples/say-server/README.md b/examples/say-server/README.md index b6629ef8..94c5a9fb 100644 --- a/examples/say-server/README.md +++ b/examples/say-server/README.md @@ -2,6 +2,8 @@ A real-time text-to-speech MCP App with karaoke-style text highlighting, powered by [Kyutai's Pocket TTS](https://github.com/kyutai-labs/pocket-tts). +![Screenshot](screenshot.png) + ## MCP App Features Demonstrated This example showcases several MCP App capabilities: @@ -26,35 +28,31 @@ This example showcases several MCP App capabilities: ## Prerequisites -- [uv](https://docs.astral.sh/uv/getting-started/installation/) - fast Python package manager -- A CUDA GPU (recommended) or CPU with sufficient RAM (~2GB for model) +- [uv](https://docs.astral.sh/uv/) - fast Python package manager ## Quick Start -The server is a single self-contained Python file that can be run directly with `uv`: +The server is a single self-contained Python file that can be run directly from GitHub: ```bash -# Run directly (uv auto-installs dependencies) -uv run examples/say-server/server.py +# Run directly from GitHub (uv auto-installs dependencies) +uv run https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/main/examples/say-server/server.py ``` The server will be available at `http://localhost:3109/mcp`. ## Running with Docker -Run directly from GitHub using the official `uv` Docker image. Mount your HuggingFace cache to avoid re-downloading the model: +Run directly from GitHub using the official `uv` Docker image: ```bash docker run --rm -it \ -p 3109:3109 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ - -e HF_HOME=/root/.cache/huggingface \ ghcr.io/astral-sh/uv:debian \ uv run https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/main/examples/say-server/server.py ``` -For GPU support, add `--gpus all` (requires [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)). - ## Usage ### With Claude Desktop @@ -66,8 +64,11 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_ "mcpServers": { "say": { "command": "uv", - "args": ["run", "server.py", "--stdio"], - "cwd": "/path/to/examples/say-server" + "args": [ + "run", + "https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/main/examples/say-server/server.py", + "--stdio" + ] } } } From ccd41ac721834954911ae9f997729d951f0e778b Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Tue, 20 Jan 2026 10:18:19 +0000 Subject: [PATCH 6/9] 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 --- README.md | 10 +++++++++- examples/say-server/README.md | 25 +++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1a37a446..a89a0bb3 100644 --- a/README.md +++ b/README.md @@ -284,12 +284,20 @@ Add to your MCP client configuration (stdio transport): "/path/to/ext-apps/examples/qr-server/server.py", "--stdio" ] + }, + "say": { + "command": "uv", + "args": [ + "run", + "/path/to/ext-apps/examples/say-server/server.py", + "--stdio" + ] } } } ``` -> **Note:** The `qr` server requires cloning the repository first. See [qr-server README](examples/qr-server) for details. +> **Note:** The `qr` and `say` servers require cloning the repository first. See [qr-server](examples/qr-server) and [say-server](examples/say-server) READMEs for details. diff --git a/examples/say-server/README.md b/examples/say-server/README.md index b6629ef8..577a063e 100644 --- a/examples/say-server/README.md +++ b/examples/say-server/README.md @@ -2,6 +2,31 @@ A real-time text-to-speech MCP App with karaoke-style text highlighting, powered by [Kyutai's Pocket TTS](https://github.com/kyutai-labs/pocket-tts). +## MCP Client Configuration + +First, clone the repository: + +```bash +git clone https://github.com/modelcontextprotocol/ext-apps.git +``` + +Then add to your MCP client configuration (stdio transport), replacing the path with your clone location: + +```json +{ + "mcpServers": { + "say": { + "command": "uv", + "args": [ + "run", + "/path/to/ext-apps/examples/say-server/server.py", + "--stdio" + ] + } + } +} +``` + ## MCP App Features Demonstrated This example showcases several MCP App capabilities: From cba7b71e2b567fa6a87cad044f735e794a08c3d0 Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Tue, 20 Jan 2026 10:42:31 +0000 Subject: [PATCH 7/9] docs(say-server): use raw GitHub URL for direct uv run --- README.md | 6 ++++-- examples/say-server/README.md | 12 ++++-------- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a89a0bb3..5fde9df8 100644 --- a/README.md +++ b/README.md @@ -289,7 +289,9 @@ Add to your MCP client configuration (stdio transport): "command": "uv", "args": [ "run", - "/path/to/ext-apps/examples/say-server/server.py", + "--default-index", + "https://pypi.org/simple", + "https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/refs/heads/main/examples/say-server/server.py", "--stdio" ] } @@ -297,7 +299,7 @@ Add to your MCP client configuration (stdio transport): } ``` -> **Note:** The `qr` and `say` servers require cloning the repository first. See [qr-server](examples/qr-server) and [say-server](examples/say-server) READMEs for details. +> **Note:** The `qr` server requires cloning the repository first. See [qr-server README](examples/qr-server) for details. diff --git a/examples/say-server/README.md b/examples/say-server/README.md index 577a063e..fec149c9 100644 --- a/examples/say-server/README.md +++ b/examples/say-server/README.md @@ -4,13 +4,7 @@ A real-time text-to-speech MCP App with karaoke-style text highlighting, powered ## MCP Client Configuration -First, clone the repository: - -```bash -git clone https://github.com/modelcontextprotocol/ext-apps.git -``` - -Then add to your MCP client configuration (stdio transport), replacing the path with your clone location: +Add to your MCP client configuration (stdio transport): ```json { @@ -19,7 +13,9 @@ Then add to your MCP client configuration (stdio transport), replacing the path "command": "uv", "args": [ "run", - "/path/to/ext-apps/examples/say-server/server.py", + "--default-index", + "https://pypi.org/simple", + "https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/refs/heads/main/examples/say-server/server.py", "--stdio" ] } From 198a1be034a587da636596d1aadf634c204717cf Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Tue, 20 Jan 2026 10:46:21 +0000 Subject: [PATCH 8/9] 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. --- examples/say-server/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/say-server/README.md b/examples/say-server/README.md index 94c5a9fb..9718fe4f 100644 --- a/examples/say-server/README.md +++ b/examples/say-server/README.md @@ -48,7 +48,7 @@ Run directly from GitHub using the official `uv` Docker image: ```bash docker run --rm -it \ -p 3109:3109 \ - -v ~/.cache/huggingface:/root/.cache/huggingface \ + -v ~/.cache/huggingface-docker-say-server:/root/.cache/huggingface \ ghcr.io/astral-sh/uv:debian \ uv run https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/main/examples/say-server/server.py ``` From 864bb6dc2d3a920b732ff9f91b4308feb186d35e Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Tue, 20 Jan 2026 10:54:04 +0000 Subject: [PATCH 9/9] docs: clarify that npm start runs examples in dev mode --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5fde9df8..a0609126 100644 --- a/README.md +++ b/README.md @@ -303,7 +303,7 @@ Add to your MCP client configuration (stdio transport): -To run all examples: +To run all examples locally in dev mode: ```bash npm install