sysmledgraph 0.7.0

package/docs/MCP_CLIENT_TEMPLATE_ANALYSIS.md

@@ -0,0 +1,196 @@
+# MCP Client Template Analysis
+
+Analysis of [andrea9293/mcp-client-template](https://github.com/andrea9293/mcp-client-template) patterns, protocol, and behavior.
+
+## Architecture
+
+**Two-tier web app:**
+- **Frontend** (Vite + TypeScript): Web UI for managing servers and sending commands
+- **Backend** (Express + TypeScript): REST API that wraps MCP SDK client operations
+
+**Data persistence:**
+- `data/mcp-servers.json` — Server configurations (command, type, args)
+- `data/auth-tokens.json` — OAuth tokens per server
+
+## Protocol & Transport
+
+### Transport Types Supported
+
+1. **`stdio`** — Newline-delimited JSON over stdin/stdout
+   - Uses `StdioClientTransport` from SDK
+   - Spawns process: `{ command, args }`
+   - Example: `{ type: 'stdio', command: 'node', args: ['server.js'] }`
+
+2. **`httpstream`** — Streamable HTTP (long-polling or streaming)
+   - Uses `StreamableHTTPClientTransport` from SDK
+   - Command is the server URL
+   - Example: `{ type: 'httpstream', command: 'https://mcp-server.example.com' }`
+
+3. **`sse`** — Server-Sent Events
+   - Uses `SSEClientTransport` from SDK
+   - Command is the server URL
+   - Example: `{ type: 'sse', command: 'https://mcp-server.example.com/events' }`
+
+### MCP SDK Usage
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const client = new Client({ name: 'my-client', version: '1.0.0' });
+const transport = new StdioClientTransport({ command: 'node', args: ['server.js'] });
+await client.connect(transport); // ← initialize happens here
+// Then: client.request({ method: 'tools/list' }, schema)
+```
+
+**Key point:** The SDK `Client.connect(transport)` handles the full MCP lifecycle:
+1. Spawns process (for stdio) or opens connection (for HTTP/SSE)
+2. Sends `initialize` request
+3. Waits for `initialize` response
+4. Sends `notifications/initialized`
+5. Client is ready for `tools/list`, `tools/call`, etc.
+
+## Connection Pattern
+
+**Per-request connection:**
+- Each `/mcp` API call creates a new `Client` + `Transport`
+- Connects, makes request(s), then closes
+- No connection pooling or reuse
+
+**Why:** Simpler error handling; each request is isolated. Trade-off: slower (reconnect cost per request).
+
+## OAuth2.1 Flow
+
+1. **First connect attempt** → `UnauthorizedError` thrown
+2. **Extract auth URL** from `OAuthClientProvider.redirectToAuthorization()`
+3. **Return 401 with `authUrl`** to frontend
+4. **User completes OAuth** in browser → redirects to `/oauth/callback`
+5. **Backend calls `transport.finishAuth(code)`**
+6. **Reconnect** with authenticated transport
+7. **Save tokens** to `auth-tokens.json` for future use
+
+**Token reuse:** On subsequent connects, if tokens exist, they're loaded into the OAuth provider before connecting.
+
+## API Endpoints
+
+### `POST /add-server`
+- Adds server config to `mcp-servers.json`
+- Body: `{ id, command, type, args }`
+- Persists immediately
+
+### `GET /servers`
+- Lists all servers from `mcp-servers.json`
+- Returns array of `{ name, command, type, args }`
+
+### `POST /mcp`
+- **Body:** `{ server: string, command: string, args?: any[] }`
+- **Command format:** `"list"` or `"call <toolName> [json-args]"`
+- **Flow:**
+  1. Load server config
+  2. `autoDetectTransport()` → create Client + Transport
+  3. `client.connect()` → initialize handshake
+  4. Parse command:
+     - `"list"` → `client.request({ method: 'tools/list' }, ListToolsResultSchema)`
+     - `"call <name> [args]"` → `client.request({ method: 'tools/call', params: { name, arguments } }, CallToolResultSchema)`
+  5. Return result as JSON
+  6. Close transport
+
+### `POST /oauth/callback`
+- Receives OAuth code from frontend
+- Calls `transport.finishAuth(code)`
+- Reconnects with authenticated transport
+- Saves tokens
+
+## Key Patterns
+
+### 1. Transport Auto-Detection
+
+```typescript
+async function autoDetectTransport(serverConfig) {
+  const client = new Client({ name: serverConfig.name, version: '1.0.0' });
+  const oauthProvider = new InMemoryOAuthProvider();
+  
+  if (type === 'stdio') {
+    const transport = new StdioClientTransport({ command, args });
+    await client.connect(transport);
+  } else if (type === 'httpstream' || type === 'sse') {
+    const TransportClass = type === 'httpstream' 
+      ? StreamableHTTPClientTransport 
+      : SSEClientTransport;
+    const transport = new TransportClass(new URL(command), { authProvider: oauthProvider });
+    await client.connect(transport);
+  }
+  return { client, transport };
+}
+```
+
+**Pattern:** Factory that creates the right transport based on `type`, handles OAuth for HTTP transports.
+
+### 2. Request Schema Validation
+
+Uses Zod schemas from SDK:
+- `ListToolsResultSchema` for `tools/list`
+- `CallToolResultSchema` for `tools/call`
+- `LoggingMessageNotificationSchema` for notifications
+
+**Pattern:** Type-safe request/response validation via SDK schemas.
+
+### 3. Error Handling
+
+- **UnauthorizedError** → Return 401 with `authUrl` for OAuth flow
+- **Other errors** → Return 500 with error details
+- **Connection errors** → Caught and returned as JSON
+
+**Pattern:** HTTP status codes map to MCP/auth errors; frontend handles 401 specially.
+
+### 4. Notification Handling
+
+```typescript
+client.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+  // Log notification (template doesn't do much here)
+});
+```
+
+**Pattern:** Register handlers for server notifications (e.g. `logging/message`); template logs them.
+
+## Comparison with Our LSP Client
+
+| Aspect | MCP Template | Our LSP Client |
+|--------|-------------|----------------|
+| **SDK** | Uses `@modelcontextprotocol/sdk` Client | Custom Content-Length transport |
+| **Framing** | Newline-delimited (SDK default) | Content-Length (LSP-style) |
+| **Lifecycle** | `client.connect()` handles initialize | Manual: `initialize` → `initialized` → requests |
+| **Connection** | Per-request (new client each time) | Shared client (reused across requests) |
+| **Protocol** | MCP (`tools/list`, `tools/call`) | LSP (`textDocument/documentSymbol`) |
+| **Transport** | stdio, HTTP, SSE | stdio only (Content-Length) |
+| **OAuth** | Full OAuth2.1 support | None (LSP doesn't use OAuth) |
+
+## Takeaways for Our Codebase
+
+1. **SDK vs Custom:** We can't use SDK `StdioClientTransport` because sysml-v2-lsp uses Content-Length, not newline-delimited. Our custom transport is correct.
+
+2. **Connection Reuse:** Template creates per-request connections; we reuse a shared client. Our approach is better for performance (no reconnect cost), but we need to handle errors/restarts.
+
+3. **Lifecycle:** Template relies on SDK's `connect()` to do initialize; we do it manually. Both are valid—SDK abstracts it, we have explicit control.
+
+4. **Error Handling:** Template maps MCP errors to HTTP status codes; we throw/return errors directly. Our approach fits our use case (CLI/scripts, not REST API).
+
+5. **OAuth:** Template has full OAuth flow; we don't need it for LSP (LSP doesn't use OAuth).
+
+## What We Should Adopt
+
+1. **Notification handlers:** If the LSP server sends notifications (e.g. `window/logMessage`), we should register handlers instead of ignoring them.
+
+2. **Request timeout:** Template doesn't show explicit timeouts, but we added 30s timeout—good practice.
+
+3. **Error mapping:** Template maps `UnauthorizedError` to 401; we could map LSP errors to more specific error types.
+
+4. **Connection retry:** Template doesn't retry; we could add retry logic for transient failures.
+
+## What We Shouldn't Adopt
+
+1. **Per-request connections:** Too slow for indexing (many files). Our shared client is better.
+
+2. **REST API wrapper:** We're a CLI/library, not a web service. Direct function calls are appropriate.
+
+3. **OAuth:** Not needed for LSP protocol.

package/docs/MCP_INTERACTION_GUIDE.md

@@ -0,0 +1,201 @@
+# MCP Client–Server Interaction Guide
+
+This guide describes how MCP (Model Context Protocol) clients and servers interact, the two stdio framing styles, and how to access the **sysml-v2-lsp** MCP server from code.
+
+## 1. Lifecycle
+
+MCP follows a fixed handshake before any tool or resource calls:
+
+```
+Client                          Server
+   |                               |
+   |  initialize (request)         |
+   |------------------------------>|
+   |  initialize (response)        |
+   |<------------------------------|
+   |  notifications/initialized   |
+   |------------------------------>|
+   |                               |
+   |  tools/call, etc.             |
+   |<=============================>|
+```
+
+1. **Initialize request**  
+   Client sends a JSON-RPC request with `method: "initialize"` and params: `protocolVersion`, `capabilities`, `clientInfo`.  
+   Example: `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}`
+
+2. **Initialize response**  
+   Server replies with the same `id`, `result` with `serverInfo`, `capabilities`, and `protocolVersion`.
+
+3. **Initialized notification**  
+   Client sends a notification (no `id`): `{"jsonrpc":"2.0","method":"notifications/initialized"}`.  
+   Only after this may the client send other requests (e.g. `tools/call`).
+
+4. **Operation**  
+   Client calls `tools/call` with `name` and `arguments`; server returns `result.content` (e.g. `[{ type: "text", text: "<json>" }]`).
+
+References: [MCP Lifecycle](https://modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle), [Building a client (Node)](https://modelcontextprotocol.io/tutorials/building-a-client-node).
+
+---
+
+## 2. Stdio transport: two framing styles
+
+Over stdio, the **framing** (how messages are delimited) must match between client and server.
+
+### 2.1 Newline-delimited (MCP spec / SDK)
+
+- **Format:** One JSON-RPC message per line. Each message is `JSON.stringify(msg)` followed by `\n`. No embedded newlines.
+- **Used by:** Official [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) **client** and **server** (e.g. [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)).
+- **Client in code:** Use the SDK’s `Client` and `StdioClientTransport`; they handle framing and lifecycle.
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({ command: "node", args: ["server.js"] });
+const client = new Client({ name: "my-client", version: "1.0.0" }, { capabilities: {} });
+await client.connect(transport);
+// then: client.request({ method: "tools/call", params: { name, arguments } }, schema)
+```
+
+### 2.2 Content-Length (LSP-style)
+
+- **Format:** For each message: a header line `Content-Length: <N>` (and optional other headers), then `\r\n\r\n`, then exactly N bytes of UTF-8 JSON. Same as LSP.
+- **Used by:** **sysml-v2-lsp** MCP server (its bundled transport uses this format).
+- **Client in code:** A custom client that sends and parses this framing (e.g. this repo’s `createSysmlMcpClient()`).
+- **MCP Client Pattern:** Even though we use LSP protocol messages (`textDocument/documentSymbol`), the client follows MCP client lifecycle patterns (initialize → initialized → requests). See [MCP client template](https://github.com/andrea9293/mcp-client-template) for reference. We can’t use `@modelcontextprotocol/sdk` `StdioClientTransport` directly because it expects newline-delimited JSON, not Content-Length framing.
+
+| Server / client          | Framing          | Use in code                          |
+|--------------------------|------------------|--------------------------------------|
+| modelcontextprotocol/servers, SDK demos | Newline-delimited | SDK `Client` + `StdioClientTransport` |
+| sysml-v2-lsp             | Content-Length   | `createSysmlMcpClient()` (this repo) |
+
+---
+
+## 3. How Cursor runs the MCP server
+
+Cursor starts the server as a **subprocess** from the **project root** (the folder that contains `.cursor/mcp.json`):
+
+- **Config:** In `.cursor/mcp.json`, `mcpServers.<name>.command` and `args` (and optional `cwd`).
+- **Example (sysml-v2):**  
+  `"command": "node"`,  
+  `"args": ["node_modules/sysml-v2-lsp/dist/server/mcpServer.js"]`  
+  with **cwd** = project root so `node_modules` resolves.
+- On Windows, if the OS would open `.js` with another app, the same process is often run via `cmd /c node ...` so Node executes the script.
+
+Cursor’s client then talks to that process over stdio using whatever framing the server expects (for sysml-v2-lsp, Content-Length).
+
+---
+
+## 4. sysml-v2-lsp server
+
+- **Package:** [sysml-v2-lsp](https://www.npmjs.com/package/sysml-v2-lsp) (npm); LobeHub: [daltskin-sysml-v2-lsp](https://lobehub.com/zh-TW/mcp/daltskin-sysml-v2-lsp).
+- **Two entry points:**
+  - **MCP:** `node_modules/sysml-v2-lsp/dist/server/mcpServer.js` — used by Cursor MCP and by this repo’s `createSysmlMcpClient()` (tools: parse, validate, getSymbols, etc.).
+  - **LSP:** `node_modules/sysml-v2-lsp/dist/server/server.js` — used by the **analyze** (index) CLI via `SYSMLLSP_SERVER_PATH`; same Content-Length framing, different protocol (LSP documentSymbol, etc.).
+- **Transport:** **Content-Length** framing on stdin/stdout (LSP-style) for both.
+- **Tools (MCP examples):** `parse`, `validate`, `getDiagnostics`, `diagnostics`, `validateFile`, `getSymbols`, `getDefinition`, `getReferences`, `getHierarchy`, `getModelSummary`, `getComplexity`, `preview`.
+
+---
+
+## 5. Accessing sysml-v2-lsp from code
+
+### 5.1 From Cursor (MCP tools)
+
+When the **sysml-v2** MCP server is enabled in this project, Cursor can call its tools directly. No extra code: use the MCP tool API with server name and `tools/call` (e.g. `parse`, `validate`). This is the most reliable way to “access” the server in practice.
+
+### 5.2 Programmatic client (this repo)
+
+For scripts or tests, use the **SysML MCP client** that speaks Content-Length and the same lifecycle as above:
+
+```ts
+import { createSysmlMcpClient, getMcpServerPath } from "./parser/sysml-mcp-client.js";
+
+const client = await createSysmlMcpClient();
+try {
+  const result = await client.parse(code, "file:///example.sysml");
+  console.log(result);
+  const valid = await client.validate(code, "file:///example.sysml");
+  console.log(valid);
+} finally {
+  client.close();
+}
+```
+
+- **Options:** `createSysmlMcpClient({ serverPath?, initTimeout?, debug? })`.  
+  - `serverPath`: defaults to `getMcpServerPath()` (from `sysml-v2-lsp` package or `node_modules/.../mcpServer.js`).  
+  - `initTimeout`: ms to wait for initialize response (default 20000).  
+  - `debug`: log raw stdout/stderr.
+- **Spawn:** Server is started with `process.execPath` (node) and `serverPath`, **cwd = process.cwd()** (project root), so behaviour matches Cursor. On Windows, the client may use `cmd /c node <path>` if needed to avoid the OS opening `.js` with another app.
+- **Framing:** Content-Length only (required for sysml-v2-lsp). Do not use the SDK’s `StdioClientTransport` for sysml-v2-lsp; it uses newline-delimited and will not interoperate.
+
+### 5.3 Example and access scripts
+
+From repo root after `npm run build`:
+
+```bash
+node scripts/example-sysml-mcp.mjs
+node scripts/access-sysml-mcp.mjs
+```
+
+- **example-sysml-mcp.mjs** — Calls `parse`, `validate`, and `getSymbols` on a small snippet.
+- **access-sysml-mcp.mjs** — Same idea; use `--debug` to log server stdout/stderr. Optional `initTimeout` (default 30s) can be increased in code if the server is slow to start.
+
+**If the script hits “initialize timeout”:**  
+When the MCP server is started from a Node script, it may not send the initialize response in time (cold start, stdout buffering, or load). In that case:
+
+1. **Use Cursor MCP** — With the sysml-v2 server enabled in `.cursor/mcp.json`, call the tools from Cursor (e.g. via the MCP tool API). This is the most reliable way to use the server.
+2. **Increase `initTimeout`** — e.g. `createSysmlMcpClient({ initTimeout: 60000 })`.
+3. **Run from the same conditions as Cursor** — Same working directory and `node`; the client already uses `cwd: process.cwd()` to match.
+
+---
+
+## 6. Index and graph map (LSP, not MCP)
+
+Indexing and generating the graph map use the **LSP** server (`server.js`), not the MCP server. The CLI runs `analyze` (which spawns the LSP and uses documentSymbol), then you can run `generate-map` to produce a markdown map.
+
+- **Kuzu:** The graph DB is backed by [kuzu](https://www.npmjs.com/package/kuzu). Ensure it is built: run `npm install` without `--ignore-scripts`, or `node node_modules/kuzu/install.js` so that `index.js` / `index.mjs` and the native addon are present. Without this, analyze and generate-map will fail with module-not-found.
+- **LSP path:** The canonical LSP for this repo is in **`lsp/`**. Run **`npm run setup-lsp`** (or `cd lsp && npm install`) once; the indexer then uses `lsp/node_modules/sysml-v2-lsp/dist/server/server.js` by default (then root `node_modules/...` as fallback). No need to set **`SYSMLLSP_SERVER_PATH`** when using the default. See docs/PLAN_INDEPENDENT_LSP.md.
+- **Commands (from repo root, after `npm run build`):**
+  - `npm run index-and-map` — Index default path `test/fixtures/sysml`, then write **graph-map.md**.
+  - `npm run index-and-map <path>` — Index the given path, then generate the map.
+  - `npm run generate-map [outFile]` — Generate map only (reads from existing DB under `~/.sysmledgraph/db/` or `SYSMEDGRAPH_STORAGE_ROOT`).
+- **Output:** `graph-map.md` (or the file you pass to generate-map) lists documents, nodes by label, and edges (interconnection view).
+
+**Why no edges (interconnection empty)?**  
+Edges come from **symbols** (Package, PartDef, etc.). The indexer gets symbols via the LSP **textDocument/documentSymbol** request. If the LSP returns no symbols (or only symbols we don’t map to a label), you get Document nodes but no symbol nodes and no edges.
+
+- **Optional MCP fallback:** Set **`SYSMEDGRAPH_USE_MCP_SYMBOLS=1`** and run index-and-map again. When the LSP returns no symbols, the indexer will try the **MCP** `getSymbols` tool (same sysml-v2-lsp server, different API). If the MCP returns symbols, they are mapped to nodes and edges. Note: spawning the MCP server from a script can be slow or hit init timeouts; if that happens, use Cursor MCP for ad‑hoc symbol queries and rely on the LSP for indexing when your LSP build supports documentSymbol.
+- **LSP behaviour:** Some builds of sysml-v2-lsp may not implement `documentSymbol` or may return a different response shape. We now pass `rootUri` and `workspaceFolders` in initialize and support both array and wrapped `{ data: [] }` responses; we also map LSP **SymbolKind** (number) to a label when `detail` is missing.
+
+---
+
+## 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. Troubleshooting
+
+| Issue | What to do |
+|-------|------------|
+| **No edges in graph-map.md** | Edges come from LSP (or MCP fallback) symbols. Ensure **SYSMLLSP_SERVER_PATH** points to a built `server.js` (with `--stdio`). Run `node scripts/debug-lsp-symbols.mjs <file.sysml>` to see raw LSP output. Use **DEBUG_SYSMLEGRAPH_SYMBOLS=1** when indexing to see if LSP or MCP is used. |
+| **LSP server not found** | Run `npm install` (or in `lsp/` for a dedicated install). On Windows, if install fails use `npm install --ignore-scripts` then build; set **SYSMLLSP_SERVER_PATH** to your built `dist/server/server.js`. |
+| **Kuzu "Could not set lock on file"** | Only one process can open the same DB. Close Cursor (or disable the sysmledgraph MCP) before running CLI analyze/export, or use a different **SYSMEDGRAPH_STORAGE_ROOT** (e.g. a temp folder) for the run. |
+| **Validate a SysML file** | `node scripts/validate-sysml-file.mjs <path-to.sysml>`. Exit 0 = no issues; exit 1 = syntax/semantic issues or script error. Requires sysml-v2-lsp MCP server (same as indexing). |
+
+---
+
+## 9. Summary
+
+| Goal                         | Approach                                                                 |
+|-----------------------------|---------------------------------------------------------------------------|
+| Understand MCP interaction | Lifecycle: initialize → response → notifications/initialized → tools/call |
+| Talk to standard MCP servers| SDK `Client` + `StdioClientTransport` (newline-delimited)                 |
+| Talk to sysml-v2-lsp        | Content-Length client; in this repo: `createSysmlMcpClient()`            |
+| Use from Cursor             | Enable sysml-v2 in `.cursor/mcp.json` and call MCP tools                 |
+| Use from Node/scripts       | `createSysmlMcpClient()` and call methods; run from project root         |
+| Index and see the map       | LSP (`server.js`); kuzu built; `npm run index-and-map` (see §6)          |
+| Validate a file             | `node scripts/validate-sysml-file.mjs <path>` (exit 0/1)                 |

package/docs/MCP_SERVER_FOR_CURSOR.md

@@ -0,0 +1,124 @@
+# MCP Server for Cursor AI
+
+This repo works as an **MCP server** so Cursor (and other MCP clients) can use the SysML knowledge graph: query symbols, context, impact, generate map, index paths, and run Cypher.
+
+## 1. What the server provides
+
+- **Server name:** `sysmledgraph`
+- **Transport:** stdio (Cursor spawns the process and talks over stdin/stdout)
+- **Tools:** indexDbGraph, list_indexed, clean_index, cypher, query, context, impact, rename, generate_map
+- **Resources:** `sysmledgraph://context`, `sysmledgraph://schema` (and per-path variants when paths are indexed)
+
+Cursor AI can call these tools when you ask about your SysML model (e.g. “what uses Modelbase?”, “show me the graph map”, “list symbols in the deploy model”).
+
+## 2. Prerequisites
+
+1. **Index at least one path** so the graph has data. Either:
+   - **CLI:** `npx sysmledgraph analyze <path>` (e.g. `modelbase-development/models`), or
+   - **MCP tool:** After the server is running in Cursor, use the **indexDbGraph** tool with the same path(s).
+2. **Kuzu:** Built (e.g. `npm install` without `--ignore-scripts`). See docs/INSTALL_NOTES.md if needed.
+3. **LSP:** For indexing, the LSP is in **`lsp/`**. Run **`npm run setup-lsp`** (or `cd lsp && npm install`) once; it is then picked automatically. No need to set **SYSMLLSP_SERVER_PATH** if the server isn’t in the default location (see docs/PLAN_INDEPENDENT_LSP.md).
+
+## 3. Enable in Cursor
+
+Add the sysmledgraph MCP server to Cursor’s MCP config.
+
+**Option A — Project-local (this repo as workspace)**
+
+Create or edit **`.cursor/mcp.json`** in the project root:
+
+```json
+{
+  "mcpServers": {
+    "sysmledgraph": {
+      "command": "node",
+      "args": ["dist/mcp/index.js"],
+      "cwd": ".",
+      "env": {
+        "SYSMEDGRAPH_STORAGE_ROOT": "C:/Users/YOU/.sysmledgraph"
+      }
+    }
+  }
+}
+```
+
+- **cwd** must be the **workspace root** (where `dist/` and the indexed paths live). Use `"."` when opening this repo as the workspace.
+- **SYSMEDGRAPH_STORAGE_ROOT:** Default is `~/.sysmledgraph`. Set to a custom path if you use one for the CLI.
+- **SYSMLLSP_SERVER_PATH (optional):** Only if not using the default. When running from this repo, the LSP in **`lsp/`** is used automatically after **`npm run setup-lsp`**.
+
+**Option B — Absolute path to built server**
+
+If the built server lives elsewhere (e.g. a global tools folder):
+
+```json
+{
+  "mcpServers": {
+    "sysmledgraph": {
+      "command": "node",
+      "args": ["C:/path/to/sysmledgraph/dist/mcp/index.js"],
+      "env": {
+        "SYSMEDGRAPH_STORAGE_ROOT": "C:/Users/YOU/.sysmledgraph"
+      }
+    }
+  }
+}
+```
+
+**Option C — npx (when published)**
+
+```json
+{
+  "mcpServers": {
+    "sysmledgraph": {
+      "command": "npx",
+      "args": ["-y", "sysmledgraph-mcp"]
+    }
+  }
+}
+```
+
+After saving, (re)start Cursor or reload MCP so it picks up the new server.
+
+## 4. Tools Cursor AI can use
+
+| Tool | Purpose |
+|------|--------|
+| **list_indexed** | List indexed root paths (so AI knows what’s in the graph). |
+| **query** | Concept search over symbol names/labels; optional `kind` filter (e.g. PartDef, Package). |
+| **context** | 360° view for one symbol: node + edges (IN_DOCUMENT, IN_PACKAGE, etc.). |
+| **impact** | Blast radius: upstream (what references this) or downstream (what this references). |
+| **generate_map** | Get Markdown of the graph (documents, nodes by label, interconnection edges). |
+| **cypher** | Run a Cypher query on the graph (advanced). |
+| **indexDbGraph** | Index path(s) (same as CLI analyze). Use when the graph is empty or you add a new folder. |
+| **clean_index** | Remove index for one path or all. |
+| **rename** | Preview or perform a symbol rename across the graph. |
+
+For “show the map of this file” or “what depends on X”, the AI can call **generate_map** or **context** / **impact** after **list_indexed** to see what’s available.
+
+## 5. Storage and LSP
+
+- **Storage:** Same as CLI. Default `~/.sysmledgraph`; override with **SYSMEDGRAPH_STORAGE_ROOT**. The MCP server uses the same DB as `sysmledgraph analyze` and `scripts/generate-map.mjs`.
+- **LSP:** Used by **indexDbGraph** and CLI analyze. The canonical LSP is in **`lsp/`**. Run **`npm run setup-lsp`** once; the indexer then uses it by default (no **SYSMLLSP_SERVER_PATH** needed). If unset and lsp/ not installed, indexing falls back to MCP getSymbols.
+
+## 6. Kuzu lock
+
+Only one process can open the same Kuzu DB at a time. If the sysmledgraph MCP is running in Cursor, it holds the DB open. To run **CLI** analyze or **scripts/export-graph.mjs** / **generate-map.mjs** without “Could not set lock on file”, either:
+
+- Close Cursor (or disable the sysmledgraph MCP), run the CLI/script, then reopen Cursor, or  
+- Use a **different** **SYSMEDGRAPH_STORAGE_ROOT** for the CLI run (e.g. a temp folder), then point the MCP at the same root if you want Cursor to see that data.
+
+See **docs/MCP_INTERACTION_GUIDE.md** §8 Troubleshooting and **docs/MCP-AND-KUZU.md** (if present).
+
+## 7. Checklist
+
+1. `npm install` and `npm run build` in this repo.
+2. Run **`npm run setup-lsp`** (or `cd lsp && npm install`) so the LSP used for indexing is installed in **`lsp/`**.
+3. Index at least one path: `npx sysmledgraph analyze modelbase-development/models` (or use **indexDbGraph** after MCP is on).
+4. Add **sysmledgraph** to `.cursor/mcp.json` with `command`/`args`/`cwd`/`env` as above.
+5. Restart Cursor or reload MCP; confirm the server appears (e.g. in Cursor MCP settings).
+6. In chat, ask e.g. “List indexed paths for sysmledgraph”, “Show the graph map”, “What is the context of Modelbase?” to confirm tools work.
+
+## 8. Next (optional)
+
+- **Prompts:** Add a Cursor rule or AGENTS.md note so the AI knows to use sysmledgraph tools for SysML/graph questions.
+- **Resources:** Expose `sysmledgraph://context` or `sysmledgraph://schema` in Cursor so the AI can pull index stats and schema when relevant.

package/docs/PLAN.md

@@ -0,0 +1,58 @@
+# Plan: LSP Client Fixes & Indexing
+
+**Released:** v0.4.3 (2026-03-19) — see `release-notes-v0.4.3.md`.
+
+## Current Status
+
+✅ **Completed:**
+- Fixed LSP client: added `--stdio` flag, Windows spawn (`cmd /c`), timeouts, error handling
+- Created `lsp/` folder with dedicated npm install for isolated LSP server init
+- Added MCP fallback: when LSP returns no symbols, automatically tries MCP `getSymbols` (shared client per index run)
+- Added LSP capabilities: `hierarchicalDocumentSymbolSupport`, `workspaceFolders`
+- Added SymbolInformation support: normalize flat list with `containerName` to DocumentSymbol-like shape
+- Added LSP SymbolKind fallback: map numeric `kind` to label when `detail` is missing
+- Enhanced symbol mapping: added MCP-style kind strings ("Part Definition", etc.) with normalized lookup
+- Analyzed MCP client template patterns
+- **✅ Phase 1 Complete:** LSP client returns symbols; graph has symbol nodes and edges (IN_DOCUMENT, IN_PACKAGE)
+- **✅ Phase 2 Complete:** LSP notification handler (e.g. `window/logMessage` when `DEBUG_LSP_NOTIFICATIONS=1`); indexed `modelbase-development/models/`; `graph-map.md` generated with full nodes and interconnection table
+- **✅ CLI exit fix:** (1) Explicit graph store close in `cmdAnalyze` (try/finally). (2) After successful analyze, CLI calls `process.exit(0)` so the process exits before Node/Kuzu teardown (avoids Windows access violation). Verified: `node scripts/index-and-map.mjs test/fixtures/sysml` completes with exit 0 and writes `graph-map.md`.
+
+## Plan
+
+### Phase 1: Test & Verify — ✅ Done
+
+1. Rebuild and test LSP client; run index-and-map.
+2. Verify `graph-map.md` has symbol nodes and edges.
+3. Debug LSP/MCP via `scripts/debug-lsp-symbols.mjs` if needed.
+
+### Phase 2: Notification Handlers & Larger Models — ✅ Done
+
+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 — ✅ Done
+
+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 — ✅ Done
+
+8. **Validate the requested file** — `scripts/validate-sysml-file.mjs` calls MCP `validate`; reports syntax errors and semantic issues; exit 0 if valid/no issues, 1 otherwise. Init/read failures handled with clear errors.
+9. **Documentation** — v0.4.3: fixes in `MCP_INTERACTION_GUIDE.md`, "no edges" and §6. **Phase 4:** MCP_INTERACTION_GUIDE §8 Troubleshooting (no edges, LSP not found, Kuzu lock, validate script); §9 Summary includes validate.
+
+## MCP server for Cursor AI
+
+So Cursor AI can use the graph, the repo runs as an **MCP server** (stdio). See **docs/MCP_SERVER_FOR_CURSOR.md** for the full plan.
+
+- **Entrypoint:** `mcp/index.ts` → `dist/mcp/index.js`; bin `sysmledgraph-mcp` and `npm run mcp`.
+- **Cursor:** Add **sysmledgraph** to `.cursor/mcp.json` (command `node`, args `dist/mcp/index.js`, cwd `.`). Example added in this repo’s `.cursor/mcp.json`.
+- **Tools:** indexDbGraph, list_indexed, clean_index, cypher, query, context, impact, rename, generate_map. Resources: sysmledgraph://context, sysmledgraph://schema.
+- **Prereq:** Index at least one path (CLI or indexDbGraph); same storage as CLI. Kuzu lock: only one process per DB (see Troubleshooting in MCP_INTERACTION_GUIDE).
+
+## Success Criteria
+
+- ✅ `graph-map.md` shows symbol nodes (Package, PartDef, Action, etc.) not just Document
+- ✅ Interconnection table has edges (IN_DOCUMENT, IN_PACKAGE)
+- ✅ Indexing writes data correctly (LSP + optional MCP fallback)
+- ✅ Validation script: `node scripts/validate-sysml-file.mjs <path>` (exit 0/1)
+- ✅ MCP server runnable via `npx sysmledgraph-mcp`; Cursor can use tools when configured (see MCP_SERVER_FOR_CURSOR.md)