matlab-debugging

MCP ツールを使った MATLAB コードの調査とデバッグ

MCP ツールを通じて、実行中の MATLAB セッションを利用できます。エラーのデバッグ、動作の把握、MATLAB コードの仕組みに関する質問への回答など、コードを積極的に調査するために使用してください。コードだけから推測するのは避けてください。

使用する場合

• ユーザーが MATLAB のエラーメッセージや予期しない結果に遭遇した場合
• ユーザーがブレークポイントを設定したり、変数の状態を調べたりしたい場合
• 関数が誤った出力を生成する原因を追跡する場合
• NaN／Inf 値が予期せず現れる場合
• MATLAB MCP ツールがエラーや例外を返した場合 — 実行時エラー、構文エラー、未定義の関数／変数エラー、テストの失敗などを含みます
• ユーザーが「MATLAB コードが動かないのはなぜですか」「デバッグを手伝ってください」と尋ねたり、MATLAB のスタックトレースを共有したりした場合

使用しない場合

• 実行時の問題がないコード品質レビュー — 代わりに matlab-reviewing-code を使用してください
• パフォーマンスのプロファイリング — パフォーマンス最適化ワークフローを使用してください
• 正しさを確認するテストの作成 — 代わりに matlab-testing を使用してください
• 特定のバグがなく、MATLAB API や言語機能を理解する場合

静的解析と実行時デバッグ

すべての問題で、実行中の MATLAB セッションが必要になるわけではありません。適切な方法を選んでください。

• 静的解析で十分な場合：構文エラー、未使用の変数、明らかなロジックの誤り、またはソースコードを読むだけでわかる問題。Read ツールと check_matlab_code を使用してください。
• 実行時デバッグが必要な場合：
  • エラーが実際のデータ値、型、または次元に依存する
  • コードに問題がないように見えるのに、出力が誤っている
  • コードに問題がないように見えるのに、ユーザーが「動かない」と言っている — 実際のデータを確認してください
  • 実行中の特定の時点で変数に何が格納されているかを知る必要がある

判断に迷ったら、まず静的解析を行ってください。ソースだけでは根本原因を特定できない場合に、実行時デバッグに進んでください。

MATLAB エラー発生時の自動トリガー

MATLAB MCP ツールがエラー（実行時エラー、構文エラー、未定義の関数／変数、次元の不一致、アサーションの失敗など）を返した場合、黙って先に進んだり、修正方法を推測したりしないでください。代わりに、次の手順に従ってください。

1. エラーを認識する — MCP ツールの出力にある Error using ...、Undefined function or variable、Index exceeds ...、Error in ... などのパターン、MATLAB のスタックトレース、テストの失敗を確認します。
2. ユーザーに許可を求める — 調査を始める前に、次のように提案します。

   「MATLAB エラーに気付きました：<brief error summary>。matlab-debugging スキルを使って、変数の確認、呼び出しスタックの追跡、根本原因の特定を行えます。調査してもよろしいですか？」

3. 確認を得てから進める — ユーザーが同意したら、以下の調査ワークフローに従います。

この手順は、ユーザーがコードを実行してエラーが発生した場合にも、ユーザーに代わってコードを実行した際（修正の検証やテストの実行など）にエラーが発生した場合にも適用されます。

利用可能なツール

ツール	用途
mcp__matlab__run_matlab_file	.m スクリプトの実行 — ユーザーのスクリプトの実行と修正の検証には、こちらを優先してください
mcp__matlab__evaluate_matlab_code	簡単な診断：変数の確認、式の評価、小さなコード片のテスト
mcp__matlab__check_matlab_code	.m ファイルの静的解析（警告、未使用の変数、潜在的な問題）
mcp__matlab__run_matlab_test_file	MATLAB テストファイルの実行
mcp__matlab__detect_matlab_toolboxes	インストール済みツールボックスの一覧表示 — 「Undefined function」がツールボックスの不足に起因する可能性がある場合に使用

スクリプトの実行には evaluate_matlab_code より run_matlab_file を優先してください。 evaluate_matlab_code は、短い診断コマンド（変数の確認や式のテストなど）にのみ使用してください。スクリプト全体をインラインで再実行するためには使わないでください。

ワークフロー

1. 目的を把握する

ユーザーが何を必要としているかを判断します。

• デバッグ — 実行時エラー、誤った出力、予期しない動作
• 理解 — このコードはどのように動作するのか、この関数は何をするのか
• 調査 — なぜこの変数はこの値なのか、このデータはどこから来るのか
• 探索 — 利用できる関数は何か、このコードベースはどのように構成されているのか

2. MATLAB で情報を収集する

mcp__matlab__evaluate_matlab_code を使用して、診断コマンドを実行します。

ソースコードを読む： ディスク上の .m ファイルには Read ツールを使用します。MATLAB の type や dbtype は使用しないでください。まだ見つかっていないファイルの場所を特定する場合に限り、 MATLAB の which を使用し、シャドーイングの確認には which -all を使用します。

大きなデータをプレビューする： 変数全体を出力するのではなく、 varName(1:min(5,end),:) や head(T) を使用して一部をプレビューします。

実行時デバッグ — まずデスクトップモードを確認します。

ブレークポイントを使用する前に、MATLAB にデスクトップがあるか確認します。

desktop('-inuse')  % true = desktop mode, false = no-desktop

デスクトップモード（desktop('-inuse') が true を返す場合）：

ブレークポイントを使用する標準的な手順に従います。

1. 実行前にブレークポイントを設定します。

   dbstop if error          % Pause on any error
   dbstop if caught error   % Pause on error inside try-catch (silent failures)
   dbstop if warning        % Pause when a warning is issued
   dbstop if naninf         % Pause on NaN or Inf
   dbstop in file at line   % Pause at a specific line
   

2. run_matlab_file でコードを実行します。 MATLAB はブレークポイントで一時停止します。
3. 呼び出しスタックを確認します。

   dbstack                  % See full call stack with file names and line numbers
   

4. whos でスコープ内の内容を確認します。 値を調べる前に、変数名、サイズ、型を確認します。 大きな配列やテーブルの場合は、全体を表示するのではなく、一部 （varName(1:5,:)、head(T)）をプレビューします。
5. フレームを移動し、各スコープの変数を確認します。

   dbup                     % Move up one frame (toward caller)
   dbdown                   % Move back down (toward callee)
   

   dbup／dbdown の後は、変数の確認コマンドはそのフレームのローカルスコープで実行されます。 これを使って、各レベルの入力／出力を確認します。
6. 再開するか終了します。

   dbcont                   % Continue execution to next breakpoint or end
   dbquit                   % Exit debug mode entirely
   dbclear all              % Remove all breakpoints when done
   

注意： MCP 経由の対話的なステップ実行（dbstep）は信頼性がありません。 evaluate_matlab_code の呼び出しごとに別のコマンドとして実行されるため、ステップの状態が 保持されない場合があります。

デスクトップなしモード（desktop('-inuse') が false を返す場合）：

dbstop if error、dbstop if naninf、dbstop if warning、または実行を一時停止する ブレークポイントは使用しないでください。 デスクトップなしモードで一時停止するブレークポイントを使うと、 MCP の評価が無期限に停止します。

代わりに、次の方法を使用します。

1. try-catch ラッパー — 問題のあるコードをラップし、エラーを捕捉して 失敗後の状態を確認します。

   try
       result = suspectFunction(data);
   catch ME
       fprintf('Error: %s\n', ME.message);
       fprintf('In: %s line %d\n', ME.stack(1).name, ME.stack(1).line);
       whos  % Show variables in scope at failure
   end
   

2. トレーサー条件付きブレークポイント — 常に false を返す条件を指定して dbstop を使用します。 これにより、MATLAB が実際には一時停止せず、副作用として値を出力します。トレーサー関数を定義します。

   function out = tracer(val)
       disp(val);
       out = false;
   end
   

   次に、これを呼び出す条件付きブレークポイントを設定します。

   dbstop in myScript at 42 if tracer(myVar)
   

   42 行目が実行されると、MATLAB は tracer(myVar) を評価し、値を出力して false を返します。 実行は一時停止せずに続行されます。 これにより、ソースファイルを変更せずに特定の行の変数を調べられます。 完了したら、トレーサーのブレークポイントを削除します：dbclear all

3. 実行してから確認する — スクリプトの場合は、run_matlab_file で実行してから、 evaluate_matlab_code を使って実行後のワークスペース変数を確認します。 同一セッション内では、ベースワークスペースは MCP 呼び出し間で保持されます。

3. 反復して調査する

ここがデバッグの中心です。状況に応じて判断してください。

• 関連するソースコードを読む — 意図を理解します。
• 失敗行の付近にある変数を確認する
• 部分式を評価する — どの部分で失敗するかを切り分けます。
• 仮説を検証する — MATLAB で小さなコード片を実行します。
• 調査対象を絞る — ワークスペース全体を出力しないでください。問題に関連するものだけを確認します。 スコープ内に変数が 7 つあっても、失敗行で使われているのが 2 つだけなら、その 2 つを確認します。

エラーが MathWorks の組み込み関数内で発生した場合、ほとんどの場合、問題はそれを呼び出した ユーザーのコードにあります。スタックをたどってユーザーコードを確認してください。

4. 診断内容を疑う

ユーザーが説明する問題が、実際の問題と一致しないことがあります。問題だと言われたものを修正する前に、まず自分で確認してください。

• 主張された失敗を直接テストする — ユーザーが ismember または strcmp が動作しないと言う場合は、実際のデータを使って自分で実行してください。多くの場合、処理自体は正常に動作しており、本当の問題はその周辺のロジックにあります。
• コードを疑う前にデータを確認する — データに対する処理が「動作しない」場合は、データを調べてください。型（class）、実際の値（いくつかサンプルを確認）、空白文字（strtrim）、非表示文字（double(str)）、次元（size）を確認します。
• コードの動作とユーザーの説明を照合する — コードを読み、実際にどの変数や列が使われているか確認してください。ユーザーが意図を説明していても、コードは別の処理をしている可能性があります。
• アプローチ自体が間違っていないか検討する — コード自体にバグはなくても、アプローチが不必要に複雑だったり、壊れやすかったりすることがあります。手動ループの代わりにテーブル結合、要素ごとの比較の代わりにベクトル化演算、自作ロジックの代わりに組み込み関数など、MATLAB らしい代替案を提案してください。

よくあるエラー — 最初に確認すること

エラーパターン	診断手順
Undefined function or variable 'X'	which X、exist('X','file')、exist('X','var') を実行し、path を確認します。detect_matlab_toolboxes を使ってツールボックスがインストールされているか確認します
Index exceeds array dimensions / Index exceeds the number of array elements	size(arr) を確認し、インデックス式を調べます。多くの場合、インデックスが1つずれているか、配列が空です
Not enough input arguments	呼び出し元で関数がどのように呼び出されているか、関数内の nargin、関数シグネチャを確認します
Too many input arguments	上記と同様です。呼び出し元から余分な引数が渡されているか、スクリプトを関数として呼び出しています
Matrix dimensions must agree / Dimension mismatch	両方のオペランドについて size(A) と size(B) を確認します。一方が行ベクトルで他方が列ベクトルである場合がよくあります
Subscript indices must either be real positive integers or logicals	インデックス変数を確認します。class(idx)、min(idx) を調べ、0 や負の値、NaN、小数のインデックスがないか確認します
Dot indexing is not supported for variables of this type	class(var) を確認します。通常、構造体ではない値（セル配列、配列、テーブル）のフィールドにアクセスしています
Unable to perform assignment	代入の両辺の class と size を確認します
Out of memory	whos で大きな変数を探し、ループ内で誤って配列が増大していないか確認します
Maximum recursion limit	基底ケースの欠落、または相互再帰の無限ループがないか確認します。エラー発生箇所で dbstack を実行します
NaN の伝播／誤った分岐への進入	デスクトップモードでは、dbstop if naninf を使って NaN が最初に生成された箇所を捕捉します。デスクトップなしモードでは、dbstop in file at line if tracer(suspect) を使って、一時停止せずに値を調べます。NaN との比較（>、<、==）は常に false になるため、if は誤った分岐に気付かないまま進みます。上流をたどり、0/0、Inf-Inf、または入力データ内の NaN を確認します。any(isnan(var)) を使ってテストします。

注意点

• 一時停止するブレークポイントは、デスクトップなしモードではハングします。 desktop('-inuse') が false を返す場合、dbstop if error、dbstop if naninf、dbstop if warning、 および無条件の行ブレークポイントによって、MCP の評価が無期限にハングします。必ず最初にデスクトップモードかどうかを確認してください。デスクトップなしモードでは、代わりにトレーサーの条件付きブレークポイントまたは try-catch ラッパーを使用してください（上記のデスクトップなしモードでの方法を参照）。
• dbstep は MCP 経由では確実に動作しません。 evaluate_matlab_code の呼び出しはそれぞれ別のコマンドであるため、呼び出し間でステップの状態が保持されない場合があります。コードをステップ実行する代わりに、ブレークポイント（dbstop in file at line）を使って特定の場所で一時停止してください。実行フローを追跡するには、一時的な fprintf() 文を挿入するか、try-catch ブロックを使用してください。
• ソースコードを読むために type や dbtype を使用しないでください。 代わりに Read ツールを使用してください。こちらのほうが高速で、MATLAB セッションの出力帯域幅も消費しません。まだ見つけていないファイルの場所を特定する場合に限り、which を使用してください。
• デバッグが終わったら、必ず dbclear all を実行してください。 前のセッションで残ったブレークポイントによって、後続の実行が予期せず一時停止することがあります。
• dbup／dbdown のスコープは呼び出しごとに設定されます。 evaluate_matlab_code を呼び出すたびに現在のフレームに戻ります。dbup と変数の確認は、同じ evaluate_matlab_code 呼び出し内で続けて実行してください：

  dbup; whos; myVar(1:min(5,end),:)
  

  dbup の後に別の evaluate_matlab_code を呼び出すと、元のフレームに戻ります。
• restoredefaultpath は絶対に実行しないでください。 MCP サーバー独自のパッケージが MATLAB のパスから削除され、評価チャネル（mcpEval が見つからない状態）が動作しなくなります。この場合、復旧するには MATLAB を完全に再起動するしかありません。
• ツールボックスは不要です。 このスキルでは、MATLAB 標準のデバッグコマンドのみを使用します。

主な原則

• ツールを使用する — MATLAB のライブセッションを利用できます。コマンドを実行し、状態を確認し、仮説を検証してください。コードを読むだけでデバッグしないでください。
• 対象を絞る — 関連する情報だけを要求してください。すべての変数を出力したり、スタック内のすべてのファイルを読んだりしないでください。
• データを取得する前にサイズを確認する — 変数を表示する前に、必ずその次元を確認してください。変数を確認せずに disp を実行しないでください。
• ユーザーコードに注目する — 組み込み関数で表面化するエラーは、ほとんどの場合、ユーザーコードから渡された不正な入力が原因です。
• 修正する前に読む — 変更を提案する前に、必ず実際のソースコードを読んでください。コードの内容を推測しないでください。
• 修正を検証する — 可能な場合は、修正したコードを MATLAB で実行して確認してください。

---

Copyright 2026 The MathWorks, Inc.

---