feedthrough

Feedthrough

AI でデバッグ — アプリの内側から。

Feedthrough は軽量なデバッグブリッジを実行中のあらゆる Web ページに挿入し、DOM の状態、コンソールログ、ネットワークリクエスト、ユーザー操作など、あらゆる情報を MCP ツールとして公開します。MCP 対応の AI エージェントなら、会話形式でリアルタイムにページを調査し、操作できます。

Browser (any)
 └── @feedthrough/core          ← injected into your page
      ├── console interceptor
      ├── fetch / XHR interceptor
      └── DOM inspector
      ↕  WebSocket
@feedthrough/mcp               ← MCP server, exposes tools over stdio
 └── Tools: click, fill, inspect_element, query_dom,
            get_console_logs, get_network_requests, …
      ↕  MCP protocol
Claude Code / Cursor / any MCP client

---

名前の由来

物理学や化学の実験の多くは、内部の空気をすべて排出して実験を汚染から守る、密閉された真空チャンバーの中で行われます。問題は、チャンバー内の機器を制御して測定値を読み取る必要がある一方で、わずかな空気漏れでも実験が台無しになることです。これを解決するのがフィードスルーです。真空を完全に保ちながら、チャンバーの壁を通して電気信号を伝える、特別に設計されたコネクターです。内部に手を伸ばすことはできませんが、フィードスルーを使えば内部の状況を観察し、制御できます。

Feedthrough も同じ考え方です。実行環境を乱すことなく、実行中の Web アプリ内部から実行時のデバッグデータを取り出し、クリック、キー入力、DOM クエリなどの制御信号を送り返します。

---

Feedthrough を使う理由

ほかのブラウザー MCP ツールはどれも外部からのオブザーバーです。Puppeteer または CDP を介してブラウザーの外から制御するため、Chrome でしか動作しません。Feedthrough は組み込み型エージェントです。ページの内部で動作するため、次のものを確認できます。

• フレームワークの内部情報（React コンポーネントツリー、Redux ストア、カスタムグローバル変数）
• Chrome 以外も含む、あらゆるブラウザー
• 既存の開発ワークフロー — 別途、制御用ブラウザーを起動する必要はありません
• テスト実行中の Cypress 独自のブラウザーコンテキスト

---

パッケージ

パッケージ	説明
@feedthrough/core	ブラウザー内ブリッジ — コンソール、fetch、XHR をインターセプトし、コマンドを処理します
@feedthrough/mcp	MCP サーバー — WebSocket 経由で、あらゆる MCP クライアントをブラウザーに接続します
@feedthrough/cypress	Cypress アダプター — 各テストページの読み込み前にブリッジを自動挿入します
@feedthrough/playwright	Playwright アダプター — page.addInitScript() 経由でブリッジを挿入します
@feedthrough/vite	静的な index.html を使うアプリ向けの Vite プラグイン
@feedthrough/webpack	Webpack プラグイン — ブリッジをグローバルエントリーポイントとして追加します
@feedthrough/nextjs	Next.js アダプター — next.config.ts を withFeedthrough() でラップします
@feedthrough/nuxt	Nuxt 3 モジュール
@feedthrough/sveltekit	SvelteKit アダプター — handle フック経由で挿入します
@feedthrough/remix	Remix アダプター — Vite 開発サーバーのミドルウェア経由で挿入します

---

フレームワークのサポート

フレームワーク	アダプター	備考
Vite + React / Vue / Solid / Preact	@feedthrough/vite	静的な index.html — プラグインは transformIndexHtml を使用します
Next.js	@feedthrough/nextjs	webpack 設定をラップします。開発時のみ
Nuxt 3	@feedthrough/nuxt	Nuxt モジュールとして登録します。開発時のみ
SvelteKit	@feedthrough/sveltekit	transformPageChunk を使う handle フック。開発時のみ
Remix	@feedthrough/remix	Vite 開発サーバーのミドルウェア。開発時のみ
Webpack アプリ	@feedthrough/webpack	グローバルエントリーポイント。本番モードでは動作しないよう制御します
Cypress	@feedthrough/cypress	window:before:load フック
Playwright	@feedthrough/playwright	page.addInitScript()

---

クイックスタート

1. MCP サーバーを起動する

npx @feedthrough/mcp

サーバーはブラウザーからの接続を ws://127.0.0.1:8765 で待ち受け、stdio で MCP ツールを公開します。ポートは FEEDTHROUGH_PORT=9000 で変更できます。ポートがすでに使用されている場合、サーバーは起動を拒否せず、次に空いているポートを使用します。詳しくは複数のセッションを同時に実行するをご覧ください。

2. MCP クライアントの設定に追加する

{
  "mcpServers": {
    "feedthrough": {
      "command": "npx",
      "args": ["@feedthrough/mcp"]
    }
  }
}

3. ブリッジをページに組み込む

Vite + React / Vue / Solid / Preact：

// vite.config.ts
import { feedthrough } from "@feedthrough/vite";
export default defineConfig({ plugins: [feedthrough()] });

Next.js：

// next.config.ts
import { withFeedthrough } from "@feedthrough/nextjs";
export default withFeedthrough()({ /* your next config */ });

Nuxt 3：

// nuxt.config.ts
export default defineNuxtConfig({ modules: ["@feedthrough/nuxt"] });

SvelteKit：

// src/hooks.server.ts
import { feedthroughHandle } from "@feedthrough/sveltekit";
import { sequence } from "@sveltejs/kit/hooks";
export const handle = sequence(feedthroughHandle);

Remix：

// vite.config.ts
import { feedthrough } from "@feedthrough/remix";
export default defineConfig({ plugins: [remix(), feedthrough()] });

Webpack：

// webpack.config.mjs
import { FeedthroughPlugin } from "@feedthrough/webpack";
export default { plugins: [new FeedthroughPlugin()] };

Cypress：

// cypress/support/e2e.ts
import { setupFeedthrough } from "@feedthrough/cypress";
setupFeedthrough();

Playwright：

// import test from the adapter instead of @playwright/test
import { test, expect } from "@feedthrough/playwright";

または手動で（任意のバンドラー）：

// main.ts
if (import.meta.env.DEV) {
  import("@feedthrough/core").then(({ init }) => init());
}

4. ページを開いて、質問を始める

ブリッジが接続されると、MCP サーバーの出力に [feedthrough] tab connected と表示されます。 最も簡単に使うには、開くタブを1つにしてください。複数のタブを同時に接続することもでき、 コマンドは最後にアクティブになったタブに送られますが、タブを1つにすれば混乱を避けられます。

次に、AI エージェントに尋ねます。

> What's on the page right now?
> Click the submit button and tell me what network requests fired
> Why is the counter showing the wrong value?

---

MCP ツール

ツール	説明
get_instructions()	使い方ガイド — 推奨ワークフロー、ツールの実行順序、セレクターのヒント
query_dom(selector)	CSS セレクターに一致するすべての要素
inspect_element(selector, properties?)	タグ、属性、完全な境界矩形と inViewport、祖先 path、厳選された計算済みスタイル、オーバーフロー情報（クリップされた／はみ出したコンテンツ）、祖先によるクリップ情報、実効的な可視性（祖先を考慮した visible と hiddenReason）、遮蔽状態（hittable と occludedBy）、アクセシビリティ（a11y：ロール、名前、状態）、pseudo の ::before／::after コンテンツ、フォームの現在の状態。properties では、名前を指定して追加の CSS プロパティを読み取ります
get_html(selector)	領域の生の outerHTML（上限 50 KB）
get_console_logs(limit?, levels?, match?, since?)	コンソール出力（すべてのメソッド）と、捕捉されなかったエラーおよび Promise の拒否。levels、match、または since のタイムスタンプでフィルタリングします
get_network_requests(filter?, since?)	捕捉された fetch と XHR — URL、メソッド、ステータス、所要時間、ヘッダー、リクエスト／レスポンス本文（上限 10 KB）。filter または since で絞り込みます
get_page_info()	URL、タイトル、readyState、ビューポートサイズ、スクロール位置、ユーザーエージェント、このページが接続しているブリッジ
connection_status()	接続中のタブとアクティブなタブ、このサーバーの名前、バージョン、バインドされたポート
click(selector)	ネイティブの click() で要素をクリックします（click とデフォルトのアクティベーションを発生させます。ポインター操作の一連のイベントは発生させません）
fill(selector, value)	input／textarea／select の値を設定します（input と change を発生させます。キー入力イベントは発生させません）
hover(selector)	mouseover／mouseenter を発生させてホバー UI をマウントします（JS ハンドラー用であり、CSS の :hover 用ではありません）
press_key(selector, key)	キー入力をディスパッチします — Enter、Escape、Tab、矢印キー、または文字
set_style(selector, properties)	見た目の修正をプレビューします — インライン CSS をリアルタイムで設定します（ソースには保存されません）
set_attribute(selector, name, value)	属性の変更をプレビューします — disabled の切り替え、class の差し替え、aria-* の設定（null を指定すると削除）
set_text(selector, text)	文言／ラベルの変更をプレビューします — 要素のテキストを置き換えます
reset_overrides()	set_style／set_attribute／set_text によるすべてのリアルタイム変更を元に戻します

ライブ編集はプレビューであり、保存ではありません。 set_style／set_attribute／set_text は 実行中の DOM を変更するため、エージェントは再ビルドせずに修正内容を表示できます。これらはソースに 書き込まれず、リロード／HMR でリセットされます。手順は次のとおりです。エージェントがライブでプレビューを表示し、 ユーザーが確認したら、エージェントが実際のソースを編集して変更を反映します。フレームワークが管理する変更（テキストや制御された属性）は、次のレンダリング時に上書きされる場合があります。その場合、ツールの結果にフラグが示されるため、エージェントから説明できます。

---

サンプルアプリ

examples/react-app は、意図的に作り込まれた3つのバグを含む小さな React アプリです。診断ワークフローを 試すのに適したサンドボックスです。

# Terminal 1 — app
cd examples/react-app && pnpm dev    # http://localhost:5173

# Terminal 2 — MCP server
cd packages/mcp && node dist/index.js

AI エージェントを接続し、問題点を見つけるよう依頼してください。3つのバグはいずれも UI からは見えませんが、 get_console_logs、get_network_requests、query_dom を使えば1分もかからずに見つけられます。

---

複数のセッションを同時に実行する

1 台のマシンで 2 つの AI エージェントセッションを実行すると、それぞれが独自の Feedthrough MCP サーバーを起動しますが、ポート 8765 を使えるのは 1 つだけです。この状況には対処できますが、その仕組みを知っておくと便利です。

サーバーは移動し、移動先を知らせます。 ポートが使用中の場合は、失敗する代わりに次のポート（8766、8767、…）へ移ります。connection_status() は実際にバインドしたポートを報告し、エージェントは起動する開発サーバーにそのポートを渡します。

FEEDTHROUGH_PORT=8766 npm run dev

すべてのビルドツールアダプター（vite、webpack、nextjs、nuxt、sveltekit、remix）は、設定の読み込み時に Node で FEEDTHROUGH_PORT（完全な ws:// URL を指定する場合は FEEDTHROUGH_URL）を読み込み、その値を注入されるブリッジに埋め込みます。そのため、コミット済みの引数なしの feedthrough() は、ファイルを編集しなくても、どのセッションでも正しく組み合わさります。明示的に指定した serverUrl オプションは、常に環境変数より優先されます。

自分で開発サーバーを起動する場合、環境変数は設定されていないため、ページは 8765 にフォールバックします。このポートは別のセッションのサーバーである可能性があります。起動前にポートをエクスポートするか、プロジェクトごとに固定してください（下記参照）。

プロジェクトごとにポートを固定する。 いつも専用のセッションで作業するプロジェクトでは、両側のポートを固定すれば、どちらも意識する必要がありません。.mcp.json に次のように記述します。

{
  "mcpServers": {
    "feedthrough": {
      "command": "npx",
      "args": ["@feedthrough/mcp"],
      "env": { "FEEDTHROUGH_PORT": "8770" }
    }
  }
}

そして、アプリの設定に feedthrough({ serverUrl: "ws://localhost:8770" }) と記述します。

ブリッジを見分ける。 各サーバーは起動時に読みやすい名前（quiet-olive-heron）を選び、接続するすべてのページに送信します。ページはブラウザーのコンソールに 1 行記録し、その名前を window.__feedthrough.server に保存して、get_page_info() から返します。エージェント自身の名前は connection_status() から取得できます。名前が異なっていれば、そのタブは別のセッションのサーバーに接続されています。そのため、「正しいアプリを操作しているか」は 1 回の呼び出しで確認でき、間違ったウィンドウの変化を見て気づく必要はありません。

---

AI エージェントでの使用

推奨ワークフロー

1. connection_status() — まずブリッジが接続されていることを確認します
2. get_console_logs() — エラーやアプリの出力から、根本原因がすぐに分かることがよくあります
3. get_network_requests() — 失敗したフェッチ、誤った URL、欠落している呼び出しを探します
4. query_dom(selector) — 要素を探し、何がレンダリングされているかを確認します
5. inspect_element(selector) — 特定の要素を詳しく調べます
6. click() / fill() — 操作した後、ログとネットワークを再確認します

プロジェクトメモ用スニペット

AI エージェントが読み込むプロジェクトメモファイル（Claude Code の CLAUDE.md、Cursor の .cursor/rules/*.md など）に次の内容を追加すると、適切なワークフローを最初に認識させられます。

## Debugging with Feedthrough

A Feedthrough MCP server is configured. When investigating UI bugs:

1. Call `connection_status()` first — fail fast if no browser is connected.
2. Check `get_console_logs()` before touching the DOM.
3. Check `get_network_requests()` for failed or missing API calls.
4. Use `query_dom` to orient yourself, `inspect_element` to dig into a specific element.
5. Interact with `click` / `fill`, then re-check logs.

Prefer element IDs as selectors — they're stable. Avoid long attribute selectors.

システムプロンプトの例

任意の MCP クライアントで単発セッションを実行する場合：

You have access to the Feedthrough MCP server. It gives you live access to a running web app
from inside the browser — console logs, network requests, DOM state, and the ability to click
and fill inputs. Start by calling get_instructions() for the recommended workflow.

---

セキュリティ

v1 はローカル専用です。次の 2 つの保護機能でこれを実現しています。

• ローカルホストへのバインド — WebSocket サーバーは 127.0.0.1 にバインドされるため、ネットワーク上の他のマシンからは接続できません。
• オリジンの検証 — 着信する WebSocket 接続ごとに、Origin ヘッダーを検証します。ループバックオリジン（localhost、127.0.0.1、::1）は常に許可されます。また、許可されたサフィックスで終わるホストも許可されます（デフォルトは .test で、Laravel Valet の myapp.test のようなローカル開発ドメインはそのまま接続できます）。FEEDTHROUGH_ALLOWED_HOST_SUFFIXES（カンマ区切り。デフォルト値を置き換えます。ループバックのみを許可するには空に設定します）でサフィックスのリストを変更できます。それ以外のオリジンは拒否されます。.test オリジンを提示できるのは、実際に .test ホストから配信されたページだけであり、そのホストはローカルに解決されます。したがって、これは接続できる「ローカルオリジンの種類」を増やすものであり、ネットワーク経由の接続範囲を広げるものではありません。

キャプチャされるデータ

キャプチャされるネットワークリクエストには、リクエストとレスポンスの本文とヘッダーが含まれます。Authorization、Cookie、その他アプリが送信するあらゆるヘッダーも含まれます。これは意図的なものです。認証やセッションのフローをデバッグするには、それらが必要です。ただし、データはローカル WebSocket 経由でページの外に送信され、MCP サーバーを通過し、接続先の AI エージェントに届きます。そのエージェントがクラウドを利用している場合、機密情報はプロバイダーに届きます。Feedthrough は開発マシンと開発用データでのみ実行してください。本番ビルドには @feedthrough/core を挿入しないでください。

---

開発

pnpm install       # install all workspace deps
pnpm build         # build all packages
pnpm typecheck     # typecheck all packages

Node.js ≥ 22 と pnpm が必要です。

リリース

パッケージは個別にバージョン管理されます。実際に変更したパッケージのみバージョンを上げ、他のパッケージはそのままにしてください。npm への公開は CI が処理します。Publish to npm ワークフローは GitHub Release が公開されるたびに実行され、npm にまだ存在しない name@version のパッケージのみを公開し、すでに公開済みのものはスキップします（トークン不要の OIDC トラステッドパブリッシングを利用）。

リリースを作成するには、次の手順を実行します。

# 1. Bump the changed package(s) only
pnpm --filter @feedthrough/mcp exec npm version 0.1.1 --no-git-tag-version
# When bumping @feedthrough/mcp, also bump the version (and packages[].version) in
# packages/mcp/server.json to match — the MCP registry validates them against npm.
git add packages/mcp/package.json packages/mcp/server.json
git commit -m "Release @feedthrough/mcp 0.1.1"
git push

# 2. Create a GitHub Release (this triggers the publish workflow)
gh release create v0.1.1 --title "v0.1.1" --notes "..."

このワークフローはすべてのパッケージをビルドし、新たにバージョンを上げたものだけを公開します。また、レジストリに現在のバージョンがない場合は、GitHub OIDC を介して 公式 MCP レジストリ に @feedthrough/mcp（io.github.feedthrough/feedthrough）を公開します。そのため、レジストリへの公開に失敗した場合は、バージョンを上げずにワークフローを再実行（Actions タブの「Run workflow」）して再試行できます。公開をスキップするには、リリースをプレリリースとして設定してください。

---

ライセンス

MIT — LICENSE を参照してください。