Sunstone Weave: Local Semantic Code Search

Name: Sunstone Weave: Local Semantic Code Search
Author: space-bacon

本地服务

github.com/space-bacon搜索与检索1今天更新

代码仓库

关于 Sunstone Weave: Local Semantic Code Search

Sunstone Weave 是面向本地代码和文档目录的语义搜索 MCP 服务。它使用 CPU 上运行的代码搜索编码器建立索引，并返回匹配段落、文件路径和行范围。

主要功能

01基于 CPU 的代码与文档语义搜索
02索引目录并更新已变更文件
03返回段落、路径和行范围
04列出或删除目录索引

适用场景

01按自然语言问题查找代码
02定位本地文档中的相关段落
03文件变更后更新索引

MCP 相关

向 MCP 客户端提供目录索引、语义搜索、索引列表和删除索引等工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "space-bacon-blackwindow-weave": {
      "command": "npx",
      "args": [
        "-y",
        "blackwindow-weave-mcp"
      ],
      "env": {
        "BLACKWINDOW_WEAVE_CACHE": "<BLACKWINDOW_WEAVE_CACHE>"
      }
    }
  }
}

启动命令npx -y blackwindow-weave-mcp

需要配置的环境变量

BLACKWINDOW_WEAVE_CACHEWhere the encoder and the indexes are kept (default ~/.cache/blackwindow-weave, %USERPROFILE%\.cache\blackwindow-weave on Windows)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmblackwindow-weave-mcp0.1.2stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
path	string	是	文件夹的绝对路径，或相对于服务器工作目录的路径

详细介绍

blackwindow-weave-mcp

面向任何 MCP 客户端，对你机器上的文件夹进行语义搜索。服务会将源代码和文档切分为片段，在你的 CPU 上使用 Motherlode（一个拥有 3,300 万参数的代码搜索编码器）为这些片段生成嵌入，并回答诸如“配对行在哪里被解析为 url、key 和 name”之类的问题，同时提供文件路径、行范围和片段内容。

首次运行时，唯一的网络请求会发送到 huggingface.co：共六个请求，会在缓存中留下五个文件，占用 133,752,819 字节。文件缓存后，运行时不会发出任何请求。

这是来自 Black Window 和 Sunstone VS Code 扩展的 weave，现已打包供使用 Model Context Protocol 通信的客户端使用。它可在 macOS、Linux 和 Windows 上运行，要求 Node 20 或更高版本。

安装

将它添加到客户端之前，先在终端中安装一次。这会安装软件包和 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 silicon）上运行 CI，每个平台均使用 Node 20、22 和 24。每个任务都会从检出目录运行下方的 stdio 冒烟测试。随后，它会在空的 npm 缓存中通过 npx 安装打包后的软件包，按照客户端的启动方式启动它，并 weave 一个文件夹。在 Windows 上，还会通过 cmd /c 启动。最后，会全局安装该软件包，并通过其命令启动。其他平台（例如 Windows on Arm、Intel Mac 和 Alpine Linux）未经测试。

故障排查

客户端首次启动服务时超时，或服务因 Cannot find module ... transformers.node.mjs 而停止。 首次安装过程中断了，通常是客户端停止等待所致，npm 保留了未安装完整的副本。删除 npm 的 npx 缓存，然后在终端中按照安装下方的命令重新安装：

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

更新。 在终端中按照上述方法安装新版本，然后更改客户端配置中的版本。

工具

工具	功能
`weave_folder`	为文件夹建立索引，或更新其索引。只有大小或修改时间发生变化的文件才会重新读取。运行时间超过 25 s 时会立即返回，并在后台继续运行。
`weave_search`	返回与自然语言或代码查询最接近的段落，并提供文件、行范围和得分。搜索本次会话中已编织的文件夹；如果没有，则搜索所有已编织的文件夹；也可以按要求搜索单个文件夹。
`weave_list`	列出已编织的文件夹及其文件和段落数量，以及仍在运行的编织任务。
`weave_forget`	删除文件夹的索引，不会触碰文件夹中的文件。

实测数据

在 Apple M2 Ultra（24 个 CPU 核心，Node 24.4.1）上，通过 MCP SDK 自带的 stdio 客户端，在 test/smoke.mjs 中测得：

文件夹	文件数	段落数	首次编织	第二次编织	搜索
此软件包的 `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 个段落的仓库约需两分半钟。上述数据均来自同一台机器上的单次运行。冒烟测试中，针对本软件包源代码提出的三个问题都会优先返回预期文件；这只是检查各部分是否连接正常，并非检索质量的衡量指标。检索质量请参阅模型卡。

工作原理

文件。 对于 git 工作树，通过 git 列出文件，因此会遵循 .gitignore。其他文件夹则会遍历目录，并跳过 node_modules、构建输出、虚拟环境、锁文件和压缩文件。超过 1 MB 的文件以及读取后判定为二进制的文件会被跳过。JSON 和 XML 文件不会纳入索引：在 Sunstone 仓库中，如果纳入 bench/results/ 下的结果文件，它们会在上述问题的搜索结果中排在第 2 和第 3 位。
段落。 代码会在定义处切分为约 700 个字符的段落，每段标注最近的定义。散文则会按段落和句子切分为约 420 个字符的段落。分块器来自 Black Window。
编码器。 使用 transformers.js 和 ONNX Runtime 在 CPU 上运行 onnx/model.onnx（fp32），采用 CLS 池化。
中心化。 每个向量都会减去模型随附的均值（centring/mean_shipped.json），再归一化为单位长度，因此得分是中心化后的余弦相似度。
搜索。 精确搜索：为每个段落打分。回答前，如果某个文件夹在过去 30 s 内未检查，且变更文件少于 200 个，就会更新该文件夹；否则会提示索引已过期。
索引。 每个文件夹在 <cache>/index/ 下各有一个索引：包含 Float32 矩阵和段落 JSONL 文件，文件名由清单指定。清单先写入临时文件，再重命名到位，因此写入中断时会保留上一个索引。无法读取的索引会被移至一旁，而非直接覆盖。

许可证

Business Source License 1.1，并附带内部使用授权。您可以将其用于任何内部用途，包括基于您本人或雇主代码进行商业开发，席位数不受限制。您不得将其作为托管搜索服务提供给他人，也不得将其随您提供的产品一同交付。2030 年 9 月 15 日，该许可证将变为 Apache-2.0。编码器根据其自身许可证下载，该许可证的条款结构相同。如需了解其他条款，请发送邮件至 [email protected]。

支持 Markdown

登录后评论