@flowcast/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+FlowCast — Proprietary License (Free to Use)
+
+Copyright (c) 2026 FlowCast. All rights reserved.
+
+You are granted a non-exclusive, non-transferable, revocable license to download,
+install, and run this software ("the Software") for personal or internal business
+purposes, at no charge.
+
+You may NOT: (a) redistribute, resell, sublicense, or host the Software as a service;
+(b) modify, decompile, reverse-engineer, or create derivative works; (c) remove or
+alter this notice. The Software is the free local client of the FlowCast service.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE SOFTWARE.
+
+Bundled third-party components are licensed separately; see THIRD-PARTY-NOTICES.

package/README.md

@@ -0,0 +1,213 @@
+<h1 align="center">FlowCast</h1>
+
+<p align="center"><strong>Turn your AI coding agent into a producer of interactive, narrated walkthroughs.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/flowcast"><img alt="npm" src="https://img.shields.io/npm/v/flowcast?color=6c5ce7"></a>
+  <img alt="node" src="https://img.shields.io/node/v/flowcast?color=43a047">
+  <img alt="license" src="https://img.shields.io/badge/license-proprietary-555">
+  <img alt="MCP" src="https://img.shields.io/badge/Model_Context_Protocol-server-000">
+</p>
+
+---
+
+FlowCast is an [MCP](https://modelcontextprotocol.io) server that renders a single,
+**self-contained interactive HTML walkthrough** from a timeline your agent authors. Code
+types itself out in a real editor, narration plays in sync, the camera follows the action —
+and the whole thing is one file you can open in any browser. **No server. No build. No dependencies.**
+
+Ask Claude (or any MCP client) *"walk me through the auth flow"* and you get back a polished,
+scrubbable explainer instead of a wall of text.
+
+The command is always the same — `npx` fetches and runs it locally over stdio, no global install:
+
+```text
+command: npx     args: -y @flowcast/mcp@latest
+```
+
+See [**Add it to your agent**](#add-it-to-your-agent) for Claude Code, Claude Desktop, Codex, Cursor, Kiro, Windsurf, VS Code, and Gemini CLI.
+
+> **Required:** every cast is narrated, so FlowCast needs a text-to-speech key — bring your own
+> OpenAI, ElevenLabs, or Google key (see [Voice](#voice)). The software is free; you only pay your
+> TTS provider for the audio it generates.
+>
+> **New here? Run `npx -y @flowcast/mcp setup`** — a one-time wizard that asks for your provider + key,
+> validates it, saves it to `~/.flowcast/config.json`, **and offers to register FlowCast into the
+> clients it detects** (Claude Code, Claude Desktop, Cursor, Codex, Kiro, Windsurf, Gemini CLI, VS
+> Code). No JSON editing required.
+
+## Add it to your agent
+
+Most clients share one JSON config; a couple use their own format. Pick yours.
+
+### CLI shortcuts
+
+```bash
+# Claude Code
+claude mcp add flowcast -- npx -y @flowcast/mcp@latest        # add -s user to enable it everywhere
+
+# OpenAI Codex                                             # writes ~/.codex/config.toml
+codex mcp add flowcast -- npx -y @flowcast/mcp@latest
+
+# Kiro
+kiro-cli mcp add --name flowcast --command npx --args "-y" --args "@flowcast/mcp@latest" --scope workspace
+
+# VS Code
+code --add-mcp '{"name":"flowcast","command":"npx","args":["-y","@flowcast/mcp@latest"]}'
+```
+
+**A TTS key is required** — pass it with `--env`. Claude Code: `claude mcp add flowcast --env VOICE_MODEL=openai --env OPENAI_API_KEY=sk-... -- npx -y @flowcast/mcp@latest`. Codex and Kiro take the same repeated `--env KEY=VALUE` flags.
+
+### Standard config (most clients)
+
+Drop this into your client's MCP config file (the `env` key holds your required TTS key — swap in your provider):
+
+```json
+{
+  "mcpServers": {
+    "flowcast": {
+      "command": "npx",
+      "args": ["-y", "@flowcast/mcp@latest"],
+      "env": { "VOICE_MODEL": "openai", "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+| Client | Config file |
+|---|---|
+| **Claude Desktop** | `claude_desktop_config.json` — Settings → Developer → Edit Config |
+| **Cursor** | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) |
+| **Kiro** | `.kiro/settings/mcp.json` (workspace) or `~/.kiro/settings/mcp.json` (user) |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
+| **Gemini CLI** | `~/.gemini/settings.json` |
+
+### Different formats
+
+**OpenAI Codex** — `~/.codex/config.toml` (TOML; note the underscore in `mcp_servers`):
+
+```toml
+[mcp_servers.flowcast]
+command = "npx"
+args = ["-y", "@flowcast/mcp@latest"]
+```
+
+**VS Code** — `.vscode/mcp.json` uses a `servers` key (not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "flowcast": {
+      "command": "npx",
+      "args": ["-y", "@flowcast/mcp@latest"],
+      "env": { "VOICE_MODEL": "openai", "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+> **Your TTS key goes under `env`** on the server entry (Codex TOML:
+> `env = { VOICE_MODEL = "openai", OPENAI_API_KEY = "sk-..." }`). It's required — see
+> [Voice](#voice) and [Configuration](#configuration).
+
+## Why it's different
+
+- **One file, fully interactive.** Scrub, pause, and play like a video — but it's live code in a real [CodeMirror](https://codemirror.net) editor, not a screen recording. Opens offline, in any browser.
+- **Your model does the thinking; FlowCast does the rendering.** It runs *no LLM of its own* — your agent authors the timeline, this server turns it into a deterministic, pixel-stable cast.
+- **Four kinds of story.** Code, whiteboard, map, and 3D — one consistent player.
+- **Always narrated.** Every cast is voiced in sync (with matching captions) — you bring a TTS key.
+- **Runs locally.** Rendering happens on your machine; your code never leaves it — only the short narration lines go to your chosen TTS provider.
+
+## Try it
+
+In any codebase, just ask:
+
+> *"Make an interactive walkthrough of the rate-limiter in `src/middleware/`."*
+> *"Diagram how a request flows through the system as a whiteboard cast."*
+> *"Give me a 3D walkthrough of our Q3 revenue numbers."*
+
+Your agent calls the matching tool and hands you a link to open.
+
+## What it can make
+
+| Tool | Produces |
+|------|----------|
+| `create_walkthrough` | **Code** — files that type out in a live editor, synced narration, precise line highlights, and a terminal panel |
+| `create_whiteboard_walkthrough` | **Whiteboard** — animated concept maps and diagrams that draw themselves |
+| `create_map_walkthrough` | **Map** — narrated tours over an interactive geographic map |
+| `create_3d_walkthrough` | **3D** — 3D scenes and data stories (e.g. animated charts) |
+
+Plus three helpers your agent uses to ship a clean result:
+
+| Tool | Does |
+|------|------|
+| `check_walkthrough` | Lints a draft for quality issues (ambiguous highlights, over-long narration, …) — read-only |
+| `revise_walkthrough` | Applies targeted fixes to a draft without re-authoring the whole timeline |
+| `export_walkthrough` | Writes the finished `.html` to a path you choose |
+
+## How you get the result
+
+Every cast is returned three ways, so it works in any client:
+
+1. **A local preview URL** — `http://127.0.0.1:7616/<id>.html` (loopback only). The most reliable way to view it with full interactivity.
+2. **A self-contained `.html` file** — handed back as a `file://` link; open or share it.
+3. **An MCP resource** — `ui://flowcast/<id>`, fetchable by resource-aware hosts.
+
+## Voice
+
+**Voice is required** — every cast is narrated, and synced captions are always shown alongside it.
+Pick a provider with `VOICE_MODEL` and set that provider's key (bring your own). Without a configured
+key, cast generation **fails with a clear error** — there is no silent captions-only fallback.
+
+The easiest way to configure it is the one-time wizard:
+
+```bash
+npx -y @flowcast/mcp setup
+```
+
+It asks for your provider + key, validates it, saves `~/.flowcast/config.json` (owner-only), **and
+then offers to add FlowCast to each MCP client it finds** — Claude Code, Codex, and VS Code via
+their own `mcp add` / `--add-mcp` command, and Claude Desktop / Cursor / Kiro / Windsurf / Gemini CLI
+by merging into their config (your existing file is backed up to `.bak` first, and every change is
+confirmed). The server reads the saved key
+automatically, so the registered entries hold no secrets. Prefer env? A key in your client's `env`
+block always overrides the saved file.
+
+| `VOICE_MODEL` | Key | Default |
+|---|---|---|
+| `openai` *(default)* | `OPENAI_API_KEY` | `gpt-4o-mini-tts` |
+| `elevenlabs` | `ELEVENLABS_API_KEY` | `eleven_turbo_v2_5`, voice `ELEVENLABS_VOICE_ID` |
+| `google` | `GOOGLE_TTS_API_KEY` | voice `GOOGLE_TTS_VOICE` (e.g. `en-US-Neural2-D`) |
+
+```jsonc
+"flowcast": {
+  "command": "npx", "args": ["-y", "@flowcast/mcp@latest"],
+  "env": { "VOICE_MODEL": "elevenlabs", "ELEVENLABS_API_KEY": "..." }
+}
+```
+
+## Configuration
+
+A TTS provider key is **required**; everything else is optional.
+
+| Variable | Purpose |
+|---|---|
+| `VOICE_MODEL` | TTS provider: `openai` (default), `elevenlabs`, `google` |
+| `OPENAI_API_KEY` / `ELEVENLABS_API_KEY` / `GOOGLE_TTS_API_KEY` | **Required** — the key for your chosen provider |
+| `FLOWCAST_CONFIG_DIR` | Where the saved config lives (default `~/.flowcast`) |
+| `FLOWCAST_OUTPUT_DIR` | Where `.html` files are written |
+| `FLOWCAST_PORT` | Local preview port (default `7616`; next free port if taken) |
+| `FLOWCAST_NO_HTTP` | Set to `1` to disable the local preview server |
+| `FLOWCAST_TTS_VOICE` / `FLOWCAST_TTS_MODEL` / `FLOWCAST_TTS_INSTRUCTIONS` | Fine-tune the OpenAI voice |
+
+## Requirements
+
+- **Node.js ≥ 18** (`npx` handles the rest).
+- A **TTS provider key** — OpenAI, ElevenLabs, or Google (see [Voice](#voice)). Required.
+- An MCP client — [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.claude.com/claude-code), Cursor, or any other.
+
+## License
+
+**Free to use — not open source.** See [LICENSE](./LICENSE) and [THIRD-PARTY-NOTICES](./THIRD-PARTY-NOTICES).
+
+<p align="center"><sub>Built with the Model Context Protocol · a hosted, zero-install edition is on the way.</sub></p>

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,11 @@
+FlowCast bundles the following third-party open-source components. Their licenses
+apply to those components only; FlowCast's own code remains proprietary.
+
+- @modelcontextprotocol/sdk — MIT
+- zod — MIT
+- @dagrejs/dagre — MIT
+- @codemirror/state — MIT
+- @breezystack/lamejs — LGPL-3.0
+- sharp — Apache-2.0 (bundles libvips — LGPL-3.0, dynamically linked)
+
+Full license texts are available from each project's repository on npm/GitHub.