YouTube 제품 데모를 구조화된 UX 플로우 보고서로 변환하고 사용자 경험을 나란히 비교할 수 있습니다.
다른 이름 DavidNgugi/flowscope, flowscope, flowscope-mcp
- 스타
- 2
- Tools
- 10
- 다운로드, 30일
- —
- 최신 버전
- 0.1.1
- 마지막 커밋
- 2026년 10월 12일
- 라이선스
- MIT
FlowScope UX Flow Analyser MCP란?
FlowScope UX Flow Analyser은(는) MCP server입니다. YouTube 제품 데모를 구조화된 UX 플로우 보고서로 변환하고 사용자 경험을 나란히 비교할 수 있습니다. 10개 도구를 제공합니다. 예: flowscope_health_check, flowscope_list_videos, flowscope_job_status.
프로젝트 README에서 생성된 요약
FlowScope UX Flow Analyser MCP server 정보
FlowScope UX Flow Analyser는 YouTube 제품 데모를 구조화된 사용자 경험 보고서로 변환하는 전문 파이프라인을 제공합니다. 이 서버는 비디오 콘텐츠에서 상세한 UX 인사이트를 추출해야 하는 제품 디자이너 및 리서처를 위해 설계되었습니다. 서버는 로컬 FlowScope 백엔드의 클라이언트 역할을 하며, 백엔드에서 비디오 다운로드, 오디오 전사, 스크린샷 추출 및 비전 모델을 사용한 개별 화면 설명 등의 무거운 작업을 처리합니다.
사용자는 Claude Desktop, Cursor 또는 VS Code와 같은 MCP 호환 클라이언트를 통해 서버와 상호작용합니다. 시스템에는 백엔드 상태 확인, 이전에 분석된 비디오 목록 조회, 플로우 단계 및 화면 단위 결과가 포함된 상세 보고서 검색을 위한 도구가 포함되어 있습니다. 분석 프로세스에 비전 모델 호출과 비디오 프로세싱이 포함되므로, ffmpeg와 LLM 제공자 키가 구성된 실행 중인 백엔드가 필요합니다. 불필요한 비용 발생을 방지하기 위해 서버는 YouTube 비디오 ID별로 결과를 캐싱하여 이전에 처리된 콘텐츠를 즉시 불러올 수 있습니다.
활용 사례
- 1UX 티어다운 수행에이전트가 단일 YouTube URL을 분석하여 온보딩이나 결제와 같은 특정 사용자 여정을 화면 단위로 상세히 분석할 수 있습니다.
- 2여러 제품 플로우 비교AI에게 두 개 이상의 서로 다른 제품 데모 비디오 간의 차이점과 공통 패턴을 식별하도록 요청할 수 있습니다.
- 3백엔드 준비 상태 확인개발자는 상태 확인 도구를 사용하여 ffmpeg나 API 키와 같은 누락된 종속성으로 인해 파이프라인 실행이 방해받고 있는지 확인할 수 있습니다.
- 4시각적 증거 추출AI 클라이언트가 생성된 보고서에서 특정 스크린샷을 가져와 사용자에게 논의 중인 UI 요소가 정확히 무엇인지 보여줄 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
FlowScope UX Flow Analyser MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 FlowScope UX Flow Analyser MCP 설치
$ claude mcp add --env 'FLOWSCOPE_API_TOKEN=<YOUR_FLOWSCOPE_API_TOKEN>' flowscope -- uvx flowscope-mcpCursor에 FlowScope UX Flow Analyser MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"flowscope": {
"command": "uvx",
"args": [
"flowscope-mcp"
],
"env": {
"FLOWSCOPE_API_TOKEN": "<YOUR_FLOWSCOPE_API_TOKEN>"
}
}
}
}VS Code에 FlowScope UX Flow Analyser MCP 설치
.vscode/mcp.json
{
"servers": {
"flowscope": {
"type": "stdio",
"command": "uvx",
"args": [
"flowscope-mcp"
],
"env": {
"FLOWSCOPE_API_TOKEN": "<YOUR_FLOWSCOPE_API_TOKEN>"
}
}
}
}VS Code CLI에 FlowScope UX Flow Analyser MCP 설치
$ code --add-mcp '{"name":"flowscope","type":"stdio","command":"uvx","args":["flowscope-mcp"],"env":{"FLOWSCOPE_API_TOKEN":"<YOUR_FLOWSCOPE_API_TOKEN>"}}'Claude Desktop에 FlowScope UX Flow Analyser MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"flowscope": {
"command": "uvx",
"args": [
"flowscope-mcp"
],
"env": {
"FLOWSCOPE_API_TOKEN": "<YOUR_FLOWSCOPE_API_TOKEN>"
}
}
}
}Codex에 FlowScope UX Flow Analyser MCP 설치
$ codex mcp add flowscope --env 'FLOWSCOPE_API_TOKEN=<YOUR_FLOWSCOPE_API_TOKEN>' -- uvx flowscope-mcpCodex config.toml에 FlowScope UX Flow Analyser MCP 설치
~/.codex/config.toml
[mcp_servers.flowscope] command = "uvx" args = ["flowscope-mcp"] [mcp_servers.flowscope.env] FLOWSCOPE_API_TOKEN = "<YOUR_FLOWSCOPE_API_TOKEN>"
Gemini CLI에 FlowScope UX Flow Analyser MCP 설치
$ gemini mcp add -s user -e 'FLOWSCOPE_API_TOKEN=<YOUR_FLOWSCOPE_API_TOKEN>' flowscope uvx -- flowscope-mcpGemini settings.json에 FlowScope UX Flow Analyser MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"flowscope": {
"command": "uvx",
"args": [
"flowscope-mcp"
],
"env": {
"FLOWSCOPE_API_TOKEN": "<YOUR_FLOWSCOPE_API_TOKEN>"
}
}
}
}FlowScope UX Flow Analyser MCP 도구 10
README에서 감지됨flowscope_health_checkflowscope_list_videosflowscope_job_statusflowscope_get_reportflowscope_frame_imageflowscope_compare_videosflowscope_analyze_videoflowscope_retry_videoflowscope_reanalyze_videoflowscope_delete_video
| flowscope_health_check | — | |
| flowscope_list_videos | — | |
| flowscope_job_status | — | |
| flowscope_get_report | — | |
| flowscope_frame_image | — | |
| flowscope_compare_videos | — | |
| flowscope_analyze_video | — | |
| flowscope_retry_video | — | |
| flowscope_reanalyze_video | — | |
| flowscope_delete_video | — |
구성
FLOWSCOPE_API_TOKEN비밀Bearer token, only needed when the backend sits behind an authenticating proxy.
FLOWSCOPE_API_URLBase URL of the running FlowScope backend. '/api' is appended if absent.
FLOWSCOPE_MAX_WAITDefault seconds that flowscope_analyze_video waits for a job before returning a job id.
| 이름 | 설명 | 유형 |
|---|---|---|
| FLOWSCOPE_API_TOKEN | Bearer token, only needed when the backend sits behind an authenticating proxy. | 비밀 |
| FLOWSCOPE_API_URL | Base URL of the running FlowScope backend. '/api' is appended if absent. | |
| FLOWSCOPE_MAX_WAIT | Default seconds that flowscope_analyze_video waits for a job before returning a job id. |
자동 검사
2026년 11월 13일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능davidngugi/flowscope is public and reachablegithub.com/davidngugi/flowscope ↗통과
- 패키지가 이 저장소를 소스로 명시flowscope-mcp names davidngugi/flowscope as sourcepypi.org/project/flowscope-mcp/ ↗통과
- 빌드 출처(Sigstore 증명)No build attestation published for this release검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-12github.com/davidngugi/flowscope ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from flowscope-mcp통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음29 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음10 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기flowscope-mcp
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.
uvx flowscope-mcp # stdio server; needs a local FlowScope backend
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:
cd backend
uvicorn app.main:app --port 8000
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:
/plugin marketplace add DavidNgugi/flowscope
/plugin install flowscope@flowscope
From PyPI
Nothing needs a permanent install — uvx runs it in a throwaway environment.
uv is the only prerequisite (brew install uv):
uvx flowscope-mcp # starts a stdio server
uvx flowscope-mcp --version # confirm the published version
uvx flowscope-mcp@0.1.0 # pin, when reproducibility matters
From a git URL or a local checkout
uvx --from /absolute/path/to/flowscope/mcp flowscope-mcp
uvx --from "git+https://github.com/DavidNgugi/flowscope.git@main#subdirectory=mcp" flowscope-mcp
Environment
| Variable | Default | Purpose |
|---|---|---|
FLOWSCOPE_API_URL |
http://127.0.0.1:8000 |
Backend base URL. /api is appended if absent, so either form works. |
FLOWSCOPE_API_TOKEN |
(empty) | Sent as Authorization: Bearer …. Only needed behind an authenticating proxy. |
FLOWSCOPE_HTTP_TIMEOUT |
30 |
Seconds for ordinary requests. |
FLOWSCOPE_MAX_WAIT |
900 |
Default wait budget for flowscope_analyze_video. |
FLOWSCOPE_POLL_INTERVAL |
5 |
Seconds between job-status polls. |
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:
uvx --from flowscope-mcp flowscope-mcp-install --help # every client + its path
uvx --from flowscope-mcp flowscope-mcp-install print # portable JSON, writes nothing
uvx --from flowscope-mcp flowscope-mcp-install claude-code
uvx --from flowscope-mcp flowscope-mcp-install cursor
uvx --from flowscope-mcp flowscope-mcp-install vscode
uvx --from flowscope-mcp flowscope-mcp-install codex
uvx --from flowscope-mcp flowscope-mcp-install gemini
uvx --from flowscope-mcp flowscope-mcp-install claude-desktop
It merges into an existing config file and leaves other servers alone.
| Harness | File | Key | Syntax |
|---|---|---|---|
| Claude Code | .mcp.json, ~/.claude.json |
mcpServers |
JSON |
| Claude Desktop | claude_desktop_config.json |
mcpServers |
JSON |
| Cursor | .cursor/mcp.json, ~/.cursor/mcp.json |
mcpServers |
JSON |
| VS Code | .vscode/mcp.json |
servers |
JSON |
| Codex CLI | ~/.codex/config.toml |
[mcp_servers.flowscope] |
TOML |
| Gemini CLI | ~/.gemini/settings.json |
mcpServers |
JSON |
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.
Run one server for several clients, or for a harness that cannot spawn a process:
flowscope-mcp --transport streamable-http --host 127.0.0.1 --port 8765
Clients connect to POST http://127.0.0.1:8765/mcp:
claude mcp add --transport http flowscope 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.
| Tool | Annotations | What it does |
|---|---|---|
flowscope_health_check |
read-only | Backend up? ffmpeg, yt-dlp, provider key present? |
flowscope_list_videos |
read-only | Every stored video with its latest job status. |
flowscope_job_status |
read-only | Progress of one analysis job. |
flowscope_get_report |
read-only | The finished UX report: flow, insights, per-screen findings. |
flowscope_frame_image |
read-only | The actual screenshot for one screen, as an image. |
flowscope_compare_videos |
open-world | Cross-video common patterns, divergences, stage matrix. |
flowscope_analyze_video |
open-world | Download and analyse one or more URLs. Costs money. |
flowscope_retry_video |
idempotent | Re-queue a failed job; completed stages are reused. |
flowscope_reanalyze_video |
destructive | Discard derived results and redo analysis. |
flowscope_delete_video |
destructive | Remove a video; optionally delete media from disk. |
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
flowscope-mcp # stdio (default)
flowscope-mcp --transport streamable-http --port 8765
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:
| Skill | Use it when |
|---|---|
analyzing-product-demo-ux |
You want a teardown of one recorded flow — how onboarding, signup, or checkout works, screen by screen. |
comparing-product-demo-ux |
You want several products compared: shared conventions, real divergences, and what is worth borrowing. |
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:
/plugin marketplace add DavidNgugi/flowscope
/plugin install flowscope@flowscope
The portable directory, which most clients scan. .agents/skills/ is the
cross-client project convention, so several harnesses pick it up from one copy:
mkdir -p .agents/skills && cp -r skills/* .agents/skills/ # this project
mkdir -p ~/.agents/skills && cp -r skills/* ~/.agents/skills/ # every project
A client's own directory, when you want it only there:
cp -r skills/* ~/.claude/skills/ # Claude Code, personal scope
cp -r skills/* ~/.codex/skills/ # Codex CLI
cp -r skills/* ~/.cursor/skills/ # Cursor
cp -r skills/* .github/skills/ # VS Code / Copilot
cp -r skills/* ~/.gemini/skills/ # Gemini CLI
With the skills CLI, for a team or one of ~80 agent targets:
npx skills add DavidNgugi/flowscope
| Client | Project | Personal |
|---|---|---|
| Claude Code | .claude/skills/ |
~/.claude/skills/ |
| Codex CLI | .agents/skills/ |
~/.codex/skills/ |
| Cursor | .agents/skills/, .cursor/skills/ |
~/.cursor/skills/ |
| VS Code / Copilot | .github/skills/, .claude/skills/, .agents/skills/ |
~/.copilot/skills/ |
| Gemini CLI | .gemini/skills/ or .agents/skills/ |
~/.gemini/skills/ |
| Zed, Cline | .agents/skills/ |
~/.agents/skills/ |
Verify a skill is portable with the official validator:
pip install "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref"
skills-ref validate .agents/skills/analyzing-product-demo-ux
# -> Valid skill: .agents/skills/analyzing-product-demo-ux
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
| Document | Contents |
|---|---|
| docs/install.md | Installing into each harness: config shapes, placeholder syntax, remote/HTTP setup, verification |
| docs/usage.md | Example prompts, what happens on each call, troubleshooting, getting better answers |
| docs/skills.md | Installing the skills into each client, the directory matrix, and using them without the server |
| docs/server-internals.md | Design rationale: annotations, error handling, protocol era, output shapes |
| docs/publishing.md | Releasing: tag or manual, versioning rules, one-time setup, recovery |
| docs/security.md | Tool poisoning, data flow, and what a non-sandboxed server means |
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.
cd mcp
./.venv/bin/python scripts/version.py bump 0.2.0 # rewrites all five files
cd ..
git commit -am "release: v0.2.0" && git tag -a v0.2.0 -m "v0.2.0"
git push && git push --tags
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:
python scripts/version.py show # what every file currently says
python scripts/version.py check # fail if any disagree, including the tag
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
cd mcp
python3 -m venv .venv && ./.venv/bin/pip install -e ".[dev]"
./.venv/bin/ruff check src tests scripts
./.venv/bin/pytest -q
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:
skills-ref validate skills/analyzing-product-demo-ux # agentskills.io reference validator
claude plugin validate . # marketplace manifest
claude plugin validate ./mcp --strict # plugin manifest
python scripts/validate_metadata.py # server.json + wheel contents
Licence
MIT
FlowScope UX Flow Analyser MCP 질문
FlowScope UX Flow Analyser MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'FLOWSCOPE_API_TOKEN=<YOUR_FLOWSCOPE_API_TOKEN>' flowscope -- uvx flowscope-mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
FlowScope UX Flow Analyser MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
FlowScope UX Flow Analyser MCP는 어떤 도구를 제공하나요?
10개 도구를 제공합니다. 예: flowscope_health_check, flowscope_list_videos, flowscope_job_status, flowscope_get_report, flowscope_frame_image.
이 서버가 분석 파이프라인을 직접 실행하나요?
아니요, 이 서버는 실제 프로세싱을 수행하는 실행 중인 FlowScope 백엔드의 클라이언트 역할을 합니다.
비디오 분석 비용은 얼마나 드나요?
분석에는 각 개별 화면에 대한 다운로드, 전사(transcription), 비전 호출이 포함되므로 실제 비용이 발생하며 2~10분이 소요됩니다.
서버가 올바르게 설정되었는지 어떻게 확인하나요?
flowscope_health_check 도구를 사용하여 백엔드가 작동 중인지, ffmpeg 또는 LLM 키와 같은 필수 구성 요소가 있는지 확인할 수 있습니다.