FlowScope UX Flow Analyser
io.github.DavidNgugiv0.1.1Updated Oct 7, 2026
Turn YouTube product demos into structured UX flow reports, and compare demos side by side.
Overview
Turns YouTube product-demo videos into structured UX flow reports and lets an assistant compare several demos screen by screen.
- What it does
- Exposes the FlowScope UX-analysis pipeline as MCP tools. It downloads a YouTube demo, transcribes it, extracts and de-duplicates screenshots, describes each screen with a vision model, and synthesises a step-by-step UX flow. Tools cover health checks, listing stored videos, job status, fetching a finished report, retrieving a screen's screenshot, comparing videos, and starting, retrying, re-analysing or deleting analyses.
- When to use it
- Useful when you want an assistant to tear down a recorded onboarding, signup or checkout flow, answer specific questions about a demo's screens and states, or compare how two or three products handle the same flow. It is aimed at UX review work rather than general video handling.
- Requirements
- Runs locally over stdio via uvx (uv is the only prerequisite) and is a client of a separately running FlowScope backend, which needs ffmpeg, yt-dlp, a Python environment and an LLM provider key. Configure FLOWSCOPE_API_URL (default and optionally FLOWSCOPE_API_TOKEN, FLOWSCOPE_MAX_WAIT, FLOWSCOPE_HTTP_TIMEOUT and FLOWSCOPE_POLL_INTERVAL in the client's server configuration. A streamable-HTTP mode is also available.
Installation
In SourceWeft
- Open FlowScope UX Flow Analyser in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
flowscope-mcp
[PyPI] [Python] [License: MIT] [CI] [release] [tag] [MCP Registry]
An MCP server that exposes the
FlowScope UX-analysis pipeline to any LLM client. Speaks MCP
protocol 2026-07-28 and ships two spec-portable
Agent Skills.
FlowScope takes a YouTube product-demo URL, downloads the video, transcribes it, extracts and de-duplicates screenshots of each distinct screen, describes every screen with a vision model, and synthesises a step-by-step UX flow. This package turns that pipeline into tools an agent can call.
Ask your agent something like:
Compare the onboarding flows in these two videos:
<url>and<url>
Tear down the checkout UX in this demo:
<url>
Requirements
This server is a client of a running FlowScope backend; it does not run the pipeline itself. Start the backend first:
The backend needs ffmpeg, a Python environment with backend/requirements.txt,
and one LLM provider key in backend/.env. The server's
flowscope_health_check tool reports exactly which of these is missing, so you
can ask your agent to check rather than guessing.
Install
As a Claude Code plugin
One step, and it brings the skills, the prompts, and the server registration:
From PyPI
Nothing needs a permanent install — uvx runs it in a throwaway environment.
uv is the only prerequisite (brew install uv):
From a git URL or a local checkout
Environment
These are read from the process environment on each call. The MCP Python SDK v2
deliberately stopped reading MCP_* variables and .env files, so set them in
your client's server configuration instead.
Point a harness at it
The config shapes genuinely differ — VS Code's own file uses servers where
every other client uses mcpServers, Codex is TOML, and Claude Desktop does
not expand ${VAR} placeholders — so generating the file is more reliable than
copying a snippet:
It merges into an existing config file and leaves other servers alone.
VS Code additionally reads the portable <project>/.mcp.json shape (key
mcpServers), which flowscope-mcp-install vscode-portable writes when you want
one config shared with Claude Code and Cursor.
Remote / shared deployment
Run one server for several clients, or for a harness that cannot spawn a process:
Clients connect to POST http://127.0.0.1:8765/mcp:
docs/install.md has the full per-harness reference, the placeholder syntax each one accepts, and the two traps that most often break an install.
Use it
Restart your client, open a new chat, and check the install first:
Check whether FlowScope is ready to use.
That runs flowscope_health_check and names anything missing — usually ffmpeg or
an LLM provider key on the backend host. Then ask for what you want.
Example prompts
One video, fully analysed
Tear down the onboarding UX in this demo:
<youtube-url>
What does this product actually do, based on this demo? Walk me through the flow screen by screen:
<youtube-url>
Analyse
<youtube-url>and tell me where a first-time user would get stuck.
A specific question about a flow
In this demo, how many steps does signup take, and what does each one ask for?
<youtube-url>
Does this demo show any error or empty states?
<youtube-url>
What's above the fold on the first screen, and what's the primary call to action?
<youtube-url>
Several videos, compared
Compare the onboarding flows in these two demos. Where do they diverge, and what's the trade-off each one makes?
<youtube-url-1><youtube-url-2>
I'm designing a checkout flow. What do these two demos do differently, and what should I borrow?
<url1><url2>
Which of these three gets a new user to first value fastest, judging by the demos?
<url1><url2><url3>
Working with what already exists
What videos has FlowScope already analysed?
Show me the screenshot of the pricing screen from that report.
You do not need to phrase these carefully. Analyses are cached by YouTube video id, so a vague prompt costs a lookup rather than a re-analysis — the agent checks the cache before spending anything.
What happens after you press enter
Analysing a video downloads it, transcribes it, extracts and de-duplicates screenshots, then makes one vision call per distinct screen plus a synthesis call. A five-minute demo typically yields 15–40 screens. Expect 2–10 minutes and real money per video.
flowscope_analyze_video waits by default and usually returns the finished
report directly, so one prompt is normally enough. If the video needs longer than
the budget it returns status: "running" with a video_id, and the agent should
poll flowscope_job_status. If it resubmits the URL instead, stop it — that
starts duplicate work.
Answers are grounded, or should be
Reports have three layers: ux_insights (the synthesis), flow_steps (the
ordered user path), and frames (the evidence — one entry per screen, with its
purpose, UI elements, and aligned narration). A good answer leads with the
insights and cites the screen behind each claim. The bundled skills enforce this,
including saying "the demo does not show this" rather than inferring.
docs/usage.md has the full walkthrough, prompt patterns that produce better answers, and a troubleshooting table.
Tools
Ten tools, split between read-only inspection and actions that cost money.
Plus two prompts (flowscope_ux_teardown, flowscope_compare_flows) and two
resources (flowscope://videos, flowscope://videos/{video_id}/report).
Cost and time
Analysing a video downloads it, transcribes it, and makes one vision call per distinct screen plus a synthesis call. That is minutes and real money per video. Two things protect against waste:
- Results are cached by YouTube video id.
flowscope_list_videosreveals existing analyses, and resubmitting a finished video is free and instant. flowscope_analyze_videochecks the cache before starting work and only submits what is actually new.
The bundled skill teaches an agent to check the cache first.
Transports
Streamable HTTP serves POST /mcp. The SDK serves the 2026-07-28 protocol
revision and the older handshake era from the same endpoint, so legacy clients
work without extra configuration. Legacy clients create server-side sessions,
which are stored in-process — if you run more than one worker behind a load
balancer, enable sticky routing.
Skills
Two Agent Skills ship alongside the server, written to the open specification so they install into any compatible client:
They carry the operational knowledge the tool descriptions cannot: check the health and the cache before spending money, read the synthesis rather than re-deriving it from the raw transcript, say "the demo does not show this" rather than inferring, and treat an auto-caption's product names with suspicion.
The skills and the server are independent — the skills are useful on a report you already have, and the server works without them.
Install them
With the plugin (Claude Code) — skills and server in one step:
The portable directory, which most clients scan. .agents/skills/ is the
cross-client project convention, so several harnesses pick it up from one copy:
A client's own directory, when you want it only there:
With the skills CLI, for a team or one of ~80 agent targets:
Verify a skill is portable with the official validator:
Both skills declare only the six fields the open specification defines, so they work unmodified in Claude Code, Claude Desktop, ChatGPT and Codex, Cursor, VS Code, Gemini CLI, Zed, Goose, OpenCode and the rest. A test enforces that.
docs/skills.md covers every route, the compatibility aliases each client reads, and how to use the skills without the MCP server at all.
Documentation
Releasing
Releases are automated and driven by version tags. .github/workflows/release.yml
verifies everything, publishes to PyPI with trusted publishing, publishes to the
MCP Registry, and creates a GitHub release with the wheel and sdist attached.
Publishing also runs on demand — Actions → Release MCP server — with a
publish input that defaults to off, so the default manual run verifies and
builds without publishing anything.
Six version declarations in five files must agree, and the MCP Registry requires
the server and its package version to match. scripts/version.py is what keeps
them in sync, because editing them by hand is how a release fails during
publishing — and PyPI permanently refuses to reuse a version number, so a
half-published release cannot be retried:
See docs/publishing.md for the full release process, version-numbering rules, the one-time PyPI configuration, and what to do when a release goes wrong.
Development
The suite is offline: tool behaviour runs against an in-memory MCP client and a mocked HTTP transport, so it needs neither a network nor a running backend. Separate tests spawn the real process to verify the stdio contract — that stdout carries only protocol frames — and validate the registry, plugin, and version metadata. The release workflow's triggers are pinned by tests too, so a future edit cannot make publishing automatic on a branch push.
Validate the skills and manifests against the official tooling:
Licence
MIT
Source: mcp/README.md at commit 9273ea0
Tools
0Version history
1- v0.1.1LatestOct 7, 2026
More servers like FlowScope UX Flow Analyser
InfoSlides — put content on a TV or screen
io.github.arnibj
Lets an assistant create a digital signage workspace and put slides, PDFs, photos, or live data onto TVs and screens.
seogeoaeo.ai
io.github.SRX9
Lets an assistant research competitors, keywords and ads, and audit public websites for SEO, AEO and GEO readiness with prioritized fixes.
Banquish
space.banquish
Lets an assistant compose live parts of real web pages into a Workspace in the Banquish Mac app.