FlowScope UX Flow Analyser

flowscope-mcp

一个 MCP 服务，可将 FlowScope 的 UX 分析工作流提供给任何大模型客户端。支持 MCP 协议 2026-07-28，并附带两个符合规范、可移植的 Agent Skills。

uvx flowscope-mcp        # stdio server; needs a local FlowScope backend

FlowScope 接收 YouTube 产品演示视频 URL，下载视频、转录内容、提取并去重每个不同画面的截图，使用视觉模型描述每个画面，并综合生成逐步的 UX 流程。此软件包将该工作流转化为 Agent 可调用的工具。

可以向 Agent 提出类似这样的请求：

比较这两段视频中的引导流程：<url> 和 <url>

拆解这个演示中的结账 UX：<url>

要求

此服务是运行中的 FlowScope 后端的客户端；它本身不会运行工作流。请先启动后端：

cd backend
uvicorn app.main:app --port 8000

后端需要 ffmpeg、包含 backend/requirements.txt 的 Python 环境，以及 backend/.env 中的一个 LLM 提供商密钥。服务的 flowscope_health_check 工具会准确报告缺少的项目，因此你可以让 Agent 检查，而不必猜测。

安装

作为 Claude Code 插件

一步即可完成，同时安装技能、提示词并注册服务：

/plugin marketplace add DavidNgugi/flowscope
/plugin install flowscope@flowscope

从 PyPI 安装

无需永久安装任何内容——uvx 会在临时环境中运行它。唯一的前置条件是 uv（brew install uv）：

uvx flowscope-mcp                 # starts a stdio server
uvx flowscope-mcp --version       # confirm the published version
uvx [email protected]           # pin, when reproducibility matters

从 git URL 或本地检出版本安装

uvx --from /absolute/path/to/flowscope/mcp flowscope-mcp
uvx --from "git+https://github.com/DavidNgugi/flowscope.git@main#subdirectory=mcp" flowscope-mcp

环境变量

这些变量会在每次调用时从进程环境中读取。MCP Python SDK v2 刻意停止读取 MCP_* 变量和 .env 文件，因此请在客户端的服务配置中设置它们。

指向它的 Harness

配置格式确实各不相同——VS Code 自己的文件使用 servers，而其他所有客户端都使用 mcpServers；Codex 使用 TOML，Claude Desktop 不会展开 ${VAR} 占位符——因此生成文件比复制代码片段更可靠：

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

它会合并到现有配置文件中，并保留其他服务不变。

VS Code 还会读取便携式 <project>/.mcp.json 格式（键为 mcpServers）。如果你想让 Claude Code 和 Cursor 共用一份配置，可以使用 flowscope-mcp-install vscode-portable 写入该文件。

flowscope-mcp --transport streamable-http --host 127.0.0.1 --port 8765

claude mcp add --transport http flowscope http://127.0.0.1:8765/mcp

docs/install.md 提供了完整的各 Harness 参考说明、每种 Harness 接受的占位符语法，以及最常导致安装出错的两个陷阱。

使用方法

重启客户端，打开新的聊天，并先检查安装情况：

检查 FlowScope 是否已准备就绪。

这会运行 flowscope_health_check 并指出缺少的内容——通常是 ffmpeg，或 后端主机上的大模型服务商密钥。然后提出你的需求即可。

提示词示例

完整分析一个视频

彻底分析这个演示中的引导体验：<youtube-url>

根据这个演示，这款产品实际上是做什么的？请逐屏带我了解整个流程：<youtube-url>

分析 <youtube-url>，并告诉我新用户第一次使用时会在哪些地方卡住。

针对流程的具体问题

这个演示中的注册需要几步？每一步会询问什么？<youtube-url>

这个演示中有错误状态或空状态吗？<youtube-url>

首屏首屏可见区域展示了什么？主要行动号召是什么？<youtube-url>

对比多个视频

对比这两个演示中的引导流程。它们有哪些不同？各自做出了什么取舍？

• <youtube-url-1>
• <youtube-url-2>

我正在设计结账流程。这两个演示的做法有什么不同？我可以借鉴什么？<url1> <url2>

根据这些演示，哪一个能让新用户最快体验到产品的核心价值？<url1> <url2> <url3>

利用已有内容

FlowScope 已经分析过哪些视频？

给我看看那份报告中的定价页面截图。

你不需要斟酌措辞。分析结果会按 YouTube 视频 ID 缓存，因此模糊的提示词只会触发一次查询，而不会重新分析——Agent 会先检查缓存，再开始消耗资源。

按下回车后会发生什么

分析视频时，系统会下载视频、转录内容、提取并去重截图，然后对每个不同的屏幕调用一次视觉模型，再进行一次综合调用。一个五分钟的演示通常会产生 15–40 个屏幕。每个视频预计需要2–10 分钟，并会产生实际费用。

flowscope_analyze_video 默认会等待，通常会直接返回完整报告，因此通常只需一个提示词。如果视频所需时间超过预算，它会返回 status: "running" 和一个 video_id，此时 Agent 应轮询 flowscope_job_status。如果它改为重新提交 URL，请立即停止它——这会启动重复任务。

答案应有依据

报告分为三层：ux_insights（综合分析）、flow_steps（按顺序排列的用户路径）和 frames（证据——每个屏幕对应一条记录，包含其用途、UI 元素和对齐的旁白）。好的答案应先给出洞察，并为每项主张引用其依据屏幕。随附的技能会强制遵循这一点，包括明确说明“演示中未展示这一点”，而不是自行推断。

docs/usage.md 提供完整的操作指南、可产出更好答案的提示词模式，以及故障排查表。

工具

共有十种工具，分为只读检查和需要付费的操作。

此外，还有两个提示词（flowscope_ux_teardown、flowscope_compare_flows）和两个资源（flowscope://videos、flowscope://videos/{video_id}/report）。

费用与耗时

分析视频时，会先下载并转录视频，然后为每个不同屏幕调用一次视觉模型，再进行一次综合分析。每个视频都需要耗费数分钟和实际费用。以下两项措施可避免浪费：

• 结果会按 YouTube 视频 ID 缓存。flowscope_list_videos 可显示已有分析结果，重新提交已完成的视频既免费又即时。
• flowscope_analyze_video 会在开始工作前检查缓存，只提交真正的新内容。

随附的技能会教 Agent 先检查缓存。

传输方式

flowscope-mcp                                  # stdio (default)
flowscope-mcp --transport streamable-http --port 8765

Streamable HTTP 通过 POST /mcp 提供服务。SDK 在同一个端点上支持 2026-07-28 协议修订版和更早的握手时代协议，因此旧版客户端无需额外配置即可使用。旧版客户端会创建服务端会话，会话存储在进程内——如果在负载均衡器后运行多个工作进程，请启用粘性路由。

技能

服务器随附两项 Agent 技能，它们遵循开放规范编写，可安装到任何兼容的客户端中：

这些技能包含工具描述无法涵盖的实操知识：付费前检查运行状况和缓存；阅读综合分析，而不是根据原始转录重新推导；明确说明“演示中未展示这一点”，而不是自行推断；并对自动字幕中的产品名称保持谨慎。

技能与服务器相互独立——已有报告也能使用这些技能，而服务器无需它们也能运行。

安装

使用插件（Claude Code）—— 一步安装技能和服务：

/plugin marketplace add DavidNgugi/flowscope
/plugin install flowscope@flowscope

通用目录，大多数客户端都会扫描该目录。.agents/skills/ 是跨客户端的项目约定，因此多个工具框架可以从同一份副本中读取：

mkdir -p .agents/skills && cp -r skills/* .agents/skills/    # this project
mkdir -p ~/.agents/skills && cp -r skills/* ~/.agents/skills/ # every project

客户端专属目录，如果你只想在该客户端中使用：

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

使用 skills CLI，适用于团队或约 80 种 Agent 目标：

npx skills add DavidNgugi/flowscope

使用官方验证器确认技能具有可移植性：

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

两个技能仅声明了开放规范定义的六个字段，因此无需修改即可在 Claude Code、Claude Desktop、ChatGPT、Codex、Cursor、VS Code、Gemini CLI、Zed、Goose、OpenCode 及其他客户端中使用。测试会对此进行验证。

docs/skills.md 介绍了所有安装方式、各客户端读取的兼容别名，以及如何在完全不使用 MCP 服务的情况下使用这些技能。

文档

发布

发布由版本标签驱动，且全程自动化。.github/workflows/release.yml 会验证所有内容、使用可信发布功能发布到 PyPI、发布到 MCP Registry，并创建附带 wheel 和 sdist 的 GitHub 发布版本。

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

也可以按需发布——Actions → Release MCP server——其 publish 输入项默认为关闭，因此默认的手动运行只会验证并构建，不会发布任何内容。

五个文件中的六处版本声明必须保持一致，且 MCP Registry 要求服务版本与其软件包版本相同。scripts/version.py 用于保持它们同步，因为手动编辑很容易导致发布在进行中失败；而 PyPI 永远不允许重复使用版本号，因此未完成的发布无法重试：

python scripts/version.py show         # what every file currently says
python scripts/version.py check        # fail if any disagree, including the tag

完整的发布流程、版本编号规则、一次性 PyPI 配置，以及发布出错时的处理方法，请参阅 docs/publishing.md。

开发

cd mcp
python3 -m venv .venv && ./.venv/bin/pip install -e ".[dev]"
./.venv/bin/ruff check src tests scripts
./.venv/bin/pytest -q

测试套件无需联网：工具行为通过内存 MCP 客户端和模拟的 HTTP 传输进行测试，因此既不需要网络，也不需要正在运行的后端。另有单独的测试会启动真实进程，以验证 stdio 契约——stdout 仅承载协议帧——并检查注册表、插件和版本元数据。测试还会固定发布工作流的触发条件，防止将来的修改导致分支推送时自动发布。

使用官方工具验证技能和清单：

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

许可证

MIT