feat(examples): add say-server - streaming Pocket TTS with karaoke highlighting

[ochafik]

Summary

Adds a new example MCP App: say-server - a real-time text-to-speech server with karaoke-style text highlighting, powered by Kyutai's Pocket TTS 🐐 🔥.

MCP App Features Demonstrated

• Single-file executable: Python server with embedded React UI - no build step required
• Partial tool inputs (ontoolinputpartial): Widget receives streaming text as it's being generated
• Queue-based streaming: Demonstrates how to stream text out and audio in via a polling tool (adds text to an input queue, retrieves audio chunks from an output queue)
• Model context updates: Widget updates the LLM with playback progress
• Native theming: Uses CSS variables for automatic dark/light mode adaptation
• Fullscreen mode: Toggle fullscreen via requestDisplayMode() API
• Multi-widget speak lock: Coordinates multiple TTS widgets via localStorage so only one plays at a time (see below)
• Hidden tools (visibility: ["app"]): Private tools only accessible to the widget, not the model
• External links (openLink): Attribution popup uses app.openLink() to open external URLs
• CSP metadata: Resource declares required domains (esm.sh) for in-browser transpilation

Multi-Widget Speak Lock

When multiple TTS widgets exist in the same browser (e.g., multiple chat messages each with their own say widget), they coordinate via localStorage to ensure only one plays at a time:

Step	Description
1. Unique IDs	Each widget receives a UUID via toolResult._meta.widgetUUID
2. Announce	On play, widget writes {uuid, timestamp} to localStorage["mcp-tts-playing"]
3. Poll	Every 200ms, playing widgets check if another took the lock
4. Yield	If another widget started, pause and yield gracefully
5. Clean up	On pause/finish, clear the lock (only if owned)

This "last writer wins" protocol ensures clicking play on any widget immediately pauses others, without requiring cross-iframe postMessage coordination.

Features

• Streaming TTS: Audio starts playing as text is being generated
• Karaoke highlighting: Words are highlighted in sync with speech
• Interactive controls: Click to pause/resume, double-click to restart
• Low latency: Uses a polling-based queue for minimal delay

Testing

• E2E tests added in tests/e2e/servers.spec.ts

• Tested locally via stdio transport

• Host config:

  {
      "mcpServers": {
          "say": {
              "command": "uv",
              "args": [
                  "run",
                  "--index",
                  "https://pypi.org/simple",
                  "https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/ochafik/say-server/examples/say-server/server.py",
                  "--stdio"
               ]
          }
      }
  }

• Less trusting host config (docker instance still can scan your host's local ports, mind you: security is always relative)

  {
      "mcpServers": {
          "say": {
              "command": "docker",
              "args": [
                  "run",
                  "--quiet",
                  "--rm",
                  "-i",
                  "ghcr.io/astral-sh/uv:debian",
                  "uv",
                  "run",
                  "--index",
                  "https://pypi.org/simple",
                  "https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/ochafik/say-server/examples/say-server/server.py",
                  "--stdio"
               ]
          }
      }
  }

Dependencies

Uses Python with uv or docker for zero-config execution:

• mcp - MCP Python SDK
• pocket-tts - Kyutai's TTS library
• uvicorn, starlette - HTTP server

Third-party Licenses

All third-party code / model is hopefully properly attributed (see LICENSE comments in server.py and in the info bubble):

• pocket-tts python package (Apache 2.0)
• pocket-tts model (CC BY 4.0)
• kyutai/tts-voices (CC BY 4.0)

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@304

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-react@304

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-vanillajs@304

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-budget-allocator@304

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-cohort-heatmap@304

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-customer-segmentation@304

@modelcontextprotocol/server-map

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-map@304

@modelcontextprotocol/server-pdf

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-pdf@304

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-scenario-modeler@304

@modelcontextprotocol/server-shadertoy

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-shadertoy@304

@modelcontextprotocol/server-sheet-music

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-sheet-music@304

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-system-monitor@304

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-threejs@304

@modelcontextprotocol/server-transcript

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-transcript@304

@modelcontextprotocol/server-video-resource

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-video-resource@304

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-wiki-explorer@304

commit: 335ba34