sysml-v2-lsp 0.1.7 → 0.3.0

package/CHANGELOG.md

@@ -1,118 +1,84 @@
 # Changelog
 
-## [0.1.7]
+## [0.3.0]
 
 ### Added
 
-- Comprehensive keyword validator tests — 14 new parser tests covering all expanded `NAME_PRECEDING_KEYWORDS` categories: KerML element keywords, visibility/prefix modifiers, action control nodes, reference-preceding keywords, relationship keywords, directionality, succession/flow, annotation/membership, `message`/`transition`, colon/specialization punctuation, and `:=` assignment skip logic
-- `findTextReferences()` unit tests — 6 new tests covering whole-word matching, partial-word exclusion, line-comment skipping, block-comment skipping, empty results, and regex special character safety
-- Cross-file references test — verifies text-based reference scanning finds usages across multiple documents
-- `includeDeclaration` filtering test — verifies references provider correctly excludes the declaration when `includeDeclaration: false`
-- Reference deduplication test — verifies no duplicate locations are returned
-- Cross-file CodeLens test — verifies reference counts include usages from other documents
-
-### Fixed
-
-- Expand `NAME_PRECEDING_KEYWORDS` from ~25 to ~120 tokens — identifiers after KerML keywords (`type`, `classifier`, `datatype`, `class`, `struct`, `assoc`, `metaclass`, etc.), action control nodes (`fork`, `join`, `merge`, `decide`), relationship keywords (`redefines`, `subsets`, `specializes`, `conjugates`, `chains`, etc.), KerML relationship elements (`specialization`, `conjugation`, `disjoining`, `inverting`, etc.), requirement/state body keywords (`assume`, `require`, `frame`, `objective`, `entry`, `do`, `exit`), and punctuation tokens (`:`, `:>`, `:>>`, `::`, `::>`, `>`, `=>`, `~`, `,`, `#`) are no longer falsely flagged as keyword typos
-- Fix skip-punctuation logic in keyword validator — replace `:`, `::`, `:>`, `:>>` (now in `NAME_PRECEDING_KEYWORDS`) with `DOT`, `=`, `:=` as the only "value/path" skip tokens
-- Add `MESSAGE` and `TRANSITION` to SysML definition/usage element keywords in `NAME_PRECEDING_KEYWORDS`
-
-## [0.1.6]
-
-### Fixed
-
-- Fix keyword validator silently ignoring extreme typos (e.g., `pasddsafart def Vehicle`) — identifiers in keyword positions are now flagged even when no close keyword match exists (Levenshtein distance > 2), with a generic "Unexpected identifier" message instead of requiring a "Did you mean?" suggestion
-- Fix `flagUnknownIdentifiers` incorrectly skipping identifiers followed by `def` — valid keywords before `def` (`part`, `action`, etc.) have their own token types, so an IDENTIFIER before `def` is always invalid
-- Fix Python LSP client missing diagnostics on first run — `drain_notifications` used a fixed 2-second timeout, but DFA warm-up on first server start takes ~15-20s. Added `drain_until_diagnostics()` which waits up to 30s and stops as soon as diagnostics arrive
-
-## [0.1.5]
-
-### Added
-
-- Python LSP client example in `clients/python/` — zero-dependency script demonstrating how to drive the SysML v2 language server from Python over JSON-RPC/stdio, using the same server as VS Code
-- `sysml.inlayHints.enabled` VS Code setting — allows users to toggle inlay hints on/off (default: true). Server-side gating returns empty results when disabled
-- Extension Development Host settings (`examples/.vscode/settings.json`) — disables inlay hints during F5 testing
-- Code completion provider tests — ensures keyword completions, snippet insert text, and resolve are covered
-- Call hierarchy typed-usage detection — `action x : TypeDef`, `state x : TypeDef`, and `calc x : TypeDef` composition patterns are now recognised as outgoing/incoming calls, not just explicit `perform`/`include`/`accept` keywords
+- Mermaid diagram preview: SysML → Mermaid diagram generation with 6 diagram types (class, activity, state, sequence, interconnection, use-case) and auto-detection
+- Mermaid focus mode: filter diagram to a specific element, its children, parent, and related types
+- Mermaid diff mode: compare original vs. modified SysML and report structural changes
+- Complexity analyzer: structural complexity metrics (nesting depth, coupling, fan-out, documentation coverage) with composite 0–100 index and per-definition hotspots
+- Semantic validator: unresolved type references, invalid multiplicity bounds, empty enumerations, duplicate definitions — with standard-library type allow-list
+- MCP tool `preview`: generates Mermaid diagrams from SysML with focus/diff support
+- MCP tool `getDiagnostics`: returns semantic diagnostics for parsed documents
+- MCP tool `getComplexity`: exposes complexity analysis as an MCP tool
+- Code action quick-fixes: naming convention (PascalCase/camelCase), missing documentation stub, empty enumeration placeholder, unused definition suppression
+- Library type-level indexing: Go-to-Definition into standard library types at exact declaration lines
+- Multiplicity extraction from parse tree (`0..*`, `1`, etc.) on symbols
+- Documentation extraction from doc/comment nodes on symbols
+- Symbol table caching per URI keyed by document version
+- Multi-specialization support: comma-separated specialization targets with `:>` and `specializes`
+- LSP `sysml/serverStats` request: uptime, memory, and cache statistics
+- LSP `sysml/clearCache` request: flush all in-memory caches
+- LSP `sysml/status` notifications: begin/end parse progress events
+- Language configuration: folding markers (`#region`/`#endregion`), indentation rules, `wordPattern`
+- Model stats: lex/parse timing breakdown and complexity report in `sysml/model` response
+- New tests: codeActions, complexity, libraryIndex, semantic validation, MCP preview/diagnostics
 
 ### Changed
 
-- Reorganise folder structure: `client/` → `clients/vscode/`, Python client at `clients/python/`
-- Call hierarchy provider no longer depends on `TextDocuments` — uses `DocumentManager` for all text access, simplifying the architecture
-- `DocumentManager.getUris()` now returns all open documents (from `TextDocuments.all()`), not just cached ones — fixes providers that scan across documents (call hierarchy, references, code lens)
-- Suppress esbuild size warnings — custom build summary replaces default output to avoid misleading ⚠️ indicators on the expected 1.4 MB ANTLR parser bundle
+- MCP `validate` response shape: now returns `syntaxErrors`, `semanticIssues`, and `totalIssues` (was `errors` + `errorCount`)
+- Symbol `typeName` → `typeNames` (array) across MCP core and model provider
+- Definition provider simplified: word-at-position logic moved inline
+- References provider: uses symbol-table–based `findReferences()` instead of cross-file text scanning
+- Diagnostics computed synchronously on document change (removed background parse worker thread)
+- Symbol table kind inference: direct string comparison replaces regex-based rule matching for minification safety
+- Document manager simplified: removed `TextDocuments` integration; parse timing now derived from `ParseResult.timing`
+- esbuild: output format changed from ESM (`.mjs`) to CJS (`.js`); simplified to server + MCP + client bundles
+- Parser simplified: removed SLL/LL two-stage fallback with `BailErrorStrategy`; single-pass parse
+- MCP server: added `instructions` field for tool-call guidance
+- Library index: `resolveLibraryPackage()` replaced by `resolveLibraryType()` for type-level lookups
 
-### Fixed
+### Removed
 
-- Fix `end` keyword in connection/interface definitions causing false positive diagnostics — identifiers after `end` (e.g., `end source : PowerPort;`) were incorrectly flagged as keyword typos
-- Fix `in`/`out`/`inout` direction keywords causing false positive diagnostics — identifiers after `in`, `out`, `inout` (e.g., `out arrived : Boolean`) were incorrectly flagged as keyword typos
-- Fix Find References only returning declarations — added text-based reference scanning (`findTextReferences`) across all open documents to find usage-site references (e.g., `action adjustWheels : AdjustWheelAngle`)
-- Fix CodeLens reference counts only counting declarations — now uses text-based scanning consistent with Find References
-- Remove redundant `activationEvents` from `package.json` — VS Code auto-generates from `contributes.languages`
-- Remove unnecessary `sysml.inlayHints.enabled` from dev workspace settings (only needed in Extension Development Host)
+- Background parse worker thread (`parseWorker.mjs`) and DFA warm-up
+- `resolveAt()` and `getWordAtPosition()` from symbol table (moved to providers)
+- `findTextReferences()` text-scanning reference finder
+- Keyword typo validation from diagnostics provider (replaced by semantic validator)
+- Several parser and symbol table tests (connection-end parsing, keyword typo, `findTextReferences`)
 
-## [0.1.4]
+## [0.2.0]
 
 ### Added
 
-- Extract MCP resource and prompt handler logic into testable `mcpCore.ts` module — 3 resource handlers (element kinds, keywords, grammar overview) and 3 prompt handlers (review SysML, explain element, generate SysML)
-- `constraint` grammar rules: `ConstraintDefinition`, `ConstraintUsage`, `RequirementConstraintMember`, `assert constraint`
-- 9 new unit tests for MCP resources and prompts (101 total tests, up from 92)
-- Constraint-related unit tests
-
-### Fixed
-
-- Fix false positive diagnostics on qualified names with `::` (e.g., `toaster::maxTemp`) — add `COLON_COLON` to next-token skip list in `parseWorker.ts`
-- Fix identifiers after `actor`, `stakeholder`, `subject`, `variant`, `ref`, `snapshot`, `timeslice` incorrectly flagged as keyword typos — add to `NAME_PRECEDING_KEYWORDS` in both validators
-- Fix false positive keyword typo diagnostics on dot-chain and expression-position identifiers (e.g., `transportPassenger.driver`) — skip identifiers preceded by `.`, `=`, `:`, `::`, `:>`, `:>>`
-- Remove unused `parseAndBuild` import in `mcpServer.ts` after refactoring
+- Custom LSP request (`sysml/model`): full semantic model with scoped queries
+- MCP server (`sysml-mcp` CLI): 7 tools, 3 resources, 3 prompts for AI-assisted modelling
+- Standard library: 94 bundled SysML v2 / KerML files from OMG release repo
+- Inlay hints: ghost text for inferred types and supertypes
+- Call hierarchy: action call graph navigation
+- Type hierarchy: specialization chain navigation
+- Signature help: parameter tooltips for action/calc invocations
+- Code lens: reference counts above definitions
+- Document links: clickable `import` statements
+- Workspace symbols: cross-document symbol search
+- Linked editing ranges: simultaneous rename of all occurrences
+- Selection ranges: smart expand/shrink selection
+- Code actions: quick-fix actions for diagnostics
+- Formatting: document and range formatting
+- Keyword validation: typo detection with "did you mean?" suggestions
+- npm package: `sysml-v2-lsp` distributable for third-party extensions
+- Python LSP client: reference JSON-RPC/stdio client
+- Parse worker: background ANTLR parsing with DFA warm-up
+- `make update-library`: fetch latest standard library from upstream
+- `make package-server` / `make test-package`: npm tarball build and validation
 
 ### Changed
 
-- Slim VS Code dev extension to lightweight harness — move TextMate grammar and snippets to separate `VSCode_SysML_Extension` repo
-- Simplify `language-configuration.json` to minimal comments and brackets for dev use
-
-## [0.1.3]
-
-### Added
-
-- `make test-package` target to test npm package in a simulated consumer project
-- README badges: npm version, license, Socket.dev supply chain security
-
-### Fixed
-
-- Fix `constructor.name` minification breaking code lens and symbol resolution — `getRuleName()` now uses ANTLR4 `ruleIndex` + `ruleNames[]` instead of `constructor.name` which is mangled by esbuild
-- Rename ESM bundles from `.js` to `.mjs` for Node 20 compatibility — `child_process.fork()` now correctly treats server and worker as ESM
-- Move `@modelcontextprotocol/sdk` and `zod` from `dependencies` to `devDependencies` — they are fully bundled by esbuild and not needed at runtime
-- Guard `postinstall` script with `[ -f tsconfig.json ]` so it only runs in dev checkout, not in consumer installs
-
-## [0.1.2]
-
-### Added
-
-- Release checklist (`.github/RELEASE_CHECKLIST.md`)
-
-### Fixed
-
-- Remove unused `antlr4-c3` dependency from server package
-- Fix client extension server path to use bundled `dist/` output (VSIX was broken)
-- Fix `postinstall` script silently swallowing server install failures
-- Sync versions across `server/package.json`, `client/package.json`, and MCP server to `0.1.1`
-- Align Node engine requirement to `>=20` in `server/package.json` (was `>=18`)
-- Update esbuild target from `node18` to `node20`
-- Add `*.tgz` to `.gitignore` to prevent accidental commits
-- Add explicit `require`/`default` conditions to `exports` field
-- Remove redundant `activationEvents` (auto-generated from `contributes.languages`)
-
-## [0.1.1]
-
-### Fixed
-
-- Update postinstall script to handle missing `client` directory gracefully
-- Add npm trusted publishing (OIDC) support and normalize repository URL
-- Remove accidentally committed `.tgz` archive
-- Skip `npm version` in release workflow when git tag already matches `package.json`
-- Drop Node 18 from CI matrix (Vite 7 requires Node 20+)
+- Go-to-definition falls back to standard library for unresolved symbols
+- Recursive type name extraction in symbol table
+- Synthetic `start`/`done` nodes in activity diagram flows
+- Element kind enum expanded to 55 kinds
+- esbuild bundles four targets: server, worker, MCP server, VS Code client
 
 ## [0.1.0]
 

package/README.md

@@ -1,288 +1,110 @@
 # SysML v2 Language Server
 
-[![npm version](https://img.shields.io/npm/v/sysml-v2-lsp)](https://www.npmjs.com/package/sysml-v2-lsp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Socket Badge](https://socket.dev/api/badge/npm/package/sysml-v2-lsp)](https://socket.dev/npm/package/sysml-v2-lsp)
+[![npm](https://img.shields.io/npm/v/sysml-v2-lsp?logo=npm)](https://www.npmjs.com/package/sysml-v2-lsp)
 
-A [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) with [Model Context Protocol](https://modelcontextprotocol.io/) implementation for [SysML v2](https://www.omgsysml.org/SysML-2.htm), providing rich editing, navigation, and code intelligence for LSP-compatible editors.
+[![SysML v2.0 Language Support VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/JamieD.sysml-v2-support?label=VS%20Code%20Marketplace&logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=JamieD.sysml-v2-support)
 
-Powered by the ANTLR4 grammar from [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar).
+A [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) implementation for [SysML v2](https://www.omgsysml.org/SysML-2.htm).
 
-> **Works with:** VS Code, Neovim, Emacs, Sublime Text, Helix, and any editor that supports the Language Server Protocol.
+## Features
 
----
+| Feature                 | Status | Description                                              |
+| ----------------------- | ------ | -------------------------------------------------------- |
+| **Diagnostics**         | ✅     | Syntax error reporting with red squiggles                |
+| **Document Symbols**    | ✅     | Outline panel with SysML model structure                 |
+| **Hover**               | ✅     | Element kind, type, and documentation on hover           |
+| **Go to Definition**    | ✅     | Ctrl+Click navigation to declarations                    |
+| **Find References**     | ✅     | Find all usages of a symbol                              |
+| **Code Completion**     | ✅     | Keywords, snippets, and symbol suggestions               |
+| **Semantic Tokens**     | ✅     | Rich, context-aware syntax highlighting                  |
+| **Folding Ranges**      | ✅     | Collapsible `{ }` blocks and comments                    |
+| **Rename**              | ✅     | Rename symbol and all references                         |
+| **Semantic Validation** | ✅     | Unresolved types, invalid multiplicity, duplicates       |
+| **Code Actions**        | ✅     | Quick-fixes: naming, doc stubs, empty enums, unused defs |
+| **Complexity Analysis** | ✅     | Structural metrics, composite index, hotspot detection   |
+| **Mermaid Preview**     | ✅     | 6 diagram types with auto-detect, focus, and diff modes  |
+| **MCP Server**          | ✅     | AI-assisted modelling via `sysml-mcp` CLI                |
 
-## Language Server Features
+## Quick Start
 
-The language server runs as a separate process and communicates over LSP — these features are available in **any** compatible editor.
+### Install from Marketplace
 
-### Editing & Navigation
+Install via the VS Code extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=JamieD.sysml-v2-support).
 
-| Feature              | Description                                                            |
-| -------------------- | ---------------------------------------------------------------------- |
-| **Diagnostics**      | Syntax errors, unknown identifiers, keyword typos with severity levels |
-| **Code Completion**  | Keywords, snippets, and symbol suggestions with documentation          |
-| **Signature Help**   | Parameter tooltips when invoking `action def` / `calc def`             |
-| **Hover**            | Element kind, type, qualified name, and documentation                  |
-| **Go to Definition** | Jump to a symbol's declaration                                         |
-| **Find References**  | Find all usages of a symbol across open files                          |
-| **Rename Symbol**    | Rename a symbol and update all references                              |
-| **Linked Editing**   | Edit a name and all same-scope occurrences update simultaneously       |
-| **Document Links**   | Clickable `import` paths — jump to the imported namespace              |
+### Dev Container (recommended)
 
-### Code Intelligence
+Open in GitHub Codespaces or VS Code Dev Containers — everything is pre-installed.
 
-| Feature               | Description                                                              |
-| --------------------- | ------------------------------------------------------------------------ |
-| **CodeLens**          | Reference counts shown above each definition                             |
-| **Inlay Hints**       | Ghost text showing inferred types (`: Type`) and supertypes (`:> Super`) |
-| **Type Hierarchy**    | Navigate specialization chains — supertypes and subtypes                 |
-| **Call Hierarchy**    | Navigate `perform`/`include` chains between actions                      |
-| **Workspace Symbols** | Fuzzy search for any definition across all open files                    |
-
-### Presentation & Formatting
-
-| Feature              | Description                                                                    |
-| -------------------- | ------------------------------------------------------------------------------ |
-| **Semantic Tokens**  | Rich, context-aware syntax highlighting (definitions, usages, keywords, types) |
-| **Document Symbols** | Outline / breadcrumbs showing SysML model structure                            |
-| **Folding Ranges**   | Collapsible `{ }` blocks and comment regions                                   |
-| **Selection Ranges** | Smart expand/shrink selection (word → line → block → enclosing block)          |
-| **Quick Fix**        | Fix keyword typos (e.g., `paart` → `part`)                                     |
-| **Formatting**       | Auto-indent, normalize braces, trim trailing whitespace                        |
-
-### Parser
-
-- ANTLR4-based parser via [antlr4ng](https://github.com/mike-lischke/antlr4ng)
-- SLL/LL dual-mode strategy — fast path with automatic fallback
-- DFA warm-up for near-instant first-parse performance
-- Worker thread architecture for non-blocking document processing
-- Symbol table with qualified name resolution and cross-file references
-
----
-
-## MCP Server (AI Integration)
-
-A standalone [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI assistants parse, validate, and query SysML v2 models. Runs independently of any editor.
-
-### Tools
-
-| Tool              | Description                                            |
-| ----------------- | ------------------------------------------------------ |
-| `parse`           | Parse SysML source, build symbol table, return summary |
-| `validate`        | Check syntax and return errors                         |
-| `getSymbols`      | List symbols (filter by kind, URI, definitions/usages) |
-| `getDefinition`   | Look up a symbol by name or qualified name             |
-| `getReferences`   | Find all references to a symbol                        |
-| `getHierarchy`    | Get parent–child containment structure                 |
-| `getModelSummary` | Counts, kinds, and loaded documents                    |
-
-### Resources
-
-| URI                        | Description                  |
-| -------------------------- | ---------------------------- |
-| `sysml://element-kinds`    | All recognised element kinds |
-| `sysml://keywords`         | Complete keyword list        |
-| `sysml://grammar-overview` | Language structure reference |
-
-### Prompts
-
-| Prompt            | Description                          |
-| ----------------- | ------------------------------------ |
-| `review-sysml`    | Review a SysML model for correctness |
-| `explain-element` | Explain a SysML element kind         |
-| `generate-sysml`  | Generate SysML from a description    |
-
-### MCP Setup
-
-**VS Code / GitHub Copilot** — The workspace includes `.vscode/mcp.json`, so the MCP server is automatically available after building.
-
-**Claude Desktop** — Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "sysml-v2": {
-      "command": "node",
-      "args": ["/path/to/sysml-v2-lsp/dist/server/mcpServer.mjs"]
-    }
-  }
-}
-```
-
-**Any MCP client** — Run the server directly via stdio:
-
-```bash
-npx sysml-v2-lsp   # after npm install -g sysml-v2-lsp
-# or
-node dist/server/mcpServer.mjs
-```
-
-### Quick Test Examples
-
-Once the MCP server is connected, try these prompts:
-
-> Parse this: `package Demo { part def Vehicle { attribute speed : Real; } part car : Vehicle; }`
-
-> Validate this: `part def Broken { attribute x :`
-
-> What symbols are in the model?
-
-> Find the definition of Vehicle
-
-> Show the hierarchy of car
-
----
-
-## VS Code Dev Extension
-
-A lightweight VS Code extension is included for **development and debugging** of the language server. It registers the `sysml` language ID, starts the LSP client, and provides a restart command — nothing more.
-
-For the full VS Code experience (TextMate grammar, snippets, language configuration, visualization), see [daltskin/VSCode_SysML_Extension](https://github.com/daltskin/VSCode_SysML_Extension).
-
-| Feature                  | Description                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------ |
-| **Language Registration**| Registers `.sysml` / `.kerml` file types                                       |
-| **LSP Client**           | Starts and manages the language server process                                 |
-| **Restart Command**      | `SysML: Restart Language Server` command                                       |
-| **Dev Container**        | Open in GitHub Codespaces or VS Code Dev Containers — everything pre-installed |
-| **Debug Configurations** | "Client + Server" compound launch for simultaneous debugging                   |
-| **Example Files**        | `examples/` folder with camera, toaster, and vehicle models                    |
-
----
-
-## Getting Started
-
-### Using the VS Code Extension
-
-Open in GitHub Codespaces or Dev Containers (recommended), or manually:
+### Manual Setup
 
 ```bash
+# Install dependencies
 npm install
-npm run build
-# Press F5 to launch the Extension Development Host
-```
-
-### Using the LSP with Other Editors
-
-Build the server, then point your editor's LSP client at it:
-
-```bash
-npm install && npm run build
-# Server binary: dist/server/server.mjs
-# Start with: node dist/server/server.mjs --stdio
-```
 
-**Neovim** (via [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig)):
-
-```lua
-vim.lsp.start({
-  name = 'sysml',
-  cmd = { 'node', '/path/to/sysml-v2-lsp/dist/server/server.mjs', '--stdio' },
-  filetypes = { 'sysml' },
-})
-```
-
-**Emacs** (via [lsp-mode](https://github.com/emacs-lsp/lsp-mode)):
+# Build
+npm run build
 
-```elisp
-(lsp-register-client
-  (make-lsp-client
-    :new-connection (lsp-stdio-connection
-                     '("node" "/path/to/sysml-v2-lsp/dist/server/server.mjs" "--stdio"))
-    :activation-fn (lsp-activate-on "sysml")
-    :server-id 'sysml-lsp))
+# Run tests
+npm test
 ```
 
-**Python** — A zero-dependency Python LSP client is included in [`clients/python/`](clients/python/):
+### Development
 
 ```bash
-cd clients/python
-python3 sysml_lsp_client.py                       # analyse all example files
-python3 sysml_lsp_client.py ../../examples/vehicle-model.sysml  # specific file
-```
-
-This demonstrates that the same LSP server used by VS Code can be driven from
-any language — see the [Python client README](clients/python/README.md) for details.
-
-### Using the MCP Server
+# Watch mode — recompiles on file changes
+npm run watch
 
-```bash
-npm install && npm run build
-node dist/server/mcpServer.mjs   # stdio transport
+# Then press F5 in VS Code to launch the extension + server
 ```
 
----
+Use the **"Client + Server"** compound debug configuration to debug both sides simultaneously.
 
 ## Architecture
 
 ```
-┌──────────────────────────────────────────────────────────────────┐
-│                     Language Server (Node.js)                    │
-│                                                                  │
-│  ┌──────────────┐  ┌──────────────────┐  ┌───────────────────┐   │
-│  │ ANTLR4 Parser│  │   Symbol Table   │  │   21 Providers    │   │
-│  │ (worker thr.)│──│ scopes, q-names  │──│ completion, hover │   │
-│  │ SLL/LL dual  │  │ cross-file refs  │  │ def, refs, rename │   │
-│  └──────────────┘  └──────────────────┘  │ hierarchy, format │   │
-│                                          │ tokens, lens, ... │   │
-│                                          └───────────────────┘   │
-└──────────────────────┬───────────────────────────┬───────────────┘
-                       │ LSP (stdio/IPC)           │
-          ┌────────────┴────────────┐              │
-          │      Any Editor         │              │
-          │  VS Code, Neovim,       │              │
-          │  Emacs, Sublime, ...    │              │
-          └─────────────────────────┘              │
-                                                   │
-┌──────────────────────────────────────────────────┴──────────────┐
-│                     MCP Server (standalone)                     │
-│  7 tools · 3 resources · 3 prompts · stdio transport            │
-│                                                                 │
-│  ┌─────────────────┐  ┌──────────────────┐ ┌──────────────────┐ │
-│  │  Claude, Copilot│  │  Cursor, Windsurf│ │  Any MCP Client  │ │
-│  └─────────────────┘  └──────────────────┘ └──────────────────┘ │
-└─────────────────────────────────────────────────────────────────┘
+┌──────────────────────┐     IPC     ┌──────────────────────────┐
+│   VS Code Extension  │ ◄─────────► │    Language Server       │
+│   (Language Client)  │             │    (Separate Process)    │
+├──────────────────────┤             ├──────────────────────────┤
+│ • Starts server      │             │ • Parser                 │
+│ • Registers language │             │ • Diagnostics            │
+│                      │             │ • Completion (keywords)  │
+│                      │             │ • Symbols / hover        │
+│                      │             │ • Go-to-def / references │
+│                      │             │ • Semantic tokens        │
+│                      │             │ • Rename / folding       │
+└──────────────────────┘             └──────────────────────────┘
 ```
 
 ### Project Structure
 
 ```
 sysml-v2-lsp/
-├── server/                 # Language Server + MCP Server
+├── client/                 # VS Code Language Client extension
+│   └── src/extension.ts    # Starts LanguageClient, connects to server
+├── server/                 # Language Server (runs in separate process)
 │   └── src/
-│       ├── server.ts           # LSP connection, capability registration
-│       ├── mcpServer.ts        # MCP server entry point (stdio)
-│       ├── mcpCore.ts          # MCP handler logic (testable)
+│       ├── server.ts       # LSP connection, capability registration
 │       ├── documentManager.ts  # Parse cache, document lifecycle
-│       ├── parser/             # ANTLR4 parse pipeline + worker thread
-│       ├── symbols/            # Symbol table, scopes, element types
-│       └── providers/          # 21 LSP feature implementations
-├── clients/                # LSP client implementations
-│   ├── vscode/                 # VS Code Language Client extension
-│   │   └── src/extension.ts        # Starts LanguageClient, registers language
-│   └── python/                 # Python LSP client demo (zero dependencies)
-│       └── sysml_lsp_client.py
-├── grammar/                # ANTLR4 grammar files (.g4)
-├── examples/               # Sample SysML models
-├── test/                   # Unit tests (vitest)
+│       ├── parser/         # Parse pipeline
+│       ├── symbols/        # Symbol table, scopes, element types
+│       ├── providers/      # LSP feature implementations
+│       ├── analysis/       # Complexity analyzer
+│       └── mcp/            # Mermaid diagram generator
+├── grammar/                # Grammar files (.g4)
+├── test/                   # Unit tests (vitest) + E2E tests
 └── package.json            # Extension manifest + monorepo scripts
 ```
 
----
+## Grammar Updates
 
-## Development
+The grammar files in `grammar/` are sourced from [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar). To pull the latest version:
 
 ```bash
-npm install                 # Install all dependencies
-npm run generate            # Generate TypeScript parser from ANTLR4 grammar
-npm run build               # Compile + bundle (esbuild)
-npm run watch               # Watch mode — recompiles on changes
-npm test                    # Run 88 unit tests (vitest)
-npm run lint                # ESLint
+npm run update-grammar
 ```
 
-Or use the Makefile:
+## Available Commands
 
 ```bash
 make install          # Install all dependencies
@@ -292,37 +114,25 @@ make watch            # Watch mode
 make test             # Run unit tests
 make lint             # ESLint
 make package          # Build .vsix
-make package-server   # Build npm tarball
 make update-grammar   # Pull latest grammar from upstream
 make ci               # Full CI pipeline
 ```
 
-### Grammar Updates
-
-The grammar files in `grammar/` are sourced from [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar). To pull the latest:
-
-```bash
-npm run update-grammar && npm run generate
-```
-
----
-
 ## Technology Stack
 
-| Component | Technology                                                                          |
-| --------- | ----------------------------------------------------------------------------------- |
-| Language  | TypeScript (strict mode)                                                            |
-| Runtime   | Node.js ≥ 20                                                                        |
-| Parser    | ANTLR4 via [antlr4ng](https://github.com/mike-lischke/antlr4ng)                     |
-| Generator | [antlr-ng](https://github.com/nicklockwood/antlr-ng)                                |
-| LSP       | [vscode-languageserver](https://github.com/microsoft/vscode-languageserver-node)    |
-| MCP       | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) |
-| Bundler   | esbuild                                                                             |
-| Tests     | vitest                                                                              |
+| Component | Technology                                                                       |
+| --------- | -------------------------------------------------------------------------------- |
+| Language  | TypeScript (strict mode)                                                         |
+| Runtime   | Node.js ≥ 18                                                                     |
+| Parser    | [antlr4ng](https://github.com/mike-lischke/antlr4ng)                             |
+| Generator | [antlr-ng](https://github.com/nicklockwood/antlr-ng)                             |
+| LSP       | [vscode-languageserver](https://github.com/microsoft/vscode-languageserver-node) |
+| Bundler   | esbuild                                                                          |
+| Tests     | vitest                                                                           |
 
 ## Related Projects
 
-- [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar) — ANTLR4 grammar for SysML v2
+- [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar) — Grammar for SysML v2
 - [daltskin/VSCode_SysML_Extension](https://github.com/daltskin/VSCode_SysML_Extension) — VS Code extension with visualization
 - [OMG SysML v2 Specification](https://github.com/Systems-Modeling/SysML-v2-Release)