Windows: semantic_search_nodes_tool hangs on stdio MCP transport (missing asyncio.to_thread + tokenizer deadlock)

[gfleg77]

Summary

On Windows, semantic_search_nodes_tool silently hangs indefinitely when sentence-transformers embeddings are available. Three layered issues prevent semantic search from working on Windows.

Environment

• OS: Windows 10 Enterprise
• Python: 3.11
• code-review-graph: 2.3.2
• sentence-transformers: 3.4.1
• FastMCP: 2.14.7
• Transport: stdio (VS Code extension)

Root Causes

1. semantic_search_nodes_tool missing asyncio.to_thread (regression vs embed_graph_tool)

embed_graph_tool already uses asyncio.to_thread (per the fix in #46 / #136) to avoid blocking the WindowsSelectorEventLoop with sentence-transformers inference. semantic_search_nodes_tool does not — it is a plain def that calls semantic_search_nodes() synchronously on the event loop, producing the same deadlock.

Fix: convert to async def + asyncio.to_thread, identical to embed_graph_tool:

@mcp.tool()
async def semantic_search_nodes_tool(
    query: str,
    ...
) -> dict:
    """..."""
    return await asyncio.to_thread(
        semantic_search_nodes,
        query=query, kind=kind, limit=limit,
        repo_root=_resolve_repo_root(repo_root),
        model=model, detail_level=detail_level,
    )

2. Rust tokenizer thread deadlock in subprocess context

Even with asyncio.to_thread, the Rust-based fast tokenizers inside sentence-transformers spawn parallel threads on first load. In a Windows MCP server subprocess this causes a deadlock. Required env vars (not currently documented):

"TOKENIZERS_PARALLELISM": "false",
"OMP_NUM_THREADS": "1"

3. 12-second cold start on first tool call

The LocalEmbeddingProvider lazy-loads SentenceTransformer on the first inference call (~12s on first call, <1s subsequently). This means the first semantic_search_nodes_tool call in a session always blocks the event loop for 12 seconds even after fix #1.

Fix: pre-warm synchronously in main() before mcp.run() starts the event loop:

def _prewarm_embeddings() -> None:
    try:
        from .embeddings import LocalEmbeddingProvider
        import os
        model_name = os.environ.get("CRG_EMBEDDING_MODEL", "all-MiniLM-L6-v2")
        provider = LocalEmbeddingProvider(model_name=model_name)
        provider._get_model()
    except Exception:
        pass  # embeddings are optional, never crash the server

def main(repo_root=None):
    ...
    if sys.platform == "win32":
        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
    _prewarm_embeddings()  # load model before event loop starts
    mcp.run(transport="stdio")

Result after all three fixes

• Semantic search responds in <1s (warm) on Windows via stdio MCP
• No deadlocks, no hangs

Notes

• embed_graph_tool was also hanging for the same tokenizer reason (fix Fix/plugin install config #2) even though it already had asyncio.to_thread. Adding TOKENIZERS_PARALLELISM=false + pre-warming fixes both tools.
• The pre-warm approach also makes embed_graph_tool's first call faster since sentence-transformers is already initialized.
• Related: Build & Embed operations hang silently on Windows 11 with uvx #46, embed_graph_tool hangs indefinitely on Windows with both sentence-transformers and Gemini provider #136

[gfleg77]

Follow-up findings — corrections and additional bug

After further testing on Windows 10 with Codex elevated sandbox, I have corrections to points 2 and 3 above, plus a new finding.

---

Correction to point 3 — prewarm should be REMOVED, not added

The recommendation to add _prewarm_embeddings() synchronously in main() before mcp.run() is the original behavior and it causes the exact problem it's meant to solve: on any system where model loading is slow (Windows, cold cache), prewarm blocks the MCP server from responding to initialize → client times out → all tools unavailable.

Moving prewarm to a background thread is also unsafe on Windows: the Rust tokenizer spawns threads that interact with the GIL and asyncio event loop, causing the entire server process to deadlock — even list_graph_stats stops responding.

Correct fix: remove prewarm entirely. Lazy load on first search call is safe when use_fast=False (see point 2 correction below). The CRG_DISABLE_EMBEDDINGS=1 env var is the right escape hatch for MCP deployments where embeddings aren't needed.

---

Correction to point 2 — use_fast=False eliminates the Rust deadlock

Setting tokenizer_kwargs={"use_fast": False} in SentenceTransformer(...) uses the Python tokenizer instead of the Rust DLL. This eliminates the deadlock entirely — TOKENIZERS_PARALLELISM=false and OMP_NUM_THREADS=1 are not needed when use_fast=False.

---

New bug — EmbeddingStore singleton: model reloaded on every search call

LocalEmbeddingProvider._get_model() stores the loaded model in self._model, but a new EmbeddingStore and new LocalEmbeddingProvider instance is created on every call to _embedding_search. The module-level _model_cache dict exists but is never populated, so self._model is always None at the start of each call.

Result: sentence-transformers reloads from scratch on every semantic_search_nodes_tool call.

Fix:

_model_cache: dict[str, Any] = {}

def _get_model(self):
    if self._model is None:
        if self._model_name not in _model_cache:
            from sentence_transformers import SentenceTransformer
            _model_cache[self._model_name] = SentenceTransformer(
                self._model_name,
                trust_remote_code=True,
                tokenizer_kwargs={"use_fast": False},
            )
        self._model = _model_cache[self._model_name]
    return self._model

---

Summary of working config on Windows 10 / Codex elevated sandbox

[mcp_servers.code-review-graph]
command = "C:\...\Scripts\code-review-graph.exe"  # absolute path required
args = ["serve"]

[mcp_servers.code-review-graph.env]
HF_HUB_OFFLINE = "1"
TRANSFORMERS_OFFLINE = "1"
CRG_DISABLE_EMBEDDINGS = "1"   # FTS5 keyword search only, no model load

With CRG_DISABLE_EMBEDDINGS=1, all 5 tested tools respond in 2–8s with no warmup call needed.