Sunstone Weave: Local Semantic Code Search

blackwindow-weave-mcp

お使いのマシン上のフォルダーを対象に、あらゆる MCP クライアントからセマンティック検索を行えます。サーバーはソースコードとドキュメントをパッセージに分割し、33M パラメーターのコード検索エンコーダーである Motherlode を使って CPU 上で埋め込みを生成し、「ペアリング行はどこで url、key、name に解析されますか」といった質問に、ファイルパス、行範囲、パッセージそのものを添えて回答します。

ネットワークリクエストは初回実行時に huggingface.co へ送信する6件だけです。これによりキャッシュに5つのファイル（合計133,752,819バイト）が保存されます。ファイルがキャッシュされていれば、実行時にネットワークリクエストは発生しません。

これは、Black Window と Sunstone VS Code 拡張機能の weave を、Model Context Protocol を話すクライアント向けにパッケージ化したものです。Node 20 以降で、macOS、Linux、Windows 上で動作します。

インストール

クライアントに追加する前に、ターミナルから一度インストールしてください。パッケージと ONNX Runtime がインストールされ、ランタイムの読み込みが完了するとバージョンが表示されます。

npx -y [email protected] --version

GitHub のホステッドランナーでは、空の npm キャッシュから初回インストールした場合、Linux と macOS で7〜13秒、Windows で55〜69秒かかりました。クライアントがサーバーの起動を待つ時間には上限があります（MCP SDK のデフォルトは60秒）。インストールの途中で待機をやめるクライアントは、npm のキャッシュに壊れたコピーを残すことがあります（トラブルシューティングを参照）。インストール後、サーバーは3秒以内に起動します。

クライアントの設定では、ここに記載したものと同じバージョンを指定してください。バージョンを指定すると、npx はインストール済みのコピーを起動します。名前だけを指定すると、npx（npm 11）は起動のたびに新しいバージョンを探してインストールするため、その間クライアントは待機します。

Linux x64 では、インストール中に ONNX Runtime が236 MBの CUDA ライブラリもダウンロードします。このサーバーは CPU 上で動作し、それらを読み込むこともないため、ダウンロードを省略できます。

ONNXRUNTIME_NODE_INSTALL=skip npx -y [email protected] --version

クライアントに追加する

macOS と Linux

Claude Code：

claude mcp add weave -- npx -y [email protected] --folder /path/to/your/repo

VS Code の .vscode/mcp.json：

{
  "servers": {
    "weave": { "type": "stdio", "command": "npx", "args": ["-y", "[email protected]", "--folder", "${workspaceFolder}"] }
  }
}

Cursor、Claude Desktop、Windsurf、その他ほとんどのクライアント：

{
  "mcpServers": {
    "weave": { "command": "npx", "args": ["-y", "[email protected]", "--folder", "/path/to/your/repo"] }
  }
}

Windows

Windows では npx はバッチファイルであり、クライアントから起動するには cmd /c を経由する必要があります。Claude Code：

claude mcp add weave -- cmd /c npx -y [email protected] --folder C:\path\to\your\repo

Cursor、Claude Desktop、Windsurf、その他ほとんどのクライアント：

{
  "mcpServers": {
    "weave": { "command": "cmd", "args": ["/c", "npx", "-y", "[email protected]", "--folder", "C:/path/to/your/repo"] }
  }
}

VS Code では、同じ command と args を .vscode/mcp.json の servers の下に置き、"type": "stdio" を指定します。

グローバルインストール

npm install -g [email protected] を実行すると、blackwindow-weave-mcp コマンドがインストールされ、クライアントから直接起動できます（Windows では cmd /c blackwindow-weave-mcp）。npm ではなくこのリポジトリから実行するには、引数の [email protected] を github:space-bacon/blackwindow-weave-mcp に置き換えてください。

オプション	意味
--folder <path>	サーバーの起動時にこのフォルダーを weave します。複数回指定できます。省略可能です。モデル自身が weave_folder を呼び出すこともできます。
--cache <dir>	エンコーダーとインデックスの保存先です。デフォルトは ~/.cache/blackwindow-weave（Windows では %USERPROFILE%\.cache\blackwindow-weave）です。または BLACKWINDOW_WEAVE_CACHE で指定できます。
--version	バージョンを表示して終了します。

プラットフォーム

プッシュのたびに、Linux（x64 と arm64）、Windows（x64）、macOS（Apple シリコン）で、Node 20、22、24 を使用して CI が実行されます。各ジョブでは、チェックアウトしたリポジトリから、以下の stdio スモークテストを実行します。続いて、空の npm キャッシュから npx でパッケージをインストールし、クライアントと同じ方法で起動してフォルダーを weave します。Windows では cmd /c 経由でも起動します。最後に、パッケージをグローバルにインストールしてコマンドから起動します。Windows on Arm、Intel Mac、Alpine Linux など、その他のプラットフォームはテストしていません。

トラブルシューティング

クライアントがサーバーの初回起動時にタイムアウトする、またはサーバーが Cannot find module ... transformers.node.mjs で停止します。 初回インストールが中断され、通常は待機をやめたクライアントが原因で、npm にインストール途中のコピーが残っています。npm の npx キャッシュを削除し、Install の行を使ってターミナルから再度インストールしてください。

• macOS および Linux：rm -rf ~/.npm/_npx
• Windows（PowerShell）：Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

更新。 上記のように、ターミナルから新しいバージョンをインストールし、クライアントの設定でバージョンを変更してください。

ツール

ツール	説明
weave_folder	フォルダーをインデックス化するか、インデックスを最新の状態に更新します。サイズまたは変更時刻が変わったファイルのみ、再度読み込まれます。実行が25秒を超えるとすぐに応答し、バックグラウンドで続行します。
weave_search	自然言語またはコードのクエリに最も近い文章を、ファイル、行範囲、スコアとともに返します。このセッションでインデックス化されたフォルダーを検索します。該当するフォルダーがない場合は、インデックス化されたすべてのフォルダーを検索します。指定された場合は、そのフォルダーを検索します。
weave_list	インデックス化されたフォルダーと、それぞれのファイル数および文章数、実行中のインデックス化処理を一覧表示します。
weave_forget	フォルダーのインデックスを削除します。フォルダー内のファイルには触れません。

実測値

Apple M2 Ultra（CPU 24コア、Node 24.4.1）で、MCP SDK 独自の stdio クライアントを介して test/smoke.mjs を実行した結果です。

フォルダー	ファイル数	文章数	初回のインデックス化	2回目のインデックス化	検索
このパッケージの src/	6	42	3.8 s、エンコーダーのダウンロードを含む	0.013 s	5〜6 ms
Sunstone リポジトリ	57	1,367	20.2 s	0.014 s	6 ms

このマシンでは、埋め込み処理は毎秒約68件の文章を処理するため、10,000件の文章があるリポジトリでは、初回に約2分半かかります。これらの数値は、1台のマシンで各1回実行した結果です。スモークテストでこのパッケージのソースについて尋ねる3つの質問は、いずれも期待されるファイルを最初に返します。これは各要素が連携して動作することを確認するものであり、検索品質を測定するものではありません。検索品質については、モデルカードを参照してください。

仕組み

• ファイル。 Git の作業ツリーは git で一覧表示するため、.gitignore が適用されます。それ以外のフォルダーは走査し、node_modules、ビルド出力、仮想環境、ロックファイル、圧縮ファイルを除外します。1 MB を超えるファイルと、読み込んだ際にバイナリと判定されるファイルは除外されます。JSON と XML も除外されます。Sunstone リポジトリでは、上記の質問について、bench/results/ 以下の結果ファイルを含めた場合に、検索順位の2位と3位を占めました。
• 文章。 コードは定義部分で分割し、各文章を約700文字にして、最も近い定義のラベルを付けます。文章は段落と文で分割し、各文章を約420文字にします。分割処理には Black Window のものを使用します。
• エンコーダー。 onnx/model.onnx（fp32）を、transformers.js と CPU 上の ONNX Runtime で処理し、CLS プーリングを行います。
• センタリング。 各ベクトルからモデルに同梱された平均値（centring/mean_shipped.json）を差し引き、単位長に戻します。そのため、スコアはセンタリング後のコサイン類似度になります。
• 検索。 全件検索で、すべての文章をスコアリングします。回答前に、過去30秒以内に確認されていないフォルダーについて、変更されたファイルが200個未満であれば最新の状態に更新します。それ以外の場合は、インデックスが古いことを回答で伝えます。
• インデックス。 <cache>/index/ 以下にフォルダーごとに1つ作成します。Float32 行列と文章を格納した JSONL を、マニフェストで名前付けします。マニフェストは一時ファイルに書き込んでから名前を変更するため、書き込みが中断されても以前のインデックスが残ります。読み込めないインデックスは上書きせず、別の場所に移動します。

ライセンス

Business Source License 1.1 に社内利用許諾が付属しています。自分または雇用主のコードに対する商用開発を含め、社内のあらゆる目的に、シート数の制限なく利用できます。他者にホスト型検索サービスとして提供したり、提供する製品に組み込んだりすることはできません。2030年9月15日に Apache-2.0 に移行します。エンコーダーは独自のライセンスに基づいてダウンロードされ、そのライセンスも同様の内容です。その他の条件については、[email protected] までお問い合わせください。