mcpField
F
FailTrace

FailTrace

ローカル
github.com開発ツール08 週間前に更新
リポジトリ公式サイト

FailTrace について

FailTraceは、コーディングエージェントによる断続的なテスト失敗の調査に使う、ローカルのコマンドラインツール兼MCPサーバーです。失敗時の試行結果を保存し、修正案を同じ条件で検証できます。

主な機能

  1. 01テストを反復して失敗基準を保存
  2. 02正常時と失敗時の試行を比較
  3. 03bisectでGit履歴を調査
  4. 04再現入力を縮小
  5. 05保存済み基準でパッチを検証
  6. 06調査結果を再生可能な形で保存

活用シーン

  1. 01編集前に不安定なテストを記録
  2. 02元の失敗を基準に修正案を確認
  3. 03回帰に関係するGit変更を特定
  4. 04入力を小さな再現例に縮小

MCP 対応

ローカルstdio MCPサーバーはCLIと同じエンジンを使う7つのツールを提供し、反復、比較、回帰検索、入力縮小、検証、再生に対応します。MCPクライアントは保存済みの試行結果やログも取得できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
  "mcpServers": {
    "lbarimi-failtrace": {
      "command": "npx",
      "args": [
        "-y",
        "failtrace"
      ]
    }
  }
}
起動コマンドnpx -y failtrace

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npmfailtrace1.5.0

ツール

7

掲載時のツール一覧 · 3 週間前に更新

パラメーター型必須説明
cwdstringいいえ作業ディレクトリです。相対パスはサーバーの作業ディレクトリを基準に解決されます。
envobjectいいえ環境変数を明示的に上書きします。null を指定すると、継承した変数の設定が解除されます。
argsarrayいいえ実行ファイル引数をリテラルとして指定すると（空の配列を含む）、シェル解析が無効になります。Minimize は、引数全体が `{input}` の場合に限り、各候補パスで置き換えます。Windows の .cmd/.bat シムにはシェルモードが必要です。
repeatintegerいいえ
commandstringはいargs がない場合はシェルコマンド、ある場合は実行ファイルです。コマンドと引数の合計は 64 KiB 以内です。実行にはお使いのローカル権限が使用されます。
predicateanyいいえ
timeoutMsintegerいいえ
captureEnvarrayいいえ選択したこれらの環境変数のみがメタデータに記録されます。
concurrencyintegerいいえ同時実行する試行の上限です。既定値は 1、最大値は 64 です。ポート、ファイル、データベースの共有やリソース競合により、失敗確率が変わることがあります。
artifactsDirstringいいえ
captureContextobjectいいえ検証用に、宣言された通常の入力／セットアップ／ソースファイルの識別情報を取得します。ソースファイルを指定すると対象はファイルのみになり、指定しない場合は Git の識別情報を取得します。関連する変数名には別途 captureEnv を使用してください。
captureContext.inputFilesarrayいいえ
captureContext.setupFilesarrayいいえ
captureContext.sourceFilesarrayいいえ
maxOutputBytesintegerいいえ試行ごとの stdout／stderr 合計バイト数の上限です。既定値は 16 MiB です。上限に達した場合、結果は判定不能です。
maxTotalOutputBytesintegerいいえすべての候補を含む実験全体の出力バイト数の上限です。既定値は 256 MiB です。
executionRequirementobjectいいえ意図したチェックの実行後に出力する任意のチェックポイントです。証拠がない場合、分類／検証は判定不能になります。Verify はベースラインからこれを継承します。
executionRequirement.streamenumはいstdout | stderr
executionRequirement.containsstringはい

詳細

FailTrace

失敗を再現し、修正を確認します。

テストが断続的に失敗します。コーディングエージェントがコードを変更します。再試行で一度成功しても、判断に迷います。

FailTrace は同じチェックを繰り返し、失敗するベースラインを保存して、提案された修正をそれと照合します。CLI または MCP ツールを使って試行結果や、より小さな再現ケース、パッチを適用する前にエージェントが調べられる証拠を取得できます。

CI License: MIT

ローカルで実行できます。AI API、アカウント、テレメトリーは不要です。既存のテストランナーとアサーションをそのまま使用できます。

クイックスタート

Node.js 22.12+ と npmを使って、任意の作業ディレクトリで次を実行します。

npx --yes failtrace demo

FailTrace のデモ：失敗を取得し、入力を縮小し、無関係なクラッシュを却下して、パッチを確認します

静的な操作ガイド · 静的なポスター · デモガイド

このデモでは、6 つの入力項目を ["BUG"] に縮小し、別の原因によるクラッシュを起こすパッチを却下して、動作するパッチを確認します。証拠を .failtrace/ に保存し、リプレイ用のコマンドを出力します。

コーディングエージェント向け

クライアントの設定から、ローカルの stdio MCP サーバーに接続します。

npx --yes [email protected] mcp --cwd "/absolute/path/to/your/project"

MCP の設定をコピーして、接続を確認する →

クライアントがこのコマンドを起動します。ターミナルで単独実行すると、MCP リクエストを待機します。ガイドには Windows の設定方法も記載されています。

次に、エージェントにこう依頼します。

編集する前に、FailTrace を使ってこのテストの失敗を取得してください。正確なテストまたは失敗メッセージを選び、上限を設定したベースラインを保存して、該当する試行を確認してください。変更後はそのベースラインと照合して検証し、無関係なエラーや不完全な証拠があれば説明してください。

7 つの MCP ツールは、CLI と同じ Core エンジンを共有しています。繰り返し、比較、回帰検索、最小化、検証、リプレイを通じて、失敗の特徴と調査の証拠を保持します。エージェントはコマンドを再実行せずに、保存された試行やログのページを取得できます。シェルを使えるエージェントは、--json を指定して CLI を使うこともできます。

MCP ワークフロー：対象を取得し、保存された stderr を調べ、宣言されたパッチを検証します

エージェントはパッチを確認する前に、保存された失敗を調べられます。

既存の単体テストを再確認する

正確な NUnit または Unity テストを修正まで追跡します。 試行ごとに、新しい NUnit 3 レポートが生成されます。テストが見つからない場合やスキップされた場合、または無関係な失敗がある場合は、結論を出せない状態のままです。そのため、エージェントが選択したテストの成功を示す証拠として、それらを受け入れることはありません。

テストを接続するか、EditMode の元の例を試す →

NUnit のサポートは、CLI と MCP を通じて 1.3.0 で追加されました。Unity の検証例として、Windows の EditMode を紹介しています。

NUnit の証拠：失敗するベースライン、成功する候補、結論を出せない状態に保たれるスキップ済みテスト

選択したテストは変わりません。スキップされたテストのレポートは、テスト成功とは見なされません。

自分の失敗ケースで使う

プロジェクトで、コマンドとメッセージを独自のものに置き換えてください。

npx --yes [email protected] run "npm test -- checkout" --repeat 20 --stderr-contains "checkout failed" --capture-context

Git プロジェクトで、編集する前に実行してください。--capture-context は Verify 用にソースの識別情報を記録します。Git の外では、--context-source でファイルを選択してください。各試行の出力が保存され、終了コード 1 は対象を正常に捕捉できたことを示す場合があります。編集してパッチを検証する →

次に知りたいことコマンド
この失敗はどのくらいの頻度で発生しますか？run
正常な試行と失敗する試行では何が異なりますか？compare
どの Git 変更が原因ですか？bisect
再現に十分な入力は何ですか？minimize
提案した修正の後に何が起きましたか？verify
この調査を再現するにはどうすればよいですか？bundle

コマンドリファレンス · 引数をそのまま実行する方法 · 再利用可能なプロジェクトスクリプト

再生用エントリーポイントとともにパッケージ化された縮小入力で、対象の失敗を再現できます

このデモのバンドルは、元の失敗を終了コード 1 で再現します。ソース、入力、再生用の内容を一緒に保管してください。独自の調査をパッケージ化する際は、対象の前提条件を用意してください。

結果から確認できること

FailTrace は、選択した設定に基づく観測結果を報告します。Verify では、対象が観測されたケース、対象が観測されなかった正常なサンプル、結論が出ない証拠を区別します。Bisect はサンプリングされた最初の親の境界を報告します。最小化では結果を再確認しますが、入力が可能な限り小さいことは保証しません。

このデモは、制御された例の結果を示すものであり、パフォーマンス測定ではありません。サンプルが成功しても、バグが解消された証明にはなりません。

コマンドはユーザーの権限で実行され、プロセスのクリーンアップはベストエフォートです。保持される stdout/stderr の既定の上限は、試行ごとに 16 MiB、実行または bisect/最小化ごとに 256 MiB です。過去の調査は個別に蓄積されます。共有する前に、ログ、コマンド、選択したファイルを確認してください。バンドルを利用するには、対象の依存関係とセットアップも引き続き必要です。

結果と終了コードのリファレンス · リソース制限 · 保存データ一覧 · バンドルガイド

利用方法とコントリビューション

クイックスタートでは npm の最新リリースを使用します。検証済みのバージョンは 1.5.0 です。MCP の設定と再現可能なインストール例では、このバージョンが正確に固定されています：インストール方法、GitHub リリース、MCP Registry のエントリー。

バージョン 1.5.0 の追加内容：短い run リファレンス、Verify の準備状況と次の手順のガイダンス、断続的な最小化に関するガイダンスです。変更履歴を参照してください。

ドキュメント：次のタスクを選ぶ →

開発手順 · 互換性 · ロードマップ · サードパーティに関する通知

コメント

Markdown 対応

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。