Source: requirements-sysmledgraph.sysml, deploy-sysmledgraph.sysml, behaviour-sysmledgraph.sysml, project-sysmledgraph.sysml.
All requirements live in package SysmledgraphRequirements. The deployment SysmledgraphDeployment satisfies all eight.
| Id | Requirement | Description |
|---|---|---|
| R1 | ReqPathOnlyInput | The tool SHALL accept path(s) only as input for indexing; no project name or concept. User groups in SysML (packages), not by project. |
| R2 | ReqSysMLGrouping | Grouping in the graph SHALL be SysML-native (packages, containment). Nodes: Document, Package, PartDef, PartUsage, ConnectionDef, ConnectionUsage, PortDef, Port, RequirementDef, etc. |
| R3 | ReqSameStorageAsGitNexus | Storage SHALL use the same embedded graph backend as GitNexus (e.g. Kuzu or LadybugDB). Only the schema differs (SysML node/edge types). Cypher supported. |
| R4 | ReqListAndClean | The tool SHALL provide list (indexed path(s)) and clean (delete index for path or all) for lifecycle and re-index. |
| R5 | ReqMCPTools | MCP SHALL expose query, context, impact, rename, cypher (and schema resource). Optional: list_indexed, clean_index as MCP tools. |
| R6 | ReqOneGraph | Multiple paths SHALL produce one merged graph; each Document has path so cypher can filter by path. |
| R7 | ReqLoadOrder | When config (e.g. config.yaml with model_files) exists at path, indexing SHALL use that order for parsing/resolution. Otherwise order SHALL be deterministic (e.g. breadth-first by path) so cross-file refs are consistent. |
| R8 | ReqErrorReporting | The tool SHALL report errors to the caller (MCP result or CLI stderr) for invalid path, parse failure, graph store failure, or invalid tool parameters; SHALL NOT leave the graph inconsistent on index/clean failure; on index failure previous graph content SHALL remain usable. |
Package structure: ProjectSysmledgraph imports SysmledgraphRequirements and Sysmledgraph (deploy); the deploy package imports SysmledgraphRequirements so the deployment can declare satisfy for each requirement.
All in package Sysmledgraph. Four part definitions form the system.
| Part | Role |
|---|---|
| Indexer | Discovers .sysml under path(s) (file discovery); applies load order (config when present); parses via sysml-v2-lsp; maps LSP symbol kinds to graph node labels and edge types (symbol→graph mapping); writes to GraphStore. Performs IndexDbGraph. |
| GraphStore | Abstraction over persistent graph (Kuzu/LadybugDB). API: addDocument, addSymbol, addEdge, getConnection. Nodes: Document, Package, PartDef, PartUsage, ConnectionDef, ConnectionUsage, PortDef, Port, RequirementDef, Block, ValueType, Action, StateMachine. Edges: IN_DOCUMENT, IN_PACKAGE, PARENT, TYPES, REFERENCES, IMPORTS, SATISFY, DERIVE, VERIFY, BINDING, CONNECTION_END. Satisfies ReqSameStorageAsGitNexus, ReqSysMLGrouping. |
| McpServer | MCP server (stdio). Exposes tools: query, context, impact, rename, cypher; list_indexed, clean_index. Resources: context (stats, staleness), schema. Reads from GraphStore. Satisfies ReqMCPTools. |
| Cli | CLI: one index command (build graph from path(s)), list, clean. Satisfies ReqListAndClean. |
SysmledgraphDeployment is the top-level part definition. It composes one instance of each part:
| Part slot | Type | Role in deployment |
|---|---|---|
| indexer | Indexer | Builds the graph from path(s); only writer of graph content for indexing. |
| graphStore | GraphStore | Single shared graph; stores documents and symbols; used by indexer (write), McpServer and Cli (read/write for list/clean). |
| mcpServer | McpServer | Exposes MCP tools and resources to agents (Cursor, etc.). |
| cli | Cli | Exposes analyze, list, clean to terminal users. |
Data flow (conceptual):
- Index: User/agent provides path(s) → Cli or McpServer → Indexer → (discovery → parse → symbol→graph) → GraphStore (addDocument, addSymbol, addEdge).
- Query / context / impact / rename / cypher: User/agent invokes MCP tool → McpServer → GraphStore (getConnection, Cypher or higher-level API).
- List: Cli or McpServer → storage/registry + GraphStore → list of indexed path(s).
- Clean: Cli or McpServer → delete DB for path(s) and update registry.
Satisfy (deployment level): SysmledgraphDeployment satisfies ReqPathOnlyInput, ReqSysMLGrouping, ReqSameStorageAsGitNexus, ReqListAndClean, ReqMCPTools, ReqOneGraph, ReqLoadOrder.
Behaviours are modelled as action definitions in package Sysmledgraph (MCP tools and CLI) and as a state machine in SysmledgraphBehaviour::SysmledgraphIndexStates (idle, indexing, ready, cleaning; error states indexingFailed, cleaningFailed with retry).
| Action | Primary performer | MCP tool | CLI | Parameters | Satisfies |
|---|---|---|---|---|---|
| IndexDbGraph | Indexer | indexDbGraph | analyze | path (string) or paths (string[]) | R1, R6, R7, R8 |
| Query | McpServer (uses GraphStore) | query | — | query (string), optional kind | R5 |
| Context | McpServer | context | — | name (symbol name) | R5 |
| Impact | McpServer | impact | — | target (name), direction (e.g. upstream/downstream) | R5 |
| Rename | McpServer | rename | — | symbol, newName, dry_run (boolean) | R5 |
| Cypher | McpServer | cypher | — | query (Cypher string) | R5 |
| ListIndexed | Cli / McpServer | list_indexed | list | (none) | R4 |
| CleanIndex | Cli / McpServer | clean_index | clean | optional path | R4, R8 |
IndexDbGraph
Build the knowledge graph from path(s). Finds all .sysml under path(s); applies load order (config.yaml model_files when present, else deterministic); parses via sysml-v2-lsp; maps symbols to nodes/edges. Re-index: replace or merge for that path (implementation documents which).
Satisfies: ReqPathOnlyInput, ReqOneGraph, ReqLoadOrder.
Query
Concept search over symbols. Uses the graph. Params: query (string), optional kind.
Context
360° view for one symbol: usages, types, satisfy/derive. Params: name (symbol name). Uses the graph.
Impact
Blast radius: what uses this element. Params: target (name), direction (e.g. upstream/downstream). Uses the graph.
Rename
Multi-file rename for defs (graph + text search). Params: symbol, newName, dry_run (boolean). Uses the graph.
Cypher
Raw Cypher over the graph. Params: query (Cypher string). Schema exposed via schema resource.
ListIndexed
List indexed path(s). No params. CLI: list; MCP: list_indexed.
Satisfies: ReqListAndClean.
CleanIndex
Delete index for path or all. Params: optional path. CLI: clean; MCP: clean_index.
Satisfies: ReqListAndClean.
| Requirement | Architecture (part) | Behaviour (action) |
|---|---|---|
| R1 Path-only input | Indexer (accepts path(s)); Cli, McpServer (pass path(s)) | IndexDbGraph |
| R2 SysML grouping | GraphStore (schema); Indexer (mapping) | (all graph operations) |
| R3 Same storage as GitNexus | GraphStore | (all graph operations) |
| R4 List and clean | Cli, McpServer | ListIndexed, CleanIndex |
| R5 MCP tools | McpServer | Query, Context, Impact, Rename, Cypher (+ ListIndexed, CleanIndex) |
| R6 One graph | GraphStore, Indexer (merge) | IndexDbGraph |
| R7 Load order | Indexer | IndexDbGraph |
| R8 Error reporting | — (all entrypoints report) | IndexDbGraph, CleanIndex (and read tools per call) |
| File | Package | Contents |
|---|---|---|
| requirements-sysmledgraph.sysml | SysmledgraphRequirements | R1–R8 (requirement definitions) |
| deploy-sysmledgraph.sysml | Sysmledgraph | Actions (8), ports, connections, part defs (4), SysmledgraphDeployment |
| behaviour-sysmledgraph.sysml | SysmledgraphBehaviour | Events (StartIndex, IndexComplete, StartClean, CleanComplete, IndexFailed, CleanFailed), SysmledgraphIndexStates (incl. indexingFailed, cleaningFailed) |
| project-sysmledgraph.sysml | ProjectSysmledgraph | Imports requirements, deploy, behaviour |
Diagrams: generate BDD/IBD from repo root with
python sysml-v2-models/scripts/visualize.py --project sysmledgraph --diagram bdd --format png (or ibd, all; svg, html).