feedthrough

# Feedthrough

**Debug with AI — from inside your app.**

Feedthrough injects a lightweight debug bridge into any running web page, then exposes everything
— DOM state, console logs, network requests, and user interactions — as MCP tools. Any
MCP-compatible AI agent can inspect and drive the page conversationally, in real time.

```
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
```

---

## The name

Many physics and chemistry experiments run inside a sealed vacuum chamber, with all the air
pumped out so nothing contaminates the experiment. The catch: you still need to control
instruments inside the chamber and read their measurements, and the smallest air leak ruins
the run. A feedthrough is the part that solves this — a specially engineered connector that
carries electrical signals through the chamber wall while keeping the vacuum perfectly intact.
You can't reach inside, but the feedthrough lets you observe and control what's happening in
there anyway.

The parallel is exact: Feedthrough extracts runtime debug data from inside a running web app
without disturbing it, and sends control signals back in — clicks, keystrokes, DOM queries —
without breaking the execution environment.

---

## Why Feedthrough?

Every other browser MCP tool is an **external observer** — it controls the browser from outside
via Puppeteer or CDP and only works in Chrome. Feedthrough is an **embedded agent**. It runs
*inside* the page, so it sees:

- Framework internals (React component trees, Redux store, custom globals)
- Any browser, not just Chrome
- Your existing dev workflow — no separate controlled browser to launch
- Cypress's own browser context during test runs

---

## Packages

| Package | Description |
|---|---|
| [`@feedthrough/core`](packages/core) | In-browser bridge — intercepts console, fetch, XHR; handles commands |
| [`@feedthrough/mcp`](packages/mcp) | MCP server — bridges any MCP client to the browser via WebSocket |
| [`@feedthrough/cypress`](packages/cypress) | Cypress adapter — auto-injects the bridge before each test page load |
| [`@feedthrough/playwright`](packages/playwright) | Playwright adapter — injects the bridge via `page.addInitScript()` |
| [`@feedthrough/vite`](packages/vite) | Vite plugin for apps with a static `index.html` |
| [`@feedthrough/webpack`](packages/webpack) | Webpack plugin — adds bridge as a global entry point |
| [`@feedthrough/nextjs`](packages/nextjs) | Next.js adapter — wraps `next.config.ts` with `withFeedthrough()` |
| [`@feedthrough/nuxt`](packages/nuxt) | Nuxt 3 module |
| [`@feedthrough/sveltekit`](packages/sveltekit) | SvelteKit adapter — injects via the `handle` hook |
| [`@feedthrough/remix`](packages/remix) | Remix adapter — injects via a Vite dev server middleware |

---

## Framework support

| Framework | Adapter | Notes |
|---|---|---|
| Vite + React / Vue / Solid / Preact | `@feedthrough/vite` | Static `index.html` — plugin uses `transformIndexHtml` |
| Next.js | `@feedthrough/nextjs` | Wraps the webpack config; dev only |
| Nuxt 3 | `@feedthrough/nuxt` | Registers as a Nuxt module; dev only |
| SvelteKit | `@feedthrough/sveltekit` | `handle` hook with `transformPageChunk`; dev only |
| Remix | `@feedthrough/remix` | Vite dev server middleware; dev only |
| Webpack apps | `@feedthrough/webpack` | Global entry point; guards against production mode |
| Cypress | `@feedthrough/cypress` | `window:before:load` hook |
| Playwright | `@feedthrough/playwright` | `page.addInitScript()` |

---

## Quick start

### 1. Start the MCP server

```bash
npx @feedthrough/mcp
```

The server listens for browser connections on `ws://127.0.0.1:8765` and exposes MCP tools on
stdio. Override the port with `FEEDTHROUGH_PORT=9000`.

### 2. Add it to your MCP client config

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

### 3. Inject the bridge into your page

**Vite + React / Vue / Solid / Preact:**

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

**Next.js:**

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

**Nuxt 3:**

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

**SvelteKit:**

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

**Remix:**

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

**Webpack:**

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

**Cypress:**

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

**Playwright:**

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

**Or manually (any bundler):**

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

### 4. Open your page and start asking

Once the bridge connects you'll see `[feedthrough] tab connected` in the MCP server output.
For the simplest experience, keep a single tab open. Multiple tabs can connect at the same time
and commands are routed to the most recently active one, but a single tab avoids any ambiguity.

Then ask your AI agent:

```
> 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 tools

| Tool | Description |
|---|---|
| `get_instructions()` | Usage guide — recommended workflow, tool ordering, and selector tips |
| `query_dom(selector)` | All elements matching a CSS selector |
| `inspect_element(selector, properties?)` | Tag, attributes, full bounding rect + inViewport, ancestor `path`, curated computed styles, overflow info (clipped/overflowing content), `clipped`-by-ancestor info, effective visibility (`visible` + `hiddenReason`, accounting for ancestors), occlusion (`hittable` + `occludedBy`), accessibility (`a11y`: role, name, states), `pseudo` ::before/::after content, live form state; `properties` reads extra CSS props by name |
| `get_html(selector)` | Raw outerHTML of a region (capped at 50 KB) |
| `get_console_logs(limit?, levels?, match?, since?)` | Console output (all methods) plus uncaught errors & promise rejections; filter by `levels`, `match`, or `since` timestamp |
| `get_network_requests(filter?, since?)` | Captured fetch + XHR — URL, method, status, duration, headers, request/response bodies (10 KB cap); narrow by `filter` or `since` |
| `get_page_info()` | URL, title, readyState, viewport size, scroll position, user agent |
| `connection_status()` | List connected tabs and which one is currently active |
| `click(selector)` | Click an element via native `click()` (fires click + default activation, not the pointer sequence) |
| `fill(selector, value)` | Set an input/textarea/select value (fires input + change, not keystrokes) |
| `hover(selector)` | Fire mouseover/mouseenter to mount hover UI (JS handlers, not CSS `:hover`) |
| `press_key(selector, key)` | Dispatch a key press — Enter, Escape, Tab, arrow keys, or a character |
| `set_style(selector, properties)` | Preview a visual fix — set inline CSS live (not saved to source) |
| `set_attribute(selector, name, value)` | Preview an attribute change — toggle disabled, swap a class, set aria-* (`null` removes) |
| `set_text(selector, text)` | Preview wording/label changes — replace an element's text |
| `reset_overrides()` | Undo every live `set_style` / `set_attribute` / `set_text` change |

**Live edit is a preview, not a save.** `set_style` / `set_attribute` / `set_text` mutate the
running DOM so the agent can show you a fix without a rebuild. They are *not* written to your
source and reset on reload/HMR. The loop: the agent previews live, you confirm, then it edits the
actual source to make it stick. Changes a framework owns (text, controlled attributes) may be
overwritten on the next render — the tool result flags this so the agent can tell you.

---

## Example app

`examples/react-app` is a small React app with three deliberate bugs — a good sandbox for
trying out the diagnostic workflow:

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

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

Connect an AI agent and ask it to find what's wrong. The three bugs are all invisible from the
UI but findable in under a minute via `get_console_logs`, `get_network_requests`, and `query_dom`.

---

## Using with an AI agent

### Recommended workflow

1. `connection_status()` — confirm the bridge is connected before anything else
2. `get_console_logs()` — errors and app output often identify the root cause immediately
3. `get_network_requests()` — look for failed fetches, wrong URLs, or missing calls
4. `query_dom(selector)` — find elements and check what's rendered
5. `inspect_element(selector)` — deep-dive on a specific element
6. `click()` / `fill()` — interact, then re-check logs and network

### Project-memory snippet

Add this to whatever project-memory file your AI agent reads — `CLAUDE.md` for Claude Code,
`.cursor/rules/*.md` for Cursor, and so on — to prime it with the right w