FlowScope UX Flow Analyser

flowscope-mcp

FlowScope の UX 分析パイプラインをあらゆる LLM クライアントに提供する MCP サーバーです。MCP プロトコル 2026-07-28 に対応し、仕様に準拠した 2 つのエージェントスキルが付属します。

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

FlowScope は YouTube の製品デモ URL を受け取り、動画をダウンロードして文字起こしし、画面ごとのスクリーンショットを抽出して重複を取り除き、各画面をビジョンモデルで説明し、手順ごとの UX フローを生成します。このパッケージにより、エージェントが呼び出せるツールとしてこのパイプラインを利用できます。

エージェントには、次のように尋ねてみてください。

次の 2 つの動画のオンボーディングフローを比較してください：<url> と <url>

このデモのチェックアウト UX を詳しく分析してください：<url>

要件

このサーバーは、実行中の FlowScope バックエンドのクライアントであり、パイプライン自体は実行しません。まずバックエンドを起動してください。

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

バックエンドには ffmpeg、backend/requirements.txt を使った Python 環境、および backend/.env に設定した LLM プロバイダーのキーが必要です。サーバーの flowscope_health_check ツールを使うと、どれが不足しているかを正確に確認できます。推測する代わりに、エージェントに確認を依頼できます。

インストール

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 ファイルの読み込みを停止したため、クライアントのサーバー設定で指定してください。

ハーネスを接続する

設定ファイルの形式は実際に異なります。VS Code 独自のファイルでは、他のすべてのクライアントが mcpServers を使うのに対し、servers を使います。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 には、ハーネスごとの詳しいリファレンス、 それぞれが受け付けるプレースホルダー構文、インストールで最もよく起きる 2つの問題を記載しています。

使い方

クライアントを再起動し、新しいチャットを開いて、まずインストール状態を確認します。

FlowScope が使える状態か確認してください。

この操作で flowscope_health_check が実行され、不足しているものが示されます。通常は、 ffmpeg または バックエンドホスト上の LLM プロバイダーキーです。その後、必要なことを 尋ねてください。

プロンプトの例

動画1本を詳しく分析する

このデモのオンボーディング UX を徹底的に分析してください：<youtube-url>

このデモに基づいて、この製品が実際に何をするのか教えてください。画面ごとにフローを説明してください：<youtube-url>

<youtube-url> を分析して、初めて使うユーザーがつまずきそうな箇所を教えてください。

フローに関する具体的な質問

このデモでは、登録に何ステップかかりますか？各ステップでは何を求められますか？<youtube-url>

このデモにエラー状態や空の状態はありますか？<youtube-url>

最初の画面でファーストビューに表示される内容と、主要な行動喚起を教えてください。<youtube-url>

複数の動画を比較する

この2つのデモのオンボーディングフローを比較してください。どこが異なり、それぞれどのようなトレードオフがありますか？

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

チェックアウトフローを設計しています。この2つのデモの違いと、取り入れるべき点を教えてください。<url1> <url2>

デモを見て、新規ユーザーが最も早く最初の価値を得られるのはどれですか？<url1> <url2> <url3>

既存の分析結果を使う

FlowScope がすでに分析した動画を教えてください。

そのレポートの料金画面のスクリーンショットを見せてください。

質問の言い回しを工夫する必要はありません。分析結果は YouTube 動画 ID を使って キャッシュされるため、曖昧なプロンプトでも再分析ではなく検索が行われます。 エージェントは処理を始める前にキャッシュを確認します。

送信後の処理

動画の分析では、動画をダウンロードして文字起こしを行い、スクリーンショットを抽出して 重複を除去した後、画面ごとに1回のビジョン呼び出しと、1回の統合呼び出しを行います。 5分のデモから通常15～40画面が抽出されます。2～10分かかり、動画ごとに料金が発生します。

flowscope_analyze_video はデフォルトで完了まで待機し、通常は完成したレポートを 直接返すため、ほとんどの場合プロンプト1つで十分です。動画の処理が予算時間を超えると、 video_id とともに status: "running" が返され、エージェントは flowscope_job_status をポーリングする必要があります。URL を再送信する場合は、 そこで止めてください。重複した処理が始まってしまいます。

回答は根拠に基づくもの、またはそうあるべきです

レポートは3つの層で構成されています。ux_insights（統合された分析）、flow_steps（順序に沿ったユーザーの操作経路）、frames（根拠 — 画面ごとに1つのエントリーがあり、その目的、UI 要素、対応するナレーションを記載）です。優れた回答はインサイトを先に示し、それぞれの主張の根拠となる画面を明示します。同梱のスキルは、「推測するのではなく、デモでは確認できない」と述べることも含め、この方法を徹底します。

docs/usage.md には、手順を網羅したガイド、より良い回答を生み出すプロンプトのパターン、トラブルシューティングの表が記載されています。

ツール

ツールは10個あり、読み取り専用の確認と費用が発生する操作に分かれています。

さらに、2つのプロンプト（flowscope_ux_teardown、flowscope_compare_flows）と2つのリソース（flowscope://videos、flowscope://videos/{video_id}/report）があります。

費用と時間

動画を分析するには、動画をダウンロードして文字起こしを行い、画面ごとに1回のビジョン呼び出しと統合処理の呼び出しを実行します。動画1本あたり数分かかり、実際に費用も発生します。無駄を防ぐ仕組みが2つあります。

• 結果は YouTube 動画 ID ごとにキャッシュされます。flowscope_list_videos で既存の分析を確認でき、分析済みの動画を再送信しても無料ですぐに完了します。
• flowscope_analyze_video は作業を開始する前にキャッシュを確認し、新たに分析が必要なものだけを送信します。

同梱のスキルは、まずキャッシュを確認するようエージェントに指示します。

トランスポート

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

Streamable HTTP は POST /mcp を提供します。SDK は同じエンドポイントで、2026-07-28 のプロトコルリビジョンと、より古いハンドシェイク方式の両方に対応するため、レガシークライアントも追加設定なしで動作します。レガシークライアントはサーバー側のセッションを作成し、そのセッションはプロセス内に保存されます。ロードバランサーの背後で複数のワーカーを実行する場合は、スティッキールーティングを有効にしてください。

スキル

2つのエージェントスキルがサーバーとともに提供されます。公開仕様に沿って記述されているため、互換性のあるあらゆるクライアントにインストールできます。

これらのスキルは、ツールの説明だけでは伝えきれない運用上の知識を補います。費用をかける前にヘルスチェックとキャッシュを確認すること、生の文字起こしから分析をやり直すのではなく統合結果を読むこと、推測するのではなく「デモでは確認できない」と伝えること、自動字幕に出てくる製品名を鵜呑みにしないことなどです。

スキルとサーバーは独立しています。スキルはすでに取得したレポートにも役立ち、サーバーはスキルなしで動作します。

インストール

プラグインを使用する場合（Claude Code）— スキルとサーバーを一度にインストールできます：

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

ポータブルディレクトリは、ほとんどのクライアントがスキャンします。.agents/skills/ はクライアント間で共通のプロジェクト規約であるため、複数のハーネスが1つのコピーからスキルを読み込めます：

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種類のエージェントターゲットにインストールできます：

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

どちらのスキルも、オープン仕様で定義されている6つのフィールドのみを宣言しているため、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 入力はデフォルトでオフのため、手動実行時のデフォルトでは公開せずに検証とビルドを行います。

5つのファイルにある6つのバージョン宣言はすべて一致している必要があり、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 の契約を検証し、レジストリ、プラグイン、バージョンのメタデータも検証します。リリースワークフローのトリガーもテストで固定しているため、将来の編集によってブランチへのプッシュ時に自動公開されることはありません。

公式ツールを使ってスキルとマニフェストを検証します：

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