Initial commit: SysML indexer, Kuzu graph, MCP server, CLI, viewer

- Discovery (find-sysml, load-order), parser (sysml-v2-lsp), symbol-to-graph mapping
- Kuzu graph store (.kuzu path), registry, list/clean
- CLI: analyze, list, clean; path normalization and .kuzu DB path
- MCP: indexDbGraph, list_indexed, clean_index, cypher, query, context, impact, rename
- Scripts: export-graph, query-one, debug-index; viewer/view.html for graph viz
- Docs: grammar-and-mapping, detailed README usage
- Tests: discovery, graph-store, integration (parser mocked)

Made-with: Cursor

Author: chouswei

.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+*.log
+.env
+.sysmledgraph/
+graph-export.json

.nvmrc

@@ -0,0 +1 @@
+20

README.md

@@ -0,0 +1,172 @@
+# sysmledgraph
+
+Path-only SysML indexer: builds a knowledge graph from `.sysml` files and exposes it via **MCP** (query, context, impact, rename, cypher, list, clean) and **CLI** (analyze, list, clean). Follows the [GitNexus](https://github.com/abhigyanpatwari/GitNexus) pattern (Kuzu graph, MCP tools) but indexes SysML only; grouping is SysML-native.
+
+**Design and plan:** SysML v2 model and development plan live in a separate repo (`sysml-v2-models/projects/sysmledgraph`). This repo is the implementation.
+
+## Requirements
+
+- **Node.js 20+** (see `.nvmrc`)
+
+## Libraries
+
+| Library | Purpose |
+|--------|--------|
+| **[Kuzu](https://kuzudb.com/)** (`kuzu`) | Embedded property graph database; Cypher queries; stores SysML nodes and edges. |
+| **[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)** | MCP server (stdio), tool and resource registration; used for the sysmledgraph MCP server. |
+| **[Commander](https://github.com/tj/commander.js)** (`commander`) | CLI subcommands: `analyze`, `list`, `clean`. |
+| **[fast-glob](https://github.com/mrmlnc/fast-glob)** | File discovery: find all `.sysml` / `.kerml` under path(s). |
+| **[Zod](https://github.com/colinhacks/zod)** | Schema validation for MCP tool parameters. |
+| **[sysml-v2-lsp](https://github.com/daltskin/sysml-v2-lsp)** | SysML v2 parser via LSP stdio; **required** for indexing. Provides document symbols (Package, PartDef, PartUsage, etc.) and IN_DOCUMENT / IN_PACKAGE edges. |
+
+**sysml-v2-lsp (required)**  
+After `npm install`, build the LSP once:  
+`cd node_modules/sysml-v2-lsp && npm run build`  
+Or set **SYSMLLSP_SERVER_PATH** to your built `dist/server/server.js`. Indexing will fail with a clear error if the LSP is not found.
+
+*Dev:* TypeScript, Vitest, @types/node.
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+### CLI
+
+Run from the project root (after `npm run build`) or via `npx sysmledgraph` if linked/published.
+
+| Command | Description |
+|--------|-------------|
+| **analyze** `<paths...>` | Index one or more directory trees: discover `.sysml` and `.kerml`, parse via LSP, build the graph. Paths are resolved to absolute and stored in the registry. |
+| **list** | Print all indexed root paths (from the registry). |
+| **clean** `[path]` | Remove the index for a given path, or for **all** indexed paths if `path` is omitted. Deletes the DB file and registry entry. |
+
+**Examples:**
+
+```bash
+# Index a single model directory
+npx sysmledgraph analyze ./path/to/sysml-models
+
+# Index multiple roots (each gets its own DB)
+npx sysmledgraph analyze ./repo1/models ./repo2/models
+
+# See what is indexed
+npx sysmledgraph list
+
+# Remove index for one path
+npx sysmledgraph clean ./path/to/sysml-models
+
+# Remove all indexed paths
+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).
+
+**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.
+
+---
+
+### MCP
+
+Server name: **sysmledgraph**. The MCP server uses the same storage root as the CLI (default `~/.sysmledgraph`), so tools operate on whatever paths you indexed via the CLI or via the **indexDbGraph** tool.
+
+**Setup (Cursor):** Add to `.cursor/mcp.json` or Cursor MCP settings.
+
+**Option A — local build:**
+
+```json
+{
+  "mcpServers": {
+    "sysmledgraph": {
+      "command": "node",
+      "args": ["C:/path/to/codebase-sysmledgraph/dist/mcp/index.js"],
+      "env": {
+        "SYSMEDGRAPH_STORAGE_ROOT": "C:/Users/you/.sysmledgraph",
+        "SYSMLLSP_SERVER_PATH": "C:/path/to/sysml-v2-lsp/dist/server/server.js"
+      }
+    }
+  }
+}
+```
+
+**Option B — npx (when published):**
+
+```json
+{
+  "mcpServers": {
+    "sysmledgraph": {
+      "command": "npx",
+      "args": ["-y", "sysmledgraph-mcp"]
+    }
+  }
+}
+```
+
+**Tools:**
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| **indexDbGraph** | `path` (string) or `paths` (string[]) | Build the graph for the given path(s). Same logic as CLI `analyze`. Uses first indexed path if none given (no-op). |
+| **list_indexed** | — | Return the list of indexed root paths (same as CLI `list`). |
+| **clean_index** | `path` (string, optional) | Remove index for one path or all (same as CLI `clean`). |
+| **cypher** | `query` (string) | Run a Cypher query on the graph for the **first** indexed path. Example: `MATCH (n:Node) RETURN n.id, n.label LIMIT 10`. |
+| **query** | `query` (string), `kind` (string, optional) | Concept search over node names/labels. Filters by node label if `kind` is set. |
+| **context** | `name` (string) | Get one node by id or name and its adjacent edges (types and targets). |
+| **impact** | `target` (string), `direction` (`"upstream"` \| `"downstream"`, optional) | List nodes that depend on `target` (upstream) or that `target` depends on (downstream). |
+| **rename** | `symbol` (string), `newName` (string), `dry_run` (boolean, optional) | Preview or perform a rename of a symbol across the graph. |
+
+**Resources:**
+
+- **sysmledgraph://context** — Index stats and list of indexed paths (Markdown).
+- **sysmledgraph://schema** — Graph node and edge schema (Markdown).
+
+Tools that need a graph (cypher, query, context, impact) use the **first** entry in the registry as the target DB. Ensure at least one path is indexed (CLI or indexDbGraph) before calling them.
+
+---
+
+### Querying the graph (scripts)
+
+For ad-hoc Cypher or exporting the graph without MCP:
+
+- **Run one Cypher query** (uses first indexed path, outputs JSON):
+
+  ```bash
+  node scripts/query-one.mjs "MATCH (n:Node) RETURN count(n) AS total"
+  node scripts/query-one.mjs "MATCH (n:Node) RETURN n.label, count(*) AS c ORDER BY c DESC LIMIT 5"
+  ```
+
+  The graph uses a single node table **Node**; always use the label in Cypher: `MATCH (n:Node) ...`.
+
+- **Export graph for viewing:** Run `npm run export-graph` (writes `graph-export.json` in the current directory). Open `viewer/view.html` in a browser, click “Load graph.json”, and select that file for a force-directed view; click a node for details. Custom output path: `node scripts/export-graph.mjs path/to/out.json`.
+
+## Project layout
+
+- `src/` — Core: indexer, graph, mcp, cli, discovery, parser, symbol-to-graph, storage.
+- `bin/cli.ts` — CLI entrypoint.
+- `mcp/index.ts` — MCP server entrypoint (stdio).
+- `test/` — Unit and integration tests.
+
+## Development
+
+- `npm run build` — Compile TypeScript.
+- `npm run test` — Run tests.
+- `npm run test:watch` — Watch mode.
+
+## View the graph
+
+See **Usage → Querying the graph (scripts)** for the full flow. Short version: `npm run export-graph` writes `graph-export.json`; open `viewer/view.html` in a browser and load that file for a force-directed graph (click nodes for id/label/path).
+
+## Schema (graph)
+
+Implemented with **Kuzu**: one `Node` table (id, name, path, label) and one rel table per edge type (Node→Node). Label values: Document, Package, PartDef, PartUsage, etc. Edge types: IN_DOCUMENT, IN_PACKAGE, PARENT, TYPES, REFERENCES, IMPORTS, SATISFY, DERIVE, VERIFY, BINDING, CONNECTION_END. See design doc (GITNEXUS_FEATURES.md) and deploy model.
+
+## License
+
+MIT

bin/cli.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * CLI entrypoint: analyze, list, clean.
+ */
+
+import { program } from 'commander';
+import {
+  configureStorageRoot,
+  cmdAnalyze,
+  cmdList,
+  cmdClean,
+} from '../src/cli/commands.js';
+
+program
+  .name('sysmledgraph')
+  .description('Path-only SysML indexer: knowledge graph, MCP server, CLI')
+  .option('--storage <path>', 'Storage root (default: ~/.sysmledgraph)', process.env.SYSMEDGRAPH_STORAGE_ROOT);
+
+program
+  .command('analyze <paths...>', { isDefault: true })
+  .description('Index path(s): discover .sysml, build graph')
+  .action(async (paths: string[]) => {
+    const opts = program.opts();
+    configureStorageRoot(opts.storage);
+    const result = await cmdAnalyze(paths);
+    if (!result.ok) {
+      process.stderr.write((result.error ?? 'Unknown error') + '\n');
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List indexed path(s)')
+  .action(async () => {
+    configureStorageRoot(program.opts().storage);
+    const result = await cmdList();
+    if (!result.ok) {
+      process.stderr.write((result.error ?? 'Unknown error') + '\n');
+      process.exit(1);
+    }
+    for (const p of result.paths) {
+      console.log(p);
+    }
+  });
+
+program
+  .command('clean [path]')
+  .description('Remove index for path or all')
+  .action(async (path?: string) => {
+    configureStorageRoot(program.opts().storage);
+    const result = await cmdClean(path);
+    if (!result.ok) {
+      process.stderr.write((result.error ?? 'Unknown error') + '\n');
+      process.exit(1);
+    }
+  });
+
+program.parse();

docs/.gitkeep

@@ -0,0 +1,54 @@
+# Grammar and symbol mapping
+
+## Two different things
+
+1. **SysML v2 language grammar** – The syntax of `.sysml` / `.kerml` (what is valid SysML). **Not in this repo.** It is defined and updated in the **sysml-v2-lsp** project (the LSP that does the actual parsing).
+2. **Symbol → graph mapping** – How LSP *output* (metaclass names, relation names) is turned into graph node labels and edge types in sysmledgraph. **This is in this repo** and is what you update when you want to index new metaclasses or relations.
+
+---
+
+## 1. Updating the SysML v2 language grammar
+
+Parsing is done by **sysml-v2-lsp** (dependency: `github:daltskin/sysml-v2-lsp`). To change what is *parsed* as valid SysML (new syntax, grammar fixes):
+
+- Work in the **sysml-v2-lsp** repository.
+- That project typically has a grammar (e.g. ANTLR `.g4` or similar) and a parser generated from it. Update the grammar there, regenerate the parser, and release or point `package.json` at your fork.
+- After updating the LSP, rebuild it (`npm run build` in the LSP repo or in `node_modules/sysml-v2-lsp`) and ensure **SYSMLLSP_SERVER_PATH** (if you use it) points to the new server binary.
+
+sysmledgraph does not contain or generate the SysML grammar; it only consumes the LSP’s document symbols.
+
+---
+
+## 2. Updating the symbol → graph mapping (in this repo)
+
+When the LSP returns **new metaclass names** or **new relation semantics**, you map them to the graph here.
+
+### Node labels (LSP metaclass → graph label)
+
+**File:** `src/symbol-to-graph/mapping.ts`
+
+- **`symbolKindToNodeLabel(kind)`** – `kind` is the LSP `DocumentSymbol.detail` (metaclass name from sysml-v2-lsp, e.g. `PartDefinition`, `RequirementUsage`). Add or change entries in the `map` object to support new metaclasses or rename labels.
+
+If you introduce a **new** graph label:
+
+1. Add it to **`NODE_LABELS`** in `src/types.ts`.
+2. Add the corresponding Kuzu schema in `src/graph/schema.ts` if you ever split into multiple node tables (currently there is a single `Node` table with a `label` property, so usually no schema change).
+3. Add the metaclass → label mapping in **`symbolKindToNodeLabel`** in `src/symbol-to-graph/mapping.ts`.
+
+### Edge types (LSP relation → graph edge type)
+
+**File:** `src/symbol-to-graph/mapping.ts`
+
+- **`relationToEdgeType(relation)`** – `relation` is the relation name from the LSP (e.g. `inDocument`, `inPackage`). Add or change entries to support new relations.
+
+If you introduce a **new** edge type:
+
+1. Add it to **`EDGE_TYPES`** in `src/types.ts`.
+2. The Kuzu schema in `src/graph/schema.ts` creates one rel table per `EDGE_TYPES` entry, so a new type will get a new table when the DB is (re)created.
+3. Add the relation name → edge type mapping in **`relationToEdgeType`** in `src/symbol-to-graph/mapping.ts`.
+
+### Where LSP output is used
+
+- **`src/parser/symbols.ts`** – Builds normalized symbols from LSP response; uses `symbolKindToNodeLabel(item.sym.detail ?? '')` and emits relations that are later mapped with `relationToEdgeType`.
+
+After editing mapping or types, run `npm run build` and re-index to see new nodes/edges in the graph.

docs/grammar-and-mapping.md

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * MCP server entrypoint (stdio). Server name: sysmledgraph.
+ * Tools: indexDbGraph, query, context, impact, rename, cypher, list_indexed, clean_index.
+ * Resources: sysmledgraph://context, sysmledgraph://schema.
+ */
+
+import { runStdio } from '../src/mcp/server.js';
+
+runStdio().catch((err) => {
+  process.stderr.write(String(err) + '\n');
+  process.exit(1);
+});