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 8091ad8..b85fb90 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 d29073d..4b3f26c 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 e0e7584..693fec3 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 22505c8..ff599af 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 41e23e3..e3fabc9 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 2090973..84a0b0e 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 b81d2e1..917abd6 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 322a116..31a0f4a 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 76a453e..6e118e9 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 ad9223d..38a4f38 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 48964a8..bdc83be 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 e98016e..0dbb54f 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 c5252a7..8d3e100 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 5f965cb..58dc639 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 8f2f990..cdcf869 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 6e34386..7330572 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 41e6d2f..2b58fee 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 dae2228..4ae89ee 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 252e6bb..01d89e6 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 bd827e3..70ac6d9 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 0dbb54f..36ae4d1 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 6057fe1..5be1f12 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 5be1f12..4ac41a5 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 36ae4d1..9ad3da6 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 b6629ef..94c5a9f 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 1a37a44..a89a0bb 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 b6629ef..577a063 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 a89a0bb..5fde9df 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 577a063..fec149c 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 94c5a9f..9718fe4 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 5fde9df..a060912 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