Clipy

@clipy/mcp

AI エージェントが Clipy の画面録画を利用できるようにします。

Clipy モノレポで開発されています。ソースの閲覧や問題の報告に利用できる公開ミラーは github.com/manovagyanik1/clipy-mcp （MIT）にあり、npm の各リリースに合わせて同期されています。

これは Model Context Protocol（MCP）サーバーです。Claude、Cursor、Windsurf などの MCP 対応エージェントが録画を検索し、文字起こしと AI 要約を読めるようになります。そのため、エージェントを離れずに 「このバグ報告の録画を Linear チケットにする」 といったことができます。また、record ツールを使えば、Web アプリをヘッドレスで録画して、Clipy の録画として取得できます（「機能を実装してから、その結果を録画する」）。

サーフェスを横断する正式な運用契約は clipy.online/agents.md です。接続中の MCP の正確なバージョンとスキーマを確認するには、標準の tools/list リクエストを使用してください。

読み取りツールには recordings:read スコープが必要です。すべてのキーには、このスコープがデフォルトで付与されています。書き込みツール（record、セッションツール（start_recording、add_marker、add_chapter、stop_recording、abort_recording）、および replace_transcript）には、さらにキーに ingest スコープ（「録画してアップロード」）が必要です。この要件はサーバーによって強制されます。get_edit_transcript と edit_recording には recordings:write スコープが必要です。recordings:read のみのキーでは録画を読めますが、作成、変更、削除はできません。

セットアップ

Clipy CLI で一度ログインします。

npx @clipy/cli@latest login

ブラウザーが開いたら、Approve を一度クリックしてください。キーは ~/.config/clipy/config.json に保存され、このサーバーはそのファイルを読み込みます。そのため、キーをどこかにコピーする必要はなく、シェルの履歴や MCP 設定に秘密情報が残ることもありません。

次に、MCP クライアントにサーバーを追加します。

Claude Code

--scope user フラグを使うと、Clipy がすべてのプロジェクトに対してグローバルにインストールされます。このフラグを付けない場合、claude mcp add はデフォルトで local スコープ（現在のフォルダーのみ）になります。

claude mcp add --scope user clipy -- npx -y @clipy/mcp

Codex

この操作により、サーバーがグローバルな ~/.codex/config.toml に書き込まれ、すべての Codex セッションで利用できるようになります。

codex mcp add clipy -- npx -y @clipy/mcp

または、~/.codex/config.toml に手動で追加します。

[mcp_servers.clipy]
command = "npx"
args = ["-y", "@clipy/mcp"]

Claude Desktop / Cursor / Windsurf

該当するユーザーレベルの設定ファイル（claude_desktop_config.json、~/.cursor/mcp.json、または Windsurf MCP 設定）を直接編集します。

{
  "mcpServers": {
    "clipy": {
      "command": "npx",
      "args": ["-y", "@clipy/mcp"]
    }
  }
}

このマシンで clipy login を使用していない場合に限り、"env": { "CLIPY_API_KEY": "clipy_sk_live_xxx" } ブロックを追加してください。

キーを明示的に設定する

キーを読み込むための clipy login がない場合（CI、コンテナーなど）や、ログイン済みのキーとは別のキーを意図的に使う場合は、CLIPY_API_KEY を使用してください。環境変数で明示的に指定した値は、常に設定ファイルの値より優先されます。キーは https://clipy.online/settings/api-keys で作成してください（キーは一度だけ表示されます）。

サーバーの起動コマンドにキーを直接記述しないでください。例： "command": "sh", "args": ["-c", "CLIPY_API_KEY=… npx -y @clipy/mcp"]。コマンドライン引数はプロセステーブル（ps、/proc）を通じてすべてのローカルプロセスから見えるため、そこにキーを置くと、実質的にマシン上で誰でも読み取れる状態になります。代わりに env ブロックに設定してください。claude mcp add --env …／codex mcp add --env … を使うと、その env ブロックが書き込まれます。これらのコマンドでキーが公開されるのは、セットアップ用コマンド 1 回分の argv のみで、長時間実行されるサーバーの argv には公開されません。

ホステッドコネクター

インストールせずに接続することもできます。Clipy はこのサーバーを https://clipy.online/api/mcp（Streamable HTTP）で実行しています。

• Claude や ChatGPT などのコネクター UI では、OAuth でサインインします。検出は https://clipy.online/.well-known/oauth-protected-resource から開始されます。
• その他のクライアントは Authorization: Bearer <Clipy API key> を送信します。
• recordings:read スコープのみを持つキーでは、読み取りツールのみが表示されます。

MCP ディレクトリとレビュアー向け

Clipy では、バグの解説、UI へのフィードバック、製品デモの3つのサンプル録画を含むデモアカウントを用意しています。ディレクトリ運営者は、[email protected] にメールを送ることで、読み取り専用のテストキーを取得できます。

ツール

ツール	機能
search_memory	Clipy のメモリー全体を一度に検索します — ユーザーが作成したすべての画面録画と、インポートしたすべての動画を対象に、タイムスタンプと該当箇所から開く URL 付きで一致した場面を返します。意味的な一致と文字どおりの一致の両方に対応しているため、「ログインフロー」で「認証画面」と発言した場面も見つかります。ユーザーが見せたもの、録画したもの、視聴したものについて言及したら、まずこのツールを使ってください。以下のライブラリ別ツールは、それぞれ全体の半分しか対象にしません。各検索結果には、次にどのツールで読み取るかを示す kind（recording または context）、タイムスタンプが正確な時点か約 50 秒の範囲かを示す resolution、空の結果を「録画されていない」と判断する前に確認すべき semantic.status が含まれます。
search_recordings	キーワード（タイトルと説明）で録画を検索します。
list_recordings	最近の録画を一覧表示します。
get_recording	1 件の録画のメタデータ（ステータス、長さ、文字起こし／要約のステータス）を取得します。
get_transcript	タイムスタンプ付きの完全な文字起こしとプレーンテキストを取得します。
get_summary	AI による要約（要約、重要なポイント、アクションアイテム）を取得します。
get_edit_transcript	録画の編集可能な文字起こしを取得します（カットした単語のテキストを含むため、recordings:write スコープが必要です）。各単語とそのインデックス、元のタイムライン上での開始／終了時刻（ms）、フィラー語（um、uh、er、hmm）を示す filler フラグ、現在のバージョンですでにカットされている単語の removed、および edit_recording に渡す revision が含まれます。fromWord／limit でページ分割します。
edit_recording	文字起こしを使って動画を編集します（recordings:write スコープが必要です）。単語の範囲または ms の範囲をカットしたり、フィラー語をすべて削除したり、カットを元に戻したり、クリック時の自動ズーム（autoZoom、Mac および Windows の録画）を有効にしたりできます。Clipy は元の動画を保持するため、所有者が元の動画を削除するまではカットを元に戻せます。共有リンクは変わらず、レンダリング完了後に新しいバージョンへ切り替わります。dryRun と expectedRevision に対応しています。
get_browser_diagnostics	プライバシーに配慮して機密情報を除去した訪問済みルート、コンソールの警告／エラー、ページ例外、失敗した fetch／XHR のメタデータを取得します。証拠にはページから報告された情報であることが明示されます。ヘッダー、本文、Cookie、トークン、入力値、生のクエリ値は記録されません。
get_interactions	準備済みルート、ポインターのサンプル、意味的なクリック、導出されたドラッグ、スクロールのまとまり、ポインターの滞留、概略的なタイピング（値や正確なキー数は記録しません）、ハイライトを、件数を制限したページで取得します。fromMs／toMs／types で絞り込み、limit（1～250、既定値 100）を設定し、フィルターを変えずに pagination.nextCursor を使って続きを取得します。ソースのカバレッジと準備状態も報告します。滞留は注意を向けていた証拠ではなく、座標は変換後の再生フレームではなくキャプチャ時のビューポートに対応します。
wait_for_artifacts	録画の文字起こし／要約の処理が完了するまでポーリングします。
download_recording	動画をクリップしたり、ffmpeg などで自分でフレームを抽出したりできるよう、MP4 をローカルにダウンロードします。
get_key_moments	重要な場面のタイムスタンプ、キャプション、クリック座標を取得します。
get_agent_context	エージェントコンテキスト一式（要約＋インタラクションのタイムライン＋重要な場面＋文字起こし＋利用可能なブラウザ診断情報）を Markdown として取得します。
record	Web アプリをヘッドレスで録画して Clipy の録画としてアップロードし、共有 URL とエージェントコンテキストの URL を返します。type（録画の種類）、viewports（複数の画面サイズを 1 本の動画にまとめて撮影）、storageState／userDataDir+profileDirectory／initScript（ログイン状態での録画）、およびタイムスタンプ付きの notes（無音の録画の文字起こしになります）を指定できます。このサーバーの環境に Playwright と、ingest スコープのキーが必要です（下記を参照）。
start_recording	作業中も録画を続ける録画セッションを開始します（独自のブラウザツールでページを操作する、コマンドを実行するなど）。type、storageState／userDataDir+profileDirectory／initScript、および exposeCdp（CDP エンドポイントと、録画中のページを操作するインページの window.__clipyMark／window.__clipyChapter ブリッジを取得）を指定できます。maxSeconds（既定値 600）で自動停止してアップロードするため、録画が止まらなくなることはありません。
add_marker	アクティブなセッションにナレーションマーカーを追加します（ライブ時計を使うか、atSeconds で過去の時刻を指定）。マーカーは録画の文字起こしチャプターになります。証拠は次のいずれかの由来を指定できます。Clipy がページ自体を確認する clipy-verified（assertSelector／assertText／assertUrl）、または独自のツールが確認した内容を報告する driver-attested（observed + verdict）です。Clipy が検証した結果には判定グリフが表示されます（✓ 成功、✗ 失敗。failMode で中断可能、⚠ 未検証 — 成功が黙って示されることはありません）。driver-attested の結果には、より控えめな見た目の留保グリフ（≈）が表示されるため、一目で混同することはありません。また、両者は別々のセグメントに集計されます。ナビゲーションとコンソールエラーは [auto] マークとして自動的に追加されます。
add_chapter	アクティブなセッションに === CHAPTER: <label> === の境界を追加し、録画を名前付きのセクションに分割します（前後のデモに最適です）。
stop_recording	セッションを終了し、ブラウザーを閉じてアップロードした後、共有 URL とエージェントコンテキストの URL を返します。
abort_recording	アクティブなセッションを破棄します。アップロードは行われません。
list_context_documents	ユーザーが clipy context import でインポートした YouTube 動画とローカル動画ファイルであるコンテキストドキュメントを一覧表示します。エージェントが読み取るためのもので、ユーザー自身の画面録画とは別のライブラリです。
get_context_document	1 件のコンテキストドキュメントのメタデータ（ソース、長さ、タグ、サーバーによる分類（動画の種類、視覚的な証拠が必要かどうか、予定されている場面）、利用可能な文字起こし／フレーム）を取得します。文字起こしそのものは取得しません。
read_context_document	コンテキストドキュメントを、コンパイル済みの Markdown として読み取ります。ヘッダー、メタデータに続いて、タイムスタンプ付きの文字起こしとフレームのキャプションが交互に表示されます。startMs／endMs を指定すると、2 時間の動画をコンテキストに一度に大量に読み込まず、セクションごとに確認できます。
update_recording	録画の名前を変更するか、説明を編集します（recordings:write が必要です）。
organize_recording	録画をフォルダーに入れ、タグを追加または削除します（recordings:write が必要です）。
set_recording_privacy	共有リンクを公開、制限付き、非公開の間で切り替えます。招待やメール送信は行いません（recordings:write が必要です）。
list_folders / create_folder	ID 付きのフォルダーを一覧表示／作成します。作成は名前を基準に冪等です。
list_comments	コメントスレッド（タイムスタンプ付きのコメント、返信、解決済みの状態）を取得します。作成者名のみを返します（comments:read が必要です）。
add_comment	キーの所有者として、特定の時点にコメントを追加するか、返信します。スレッド内の全員に通知されます（comments:write が必要です）。
get_analytics	視聴回数、ユニーク視聴者数、完了率、視聴者を取得します（analytics:read が必要です）。無料アカウントでは合計値のみ取得できます。
upload_video	このマシンから WebM、MP4、QuickTime .mov をアップロードし、共有 URL とエージェントコンテキストの URL を取得します（ingest が必要です）。
delete_recording	録画を完全に削除します。confirm には ID を再度指定する必要があります（clipy login --allow-delete で許可した recordings:delete が必要です）。
replace_transcript	録画の文字起こしを自分で作成したテキストで置き換えます（ingest スコープが必要です）。最初に get_transcript を呼び出し、その revision を渡してください。古いリビジョンによる置き換えは、同時編集を上書きせずに拒否されます。要約は自動的に再生成されます。エージェントが編集したものとして記録され、音声認識による文字起こしと偽ることはありません。
読み取りツールでは、録画の公開 ID（共有 URL 内のスラッグ）または完全な
https://clipy.online/video/<id> URL を指定します。

実際の画面の録画は CLI 専用です。 これらのツールでは、ヘッドレス Chromium ページを録画します。 実際の画面または単一のアプリウィンドウ（macOS では Mac アプリ、Linux では X ディスプレイ、実際にログインしているブラウザー）を録画するには、Clipy CLI を使用します：clipy record --source screen --window "<app>"。

record の使用

record はヘッドレス Chromium で URL を開き（CI／クラウドサンドボックスで動作し、ディスプレイは不要です）、数秒間録画して Clipy にストリーミングします。その後、ID を返すので、wait_for_artifacts と get_agent_context を呼び出して録画を読み戻せます。必要なものは次のとおりです。

1. この MCP サーバーを実行する環境の Playwright：

   npm install -g playwright && npx playwright install chromium
   

2. 「Record & upload」（取り込み）権限を持つ API キー。キーの発行時に clipy.online/settings/api-keys で選択します。

パラメーター：url（必須、http/https）、durationSeconds（デフォルトは 15、最大 300。ビューポートごとのパスに適用）、name、description、type（録画の種類 — bug_report、feature_request、product_demo、walkthrough_tutorial、feedback_review、discussion_talk、other とその別名）、viewports（例：mobile,desktop または 390x844,1440x900 — 1 つの動画に順番に録画され、最大のサイズに合わせてフレームが設定されます。各パスではゆっくりスクロールし、自動でチャプターが作成されます）、storageState ／ initScript（パス。ログに記録されません）、notes、width／height（デフォルトは 1280×720。viewports が設定されている場合は無視されます）。

ログインが必要なページの録画。 storageState は JSON に含まれる内容（Cookie と localStorage）のみを設定しますが、ブラウザーの完全な ID（IndexedDB、サービスワーカー、一部のクロスオリジン認証）は再現できません。完全な ID を使うには、Chrome の ユーザーデータルート（macOS の場合：~/Library/Application Support/Google/Chrome）を userDataDir に渡し、次のいずれかのモードを使用します。

• 名前付きプロファイルをコピーする（推奨）。 profileDirectory（"Profile 1"、"Default"、… — chrome://version → プロファイル パス に表示される正確なフォルダー名）を追加します。Clipy はそのプロファイルを一時ルートにコピーして、コピーを録画します。そのため、実際のプロファイルが開かれたり変更されたりすることはなく、アップロード後にコピーは削除されます。ツールの結果にはコピーの詳細（プロファイル名、バイト数、Chrome の実行中にコピーされた場合の警告）が記載されます。

  ⚠️ macOS：Cookie によるログインはコピー後に維持されない場合があります。 Chrome は Cookie を Chrome Safe Storage キーチェーンキーで暗号化しますが、録画に使用する同梱の Chromium は Chromium Safe Storage を探します。そのため macOS では、コピーしたプロファイルを使うと、セッションが Cookie に基づくサイトで見た目は自分の ID と同じでも、ログアウトした状態になる場合があります。localStorage／Preferences に基づくセッションは引き続き動作します。これは以前からある Playwright と Chrome の制約であり、コピーによって発生するものではありません。コピーの詳細にもこの注意が記載されます。録画時にログアウト状態になる場合は、これが原因です。 CLI の clipy record --source screen で実際のブラウザーを録画するか、独自のブラウザーを操作して add_marker の observed／verdict から証拠を添付してください。

• Default プロファイルを直接開く。 profileDirectory を省略します。Clipy はルートの Default プロファイルを開き、そこに書き込みます。そのため、Chrome が実行中でロックされている間は拒否されます。先に Chrome を終了してください。ディレクトリが実際の Chrome ルートと判断された場合、結果にはその旨を示す userDataDirWarning が含まれ、profileDirectory（一時コピー）または CLI の --source screen を案内します。特にその場での使用が必要な場合を除き、これらの方法を推奨します。

Playwright は Chromium の --profile-directory を削除するため（指定されたディレクトリから常に Default を読み込みます）、名前付きプロファイルを録画するにはコピーが唯一の方法です。userDataDir にプロファイルのサブディレクトリ（.../Chrome/Default）を指定することは拒否されます。そこから起動すると、ログアウト状態の空のプロファイルが録画されてしまうためです。

storageState と userDataDir は同時に指定できません。profileDirectory を指定するには userDataDir が必要です。

作業前にカメラを確認する

record と start_recording はどちらも、実際に録画されている内容を示す source オブジェクトを返します。録画開始時に最新の状態が解決され、リダイレクト後の url、ページの title、録画時の viewport が含まれます。

"source": {
  "kind": "headless_browser",
  "title": "Orders — Admin",
  "url": "https://app.example.com/orders",
  "viewport": { "width": 1280, "height": 720 }
}

何分も作業する前に、ドライバーが操作している画面と照合してください。これは、ドライバーが認証した証拠はドライバーが見たものを証明するだけで、カメラが見たものとは何も結び付いていないためです。間違った対象の映像に対して、正確なマークを付けてしまうことも十分にあり得ます。Clipy がウィンドウやタブにフォーカスを当てたり、前面に表示したりすることはありません。ドライバーとカメラを同じ画面に向けるのは、呼び出し側の役割です。

ここでの kind は常に headless_browser です。これらのツールは、Clipy が所有するヘッドレスページを録画します。実際のアプリケーションウィンドウやディスプレイのキャプチャは CLI 専用です（clipy record --source screen --window "<app>"）。そのため、ウィンドウ ID やウィンドウタイトルは報告されません。空の値や捏造した値を返すことは、このフィールドが防ごうとしている誤った確信そのものです。

マーカーの証拠：2 種類の出所

add_marker に付けられる証拠の出所は、次の 2 種類のうちいずれか 1 つです。それぞれ別々に集計・表示され、決して合算されません。

出所	方法	意味
clipy-verified	assertSelector / assertText / assertUrl	Clipy が録画ページ自体を確認しました。最も強い証拠です。[assert ✓ verified-by-clipy; …]、[ASSERT ✗ verified-by-clipy; …]、または確認できなかった場合は [ASSERT ⚠ clipy could not evaluate — …] と表示されます。
driver-attested	observed + verdict（両方必須）	あなたが、自分のツールで確認した内容を報告します。Clipy が保証するのは、あなたがそう述べたことだけであり、検証したことではありません。報告内容は録画フレームと照合して反証できます。判定記号ではなく、留保を示す記号付きで表示されます。[≈ ASSERT driver-attested; observed=…] または [≈ FAILED driver-attested; observed=…] と表示されます。

エージェントが独自のブラウザー／ツールを操作しながら Clipy が録画する場合（例：CLI の --source screen）、または検証対象となる Clipy 所有のページがない場合は、driver-attested を使用してください。clipy-verified より弱いものの、単なる文章よりはるかに強力です。トランスクリプトの先頭にある [verification] の注記で 2 種類を区切ります。例：[verification] 3 clipy-verified: 2 passed, 1 failed · 2 driver-attested: 2 passed, 0 failed。

CDP 経由で録画ページを操作する（start_recording + exposeCdp: true）

start_recording に exposeCdp: true を渡すと、録画用ブラウザーが Chrome DevTools Protocol エンドポイントを開き、結果として cdpHttpUrl と cdpUrl を返します。独自の Playwright を接続して、Clipy が録画している間にページを操作できます。

const { chromium } = require("playwright");
const browser = await chromium.connectOverCDP(cdpHttpUrl);
const page = browser.contexts()[0].pages()[0]; // the page being recorded
await page.goto("http://localhost:3000/settings");
await browser.close();                          // detaches; the recording keeps going

デフォルトでは無効です。有効にしている間は、ローカルのあらゆるプロセスがそのブラウザーに接続できます。CLIPY_DISABLE_CDP=1 は、強制的に無効にする緊急停止スイッチです。注意点：録画ページは contexts()[0].pages()[0] です（新しく開いたコンテキストはキャプチャされません）。CDP 接続では page.viewportSize() は null を返します。また、ビューポートを変更するには setViewportSize ではなく、newCDPSession と Emulation.setDeviceMetricsOverride を使用してください。

ページ内ブリッジ（追加のツール呼び出し不要）。 exposeCdp が有効な場合、録画ページでは window.__clipyMark(text, opts?) と window.__clipyChapter(label) も公開されます。これにより、CDP ドライバーはページ内から検証済みのマークやチャプターを追加できます。

await page.evaluate(() =>
  window.__clipyMark("saved the form", { assertSelector: ".toast", assertText: "Saved" }),
);
await page.evaluate(() => window.__clipyChapter("AFTER — fix applied"));

opts は add_marker（assertSelector / assertText / assertUrl / failMode）に対応します。assertText には assertSelector が必要です（そうでなければ呼び出しは拒否されます）。failMode: "abort" で検証に失敗するとセッションは破棄されます。ツールと同じ注釈と集計結果になります。

設定

環境変数	必須	デフォルト	備考
CLIPY_API_KEY	いいえ	~/.config/clipy/config.json の apiKey	/settings/api-keys で取得する個人用キーです。このマシンで clipy login を実行していない場合にのみ設定してください。設定すると、構成ファイルの値より優先されます。
CLIPY_API_URL	いいえ	https://clipy.online	セルフホスト／ステージング環境用の上書き設定です。

プライバシー

キーが読み取るのは、ご自身の録音だけです。キーはいつでも /settings/api-keys で取り消せます。サーバーはお使いのマシン上でローカルに実行され、キーが Clipy API 以外の場所に送信されることはありません。Clipy API への通信は HTTPS で行われます。