weavatrix-refactor

Weavatrix Refactor

Weavatrix エコシステムにおける、明示的なソース書き込みレイヤーです。Core は引き続き読み取り専用です。

エージェントに推測させずに、複数のファイルをまたいでリファクタリングできます。

Weavatrix Refactor は、コーディングエージェント向けのネイティブ MCP サーバーです。リポジトリのグラフを使ってシンボルを見つけ、バイト単位で正確な編集をプレビューし、確証を得られなかった同名の出現箇所をすべて報告します。また、ハッシュに紐づいた明示的な確認の後にのみ書き込みを行います。

重要なのは「AI が単語をリネームできる」ことではありません。書き込み前にエージェントが根拠を得られ、書き込み後に復元可能なトランザクションを利用できることです。

インストール

npm からネイティブバイナリを実行します。

npx -y weavatrix-refactor mcp /absolute/path/to/repository

または、Cargo でインストールします。

cargo install weavatrix-refactor --locked
weavatrix-refactor mcp /absolute/path/to/repository

MCP クライアントから直接起動できます。絶対パスを指定するか、Cursor の ${workspaceFolder} を使ってください。こうすることで、書き込みサーバーがホストプロセスの cwd を参照しなくなります。

{
  "mcpServers": {
    "weavatrix-refactor": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp", "${workspaceFolder}", "--profile=refactor"],
      "env": {"WEAVATRIX_ALLOW_SOURCE_EDITS": "1"}
    }
  }
}

プレビューのみのセッションでは、WEAVATRIX_ALLOW_SOURCE_EDITS を設定しないでください。プレビューは読み取り操作です。ゲートが必要なのは、確認後の適用またはロールバックのみです。Refactor は Core の open_repo を公開しないため、セッション中に対象をひそかに切り替えることはできません。起動時に指定したルートだけが編集対象になります。

プラグインとしてインストールする

リポジトリには、Cursor、Codex、Claude Code、 Grok Build 用のプラグインバンドルも含まれています。このプラグインは拡張機能専用プロファイルを起動するため、Weavatrix Core の読み取り専用メソッド 43 個を重複して定義することなく、Refactor の 11 個のメソッドを追加できます。両方の機能が必要な場合は、Weavatrix プラグインを別途インストールしてください。

同梱のスキルは任意で、リファクタリングを明示的に依頼した場合にのみ有効になります。エントリーポイントは短く保たれており、各メソッドのリファレンスカードは必要になったときだけ読み込まれます。

• Cursor：マーケットプレイスでの承認後、Weavatrix Refactor を検索します。
• Codex：.agents/plugins から Weavatrix/weavatrix-refactor マーケットプレイスを追加し、weavatrix-refactor@weavatrix-refactor を追加します。
• Claude Code：.claude-plugin から同じリポジトリのマーケットプレイスを追加し、weavatrix-refactor@weavatrix-refactor をインストールします。
• Grok Build：grok plugin marketplace add Weavatrix/weavatrix-refactor を実行し、/marketplace を開いてインストールします。

プラグインは WEAVATRIX_ALLOW_SOURCE_EDITS=1 を設定しますが、すべての書き込みには、正確なプレビューに紐づいた、有効期間の短い一度限りのトークンが必要です。

リネームタスクでは、エージェントに必要な 2 つのツールだけを公開します。

weavatrix-refactor mcp /absolute/path/to/repository --profile=rename

rename プロファイルで利用できるのは rename_symbol と rollback_last_apply だけです。関係のないグラフおよびリファクタリングツールは存在せず、呼び出すこともできません。すべての Refactor メソッド 11 個を利用するには、このオプションを省略するか、--profile=refactor を使ってください。カタログを絞ることで、エージェントのコンテキストが繰り返し増えるのを抑えられます。プレビューハッシュ、書き込みゲート、確認トークン、ロールバックのチェックが弱まることはありません。

Weavatrix Core が別の MCP としてすでにインストールされている場合は、Refactor が追加する 11 個のメソッドだけを公開します。

weavatrix-refactor mcp /absolute/path/to/repository --profile=refactor

MCP と list-tools では、マーケットプレイスのプラグインを含め、refactor プロファイルがデフォルトです。以前の full 互換プロファイルは削除され、どちらのコマンドでも拒否されます。Refactor は Core のメソッドを再公開しなくなりました。読み取り専用のリポジトリ情報も必要な場合は、Weavatrix Core を独立した MCP としてインストールしてください。

3 回の呼び出しで安全にファイル間の名前を変更する

2 つのファイルで resolveTarget が宣言されているとします。単独の名前では曖昧なため、サーバーはどちらかを選ばず、正確な ID を返します。

// rename_symbol
{"symbol":"resolveTarget","new_name":"locateTarget","output_format":"json"}

{
  "status": "NOT_FOUND",
  "reason": "the name matches more than one symbol; pass one of the candidate ids",
  "candidates": [
    "symbol:src/core.ts#function:resolveTarget@2:1",
    "symbol:src/shadow.ts#function:resolveTarget@3:1"
  ]
}

意図した ID を指定して再試行します。結果は引き続き読み取り専用です。編集計画、コンテンツハッシュ、証明済みの編集数、そしてバックエンドが推測を拒んだ参照が含まれます。

// rename_symbol
{
  "symbol": "symbol:src/core.ts#function:resolveTarget@2:1",
  "new_name": "locateTarget",
  "output_format": "json"
}

{
  "status": "PLANNED",
  "completeness": "PARTIAL",
  "renamedEdits": 7,
  "uncertainReferences": ["... three named locations ..."],
  "confirmToken": "single-use-token",
  "plan": {"schemaVersion":"weavatrix.edit-plan.v1","files":["..."]}
}

計画を確認した後、同じ入力とトークンを使って同じ操作を繰り返します。

// rename_symbol
{
  "symbol": "symbol:src/core.ts#function:resolveTarget@2:1",
  "new_name": "locateTarget",
  "mode": "apply",
  "confirm_token": "single-use-token",
  "output_format": "json"
}

{"status":"APPLIED"}

この一連の手順は、実際の stdio MCP サーバーに対して実行されます。リポジトリのフィクスチャでは、3 つのファイルにまたがる 7 件の編集が必要です。4 つの誤編集要因（より長い識別子、文字列、コメント、無関係なシャドーイング）を維持し、コンパイルも成功させる必要があります。スコアは 12/12 です。

現在自動化されている内容

11 個のツールが、すべて同じレベルの自動化を提供しているわけではありません。

レベル	ツール	エージェントが受け取るもの
完全なプレビュー／適用ワークフロー	rename_symbol、rename_related_symbols	生成された計画とトークン。その後、同じ操作を繰り返して確定した書き込みを実行
計画の生成	change_signature、edit_symbol、bulk_replace、organize_imports、move_file	バイト単位で正確な編集、またはレビュー用の計画。編集計画のエンベロープが返される場合は、apply_edit_plan を使用
助言	move_symbol、delete_readiness	影響範囲、循環／アーキテクチャ上のリスク、または削除可否の判定。ソースの自動書き込みは行わない
安全性の基盤	apply_edit_plan、rollback_last_apply	編集計画のエンベロープの検証／適用、およびドリフトに安全な復元

Refactor は内部で Rust Weavatrix グラフを証拠として使用しますが、Core のメソッドを公開することはありません。読み取り専用のリポジトリインテリジェンスを利用するには、別途 Weavatrix プラグインをインストールしてください。Refactor MCP が所有する拡張メソッドは、ちょうど 11 個です。--profile=rename は、任意で選択できる、対象を 2 つのメソッドに絞ったワークフローです。

安全性モデルと厳密な制限

• 曖昧な名前が指定された場合は、最初の候補を選ぶのではなく、候補 ID を返して処理を失敗させます。
• PARTIAL は、グラフが計画内の編集を証明したものの、ほかに意味的な参照が存在しないことまでは証明できなかったことを意味します。uncertainReferences に、レビューが必要な箇所が示されます。
• 計画内の各ファイルにはコンテンツハッシュが付与されます。作業ツリーが変更されると、古い座標のまま適用されるのではなく、プレビューが古いものとして扱われます。
• 適用には WEAVATRIX_ALLOW_SOURCE_EDITS=1 と、対象リポジトリおよび再計算された正確な計画に紐付けられた、有効期間の短い使い捨てトークンが必要です。
• rollback_last_apply は、トランザクション後に変更されたファイルを上書きしません。
• 複数ファイルへの書き込みはジャーナルに記録され、クラッシュ後に復旧できます。ただし、無関係なプロセスから観察したときに原子的な操作として見えるわけではありません。別のプロセスが、一時的な中間状態のファイルシステムを観察する場合があります。

適用されるのは、由来が証明された編集だけです。字句解析またはグラフを使うバックエンドは、意図的に言語サーバーより保守的に設計されており、コンパイラーの意味論を完全に扱えるという主張として受け取ってはなりません。

異なるレイヤーを分けた実測ベンチマーク

チェックイン済みの2026年8月のベンチマークでは、同等の敵対的な TypeScript、Rust、Python のフィクスチャを使用しています。それぞれに7つの必須編集、4つのトラップ、ビルド／テストのゲートが含まれています。プロトコルの実行では、o200k_base の初期化、カタログ、リクエスト、レスポンスの正確なトークン数を計測します。エージェントの実行では、固定した gpt-5.6-sol／medium reasoning を使用する Codex CLI が報告した実際の累積使用量を計測します。バイト数による代用や、推定したトークン毎秒への換算は使用していません。

新しい名前変更専用プロファイルでは、9回すべてのプロトコル実行で12/12を維持しながら、固定 MCP コンテキストを9,331トークンから485トークンに削減しました。ガイド付き TypeScript エージェントの A/B テスト結果は次のとおりです。

アーム	正確性	エンドツーエンド時間の中央値	入力トークン数の中央値
素の Codex	12/12 x3	42,602 ms	72,169
Weavatrix 1.0.6 --profile=rename	12/12 x3	48,389 ms	108,155
Weavatrix 1.0.5 の全機能	12/12 x3	58,719 ms	275,784
Serena	12/12 x3	68,728 ms	388,271

エージェントの全マトリックスでは、TypeScript／Rust／Python の27回すべての実行で12/12を達成しました。また、すべての実行が正常に完了し、サニタイズ済み編集チャネルの監査にも合格しました。決定論的なプロトコルのマトリックスでは、言語固有の Serena の欠陥も明らかになりました。推奨される find_symbol → rename_symbol のフローは、TypeScript で3回すべて7/12となりましたが、Rust と Python では合格しました。また、Rust のマクロ呼び出しと、Python の f 文字列／モジュールレベルの呼び出しに関する証拠の修正も検出し、促しました。

この小規模な TypeScript リポジトリでは、素の Codex のほうが、機能を絞ったプロファイルよりも引き続き高速で低コストです。Weavatrix で実証された価値は、書き込み前のプレビュー、不確実性の明示、古くなった計画の拒否、明示的な認可、ロールバックにあり、あらゆる小規模リポジトリでトークンを削減することではありません。

方法論、各言語の中央値、生の結果へのリンク、制限事項の全容を参照してください。

コントラクト

11個の Refactor ツール名、スキーマ、結果状態は、contract/refactor-tools.v1.json で固定されています。すべてのリファクタリング操作はネイティブの Rust で実行されます。ホストは、メソッドをデフォルトのインターフェースで公開せずに、グラフの証拠を取得するため、読み取り専用の weavatrix-rust エンジンを内部で使用します。

バージョン0.1.xでは JavaScript エンジンを使用していました。この系統は引き続き weavatrix-refactor-js として提供され、個別の状態ディレクトリ、トークンストア、ロールバックジャーナルを保持します。

ライセンス

MIT。