|
| 1 | +# MCP Server for Cursor AI |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## 1. What the server provides |
| 6 | + |
| 7 | +- **Server name:** `sysmledgraph` |
| 8 | +- **Transport:** stdio (Cursor spawns the process and talks over stdin/stdout) |
| 9 | +- **Tools:** indexDbGraph, list_indexed, clean_index, cypher, query, context, impact, rename, generate_map |
| 10 | +- **Resources:** `sysmledgraph://context`, `sysmledgraph://schema` (and per-path variants when paths are indexed) |
| 11 | + |
| 12 | +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”). |
| 13 | + |
| 14 | +## 2. Prerequisites |
| 15 | + |
| 16 | +1. **Index at least one path** so the graph has data. Either: |
| 17 | + - **CLI:** `npx sysmledgraph analyze <path>` (e.g. `modelbase-development/models`), or |
| 18 | + - **MCP tool:** After the server is running in Cursor, use the **indexDbGraph** tool with the same path(s). |
| 19 | +2. **Kuzu:** Built (e.g. `npm install` without `--ignore-scripts`). See docs/INSTALL_NOTES.md if needed. |
| 20 | +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). |
| 21 | + |
| 22 | +## 3. Enable in Cursor |
| 23 | + |
| 24 | +Add the sysmledgraph MCP server to Cursor’s MCP config. |
| 25 | + |
| 26 | +**Option A — Project-local (this repo as workspace)** |
| 27 | + |
| 28 | +Create or edit **`.cursor/mcp.json`** in the project root: |
| 29 | + |
| 30 | +```json |
| 31 | +{ |
| 32 | + "mcpServers": { |
| 33 | + "sysmledgraph": { |
| 34 | + "command": "node", |
| 35 | + "args": ["dist/mcp/index.js"], |
| 36 | + "cwd": ".", |
| 37 | + "env": { |
| 38 | + "SYSMEDGRAPH_STORAGE_ROOT": "C:/Users/YOU/.sysmledgraph" |
| 39 | + } |
| 40 | + } |
| 41 | + } |
| 42 | +} |
| 43 | +``` |
| 44 | + |
| 45 | +- **cwd** must be the **workspace root** (where `dist/` and the indexed paths live). Use `"."` when opening this repo as the workspace. |
| 46 | +- **SYSMEDGRAPH_STORAGE_ROOT:** Default is `~/.sysmledgraph`. Set to a custom path if you use one for the CLI. |
| 47 | +- **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`**. |
| 48 | + |
| 49 | +**Option B — Absolute path to built server** |
| 50 | + |
| 51 | +If the built server lives elsewhere (e.g. a global tools folder): |
| 52 | + |
| 53 | +```json |
| 54 | +{ |
| 55 | + "mcpServers": { |
| 56 | + "sysmledgraph": { |
| 57 | + "command": "node", |
| 58 | + "args": ["C:/path/to/sysmledgraph/dist/mcp/index.js"], |
| 59 | + "env": { |
| 60 | + "SYSMEDGRAPH_STORAGE_ROOT": "C:/Users/YOU/.sysmledgraph" |
| 61 | + } |
| 62 | + } |
| 63 | + } |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +**Option C — npx (when published)** |
| 68 | + |
| 69 | +```json |
| 70 | +{ |
| 71 | + "mcpServers": { |
| 72 | + "sysmledgraph": { |
| 73 | + "command": "npx", |
| 74 | + "args": ["-y", "sysmledgraph-mcp"] |
| 75 | + } |
| 76 | + } |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +After saving, (re)start Cursor or reload MCP so it picks up the new server. |
| 81 | + |
| 82 | +## 4. Tools Cursor AI can use |
| 83 | + |
| 84 | +| Tool | Purpose | |
| 85 | +|------|--------| |
| 86 | +| **list_indexed** | List indexed root paths (so AI knows what’s in the graph). | |
| 87 | +| **query** | Concept search over symbol names/labels; optional `kind` filter (e.g. PartDef, Package). | |
| 88 | +| **context** | 360° view for one symbol: node + edges (IN_DOCUMENT, IN_PACKAGE, etc.). | |
| 89 | +| **impact** | Blast radius: upstream (what references this) or downstream (what this references). | |
| 90 | +| **generate_map** | Get Markdown of the graph (documents, nodes by label, interconnection edges). | |
| 91 | +| **cypher** | Run a Cypher query on the graph (advanced). | |
| 92 | +| **indexDbGraph** | Index path(s) (same as CLI analyze). Use when the graph is empty or you add a new folder. | |
| 93 | +| **clean_index** | Remove index for one path or all. | |
| 94 | +| **rename** | Preview or perform a symbol rename across the graph. | |
| 95 | + |
| 96 | +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. |
| 97 | + |
| 98 | +## 5. Storage and LSP |
| 99 | + |
| 100 | +- **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`. |
| 101 | +- **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. |
| 102 | + |
| 103 | +## 6. Kuzu lock |
| 104 | + |
| 105 | +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: |
| 106 | + |
| 107 | +- Close Cursor (or disable the sysmledgraph MCP), run the CLI/script, then reopen Cursor, or |
| 108 | +- 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. |
| 109 | + |
| 110 | +See **docs/MCP_INTERACTION_GUIDE.md** §8 Troubleshooting and **docs/MCP-AND-KUZU.md** (if present). |
| 111 | + |
| 112 | +## 7. Checklist |
| 113 | + |
| 114 | +1. `npm install` and `npm run build` in this repo. |
| 115 | +2. Run **`npm run setup-lsp`** (or `cd lsp && npm install`) so the LSP used for indexing is installed in **`lsp/`**. |
| 116 | +3. Index at least one path: `npx sysmledgraph analyze modelbase-development/models` (or use **indexDbGraph** after MCP is on). |
| 117 | +4. Add **sysmledgraph** to `.cursor/mcp.json` with `command`/`args`/`cwd`/`env` as above. |
| 118 | +5. Restart Cursor or reload MCP; confirm the server appears (e.g. in Cursor MCP settings). |
| 119 | +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. |
| 120 | + |
| 121 | +## 8. Next (optional) |
| 122 | + |
| 123 | +- **Prompts:** Add a Cursor rule or AGENTS.md note so the AI knows to use sysmledgraph tools for SysML/graph questions. |
| 124 | +- **Resources:** Expose `sysmledgraph://context` or `sysmledgraph://schema` in Cursor so the AI can pull index stats and schema when relevant. |
0 commit comments