Handoff MCP v0.27.0 — プリビルドバイナリ配布で「入れたのに動かない」を解消

Handoff MCP v0.27.0 をリリースしました。今回は機能追加よりもインストール体験が主題です。npm パッケージがプリビルドバイナリ配布に切り替わり、ビルド環境を問わず動くようになりました。

Rust ツールチェーンが不要になりました

これまで npm install -g handoff-mcp-server は、インストール時に手元でソースをビルドしていました。つまり Rust ツールチェーンと C++ リンカが必要で、環境が揃っていなければインストールが失敗していました。

v0.27.0 からは、プラットフォームに合致するバイナリを npm がそのままダウンロードします。コンパイルは発生しません。

WSL は通常の Linux インストールとして動作します。musl/Alpine、FreeBSD、32bit、glibc 2.35 未満といった対象外の環境では、これまで通り cargo install handoff-mcp でソースからビルドしてください。自前でビルドしたバイナリを使いたい場合は HANDOFF_MCP_BINARY_PATH で npm ラッパーの参照先を指定できます。

npm v12 で「静かに壊れていた」問題の解消

これが今回の最重要修正です。

npm v12 はパッケージの install script を既定で無効化しました。従来の Handoff MCP はまさにその install script でビルドを行っていたため、インストールは成功したように見えるのに、CLI を起動すると "binary not found" で落ちるという状態になっていました。エラーが出ないぶん原因が分かりにくい、たちの悪い壊れ方です。

v0.27.0 ではインストール時にスクリプトを一切実行しません。実行されないスクリプトがそもそも存在しないため、スキップされて壊れることもありません。なお --omit=optional を付けるとバイナリ本体がスキップされますが、この場合は沈黙せず原因を明示して失敗します。

副次的な効果として、インストール時に任意のコードが走らなくなり、サプライチェーン攻撃の面が一つ消えました。

Windows サポート

npm install -g handoff-mcp-server が Windows で動作するようになりました。従来は EBADPLATFORM で失敗していたものです。Linux・macOS・WSL への影響はありません。

Windows 環境に固有の不具合もあわせて修正しています。

• config.toml の ~/ パス展開 — scan_dirs の ~/ 始まりのエントリが展開されず、handoff_dashboard と handoff_refer が設定済みディレクトリを黙って全てスキップしていました。POSIX の HOME しか参照していなかったのが原因です。USERPROFILE をフォールバックとして使うようにし、~\ 表記も受け付けます。
• 書き込みの一時的な失敗 — VSCode 拡張がファイルを開いた状態でタスクやセッションを保存すると、権限エラーで失敗することがありました。短時間のリトライを行うようにしています。

同一ファイルへの並行書き込み修正

2つのスレッドが同じ .handoff/ ファイルへ同時に書き込むと、一時ファイル名が衝突して互いのデータを破壊する可能性がありました。一時ファイル名を書き込みごとに一意化しています。

macOS arm64 の署名

macOS arm64 向けバイナリには ad-hoc 署名を施しています。未署名バイナリが Killed: 9 で起動できない問題は発生しません。

インストール・アップデート

npx handoff-mcp-server@latest

Claude Code のプラグインとして使っている場合:

/plugin install alphaelements/handoff-mcp

Handoff の実績ページを見る