Vite React MCP

Agentic React

英語 · 简体中文

コーディングエージェントが、UI の背後にある React ソースをより少ないトークンと検索時間で見つけ、変更できるようにします。マルチモーダルモデルは不要です。

ブラウザーで 1 つまたは複数の要素を選択します。Agentic React は各選択を、React コンポーネント、安定したセレクター、ソースファイル、周辺コード、所有者のトレース、用意された UI 調整プロンプトを含む、ソースを把握したテキストまたは JSON に変換します。

実際のソース特定タスクでの測定結果

3 つの領域を対象にした統制ベンチマークでは、どちらの入力方法でも正しい React ソースを特定できました。切り抜いたスクリーンショットを Agentic React の UI コンテキストを貼り付ける方法に置き換えたところ、エージェントがソースを特定する際に使用したトークン数と観測された実行時間が減少しました。

測定結果	切り抜いたスクリーンショット	Agentic React のコンテキスト	削減率
合計トークン数	388,694	180,302	53.6%
観測されたソース特定の実行時間	84.63s	66.20s	21.8%
API 換算コスト	$0.3699	$0.1254	66.1%

これは 3 つの UI 領域で測定した結果であり、一般的な保証ではありません。統制されたプロンプト、全比較表、ハッシュ、料金の前提条件、制限事項については、ベンチマークの解説と生データのマニフェストを参照してください。

Agentic React を選ぶ理由

• ソース特定に使うトークンを削減： エージェントに、ピクセルからすべてを推測させる代わりに、コンポーネント、セレクター、ソースの場所、周辺コードを渡します。
• マルチモーダルモデル不要： コピーされるコンテキストは構造化されたテキストまたは JSON なので、ソース特定ワークフローはスクリーンショットの解釈やビジョン対応モデルに依存しません。
• React エコシステム全体で動作： バンドラーに依存しないコアに、Vite、Webpack、Next.js 用アダプターを組み合わせて使用でき、Nx／モジュールフェデレーションのプレイグラウンドにも対応します。
• エージェントへの引き継ぎを想定した設計： コンテキストを直接コピーするか、ローカル MCP ツールを介して公開できます。選択した UI とそのソースは一緒に保たれます。
• 用意された UI 調整プロンプト： 調整モーダルで色、タイポグラフィ、寸法、間隔、レイアウトを選択します。Agentic React は、結果の変更リクエストをエージェントが編集すべき正確なソース位置の隣に配置します。

セレクターだけでなく、変更リクエストをコピー

調整モーダルでは、新しいテキストカラーやフォントファミリーなどの選択が、明確な指示に変換されます。コピーされるペイロードには、コンポーネントとソースのトレースに加えて、これらの指示も含まれます。

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

エージェントは、希望する 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 ファイバーの調査、コンポーネントのハイライト、選択コンテキストの整形を行い、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 はキャンセル用に予約されており、変更できません。ショートカットの登録時には、修飾キー以外のキーが1つであること、サポート対象のキーのみを使っていること、正規化後に重複したショートカットがないことが検証されます。

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 は、キャメルケースのトークン名を --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 などのトークンを参照します。

アダプターには次のように設定を渡します。

// Vite
AgenticReact({ toolkit });

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

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

構造を拡張するには、ブラウザー側のチューニングモーダル拡張機能を登録します。スロットレンダラーを使うと、フィールドの前後やフッターにカスタム DOM を追加できます。wrapModal はモーダルの surfaceElement と panelElement を受け取るため、デザインシステムで、描画されたモーダルの周囲にラッパー、データ属性、オブザーバー、ポータルを追加したり、クリーンアップを考慮した動作を実装したりできます。

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

E2E 自動化では、Playwright はプレイグラウンドのパッケージ設定で構成された固定のローカルポートを使用します。

謝辞

このプロジェクトは vite-plugin-vue-mcp に着想を得ています。

ライセンス

MIT