Phase 3: LSP/MCP retry and debug symbol source

- LSP: retry createLspClient once after 1.5s on failure
- MCP: retry getSymbols once after 1s on failure
- DEBUG_SYSMLEGRAPH_SYMBOLS=1 logs per-file LSP vs MCP source
- PLAN: Phase 3 done; MCP_INTERACTION_GUIDE §7 Debugging

Made-with: Cursor

Author: chouswei

docs/MCP_INTERACTION_GUIDE.md

@@ -170,7 +170,14 @@ Edges come from **symbols** (Package, PartDef, etc.). The indexer gets symbols v
 
 ---
 
-## 7. Summary
+## 7. Debugging
+
+- **`DEBUG_SYSMLEGRAPH_SYMBOLS=1`** — Log to stderr per file whether symbols came from **LSP** or **MCP** (and count for MCP). Use when indexing to see which path is used.
+- **`DEBUG_LSP_NOTIFICATIONS=1`** — Log LSP `window/logMessage` and `window/showMessage` to stderr when using the LSP client.
+
+---
+
+## 8. Summary
 
 | Goal                         | Approach                                                                 |
 |-----------------------------|---------------------------------------------------------------------------|

docs/PLAN.md

@@ -30,15 +30,10 @@
 4. **LSP notification handler** — Handler added in `lsp-client.ts`; `window/logMessage` and `window/showMessage` logged when `DEBUG_LSP_NOTIFICATIONS=1`.
 5. **Real SysML files** — Indexed `modelbase-development/models/` (4 files); map shows Action, Block, Package, PartDef, PartUsage, RequirementDef and IN_DOCUMENT/IN_PACKAGE edges.
 
-### Phase 3: Robustness (If Needed)
+### Phase 3: Robustness — ✅ Done
 
-6. **Connection retry logic**
-   - If LSP client fails to initialize, retry once (transient failures)
-   - If MCP init times out, retry with longer timeout or skip gracefully
-
-7. **Better error reporting**
-   - Map LSP errors to specific types (like template maps `UnauthorizedError`)
-   - Log which path succeeded (LSP vs MCP) for debugging
+6. **Connection retry logic** — LSP: `getDocumentSymbolsFromLsp` retries `createLspClient()` once after 1.5s on failure. MCP: `getSymbolsFromMcp` retries the getSymbols call once after 1s on failure; still returns [] if unavailable.
+7. **Better error reporting** — When **`DEBUG_SYSMLEGRAPH_SYMBOLS=1`**, log to stderr per file whether symbols came from LSP or MCP (and count for MCP). LSP errors still fall through to MCP; no custom error types added.
 
 ### Phase 4: Validation & Documentation
 
@@ -48,10 +43,9 @@
 
 9. **Documentation** — Done in v0.4.3: fixes in `MCP_INTERACTION_GUIDE.md`, "no edges" and troubleshooting, `lsp/` usage in README and release notes. Further troubleshooting can be added as needed.
 
-## Next Steps (Phase 3 / 4)
+## Next Steps (Phase 4)
 
-1. **Optional:** Connection retry and clearer error reporting (Phase 3).
-2. **Optional:** MCP `validate` on a SysML file; expand troubleshooting in docs (Phase 4).
+1. **Optional:** MCP `validate` on a SysML file; expand troubleshooting in docs (Phase 4).
 
 ## Success Criteria
 

src/parser/lsp-client.ts

@@ -260,10 +260,17 @@ export async function createLspClient(): Promise<{
 
 let sharedClient: Awaited<ReturnType<typeof createLspClient>> | null = null;
 
-/** Spawns external LSP (SYSMLLSP_SERVER_PATH). Throws if unset or startup fails. */
+const LSP_INIT_RETRY_DELAY_MS = 1500;
+
+/** Spawns external LSP (SYSMLLSP_SERVER_PATH). Throws if unset or startup fails. Retries once on transient failure. */
 export async function getDocumentSymbolsFromLsp(filePath: string, content: string): Promise<DocumentSymbolLsp[]> {
   if (!sharedClient) {
-    sharedClient = await createLspClient();
+    try {
+      sharedClient = await createLspClient();
+    } catch (firstErr) {
+      await new Promise((r) => setTimeout(r, LSP_INIT_RETRY_DELAY_MS));
+      sharedClient = await createLspClient();
+    }
   }
   const uri = pathToFileURL(filePath).href;
   return await sharedClient.getDocumentSymbols(uri, content);

src/parser/symbols.ts

@@ -86,18 +86,31 @@ async function createMcpClient(): Promise<{
   };
 }
 
-/** Use shared MCP client for getSymbols (one init per index run). Returns [] if MCP unavailable or fails. */
+const MCP_RETRY_DELAY_MS = 1000;
+
+/** Use shared MCP client for getSymbols (one init per index run). Returns [] if MCP unavailable or fails. Retries once on failure. */
 async function getSymbolsFromMcp(filePath: string, content: string): Promise<NormalizedSymbol[]> {
-  try {
+  const attempt = async (): Promise<NormalizedSymbol[]> => {
     if (!sharedMcpClient) sharedMcpClient = await createMcpClient();
     if (!sharedMcpClient) return [];
     const uri = `file:///${filePath.replace(/\\/g, '/')}`;
     return await sharedMcpClient.getSymbols(content, uri, filePath);
+  };
+  try {
+    return await attempt();
   } catch {
-    return [];
+    await new Promise((r) => setTimeout(r, MCP_RETRY_DELAY_MS));
+    try {
+      return await attempt();
+    } catch {
+      return [];
+    }
   }
 }
 
+/** When set, log to stderr whether symbols came from LSP or MCP (per file). */
+const DEBUG_SYMBOL_SOURCE = process.env.DEBUG_SYSMLEGRAPH_SYMBOLS === '1';
+
 /**
  * Get symbols and relations for a single file. Tries LSP documentSymbol first when SYSMLLSP_SERVER_PATH is set;
  * if LSP returns no symbols (or is unset), uses MCP getSymbols (one shared client per index run).
@@ -114,6 +127,7 @@ export async function getSymbolsForFile(filePath: string, content?: string): Pro
         ),
       ]);
       if (lspSymbols.length > 0) {
+        if (DEBUG_SYMBOL_SOURCE) process.stderr.write(`[sysmledgraph] symbols from LSP: ${filePath}\n`);
         const flat = flattenSymbols(lspSymbols, null);
         const normalized: NormalizedSymbol[] = [];
         for (const item of flat) {
@@ -130,7 +144,9 @@ export async function getSymbolsForFile(filePath: string, content?: string): Pro
       // LSP failed or unavailable; fall through to MCP
     }
   }
-  return getSymbolsFromMcp(filePath, text);
+  const mcpSymbols = await getSymbolsFromMcp(filePath, text);
+  if (DEBUG_SYMBOL_SOURCE) process.stderr.write(`[sysmledgraph] symbols from MCP: ${filePath} (${mcpSymbols.length})\n`);
+  return mcpSymbols;
 }
 
 /** Close shared MCP client (used when LSP returned no symbols). */