feedthrough

Feedthrough

借助 AI 调试 — 直接在应用内部进行。

Feedthrough 会将轻量级调试桥接注入任意正在运行的网页，然后将所有信息 ——DOM 状态、控制台日志、网络请求和用户交互——作为 MCP 工具开放出来。任何 兼容 MCP 的 AI Agent 都能通过对话实时检查并操控页面。

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 则是嵌入式 Agent。它在页面内部运行，因此可以看到：

• 框架内部信息（React 组件树、Redux store、自定义全局变量）
• 任意浏览器，不限于 Chrome
• 现有的开发工作流——无需另外启动受控浏览器
• 测试运行期间 Cypress 自身的浏览器上下文

---

软件包

软件包	描述
@feedthrough/core	浏览器内桥接程序——拦截 console、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 适配器——使用 withFeedthrough() 包装 next.config.ts
@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。 为获得最简单的体验，请保持只打开一个标签页。多个标签页可以同时连接， 命令会发送到最近活动的标签页，但只打开一个标签页可避免任何歧义。

然后向你的 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 工具

工具	说明
get_instructions()	使用指南 — 推荐的工作流、工具调用顺序和选择器提示
query_dom(selector)	匹配 CSS 选择器的所有元素
inspect_element(selector, properties?)	标签、属性、完整边界矩形及 inViewport、祖先 path、精选计算样式、溢出信息（内容被裁剪/溢出）、被祖先裁剪的信息、有效可见性（visible + hiddenReason，会考虑祖先元素）、遮挡情况（hittable + occludedBy）、可访问性（a11y：role、name、状态）、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，以便 Agent 无需重新构建即可向你展示修复效果。它们不会写入源代码， 并会在重新加载/HMR 时重置。工作流程：Agent 实时预览，你确认后，它再编辑 实际源代码，使更改生效。框架管理的变更（文本、受控属性）可能会在下一次渲染时被覆盖 —— 工具结果会标记这一点，以便 Agent 告知你。

---

示例应用

examples/react-app 是一个小型 React 应用，其中有三个刻意设置的 Bug —— 非常适合作为诊断工作流的试验场：

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

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

连接 AI Agent，并询问它哪里出了问题。这三个 Bug 在 UI 中都不可见，但使用 get_console_logs、get_network_requests 和 query_dom，不到一分钟就能找到。

---

同时运行多个会话

同一台机器上的两个 AI Agent 会话各自启动一个 Feedthrough MCP 服务，但 8765 端口只能由其中一个占用。这种情况已妥善处理，不过了解其工作方式也很有帮助。

服务会切换端口，并告知你新端口。 如果端口已被占用，它会依次尝试更高的端口（8766、8767，……），而不是直接失败。connection_status() 会报告它实际绑定的端口，Agent 会将该端口传给自己启动的开发服务器：

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），并将其发送给每个连接的页面。页面会在浏览器控制台记录一行，将名称存储在 window.__feedthrough.server 中，并通过 get_page_info() 返回该名称。Agent 自身的名称来自 connection_status()。如果两个名称不同，就说明该标签页配对的是另一个会话的服务——因此，只需调用一次就能确认“我控制的是正确的应用吗？”，无需等到看到错误窗口发生变化才发现问题。

---

与 AI Agent 搭配使用

推荐工作流

1. connection_status() — 首先确认桥接已连接
2. get_console_logs() — 错误和应用输出通常能立即指出根本原因
3. get_network_requests() — 查找失败的 fetch、错误的 URL 或缺失的调用
4. query_dom(selector) — 查找元素并检查渲染结果
5. inspect_element(selector) — 深入检查特定元素
6. click() / fill() — 执行交互，然后再次检查日志和网络请求

项目记忆片段

将以下内容添加到 AI Agent 会读取的项目记忆文件中——例如 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 仅限本地使用。以下两项防护措施共同确保这一点：

• 绑定到 localhost — WebSocket 服务绑定到 127.0.0.1，因此网络中的其他机器无法访问它。
• Origin 验证 — 每个传入的 WebSocket 连接都会根据其 Origin 标头进行检查。 环回来源（localhost、127.0.0.1、::1）始终会被接受，任何以允许的后缀结尾的主机也会被接受（默认后缀为 .test，因此 Laravel Valet 的 myapp.test 等本地开发域名开箱即用）。使用 FEEDTHROUGH_ALLOWED_HOST_SUFFIXES 覆盖后缀列表（以逗号分隔；会替换默认值——设为空即可仅允许环回来源）。其他任何来源都会被拒绝。.test 来源只能由实际通过 .test 主机提供服务的页面声明，而这类主机会解析到本地，因此这只会扩大可连接的本地来源范围，不会扩大网络可达范围。

捕获的内容

捕获的网络请求包括请求和响应的正文与标头，包括 Authorization、Cookie 以及 应用发送的任何其他标头。这是有意为之——调试身份验证和会话流程需要这些信息。不过，数据 确实会通过本地 WebSocket 离开页面，流经 MCP 服务，并到达你连接的 AI Agent。如果该 Agent 由云端提供支持，敏感值就会传输给服务提供商。仅在开发机器和开发数据上运行 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 处理：每次发布 GitHub Release 时，Publish to npm 工作流都会运行，并且只发布 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 "..."

该工作流会构建所有包，并且只发布新升级版本的包。只要官方 MCP 注册表中缺少当前版本，它也会通过 GitHub OIDC 将 @feedthrough/mcp 发布到该注册表（io.github.feedthrough/feedthrough）。因此，如果注册表发布失败，可以在不升级版本的情况下重新运行工作流（在 Actions 标签页中选择“Run workflow”）重试。将发布标记为预发布版本即可跳过发布。

---

许可证

MIT — 详见 LICENSE。