Docs: two MCPs, Kuzu lock, LSP path; resolve LSP from repo root

- Add docs/MCP-AND-KUZU.md (sysmledgraph vs sysml-v2, no conflict; Kuzu lock; LSP path)
- LSP resolver: walk up from cwd to find node_modules/sysml-v2-lsp (e.g. repo root)
- README: env note, link to MCP-AND-KUZU.md
- chore: release v0.3.0

Made-with: Cursor

Author: chouswei

README.md

@@ -69,7 +69,7 @@ npx sysmledgraph clean
 **Options and environment:**
 
 - **`--storage <path>`** — Override the storage root (default: `~/.sysmledgraph`). Same as env **`SYSMEDGRAPH_STORAGE_ROOT`**.
-- **`SYSMLLSP_SERVER_PATH`** — Optional. Path to the sysml-v2-lsp server JS (e.g. `dist/server/server.js`). If unset, the CLI uses `node_modules/sysml-v2-lsp/dist/server/server.js` (must be built).
+- **`SYSMLLSP_SERVER_PATH`** — Optional. Path to the sysml-v2-lsp server JS (e.g. `dist/server/server.js`). If unset, the CLI looks in local `node_modules` and then walks up from the current working directory (e.g. repo root when run from a subfolder like `tools/sysmledgraph`).
 
 **Storage layout:** Under the storage root: `registry.json` (list of indexed paths), and `db/<sanitized-path>.kuzu` (one Kuzu database per indexed path). On failure, the CLI writes errors to stderr and exits non-zero.
 
@@ -154,7 +154,7 @@ For ad-hoc Cypher or exporting the graph without MCP:
 - `bin/cli.ts` — CLI entrypoint.
 - `mcp/index.ts` — MCP server entrypoint (stdio).
 - `test/` — Unit and integration tests.
-- `docs/` — [INSTALL_NOTES.md](docs/INSTALL_NOTES.md) (slow install, Windows workarounds), [grammar-and-mapping.md](docs/grammar-and-mapping.md).
+- `docs/` — [INSTALL_NOTES.md](docs/INSTALL_NOTES.md) (slow install, Windows), [MCP-AND-KUZU.md](docs/MCP-AND-KUZU.md) (two MCPs, Kuzu lock, LSP path), [grammar-and-mapping.md](docs/grammar-and-mapping.md).
 
 ## Development
 

docs/MCP-AND-KUZU.md

@@ -0,0 +1,39 @@
+# Two MCPs, Kuzu lock, and LSP path
+
+## How the two MCPs relate
+
+| | **sysmledgraph** | **sysml-v2** (e.g. SysML v2 MCP) |
+|--|------------------|----------------------------------|
+| **Role** | Path-based indexer: builds a Kuzu graph from `.sysml` paths | SysML LSP MCP: parse, validate, symbols, loadProject, impact, context, query, preview |
+| **Uses LSP** | Spawns `server.js` (stdio) only when indexing | Runs `mcpServer.js` as the MCP server |
+| **Uses Kuzu** | Yes (one DB per indexed path) | No |
+| **Same package** | Same sysml-v2-lsp package, different entry points (`server.js` vs `mcpServer.js`) | Same |
+
+So there is **no MCP-vs-MCP conflict**. The sysml-v2 MCP does not use Kuzu, so the two MCPs don’t contend over the database.
+
+---
+
+## Kuzu lock
+
+**Only sysmledgraph uses Kuzu.** The “Could not set lock on file” (or similar) error happens when the **same DB file is opened more than once**:
+
+- MCP has the DB open and you run the sysmledgraph **CLI** (e.g. `npx sysmledgraph analyze`), or  
+- Two connections to the same DB in one process (we fixed that with a connection cache in the MCP).
+
+**Fixes:**
+
+- **Within one process:** The MCP uses a single cached connection per DB path (v0.2.0+), so repeated/concurrent tool calls don’t open the same file twice.  
+- **Across processes:** Only one writer at a time. If you do a full re-index from the CLI, close Cursor (or stop the sysmledgraph MCP) first, or run the CLI when the MCP isn’t using that DB.
+
+---
+
+## “sysml-v2-lsp not found” / LSP path
+
+That was **path resolution**: the sysmledgraph CLI (or MCP) was only looking in its own `node_modules` (e.g. `tools/sysmledgraph/node_modules/...`) and didn’t see the LSP at **repo root**.
+
+**Fixes:**
+
+- Resolver now also checks **repo root** (and parent directories) for `node_modules/sysml-v2-lsp/dist/server/server.js`, so when sysmledgraph runs from a subfolder (e.g. `tools/sysmledgraph`), it can find the LSP at the repo root.  
+- You can always set **SYSMLLSP_SERVER_PATH** to the absolute path of your built `dist/server/server.js` if you want to point at a specific LSP install.
+
+The sysml-v2 MCP runs from repo root and uses `mcpServer.js`; it doesn’t depend on this resolver and doesn’t block it.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sysmledgraph",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Path-only SysML indexer: knowledge graph (Kuzu), MCP server (query, context, impact, rename, cypher), CLI (analyze, list, clean)",
   "type": "module",
   "main": "dist/src/index.js",

release-notes-v0.3.0.md

@@ -0,0 +1,5 @@
+## Changes
+
+- **Docs: Two MCPs, Kuzu lock, LSP path** — New [docs/MCP-AND-KUZU.md](docs/MCP-AND-KUZU.md) explains how sysmledgraph and the sysml-v2 MCP relate (no conflict; only sysmledgraph uses Kuzu), when Kuzu lock happens (same DB opened twice), and how to avoid it. Also documents the "sysml-v2-lsp not found" path-resolution fix.
+- **LSP path resolution** — Resolver now walks up from the current working directory to find `node_modules/sysml-v2-lsp/dist/server/server.js`. When sysmledgraph runs from a subfolder (e.g. `tools/sysmledgraph`), it can use the LSP at repo root without setting `SYSMLLSP_SERVER_PATH`.
+- **README** — CLI env note and project layout link to MCP-AND-KUZU.md.

src/parser/lsp-client.ts

@@ -1,7 +1,7 @@
 /**
  * sysml-v2-lsp integration: stdio LSP client.
  * Spawns the LSP server (dist/server/server.js). Uses LSP message framing (Content-Length).
- * Server path: SYSMLLSP_SERVER_PATH or node_modules/sysml-v2-lsp/dist/server/server.js.
+ * Server path: SYSMLLSP_SERVER_PATH, or local node_modules, or walk up from cwd (e.g. repo root).
  */
 
 import { spawn } from 'child_process';
@@ -12,6 +12,20 @@ import { existsSync } from 'fs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+const LSP_REL_PATH = join('sysml-v2-lsp', 'dist', 'server', 'server.js');
+
+function findLspInNodeModules(startDir: string): string | null {
+  let dir = startDir;
+  for (;;) {
+    const candidate = join(dir, 'node_modules', LSP_REL_PATH);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
 export interface DocumentSymbolLsp {
   name: string;
   detail?: string;
@@ -25,9 +39,11 @@ async function resolveServerPath(): Promise<string | null> {
   if (process.env.SYSMLLSP_SERVER_PATH) {
     return process.env.SYSMLLSP_SERVER_PATH;
   }
-  const root = join(__dirname, '..', '..', '..');
-  const candidate = join(root, 'node_modules', 'sysml-v2-lsp', 'dist', 'server', 'server.js');
-  if (existsSync(candidate)) return candidate;
+  const packageRoot = join(__dirname, '..', '..', '..');
+  const local = join(packageRoot, 'node_modules', LSP_REL_PATH);
+  if (existsSync(local)) return local;
+  const fromCwd = findLspInNodeModules(process.cwd());
+  if (fromCwd) return fromCwd;
   return null;
 }