§ mcp · 日本語クイックスタート 20 tools

MCP クイックスタート

開発サーバーは Model Context Protocol にも対応しています。Claude Code などのコーディングエージェントが、パネルと同じレンダー・リアクティビティ・load・フレームレートのデータを読めます。どの回答も、自分が何をカバーしているかを明示します。

このページは vite-devtools-svelte ≥ 0.10.0 を対象にした、英語の MCP ガイドの要約です。内容が食い違う場合は英語版が正です。実際の回答例(JSON)とスクリーンショットは英語版にあります。先に Getting Started でプラグインを設定してください。

01

これは何か

vite dev の実行中、プラグインは /__svelte-devtools/mcp に MCP エンドポイント(Streamable HTTP)を提供します。エージェントは通常、各呼び出しを中継する小さな stdio サーバー vite-devtools-svelte mcp を通してツールを呼び、パネルに表示される内容を読みます: 活発なコンポーネント、1 つのインスタンスのリアクティブグラフ、サンプリングされた state の変化、レンダープロファイル、load 関数、フレームレート。変更の前後を比べる計測セッションも実行できます。

アプリのコードや state を変更するツールはありません。起きることは 2 つです: 呼び出しのたびにページ内のランタイムが約 1 分間サンプリングを続けること、そしてセッション系のツールが計測セッションを保持すること(メモリ内。ディスクには指定したときだけ書き込み、delete_session で削除できます)。実行時のデータはブラウザで開いているアプリのページから来るので、エージェントの作業中はアプリを開いたままにしてください。

02

Claude Code に接続する

プロジェクトごとに 1 回、MCP サーバーを登録します。開発サーバーも起動時にこのコマンドを表示します:

bash bash
claude mcp add svelte-devtools -- npx @sveltejs/vite-devtools-svelte mcp

vite-devtools-svelte mcp は stdio で動き、カレントディレクトリのプロジェクトで動いている開発サーバーに各呼び出しを中継します。開発サーバーとそのポート、トークンは自分で見つけるので、再起動やポートの変更があっても登録し直す必要はありません。開発サーバーが動いていないときは、ツールが起動のしかたを返します。

動いている開発サーバーは ~/.cache/vite-devtools-svelte/servers/ に 1 つずつファイルを書いて自分の存在を知らせます($XDG_CACHE_HOME があればその下、Windows では %LOCALAPPDATA% の下)。使われるのは同じマシンの開発サーバーだけです。

Svelte のドキュメントとコードチェック

ドキュメントと svelte-autofixer は公式の Svelte MCP サーバーが提供します。このサーバーは、公式サーバーが設定されていればそちらを使うよう AI に指示するので、あわせて追加してください:

bash bash
claude mcp add svelte -- npx -y @sveltejs/mcp

コマンドの代わりにプロジェクトのファイルを使う

claude mcp add は自分だけにサーバーを登録します(local スコープ)。プロジェクトの .mcp.json はプロジェクトを開く全員と共有されます(project スコープ)。トークンを含まないので、コミットしてかまいません:

.mcp.json json
{
  "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 で応答します。手動で確認するには:

bash bash
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 の場合:

bash bash
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 と同じ方法):
server.js 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?.();

聞いてみる

たとえばアプリのカートページを開いた状態で:

prompt text
/cart で税率を変えるとカートの合計がおかしい。
svelte-devtools MCP サーバーを使って、活発なコンポーネントを探し、
ReactivePriceChart のインスタンスを見て、grandTotal に影響しうる state と、
税率を編集したときに何が変わったかを教えて。

エージェントは通常 get_reactive_summary か list_performance_issues から始め、回答に含まれるヒントをたどります。

03

基本の流れ

大きなアプリでも回答を小さく保つ順序です。各ステップの実際の回答は英語版の Walkthroughにあります(合成データのサンプルアプリ examples/sample-app(現 examples/kit-shop)で CI が記録したもの)。

  1. get_reactive_summary — まず全体の活発さを見ます。グラフは取得しないので、大きなアプリでも回答は小さく収まります。回数は各インスタンスがマウントされてからの累計で、lastActiveAt が最後に動いた時刻を示します。
  2. get_live_components — includeMeta: true で、インスタンスの id とその epoch(ページ読み込み)を一緒に取得します。id はページを読み込むたびに振り直されます。
  3. get_reactive_scope — componentId と epoch を渡して、1 つのインスタンスのノードと直接の隣接ノードを見ます。エッジは「影響しうる」(現在の依存関係)という意味で、変化の原因ではありません。
  4. get_state_timeline — 最初はカーソルなしで呼び(reset: true)、返された cursor を保存します。アプリで値を変えたあと、cursor を since に渡すと新しい変化だけが返ります。
  5. get_capture_info — 上限で切られたデータから結論を出す前に、DevTools が保持している量とアプリが報告した量を確認します。total が null の場合は不明という意味です。

ページをリロードすると、古い epoch のままの componentId は別のインスタンスとして推測されず、staleReason: "epoch-changed" の空の回答になります。get_live_components で新しい id を取得し直してください。

04

20 のツール

入力は ? が付いていないもの以外すべて省略できます。

開発サーバーのエンドポイントにあるのは以下の 20 のツールです。vite-devtools-svelte mcp は list_dev_servers を追加し、各ツールに server? の入力を加えます(最後のグループを参照)。

リアクティビティ(範囲を限定して取得)

0.4.0 で追加。どの回答も、対象範囲・サンプリング・上限・ページ読み込み(epoch)・古いデータかどうかを明示します。大きなアプリではここから始めてください。

get_reactive_summary

topK?: 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_scope

componentId?: 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_timeline

since?: cursor, limit?: 1–500 (default 100), maxValueChars?: 16–32768 (default 2048)

カーソル以降にサンプリングされた $state の変化を、変更前後の値つきで返します。返された `cursor` を次の呼び出しの `since` に渡します。

`reset: true` はカーソルが古く、バッファ全体(最新 500 件)を返したという意味です。大きな値はサイズの要約に置き換わります。時刻は検出した時刻です。

get_capture_info

—

データセットごとに、DevTools が保持している件数とアプリが報告した件数、選択の方針、理由別の破棄件数を返します。

上限で切られたデータから結論を出す前に確認してください。

パフォーマンスの問題

レンダー、リアクティビティ、load 関数、フレームレートをまたいだ問題を順位付きで返します。

list_performance_issues

avgRenderTimeMs?, renderCount?, loadDurationMs?, fpsDropThreshold?, effectMaxDeps? (thresholds)

すべての指標を横断して問題を順位付きで返します。各問題は次に呼ぶツールを `suggestedTool` で示します。

アプリ全体のリアクティブグラフを読みます(上限 5000 ノード / 20000 エッジ)。

get_component_hotspots

topN?: 1–200 (default 20)

合計レンダー時間の多いコンポーネントを、レンダー回数と 1 回あたりの平均とともに返します。

get_render_profile

file: string (substring)

ファイル名に `file` を含むコンポーネントのレンダープロファイル。

get_reactive_graph_problems

effectMaxDeps?: number

依存の多すぎる effect、まだ一度も評価されていない derived、孤立したノード(追跡している依存も読み手もないもの。マークアップからの読み取りは読み手に数えます)を、グラフ全体ではなく分類として返します。

アプリ全体のリアクティブグラフを読みます(上限 5000 ノード / 20000 エッジ)。

get_load_waterfall

route?: string

SvelteKit の load プロファイルをルートごとに、時間とデータサイズつきで返します。

get_fps_drops

threshold?: 1–120 (default 40), sinceMs?: number

しきい値を下回ったフレームレートのサンプル。

プロジェクトの情報

静的解析と実行中のページから、アプリの構成を返します。

get_project_info

—

パッケージ名とバージョン、Svelte / SvelteKit / Vite のバージョン、依存関係の一覧。

get_routes

—

静的解析による SvelteKit のルートツリー。

get_live_components

includeMeta?: boolean, limit?: 1–50000

ブラウザにマウントされているコンポーネントインスタンス(親が先)。includeMeta 付きでは `{ epoch, total, captured, truncated, components }` を返し、既定で 1000 件までです。

コンポーネント id はその epoch(1 回のページ読み込み)の中でだけ有効です。

get_component_relations

—

.svelte コンポーネント間の静的な import 関係。

計測セッション

変更の前後を計測して比較します。

start_session

label: string, persist?: boolean

ラベルを付けて指標の記録を始めます。同時に有効なセッションは 1 つです。

end_session

keep?: "memory" | "disk" | "discard" (default "memory")

有効なセッションを終了し、その差分を返します。

"disk" はプロジェクトの node_modules/.vite-devtools-svelte/sessions/ に書き込みます。

compare_sessions

a: session id, b: session id

終了した 2 つのセッションのレンダー・load・フレームレートの指標を比較します。各項目に判定(improved / regressed / unchanged)が付きます。

list_sessions

—

メモリとディスクにあるセッションを新しい順に返します。

load_session

id: session id

セッションの記録全体(終了後は差分を含む)。

delete_session

id: 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` にその接続先が入り、一覧のどのサーバーも既定になりません。

05

変更を計測する

start_session でセッションを始めてアプリを操作し、end_session で終了します。変更後にも同じことをして、compare_sessions で比較します。比較の各項目には判定(improved / regressed / unchanged)が付きます。

セッションは開発サーバーが動いている間メモリに保持されます。end_session に keep: "disk" を指定すると、プロジェクトの node_modules/.vite-devtools-svelte/sessions/ に書き込まれます。

06

回答がカバーする範囲

  • サンプリング。 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 が計算時刻を示します。

非常に大きなアプリでの性能は計測していません。対応できる規模は約束していません。

07

トラブルシューティング

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() より前にあることを確認してください。
アプリのタブが複数ある
回答は最後に報告したページに従います。他のタブは閉じてください。
08

セキュリティ

  • エンドポイントは開発サーバーにだけ存在します。本番ビルドには含まれません。
  • すべてのリクエストにトークンが必要です。トークンは起動ごとにランダムで、自分のユーザーだけが読めるファイル(~/.cache/vite-devtools-svelte/servers/)に置かれます。パスワードと同じように扱い、コミットしないでください。
  • トークンはパネルのブラウザでのサインイン(ワンタイムコード)とは別物です。MCP クライアントはローカルのプロセスなのでブラウザの origin は確認されず、トークンだけが関門です。
  • get_state_timeline は実行中のアプリの実際の state の値を返すので、エージェントにも見えます。開発中の state に秘密情報を入れないか、このツールを使わないでください。
  • 開発サーバーがネットワークで待ち受けている場合(--host)、エンドポイントも同様です。localhost を推奨します。
  • セッションがディスクに書かれるのは persist か keep: "disk" を指定したときだけで、プロジェクトの node_modules/ 以下です。
09

バージョンと資料

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 ガイドにあります。

次に読む