Skip to main content
Glama
space-bacon

Sunstone Weave: Local Semantic Code Search

by space-bacon
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

blackwindow-weave-mcp

Semantic search over the folders on your machine, for any MCP client. The server cuts source code and documentation into passages, embeds them with Motherlode, a 33M-parameter code-search encoder, on your CPU, and answers questions such as "where is a pairing line parsed into url, key and name" with file paths, line ranges and the passages themselves.

The only network requests are to huggingface.co on the first run: six requests, which leave five files, 133,752,819 bytes, in the cache. With the files cached, a run makes none.

This is the weave from Black Window and the Sunstone VS Code extension, packaged for clients that speak the Model Context Protocol. It runs on macOS, Linux and Windows with Node 20 or later.

Install

Install it once from a terminal, before adding it to a client. This installs the package and ONNX Runtime and prints the version once the runtime has loaded:

npx -y blackwindow-weave-mcp@0.1.2 --version

On GitHub's hosted runners, from an empty npm cache, this first install took 7 to 13 s on Linux and macOS and 55 to 69 s on Windows. Clients wait a limited time for a server to start (the MCP SDK's default is 60 s), and a client that stops waiting in the middle of an install can leave a broken copy in npm's cache (see Troubleshooting). Once installed, the server starts in under 3 s.

Keep the version in the client's configuration the same as here. With a version given, npx starts the copy it installed; with the bare name, npx (npm 11) looks for a newer version on every start and installs it while the client waits.

On Linux x64, ONNX Runtime also downloads 236 MB of CUDA libraries during the install. This server runs on the CPU and never loads them, so you can skip them:

ONNXRUNTIME_NODE_INSTALL=skip npx -y blackwindow-weave-mcp@0.1.2 --version

Related MCP server: MCP Codebase RAG Server

Add it to a client

macOS and Linux

Claude Code:

claude mcp add weave -- npx -y blackwindow-weave-mcp@0.1.2 --folder /path/to/your/repo

VS Code, in .vscode/mcp.json:

{
  "servers": {
    "weave": { "type": "stdio", "command": "npx", "args": ["-y", "blackwindow-weave-mcp@0.1.2", "--folder", "${workspaceFolder}"] }
  }
}

Cursor, Claude Desktop, Windsurf and most other clients:

{
  "mcpServers": {
    "weave": { "command": "npx", "args": ["-y", "blackwindow-weave-mcp@0.1.2", "--folder", "/path/to/your/repo"] }
  }
}

Windows

On Windows npx is a batch file, which a client can only start through cmd /c. Claude Code:

claude mcp add weave -- cmd /c npx -y blackwindow-weave-mcp@0.1.2 --folder C:\path\to\your\repo

Cursor, Claude Desktop, Windsurf and most other clients:

{
  "mcpServers": {
    "weave": { "command": "cmd", "args": ["/c", "npx", "-y", "blackwindow-weave-mcp@0.1.2", "--folder", "C:/path/to/your/repo"] }
  }
}

In VS Code the same command and args go under servers in .vscode/mcp.json, with "type": "stdio".

Installed globally

npm install -g blackwindow-weave-mcp@0.1.2 installs a blackwindow-weave-mcp command, which a client can start directly (cmd /c blackwindow-weave-mcp on Windows). To run from this repository instead of npm, replace blackwindow-weave-mcp@0.1.2 in the arguments with github:space-bacon/blackwindow-weave-mcp.

option

meaning

--folder <path>

Weave this folder when the server starts. Repeatable. Optional: the model can call weave_folder itself.

--cache <dir>

Where the encoder and the indexes live. Default ~/.cache/blackwindow-weave (on Windows %USERPROFILE%\.cache\blackwindow-weave), or BLACKWINDOW_WEAVE_CACHE.

--version

Print the version and exit.

Platforms

Every push runs CI on Linux (x64 and arm64), Windows (x64) and macOS (Apple silicon), each with Node 20, 22 and 24. Each job runs the stdio smoke test below from a checkout. It then installs the packed package through npx from an empty npm cache, starts it the way a client does and weaves a folder. On Windows it also starts it through cmd /c. Last, it installs the package globally and starts it by its command. Other platforms, such as Windows on Arm, Intel Macs and Alpine Linux, are not tested.

Troubleshooting

The client times out when it first starts the server, or the server stops with Cannot find module ... transformers.node.mjs. A first install was interrupted, usually by a client that stopped waiting, and npm kept the half-installed copy. Delete npm's npx cache and install again from a terminal with the line under Install:

  • macOS and Linux: rm -rf ~/.npm/_npx

  • Windows (PowerShell): Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

Updating. Install the new version from a terminal as above, then change the version in the client's configuration.

Tools

tool

what it does

weave_folder

Index a folder, or bring its index up to date. Only files whose size or modification time changed are read again. A run longer than 25 s returns at once and continues in the background.

weave_search

The passages nearest a plain-language or code query, with file, line range and score. Searches the folders woven in this session, or every woven folder if none was, or one folder when asked.

weave_list

The woven folders with their file and passage counts, and any weave still running.

weave_forget

Delete a folder's index. The folder's files are not touched.

Measured

On an Apple M2 Ultra (24 CPU cores, Node 24.4.1), through the MCP SDK's own stdio client, in test/smoke.mjs:

folder

files

passages

first weave

second weave

search

this package's src/

6

42

3.8 s, with the encoder's download

0.013 s

5 to 6 ms

the Sunstone repository

57

1,367

20.2 s

0.014 s

6 ms

Embedding runs at about 68 passages a second on that machine, so a repository of 10,000 passages takes about two and a half minutes the first time. Those figures are one run each on one machine. The smoke test's three questions about this package's own source each return the expected file first; they are a check that the pieces are wired together, not a measure of retrieval quality. For retrieval quality see the model card.

How it works

  • Files. A git work tree is listed by git, so .gitignore holds. Any other folder is walked, skipping node_modules, build output, virtual environments, lock files and minified files. Files over 1 MB and files that read as binary are skipped. JSON and XML are left out: in the Sunstone repository, result files under bench/results/ took ranks 2 and 3 of the question above when they were included.

  • Passages. Code is cut at definitions into passages of about 700 characters, each labelled with the nearest definition. Prose is cut at paragraphs and sentences into passages of about 420 characters. The chunkers are Black Window's.

  • Encoder. onnx/model.onnx (fp32) through transformers.js and ONNX Runtime on the CPU, CLS pooling.

  • Centring. Every vector has the model's shipped mean (centring/mean_shipped.json) subtracted and is brought back to unit length, so a score is a cosine after centring.

  • Search. Exact: every passage is scored. Before answering, a folder not checked in the last 30 s is brought up to date if fewer than 200 of its files changed; otherwise the answer says the index is stale.

  • Index. One per folder under <cache>/index/: a Float32 matrix and a JSONL of passages, named by a manifest that is written to a temporary file and renamed into place, so an interrupted write leaves the previous index. An index that cannot be read is moved aside rather than overwritten.

Licence

Business Source License 1.1 with an internal-use grant. You may use it for any internal purpose, including commercial development on your own or your employer's code, with no limit on seats. You may not offer it to others as a hosted search service or ship it inside a product you supply. On 15 September 2030 it becomes Apache-2.0. The encoder is downloaded under its own licence, which has the same shape. For other terms, write to burton@sunstonenorth.com.

Available Tools

4 tools
weave_folderWeave a folderA
Idempotent

Index a folder on this machine (source code and docs) for semantic search, or bring its index up to date: only files that changed since the last run are read again. Call it once per project. The first run downloads the 33M-parameter encoder (133 MB) and embeds every passage on the CPU; a run longer than 25 s continues in the background and weave_list reports its progress.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesAbsolute path of the folder, or a path relative to the server's working directory

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond the annotations: incremental re-indexing (only changed files re-read), a 133 MB / 33M-parameter model download on first run, CPU-bound embedding, and background continuation past 25 s. This is consistent with idempotentHint=true and readOnlyHint=false, and no contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the primary action before the operational caveats (download, runtime, backgrounding). Every sentence carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, no-output-schema tool, the description covers the mutation semantics, idempotent behavior, latency characteristics, and where progress is reported. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter and schema coverage is 100%, so the schema already documents the absolute-vs-relative path semantics. The description adds nothing about the path argument itself, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('index a folder ... for semantic search') plus the secondary mode ('bring its index up to date'), which cleanly separates it from the read-only siblings weave_search and weave_list. An agent can route to it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Call it once per project' gives an explicit usage cadence, and the reference to weave_list for progress tells the agent where to look while a run is in flight. It does not state when-not to use it or contrast directly with weave_search/weave_forget, so it stops short of a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

weave_forgetForget a woven folderA
DestructiveIdempotent

Delete a folder's index from this machine. The folder's own files are not touched.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe woven folder

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is partly covered. The description adds genuinely useful context beyond that: what is destroyed (the index) and what is explicitly preserved (the folder's files), which softens the otherwise alarming destructive hint. It does not discuss reversibility or how the index can be rebuilt.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and followed by the critical scope limitation. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, no-output tool whose annotations carry the safety profile, the description covers the essentials. The only real gap is behavior on non-woven folders and whether the index can be regenerated, which matters given the destructive hint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With a single parameter and 100% schema description coverage, the schema already documents 'path' as the woven folder. The description adds no format, path-shape, or example beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource — deleting a folder's index — and immediately disambiguates 'forget' from file deletion with 'the folder's own files are not touched.' It is clear on its own, though it does not explicitly contrast itself with siblings like weave_folder or weave_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus alternatives, no prerequisites, and no mention of the sibling tools. The intended usage (removing a folder from the index) is only inferable from the purpose sentence.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

weave_listList woven foldersA
Read-only

List the folders this server has indexed, with their file and passage counts.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety and scope profile is covered. The description adds that results are limited to folders 'this server has indexed' and that file and passage counts are included, but says nothing about ordering, pagination, or behavior on an empty index.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler, front-loaded with the action and resource, and it still conveys the returned metrics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only, parameterless listing tool with annotations covering safety and no output schema, the description adequately conveys both scope and what is returned. Only ordering/pagination detail is absent, which is minor here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (folders) plus the scope of what is listed ('this server has indexed'). It does not differentiate itself from siblings like weave_search or weave_folder, so an agent must infer the boundary itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the purpose: enumerate indexed folders before, say, searching or forgetting within one. However, there is no explicit when-to-use, no when-not-to-use, and no sibling alternative named, so the routing guidance is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedweave_folder
    • First observedweave_forget
    • First observedweave_list
    • First observedweave_search
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool maps to a distinct operation in the indexing lifecycle: index (weave_folder), query (weave_search), inspect (weave_list), and remove (weave_forget). There is no meaningful overlap, and the descriptions reinforce when to use each (e.g. search before grep).

Naming Consistency4/5

The weave_ prefix is applied uniformly, giving a clear namespace. Suffixes are mostly verbs (search, list, forget) except weave_folder, which is a noun referring to the resource it indexes, a minor deviation but still readable and predictable.

Tool Count4/5

Four tools is a tight, well-scoped set for a semantic-index server: create, query, enumerate, and delete. It is on the lean side with no configuration or content-retrieval tool, but each tool earns its place and nothing feels redundant.

Completeness4/5

The index lifecycle is fully covered: build/refresh (weave_folder), search (weave_search), list (weave_list), and delete (weave_forget), with re-indexing handled by weave_folder's incremental behavior. Minor gap: no tool to fetch a passage's or file's contents directly, so agents must fall back on other file-reading tools after a search hit.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • code-search

    amolchanov
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables semantic code search across indexed code folders using vector embeddings, with support for multiple embedding providers and automatic file watching. Provides an admin UI and integrates with MCP clients for natural language code queries.
    1
    MIT