これは何か
vite dev の実行中、プラグインは /__svelte-devtools/mcp に MCP エンドポイント(Streamable
HTTP)を提供します。エージェントは通常、各呼び出しを中継する小さな stdio サーバー vite-devtools-svelte mcp を通してツールを呼び、パネルに表示される内容を読みます:
活発なコンポーネント、1 つのインスタンスのリアクティブグラフ、サンプリングされた state の変化、レンダープロファイル、load
関数、フレームレート。変更の前後を比べる計測セッションも実行できます。
アプリのコードや state を変更するツールはありません。起きることは 2 つです:
呼び出しのたびにページ内のランタイムが約 1
分間サンプリングを続けること、そしてセッション系のツールが計測セッションを保持すること(メモリ内。ディスクには指定したときだけ書き込み、delete_session で削除できます)。実行時のデータはブラウザで開いているアプリのページから来るので、エージェントの作業中はアプリを開いたままにしてください。
Claude Code に接続する
プロジェクトごとに 1 回、MCP サーバーを登録します。開発サーバーも起動時にこのコマンドを表示します:
claude mcp add svelte-devtools -- npx @sveltejs/vite-devtools-svelte mcpvite-devtools-svelte mcp は stdio で動き、カレントディレクトリのプロジェクトで動いている開発サーバーに各呼び出しを中継します。開発サーバーとそのポート、トークンは自分で見つけるので、再起動やポートの変更があっても登録し直す必要はありません。開発サーバーが動いていないときは、ツールが起動のしかたを返します。
動いている開発サーバーは ~/.cache/vite-devtools-svelte/servers/ に 1 つずつファイルを書いて自分の存在を知らせます($XDG_CACHE_HOME があればその下、Windows では %LOCALAPPDATA% の下)。使われるのは同じマシンの開発サーバーだけです。
Svelte のドキュメントとコードチェック
ドキュメントと svelte-autofixer は公式の Svelte MCP サーバーが提供します。このサーバーは、公式サーバーが設定されていればそちらを使うよう AI
に指示するので、あわせて追加してください:
claude mcp add svelte -- npx -y @sveltejs/mcpコマンドの代わりにプロジェクトのファイルを使う
claude mcp add は自分だけにサーバーを登録します(local
スコープ)。プロジェクトの .mcp.json はプロジェクトを開く全員と共有されます(project
スコープ)。トークンを含まないので、コミットしてかまいません:
{
"mcpServers": {
"svelte-devtools": {
"command": "npx",
"args": ["@sveltejs/vite-devtools-svelte", "mcp"]
}
}
}開発サーバーが複数あるとき
stdio
のサーバーは、カレントディレクトリを含むルートの開発サーバー(いちばん内側のもの)を使い、なければカレントディレクトリの中にある唯一の開発サーバーを使います。モノレポのルートから使う場合や、同じアプリを
2 つ起動している場合は、複数が該当します。そのとき AI は list_dev_servers を呼び、使うサーバーを server で指定します(id、ルート、パッケージ名のどれか)。
他の MCP クライアント
stdio のサーバーを起動できるクライアントでは、同じコマンド(npx @sveltejs/vite-devtools-svelte mcp)を使います。カスタムヘッダー付きの Streamable HTTP
にしか対応していないクライアントは、開発サーバーに直接接続します。必要なのは URL(http://localhost:<port>/__svelte-devtools/mcp)とヘッダー(x-svelte-devtools-token: <token>)の 2
つです。トークンは開発サーバーを起動するたびに変わります(トークンの取得方法)。HTTP のエンドポイントはステートレスで JSON で応答します。手動で確認するには:
curl -s http://localhost:5173/__svelte-devtools/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H 'x-svelte-devtools-token: <token>' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'コンテナ、別のマシン、ミドルウェアモード
stdio のサーバーが見つけられるのは、同じマシンで自分の存在を知らせた開発サーバーだけです。コンテナや別のマシンで動いている開発サーバーは見つからず、Vite のミドルウェアモードでは、プラグインが存在を知らせるのに使う自前のサーバーがありません。その場合は接続先を自分で stdio のサーバーに渡します:
VITE_DEVTOOLS_SVELTE_URL: MCP クライアントから届く開発サーバーの URL(例:http://localhost:5173)。パスがなければ/__svelte-devtools/mcpを補います。VITE_DEVTOOLS_SVELTE_TOKEN: その開発サーバーのトークン。URL を設定したら必須です。
これらを設定すると、すべての呼び出しがその接続先に送られ、server は無視されます。Claude Code の場合:
claude mcp add svelte-devtools \
-e VITE_DEVTOOLS_SVELTE_URL=http://localhost:5173 \
-e VITE_DEVTOOLS_SVELTE_TOKEN=<token> \
-- npx @sveltejs/vite-devtools-svelte mcpトークンは起動のたびに変わるので、開発サーバーを再起動したら登録を更新してください。
トークンの取得方法
- 開発サーバーが動いているマシン(またはコンテナ)の
~/.cache/vite-devtools-svelte/servers/にあるファイルから読みます。ファイル名は<pid>-<port>.jsonで、tokenとurlが入っています。 - ミドルウェアモードではファイルは書かれません。
vite-devtools-svelteという名前のプラグインの API から読みます(リポジトリのexamples/svelte-middleware/server.jsと同じ方法):
const vite = await createServer({ server: { middlewareMode: true } });
const devtools = vite.config.plugins.find(p => p.name === 'vite-devtools-svelte');
const token = devtools?.api?.getDevtoolsToken?.();聞いてみる
たとえばアプリのカートページを開いた状態で:
/cart で税率を変えるとカートの合計がおかしい。
svelte-devtools MCP サーバーを使って、活発なコンポーネントを探し、
ReactivePriceChart のインスタンスを見て、grandTotal に影響しうる state と、
税率を編集したときに何が変わったかを教えて。エージェントは通常 get_reactive_summary か list_performance_issues から始め、回答に含まれるヒントをたどります。
基本の流れ
大きなアプリでも回答を小さく保つ順序です。各ステップの実際の回答は英語版の Walkthroughにあります(合成データのサンプルアプリ examples/sample-app(現 examples/kit-shop)で CI が記録したもの)。
get_reactive_summary— まず全体の活発さを見ます。グラフは取得しないので、大きなアプリでも回答は小さく収まります。回数は各インスタンスがマウントされてからの累計で、lastActiveAt が最後に動いた時刻を示します。get_live_components— includeMeta: true で、インスタンスの id とその epoch(ページ読み込み)を一緒に取得します。id はページを読み込むたびに振り直されます。get_reactive_scope— componentId と epoch を渡して、1 つのインスタンスのノードと直接の隣接ノードを見ます。エッジは「影響しうる」(現在の依存関係)という意味で、変化の原因ではありません。get_state_timeline— 最初はカーソルなしで呼び(reset: true)、返された cursor を保存します。アプリで値を変えたあと、cursor を since に渡すと新しい変化だけが返ります。get_capture_info— 上限で切られたデータから結論を出す前に、DevTools が保持している量とアプリが報告した量を確認します。total が null の場合は不明という意味です。
ページをリロードすると、古い epoch のままの componentId
は別のインスタンスとして推測されず、staleReason: "epoch-changed" の空の回答になります。get_live_components で新しい id を取得し直してください。
20 のツール
入力は ? が付いていないもの以外すべて省略できます。
開発サーバーのエンドポイントにあるのは以下の 20 のツールです。vite-devtools-svelte mcp は list_dev_servers を追加し、各ツールに server? の入力を加えます(最後のグループを参照)。
リアクティビティ(範囲を限定して取得)
0.4.0 で追加。どの回答も、対象範囲・サンプリング・上限・ページ読み込み(epoch)・古いデータかどうかを明示します。大きなアプリではここから始めてください。
get_reactive_summarytopK?: 1–200
全インスタンスの実行時カウンタから、最も活発な表示中のコンポーネントインスタンスを返します(グラフは取得しません)。各インスタンスがマウントされてからサンプリングされた state の変化とレンダーの回数、最後に動いた時刻を返し、`rows` と `other` の合計が総数になります。
回数は累計のサンプリング値(1 つの state につき 200 ms ごとに最大 1 回)で、発生率ではありません。破棄されたインスタンスは回数ごと消えます。state の変化はパネルかエージェントが見ている間だけサンプリングします。追跡するのは、コンポーネントの初期化中に作られた state と、.svelte.js/.ts モジュールの共有 state です。モジュールは kind "module" の行になり、その componentId は get_reactive_scope にも使えます。最大 1 秒間はキャッシュから回答します。
get_reactive_scopecomponentId?: number, epoch?: string, maxNodes?: 1–5000, maxEdges?: 1–20000
1 つのコンポーネントインスタンスの $state / $derived / $effect ノードと、その直接の隣接ノード。componentId を省略するとアプリ全体のグラフ(上限あり)。
componentId には取得元の epoch が必要です(includeMeta 付きの get_live_components)。リロード後は staleReason "epoch-changed" の空の回答になります。エッジは「影響しうる」関係で、記録された原因ではありません。
get_state_timelinesince?: cursor, limit?: 1–500 (default 100), maxValueChars?: 16–32768 (default 2048)
カーソル以降にサンプリングされた $state の変化を、変更前後の値つきで返します。返された `cursor` を次の呼び出しの `since` に渡します。
`reset: true` はカーソルが古く、バッファ全体(最新 500 件)を返したという意味です。大きな値はサイズの要約に置き換わります。時刻は検出した時刻です。
get_capture_info—
データセットごとに、DevTools が保持している件数とアプリが報告した件数、選択の方針、理由別の破棄件数を返します。
上限で切られたデータから結論を出す前に確認してください。
パフォーマンスの問題
レンダー、リアクティビティ、load 関数、フレームレートをまたいだ問題を順位付きで返します。
list_performance_issuesavgRenderTimeMs?, renderCount?, loadDurationMs?, fpsDropThreshold?, effectMaxDeps? (thresholds)
すべての指標を横断して問題を順位付きで返します。各問題は次に呼ぶツールを `suggestedTool` で示します。
アプリ全体のリアクティブグラフを読みます(上限 5000 ノード / 20000 エッジ)。
get_component_hotspotstopN?: 1–200 (default 20)
合計レンダー時間の多いコンポーネントを、レンダー回数と 1 回あたりの平均とともに返します。
get_render_profilefile: string (substring)
ファイル名に `file` を含むコンポーネントのレンダープロファイル。
get_reactive_graph_problemseffectMaxDeps?: number
依存の多すぎる effect、まだ一度も評価されていない derived、孤立したノード(追跡している依存も読み手もないもの。マークアップからの読み取りは読み手に数えます)を、グラフ全体ではなく分類として返します。
アプリ全体のリアクティブグラフを読みます(上限 5000 ノード / 20000 エッジ)。
get_load_waterfallroute?: string
SvelteKit の load プロファイルをルートごとに、時間とデータサイズつきで返します。
get_fps_dropsthreshold?: 1–120 (default 40), sinceMs?: number
しきい値を下回ったフレームレートのサンプル。
プロジェクトの情報
静的解析と実行中のページから、アプリの構成を返します。
get_project_info—
パッケージ名とバージョン、Svelte / SvelteKit / Vite のバージョン、依存関係の一覧。
get_routes—
静的解析による SvelteKit のルートツリー。
get_live_componentsincludeMeta?: boolean, limit?: 1–50000
ブラウザにマウントされているコンポーネントインスタンス(親が先)。includeMeta 付きでは `{ epoch, total, captured, truncated, components }` を返し、既定で 1000 件までです。
コンポーネント id はその epoch(1 回のページ読み込み)の中でだけ有効です。
get_component_relations—
.svelte コンポーネント間の静的な import 関係。
計測セッション
変更の前後を計測して比較します。
start_sessionlabel: string, persist?: boolean
ラベルを付けて指標の記録を始めます。同時に有効なセッションは 1 つです。
end_sessionkeep?: "memory" | "disk" | "discard" (default "memory")
有効なセッションを終了し、その差分を返します。
"disk" はプロジェクトの node_modules/.vite-devtools-svelte/sessions/ に書き込みます。
compare_sessionsa: session id, b: session id
終了した 2 つのセッションのレンダー・load・フレームレートの指標を比較します。各項目に判定(improved / regressed / unchanged)が付きます。
list_sessions—
メモリとディスクにあるセッションを新しい順に返します。
load_sessionid: session id
セッションの記録全体(終了後は差分を含む)。
delete_sessionid: session id
セッションをメモリとディスクから削除します。
開発サーバー(stdio のみ)
vite-devtools-svelte mcp が追加します。上のすべてのツールが server?: id from list_dev_servers, root or package name も受け取ります。必要なのは複数の開発サーバーが該当するときだけです。
list_dev_servers—
このマシンでプラグイン付きで動いている開発サーバー(id、パッケージ名、ルート、URL、起動時刻)と、`server` を省略したときに他のツールが使うサーバーを返します。
VITE_DEVTOOLS_SVELTE_URL を設定しているときは `override` にその接続先が入り、一覧のどのサーバーも既定になりません。
変更を計測する
start_session でセッションを始めてアプリを操作し、end_session で終了します。変更後にも同じことをして、compare_sessions で比較します。比較の各項目には判定(improved / regressed / unchanged)が付きます。
セッションは開発サーバーが動いている間メモリに保持されます。end_session に keep: "disk" を指定すると、プロジェクトの node_modules/.vite-devtools-svelte/sessions/ に書き込まれます。
回答がカバーする範囲
- サンプリング。 state は 200 ms ごとに確認され、1 回のサンプル内の複数回の書き込みは 1 回と数えます。回数は総数や発生率ではありません。
- コンポーネントとモジュールの state。 コンポーネントの初期化中に作られた state と、
.svelte.js/.svelte.tsモジュールの共有 state を追跡します。それ以外の場所(イベントハンドラーの中など)で作られた state は対象外です。 - 「影響しうる」であって「原因」ではない。 エッジは現在の依存関係です。どの書き込みが値を変えたかは記録しません。
- 表示されない依存関係があります。 DevTools が追跡していない
state(SvelteKit のページの state など、
node_modulesで作られたもの)の読み取りにはエッジがなく、そのノードのuntrackedDepsに数えられます。 - グラフ内の値は要約。 オブジェクトや配列は
(object)、[n]、{n}と表示されます。タイムラインにはmaxValueCharsまでの値が含まれます。 - signal ごとの履歴はありません。 タイムラインはすべての signal をまとめて、サンプリングされた最新 500 件の変化を保持します。
- 上限。 グラフは 5000 ノード・20000
エッジで打ち切られ、そのことを明示します(
truncated、total、edgesOmitted)。get_capture_infoが何をなぜ落としたかを報告します。 - 1 回のページ読み込み。 コンポーネント id は 1 つの epoch
の中でだけ有効です。回答は最大 1 秒間キャッシュから返ることがあり、
computedAtが計算時刻を示します。
非常に大きなアプリでの性能は計測していません。対応できる規模は約束していません。
トラブルシューティング
403 Forbidden- HTTP で接続している場合: トークンがないか、以前の起動のものです。
~/.cache/vite-devtools-svelte/servers/にある開発サーバーのファイルから読み直してください。 No running dev server for …- Claude Code
を動かしているプロジェクトの開発サーバーを起動するか、回答に並んだ開発サーバーのどれかを
serverで指定してください。回答に、インストールされているバージョンは開発サーバーの存在を知らせないとあれば、0.10.0 以降に上げてください。コンテナ、別のマシン、ミドルウェアモードでは環境変数を設定してください。 The dev server at … did not answer- 開発サーバーが止まっているか、
VITE_DEVTOOLS_SVELTE_URLを使っている場合は URL かトークンが間違っています。トークンは起動のたびに変わります。 VITE_DEVTOOLS_SVELTE_URL is set without VITE_DEVTOOLS_SVELTE_TOKEN- 両方を設定するか、どちらも設定しないでください。
staleReason: "no-runtime"の空の回答- アプリのページが接続されていません。ブラウザでアプリを開いてから呼び直してください。
staleReason: "timeout"- アプリのページが 1 秒以内に応答しませんでした。回答は前回のもの(その
computedAtつき)か空です。呼び直してください。 staleReason: "epoch-changed"- ページがリロードされました。
includeMeta: trueでget_live_componentsを呼び、新しい id と epoch を取得してください。 componentId requires epoch- 同じ
get_live_componentsの回答に含まれる epoch を渡してください。 - コンポーネントやリアクティブノードが出てこない
componentTrackingがfalseになっていないこと、vite.config.tsでプラグインがsveltekit()より前にあることを確認してください。- アプリのタブが複数ある
- 回答は最後に報告したページに従います。他のタブは閉じてください。
セキュリティ
- エンドポイントは開発サーバーにだけ存在します。本番ビルドには含まれません。
- すべてのリクエストにトークンが必要です。トークンは起動ごとにランダムで、自分のユーザーだけが読めるファイル(
~/.cache/vite-devtools-svelte/servers/)に置かれます。パスワードと同じように扱い、コミットしないでください。 - トークンはパネルのブラウザでのサインイン(ワンタイムコード)とは別物です。MCP クライアントはローカルのプロセスなのでブラウザの origin は確認されず、トークンだけが関門です。
get_state_timelineは実行中のアプリの実際の state の値を返すので、エージェントにも見えます。開発中の state に秘密情報を入れないか、このツールを使わないでください。- 開発サーバーがネットワークで待ち受けている場合(
--host)、エンドポイントも同様です。localhost を推奨します。 - セッションがディスクに書かれるのは
persistかkeep: "disk"を指定したときだけで、プロジェクトのnode_modules/以下です。
バージョンと資料
- vite-devtools-svelte
vite-devtools-svelte mcpとこのガイドは ≥ 0.10.0。4 つのリアクティビティツールは 0.4.0 で追加されました- Vite
- ≥ 8.3.5
- Svelte
- ≥ 5.46.4(runes モード)。plain Svelte と SvelteKit 3 を CI でテストしています
- MCP
- Streamable HTTP、ステートレス、JSON 応答。CI はプレーンな HTTP(
initialize、tools/list、tools/call)でエンドポイントを呼んでいます。 - 資料
- 動画による解説はまだありません。実際の回答例とスクリーンショット(CI で記録)は英語の MCP ガイドにあります。