Vite React MCP

Agentic React

English · 简体中文

帮助编码 Agent 以更少的令牌和更短的搜索时间，找到并修改 UI 背后的 React 源代码——无需多模态模型。

在浏览器中选择一个或多个元素。Agentic React 会将每次选择转换为可感知源码的文本或 JSON，其中包含 React 组件、稳定选择器、源文件、附近代码、所有者追踪，以及任何已准备好的 UI 调整提示词。

真实源码定位任务的实测结果

在一项包含三个区域的受控基准测试中，两种输入方式都找到了正确的 React 源代码。用粘贴的 Agentic React UI 上下文替代裁剪后的屏幕截图，减少了 Agent 定位该源码所用的令牌和实测运行时间：

实测结果	裁剪后的屏幕截图	Agentic React 上下文	降幅
总令牌数	388,694	180,302	53.6%
实测源码定位运行时间	84.63s	66.20s	21.8%
API 等效成本	$0.3699	$0.1254	66.1%

这是针对三个 UI 区域的实测证据，并非普遍保证。受控提示词、完整矩阵、哈希值、定价假设和限制详见基准测试说明和原始证据清单。

为什么选择 Agentic React

• **减少定位源码所需的令牌：**提供组件、选择器、源码位置和附近代码，让 Agent 无需从像素中推断这些信息。
• **无需多模态模型：**复制的上下文是结构化文本或 JSON，因此源码定位工作流不依赖屏幕截图解读或支持视觉的模型。
• **适用于 React 生态系统：**使用与打包工具无关的核心，并搭配 Vite、Webpack 和 Next.js 适配器，以及 Nx／模块联邦 Playground。
• **为 Agent 交接而构建：**直接复制上下文，或通过本地 MCP 工具提供上下文，让选中的 UI 与其源码保持关联。
• **预先准备 UI 调整提示词：**在调整模态框中选择颜色、字体、尺寸、间距或布局。Agentic React 会将生成的更改请求与 Agent 应编辑的确切源码位置放在一起。

复制更改请求，而不只是选择器

调整模态框会将新文本颜色或字体系列等选择转换为明确的指令。复制的内容会将这些指令与组件和源码追踪信息一同传递：

<web_context type="react_component_location">
component: ProfileField
tuning prompts:
- Change <ProfileField> in src/components/UserProfile/ProfileField.jsx:19 text color to rgb(15, 118, 110).
- Change <ProfileField> in src/components/UserProfile/ProfileField.jsx:19 font family to Inter.
selector: #profile-field-email
source: src/components/UserProfile/ProfileField.jsx:19
source trace:
  -> <ProfileField> at src/components/UserProfile/ProfileField.jsx:19
  -> <ProfileContent> at src/components/UserProfile/ProfileContent.jsx:54
</web_context>

Agent 会同时收到所需的 UI 更改，以及代码库中应进行该更改的位置。

演示

单选

多选

这些软件包以 @agentic-react 命名空间发布。

软件包

• @agentic-react/core：与打包工具无关的浏览器运行时、React 选择工具包和 MCP 基元。
• @agentic-react/vite：用于本地开发的 Vite 适配器。
• @agentic-react/webpack：用于本地开发的 Webpack 适配器。
• @agentic-react/next：用于本地开发的 Next.js 适配器。

如需完整的本地开发功能，请安装适用于你的打包工具的适配器。适配器在内部依赖 @agentic-react/core，因此应用用户无需同时导入这两个软件包。

本地开发用法

Vite

pnpm install @agentic-react/vite -D

// vite.config.ts
import { defineConfig } from 'vite';
import AgenticReact from '@agentic-react/vite';

export default defineConfig({
  plugins: [AgenticReact()],
});

Vite 适配器会注入核心浏览器运行时，将运行时桥接器连接到开发服务器，并通过以下地址提供 MCP：

http://localhost:<vite-port>/mcp

Webpack

pnpm install @agentic-react/webpack -D

// webpack.config.mjs
import withAgenticReactWebpack from '@agentic-react/webpack';

export default (env, argv) =>
  withAgenticReactWebpack(config, { mode: argv.mode });

Webpack 适配器会前置一个生成的运行时入口，将运行时桥接器连接到 webpack-dev-server，并在以下地址提供 MCP：

http://localhost:<webpack-dev-server-port>/mcp

Next.js

pnpm install @agentic-react/next -D

// next.config.mjs
import withAgenticReactNext from '@agentic-react/next';

export default withAgenticReactNext(nextConfig);

Next 适配器通过 Next 的 Webpack 配置注入浏览器运行时，并启动本地桥接服务。默认情况下，MCP 可通过以下地址访问：

http://127.0.0.1:51426/mcp

仅运行时用法

如果只需要浏览器端的选择／运行时 API，而不需要本地源文件查找或 MCP 开发服务器接线，可直接使用 @agentic-react/core。

pnpm install @agentic-react/core

import { createSelectionToolkit } from '@agentic-react/core';

const toolkit = createSelectionToolkit();
toolkit.enable();

仅运行时模式可以检查实时浏览器树，但无法读取或编辑本地文件。源代码查找和本地 MCP 传输由适配器层负责。

适配器的额外功能

@agentic-react/core 在浏览器中运行，可选择元素、检查 React fiber、高亮组件、格式化选择上下文，并公开 window.__AGENTIC_REACT__ / window.__AGENTIC_REACT_TOOLS__。

打包器适配器提供运行时本身无法获知的本地开发功能：

• 自动注入核心运行时
• 添加本地 MCP Streamable HTTP /mcp 端点
• 将 MCP 调用从 Node 桥接至浏览器运行时
• 为源代码查找提供本地源代码根目录上下文
• 通过适配器托管的桥接服务持久化工具箱设置
• 确保仅开发环境使用的工具不会进入生产构建包

设置与选择确认

通过受支持的开发适配器运行时，工具箱会显示“设置”部分。设置可配置单选、多选、工具箱切换和“完成”快捷键，也可将启动器图标替换为裁剪后的自定义图片。

用户设置在本地计算机上全局生效，并存储在 ~/.agentic-react/ 下。设置不会限定于某个项目、浏览器来源、主机名、端口或打包器。有效值按以下顺序解析：

global user override
  > project configuration default
  > package default

重置某项设置只会移除全局覆盖；如果存在项目默认值，则恢复为该值，否则使用包默认值。项目默认值来自适配器选项：快捷键默认值为 toolkit.settings.shortcuts，工具箱图标默认值为 toolkit.iconUrl。

包默认值如下：

操作	默认快捷键
单选	Ctrl+Alt+Shift+S
多选	Ctrl+Alt+Shift+M
切换工具箱	Ctrl+Alt+Shift+A
完成	Enter

Escape 专用于取消操作，且无法配置。录制快捷键时会验证是否仅包含一个非修饰键、是否只使用受支持的按键，以及规范化后的快捷键是否重复。

settingsRoot 是适配器选项，适用于测试、演示和临时沙盒等隔离环境。对于类似生产环境的本地使用，通常应省略该选项，以便 Agentic React 使用用户的全局 ~/.agentic-react 目录。

// Vite
AgenticReact({
  settingsRoot: '/tmp/agentic-react-settings',
  toolkit: {
    iconUrl: '/agentic-react-logo.png',
    settings: {
      shortcuts: {
        singleSelect: 'Ctrl+Shift+S',
        done: 'Enter',
      },
    },
  },
});

// Webpack
withAgenticReactWebpack(
  config,
  { mode: 'development' },
  {
    settingsRoot: '/tmp/agentic-react-settings',
    toolkit: {
      iconUrl: '/agentic-react-logo.png',
      settings: {
        shortcuts: {
          multiSelect: 'Ctrl+Shift+M',
        },
      },
    },
  }
);

// Next.js
withAgenticReactNext(nextConfig, {
  settingsRoot: '/tmp/agentic-react-settings',
  toolkit: {
    iconUrl: '/agentic-react-logo.png',
    settings: {
      shortcuts: {
        toggleToolbox: 'Ctrl+Shift+A',
      },
    },
  },
});

选择是一项明确的事务。点击目标会捕获并显示待处理的上下文，但不会立即复制。点击“完成”或按下配置的“完成”快捷键（默认为 Enter），即可复制并提交待处理的选择。在多选模式下，“完成”会复制完整的待处理选择集。Escape 会取消待处理的单选和多选操作，不进行复制，并保留上一次已提交的选择。

仅运行时使用 @agentic-react/core 仍可运行浏览器端选择 API，并使用代码提供的工具包默认值，但没有适配器托管的桥接服务时，不会持久化设置。

调整模态框 API

选择叠加层包含一个调整模态框，可将视觉调整转换为提示词文本。通过适配器的 toolkit 选项进行配置，或在运行时调用 window.__AGENTIC_REACT__.setToolkitConfig()。

import type { ToolkitConfig } from '@agentic-react/vite';

// Import ToolkitConfig from the adapter package you use.
const toolkit: ToolkitConfig = {
  enabled: true,
  defaultVisible: true,
  defaultExpanded: false,
  position: 'bottom-right',
  offset: { x: 20, y: 20 },
  accentColor: '#111827',
  zIndex: 2147483000,
  iconUrl: '/agentic-react-logo.png',
  tuningModal: {
    classNames: {
      surface: 'my-tuning-surface',
      panel: 'my-tuning-panel',
      control: 'my-tuning-control',
    },
    styles: {
      panel: { border: '1px solid rgba(15, 23, 42, 0.18)' },
      targetTag: { background: '#f8fafc', color: '#0f172a' },
    },
    tokens: {
      panelRadius: '14px',
      controlRadius: '10px',
      primaryButtonBackground: '#0f766e',
      primaryButtonColor: '#ffffff',
      panelShadow: '0 24px 72px rgba(15, 118, 110, 0.22)',
    },
  },
};

tuningModal.classNames 会为模态框插槽添加类名。tuningModal.styles 会为相同插槽应用内联样式对象。支持的插槽有 root、surface、panel、arrow、title、body、targetTag、customPromptForm、customPromptInput、customPromptButton、sectionTitle、row、label、controlWrap、control、colorInput、numberInput、stepperButton、select、textarea、suffix 和 closeButton。

tuningModal.tokens 会将驼峰式 token 名称映射为以 --agentic-react-tuning- 为前缀的 CSS 变量。例如，panelRadius 会变为 --agentic-react-tuning-panel-radius，而 primaryButtonBackground 会变为 --agentic-react-tuning-primary-button-background。内置控件目前会读取 panelBackground、panelBorder、panelRadius、panelShadow、panelColor、controlBorder、controlRadius、controlBackground、controlColor、labelColor、sectionColor、primaryButtonBorder、primaryButtonBackground、primaryButtonColor、secondaryButtonBackground 和 secondaryButtonColor 等 token。

适配器按如下方式传递配置：

// Vite
AgenticReact({ toolkit });

// Webpack
withAgenticReactWebpack(config, { mode: 'development' }, { toolkit });

// Next.js
withAgenticReactNext(nextConfig, { toolkit });

如需扩展结构，请注册浏览器端的调整模态框扩展。插槽渲染器可在字段前、字段后或页脚中添加自定义 DOM。wrapModal 会接收模态框的 surfaceElement 和 panelElement，让设计系统能够在渲染后的模态框周围添加包装器、数据属性、观察器、Portal 或具备清理机制的行为。

const unregister = window.__AGENTIC_REACT__?.registerTuningModalExtension({
  id: 'design-system-audit',
  beforeFields({ container, context }) {
    const badge = document.createElement('div');
    badge.textContent = `Editing ${context.tagName}`;
    badge.className = 'agentic-design-system-badge';
    container.appendChild(badge);
  },
  wrapModal({ surfaceElement, actions }) {
    surfaceElement.dataset.designSystem = 'acme';
    const onTransitionEnd = () => actions.requestReposition();
    surfaceElement.addEventListener('transitionend', onTransitionEnd);
    return () => {
      surfaceElement.removeEventListener('transitionend', onTransitionEnd);
    };
  },
});

具体的 Playground 示例：

// playground/agentic-react-vite-playground/vite.config.js
AgenticReact({
  toolkit: {
    iconUrl: '/agentic-react-logo.png',
    tuningModal: {
      classNames: {
        surface: 'vite-playground-tuning-surface',
        panel: 'vite-playground-tuning-panel',
        control: 'vite-playground-tuning-control',
      },
      tokens: {
        panelRadius: '14px',
        controlRadius: '10px',
        primaryButtonBackground: '#0f766e',
        primaryButtonColor: '#ffffff',
        panelShadow: '0 24px 72px rgba(15, 118, 110, 0.22)',
      },
      styles: {
        surface: {
          filter: 'drop-shadow(0 18px 40px rgba(15, 118, 110, 0.16))',
        },
        panel: {
          border: '1px solid rgba(15, 118, 110, 0.22)',
        },
        targetTag: {
          background: '#ecfeff',
          color: '#0f766e',
        },
        sectionTitle: {
          color: '#0f766e',
        },
      },
    },
  },
});

自定义工具

适配器支持浏览器端自定义工具。从你所用的适配器包中导入共享类型：

import type { ToolResultValue } from '@agentic-react/vite';

export default function logMessage(args: { message: string }): ToolResultValue {
  return {
    success: true,
    message: `Received: ${args.message}`,
  };
}

import { defineConfig } from 'vite';
import AgenticReact from '@agentic-react/vite';
import { z } from 'zod';
import logMessage from './src/tools/logMessage';

export default defineConfig({
  plugins: [
    AgenticReact({
      customTools: [
        {
          name: 'log-message',
          description: 'Log a message in the browser runtime',
          schema: z.object({ message: z.string() }),
          clientFunction: logMessage,
        },
      ],
    }),
  ],
});

发布冒烟测试

使用以下命令在本地运行发布自动化冒烟测试：

pnpm run test:release-smoke

该测试不会发布到 npm，也不会调用 GitHub。它会读取 .github/workflows/release.yml，创建临时 Git 测试环境，并使用伪造的 pnpm 和 gh 命令覆盖发布自动化分支。 该测试可防止此工作流中已修复的发布回归问题：

• 检测待处理的 changeset 时会忽略 .changeset/README.md；仅当存在真正的 changeset Markdown 文件时才运行 version-packages，提交 chore: version packages，并将该提交推送回 main
• 发布工作流仍然是 main 推送工作流，并保持版本更新、构建、发布、推送标签、创建 GitHub 发布的顺序
• 发布期间创建的软件包标签会通过 git push origin --tags 推送
• GitHub 发布会从指向 HEAD 的标签中选取，并筛选出 @agentic-react/*，因此过时的软件包标签和非软件包标签不会创建发布

开发

pnpm run build
pnpm run playground:vite
pnpm run playground:webpack
pnpm run playground:next
pnpm run playground:nx-mf

对于端到端自动化，Playwright 使用在 Playground 包配置中指定的固定本地端口。

致谢

本项目的灵感来自 vite-plugin-vue-mcp。

许可证

MIT