fix: run sync MCP handlers in thread pool, prevent mermaid validation hang

- Wrap synchronous tool handlers in asyncio.to_thread() to avoid
  blocking the event loop (analyze_repo excluded — Tree-sitter C
  extensions are not thread-safe)
- Disable mermaid-py validation by default (set MERMAID_VALIDATE=1
  to enable), add 15s timeout to prevent indefinite hangs

Author: mambo-wang

codewiki/mcp/server.py

@@ -415,21 +415,26 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
     """Route tool calls to the appropriate handler."""
     try:
         # --- Fine-grained tools (no LLM config needed) ---
+        # Synchronous handlers run via asyncio.to_thread() so they never
+        # block the event loop (which would hang the MCP stdio server).
         if name == "analyze_repo":
             from codewiki.mcp.tools.analysis import handle_analyze_repo
+            # NOTE: Tree-sitter C extensions are not thread-safe, so this
+            # must run on the main thread (blocking the event loop is
+            # acceptable for this one-time heavy operation).
             return [_text(handle_analyze_repo(arguments, _store))]
 
         elif name == "read_code_components":
             from codewiki.mcp.tools.code_reader import handle_read_code_components
-            return [_text(handle_read_code_components(arguments, _store))]
+            return [_text(await asyncio.to_thread(handle_read_code_components, arguments, _store))]
 
         elif name == "list_components":
             from codewiki.mcp.tools.analysis import handle_list_components
-            return [_text(handle_list_components(arguments, _store))]
+            return [_text(await asyncio.to_thread(handle_list_components, arguments, _store))]
 
         elif name == "view_repo_file":
             from codewiki.mcp.tools.code_reader import handle_view_repo_file
-            return [_text(handle_view_repo_file(arguments, _store))]
+            return [_text(await asyncio.to_thread(handle_view_repo_file, arguments, _store))]
 
         elif name == "write_doc_file":
             from codewiki.mcp.tools.doc_writer import handle_write_doc_file
@@ -443,15 +448,15 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
 
         elif name == "save_module_tree":
             from codewiki.mcp.tools.module_tree import handle_save_module_tree
-            return [_text(handle_save_module_tree(arguments, _store))]
+            return [_text(await asyncio.to_thread(handle_save_module_tree, arguments, _store))]
 
         elif name == "get_processing_order":
             from codewiki.mcp.tools.module_tree import handle_get_processing_order
-            return [_text(handle_get_processing_order(arguments, _store))]
+            return [_text(await asyncio.to_thread(handle_get_processing_order, arguments, _store))]
 
         elif name == "get_prompt":
             from codewiki.mcp.tools.prompt_server import handle_get_prompt
-            return [_text(handle_get_prompt(arguments, _store))]
+            return [_text(await asyncio.to_thread(handle_get_prompt, arguments, _store))]
 
         elif name == "close_session":
             sid = arguments["session_id"]

codewiki/src/be/utils.py

@@ -1,4 +1,5 @@
 import asyncio
+import os
 import re
 import sys
 import threading
@@ -150,6 +151,12 @@ def extract_mermaid_blocks(content: str) -> List[Tuple[int, str]]:
 # Skip it proactively so SpiderMonkey is never loaded into the process.
 _PYTHONMONKEY_BROKEN = sys.version_info >= (3, 12)
 
+# mermaid-py spawns a Node.js subprocess that can hang indefinitely (e.g. when
+# Node.js is missing or the mermaid CLI is misconfigured).  Default to
+# disabled; set MERMAID_VALIDATE=1 to enable.
+_MERMAID_PY_BROKEN = os.environ.get("MERMAID_VALIDATE", "0") != "1"
+_MERMAID_PY_PROBED = True  # Skip probing — rely on env var
+
 
 async def _try_pythonmonkey_parse(diagram_content: str) -> str | None:
     """Attempt to parse via PythonMonkey/mermaid-parser-py.
@@ -232,8 +239,16 @@ async def validate_single_diagram(diagram_content: str, diagram_num: int, line_s
     """
     core_error = await _try_pythonmonkey_parse(diagram_content)
     if core_error is None:
+        # Both PythonMonkey (3.12+) and mermaid-py (env disabled) are unavailable
+        if _MERMAID_PY_BROKEN:
+            return ""  # Skip validation gracefully
         try:
-            core_error = _parse_via_mermaid_py(diagram_content)
+            core_error = await asyncio.wait_for(
+                asyncio.to_thread(_parse_via_mermaid_py, diagram_content),
+                timeout=15.0,
+            )
+        except asyncio.TimeoutError:
+            return ""  # Graceful skip on timeout
         except Exception as e:
             return f"  Diagram {diagram_num}: Exception during validation - {str(e)}"