lady-lens 0.0.0-stage → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (159) hide show
  1. package/DOCUMENTATIE.md +408 -0
  2. package/LICENSE +674 -0
  3. package/README.md +356 -2
  4. package/bin/lens.mjs +184 -0
  5. package/core/branches/branchDiff.js +38 -0
  6. package/core/branches/branchImpact.js +42 -0
  7. package/core/branches/changedFunctions.js +65 -0
  8. package/core/branches/commitShow.js +22 -0
  9. package/core/branches/compare.js +120 -0
  10. package/core/branches/functionHistory.js +27 -0
  11. package/core/branches/index.js +5 -0
  12. package/core/configuration/contextBudget.js +24 -0
  13. package/core/configuration/env.js +28 -0
  14. package/core/configuration/frontmatter.js +186 -0
  15. package/core/configuration/index.js +4 -0
  16. package/core/configuration/paths.js +57 -0
  17. package/core/discussions/index.js +43 -0
  18. package/core/discussions/mcp/discussionTools.js +164 -0
  19. package/core/discussions/mcp/index.js +14 -0
  20. package/core/discussions/model/index.js +22 -0
  21. package/core/discussions/model/nodes.js +151 -0
  22. package/core/discussions/model/record.js +158 -0
  23. package/core/discussions/query/discussionQuery.js +100 -0
  24. package/core/discussions/query/index.js +10 -0
  25. package/core/discussions/query/sourceStatus.js +33 -0
  26. package/core/discussions/storage/discussionStore.js +132 -0
  27. package/core/discussions/storage/index.js +15 -0
  28. package/core/discussions/storage/markdownExtractor.js +38 -0
  29. package/core/eval/fixtureGold.json +135 -0
  30. package/core/eval/graphEval.js +163 -0
  31. package/core/eval/index.js +2 -0
  32. package/core/eval/searchBench.js +56 -0
  33. package/core/git/fakeGit.js +130 -0
  34. package/core/git/index.js +116 -0
  35. package/core/graph/adapters/ladybug/configIndexer.js +109 -0
  36. package/core/graph/adapters/ladybug/directQueries.js +164 -0
  37. package/core/graph/adapters/ladybug/index.js +28 -0
  38. package/core/graph/adapters/ladybug/ladybugGraphStore.js +181 -0
  39. package/core/graph/adapters/ladybug/ladybugIndexer.js +71 -0
  40. package/core/graph/adapters/ladybug/ladybugMarkdownIndexer.js +105 -0
  41. package/core/graph/adapters/ladybug/projectWriteQueries.js +13 -0
  42. package/core/graph/adapters/ladybug/repositoryStore.js +200 -0
  43. package/core/graph/adapters/memory/directQueries.js +178 -0
  44. package/core/graph/adapters/memory/index.js +3 -0
  45. package/core/graph/adapters/memory/repositoryStore.js +128 -0
  46. package/core/graph/index.js +10 -0
  47. package/core/graph/model/calls.js +41 -0
  48. package/core/graph/model/decisions.js +52 -0
  49. package/core/graph/model/graphIds.js +65 -0
  50. package/core/graph/model/graphModel.js +209 -0
  51. package/core/graph/model/graphRows.js +61 -0
  52. package/core/graph/model/graphValidation.js +69 -0
  53. package/core/graph/model/index.js +6 -0
  54. package/core/graph/ports/graphStorePort.js +26 -0
  55. package/core/graph/ports/index.js +1 -0
  56. package/core/graph/query/architectureMetrics.js +126 -0
  57. package/core/graph/query/codeHealth.js +177 -0
  58. package/core/graph/query/folderView.js +200 -0
  59. package/core/graph/query/functionView.js +175 -0
  60. package/core/graph/query/graphContext.js +99 -0
  61. package/core/graph/query/graphQuery.js +233 -0
  62. package/core/graph/query/graphRank.js +221 -0
  63. package/core/graph/query/graphSemantic.js +238 -0
  64. package/core/graph/query/hubsAndBridges.js +63 -0
  65. package/core/graph/query/impact.js +161 -0
  66. package/core/graph/query/importCycles.js +62 -0
  67. package/core/graph/query/importLookup.js +221 -0
  68. package/core/graph/query/index.js +11 -0
  69. package/core/graph/repository/graphRepository.js +125 -0
  70. package/core/graph/repository/index.js +3 -0
  71. package/core/graph/repository/projectGraphGate.js +83 -0
  72. package/core/graph/sync/branchIndex.js +68 -0
  73. package/core/graph/sync/codeFacts.js +215 -0
  74. package/core/graph/sync/contributors.js +23 -0
  75. package/core/graph/sync/documentRelations.js +81 -0
  76. package/core/graph/sync/fileEntity.js +27 -0
  77. package/core/graph/sync/functionComplexity.js +106 -0
  78. package/core/graph/sync/gitHistory.js +30 -0
  79. package/core/graph/sync/graphSync.js +181 -0
  80. package/core/graph/sync/headCommit.js +36 -0
  81. package/core/graph/sync/index.js +11 -0
  82. package/core/graph/sync/languages/blocks.js +28 -0
  83. package/core/graph/sync/languages/cpp.js +36 -0
  84. package/core/graph/sync/languages/csharp.js +32 -0
  85. package/core/graph/sync/languages/docker.js +107 -0
  86. package/core/graph/sync/languages/engine.js +185 -0
  87. package/core/graph/sync/languages/go.js +33 -0
  88. package/core/graph/sync/languages/index.js +185 -0
  89. package/core/graph/sync/languages/infra.js +116 -0
  90. package/core/graph/sync/languages/java.js +36 -0
  91. package/core/graph/sync/languages/javascript.js +7 -0
  92. package/core/graph/sync/languages/kotlinSwift.js +59 -0
  93. package/core/graph/sync/languages/php.js +32 -0
  94. package/core/graph/sync/languages/python.js +35 -0
  95. package/core/graph/sync/languages/ruby.js +28 -0
  96. package/core/graph/sync/languages/rust.js +33 -0
  97. package/core/graph/sync/languages/shell.js +190 -0
  98. package/core/graph/sync/languages/sql.js +95 -0
  99. package/core/graph/sync/languages/typescript.js +38 -0
  100. package/core/graph/sync/languages/web.js +141 -0
  101. package/core/graph/sync/mendix.js +144 -0
  102. package/core/graph/sync/projectRelations.js +71 -0
  103. package/core/language/fuzzy.js +51 -0
  104. package/core/language/index.js +4 -0
  105. package/core/language/lexicon.js +79 -0
  106. package/core/language/lexiconValidation.js +46 -0
  107. package/core/mcp/agentInstall.js +156 -0
  108. package/core/mcp/daemon.js +191 -0
  109. package/core/mcp/handlers/branchDiff.js +24 -0
  110. package/core/mcp/handlers/config.js +61 -0
  111. package/core/mcp/handlers/crossRepoSearch.js +26 -0
  112. package/core/mcp/handlers/index.js +7 -0
  113. package/core/mcp/handlers/repoAdd.js +15 -0
  114. package/core/mcp/handlers/repoList.js +3 -0
  115. package/core/mcp/handlers/repoRemove.js +6 -0
  116. package/core/mcp/handlers/repoSync.js +14 -0
  117. package/core/mcp/httpServer.js +278 -0
  118. package/core/mcp/index.js +38 -0
  119. package/core/mcp/managementSchemas.js +191 -0
  120. package/core/mcp/policyInstall.js +77 -0
  121. package/core/mcp/server.js +130 -0
  122. package/core/mcp/streamableHttp.js +32 -0
  123. package/core/mcp/tomlInstall.js +39 -0
  124. package/core/mcp/toolRoutes.js +33 -0
  125. package/core/observability/debugLog.js +23 -0
  126. package/core/observability/index.js +2 -0
  127. package/core/observability/profiler.js +138 -0
  128. package/core/repository/index.js +16 -0
  129. package/core/repository/projectScanner.js +62 -0
  130. package/core/repository/projectSettings.js +125 -0
  131. package/core/repository/registry.js +138 -0
  132. package/core/search/budget.js +33 -0
  133. package/core/search/chunkReader.js +139 -0
  134. package/core/search/codeHealth.js +68 -0
  135. package/core/search/definedIn.js +20 -0
  136. package/core/search/diffImpact.js +58 -0
  137. package/core/search/docMentions.js +40 -0
  138. package/core/search/exports.js +38 -0
  139. package/core/search/folderView.js +37 -0
  140. package/core/search/functionView.js +37 -0
  141. package/core/search/graphModelLoader.js +148 -0
  142. package/core/search/graphQuery.js +84 -0
  143. package/core/search/grepSearch.js +122 -0
  144. package/core/search/imports.js +44 -0
  145. package/core/search/index.js +116 -0
  146. package/core/search/packageFolderView.js +49 -0
  147. package/core/search/queryFlow.js +85 -0
  148. package/core/search/schemas.js +122 -0
  149. package/core/search/searchView.js +95 -0
  150. package/index.js +90 -0
  151. package/package.json +102 -6
  152. package/skills/lady-lens/SKILL.md +53 -0
  153. package/skills/lady-lens/lens-instructions.md +11 -0
  154. package/skills/lady-lens-mendix/SKILL.md +40 -0
  155. package/ui/graph-ui.css +122 -0
  156. package/ui/graph-ui.html +200 -0
  157. package/ui/graph-ui.mjs +73 -0
  158. package/ui/humanuses.png +0 -0
  159. package/ui/index.js +1 -0
@@ -0,0 +1,408 @@
1
+ # lady-lens documentation
2
+
3
+ Full guide to architecture, API ports, MCP integration, npm package use and configuration through `config.json`. (The file name stays `DOCUMENTATIE.md` so existing links keep working.)
4
+
5
+ ---
6
+
7
+ ## 0. Installation and setup
8
+
9
+ Requires Node.js 18 or newer. `lady-lens` is not on npmjs.org; install it from a package you build yourself. Do these steps once, in order.
10
+
11
+ **Step 1: install**
12
+
13
+ ```bash
14
+ cd C:\git\lady-lens
15
+ npm install # dependencies of lady-lens itself
16
+ npm run pack # builds dist\lady-lens-<version>.tgz
17
+ npm install -g .\dist\lady-lens-<version>.tgz
18
+ lens v # prints the version: `lens` is now on your PATH
19
+ ```
20
+
21
+ For development you can use `npm link` instead of the last install step; `lens` then runs straight from this folder.
22
+
23
+ **Step 2: register a project and index it**
24
+
25
+ ```bash
26
+ lens add C:\git\my-project # registers the project and runs the first sync
27
+ lens list # check that it is listed
28
+ lens sync # later: incremental sync (--full = everything)
29
+ ```
30
+
31
+ **Step 3: connect your AI assistant (stdio, no daemon needed)**
32
+
33
+ ```bash
34
+ lens install # every agent found; or one: lens install vscode
35
+ lens install --skill # also the Lady-lens workflow skill
36
+ lens install --dry-run # shows what would change, writes nothing
37
+ ```
38
+
39
+ `lens install` adds a stdio entry to each agent's MCP configuration (VS Code: `%APPDATA%\Code\User\mcp.json`), keeps the other servers and saves the old file as `<file>.lady-lens.bak`. Restart the agent afterwards (VS Code: *MCP: List Servers* or reload the window).
40
+
41
+ **Step 4 (alternative): one background daemon for all projects**
42
+
43
+ ```bash
44
+ lens mcp -d # MCP on http://127.0.0.1:4318/mcp, UI on http://127.0.0.1:4317
45
+ lens status # is it running?
46
+ lens ps # tracked PIDs per folder
47
+ lens stop # stop it
48
+ ```
49
+
50
+ Example for VS Code (`mcp.json`):
51
+
52
+ ```json
53
+ { "servers": { "lady-lens": { "type": "http", "url": "http://127.0.0.1:4318/mcp?repo=C:/git/my-project" } } }
54
+ ```
55
+
56
+ See [section 5](#5-using-it-as-an-mcp-server) for several projects per daemon and other agents.
57
+
58
+ **Step 5: update**
59
+
60
+ One command stops lens, installs the newest package from `dist` and starts the daemon again:
61
+
62
+ ```powershell
63
+ .\scripts\update-lens.ps1 -Pack # first build a fresh package from this source
64
+ .\scripts\update-lens.ps1 # only install the newest package already in dist
65
+ .\scripts\update-lens.ps1 -Source github:kimVanRenterghemNew/lady-lens # another source
66
+ ```
67
+
68
+ The script only restarts the daemon when the install succeeded. Restart the MCP server in your agent afterwards so new or changed tools show up.
69
+
70
+ ---
71
+
72
+ ## 1. Architecture overview and philosophy
73
+
74
+ `lady-lens` is a fast, local code graph and semantic analysis engine built on [LadybugDB](https://www.npmjs.com/package/@ladybugdb/core). It indexes source code, documentation, decisions and dependencies into a directed graph. AI coding agents and developers can ask for exact facts about the codebase (definitions, import chains, callers, test reach, code health and architecture metrics) without spending expensive LLM tokens on context.
75
+
76
+ The code base follows a strict **hexagonal architecture (ports and adapters)**:
77
+ - **Core domain / model**: graphs, nodes (files, functions, documents, decisions) and edges (`IMPORTS`, `CALLS`, `TESTS`, `READS`, `CO_CHANGES`).
78
+ - **Storage port (`GraphStorePort`)**: interchangeable storage adapters (in memory for fast tests, LadybugDB for persistent indexing).
79
+ - **Sync and extraction port**: incremental parsing and AST extraction for JavaScript/TypeScript, C# and other registered languages; Mendix `.mpr` models are handled through `mxcli` as an external graph contributor.
80
+ - **Git port (`core/git`)**: the only place that starts git; see [Branches and commits](#branches-and-commits).
81
+ - **Query and view ports**: `functionView`, `folderView`, `codeHealth`, `rankGraphNodes`, `impact`.
82
+ - **Primary adapters**: reachable through the **npm package**, the **MCP server (Model Context Protocol)** and the **CLI (`lens`)**.
83
+
84
+ ---
85
+
86
+ ## 2. API ports: access through MCP and the npm package
87
+
88
+ Every feature of `lady-lens` is a **first-class API port**, available programmatically through the npm package (`lady-lens`) and interactively through the Model Context Protocol (MCP).
89
+
90
+ The library sync API is `createGraphSync().sync({ mode: 'incremental' })`; use `mode: 'full'` for a complete re-index.
91
+
92
+ ### Overview of all ports
93
+
94
+ | Port / domain | MCP tool | npm export (`lady-lens`) | Description |
95
+ | :--- | :--- | :--- | :--- |
96
+ | **Function analysis** | `functionView` | `functionView(graph, symbol, { readFile, maxSites })` / `functionViewTool(args)` | Definition, line numbers, docstring/purpose, all calling files (`callers`), linked tests and referenced backlog stories of a function; `resolved` and `unresolved` call counts (a `note` "niet bewezen leeg" when none is bound but the name appears); for a class `children` (methods) and `inheritors` (subclasses). |
97
+ | **Folder and module analysis** | `folderView` | `folderView(graph, folder)` / `folderViewTool(args)` | Structure of a folder: parts, internal data flow, who calls the folder from outside and possible deviations (cycles, untested files). |
98
+ | **Code health and metrics** | `health` | `codeHealth(graph, opts)` / `healthTool(args)` | NDepend-style statistics: test reach (including index.js barrels), cyclic dependencies, boundary violations, hotspots (churn x lines), coupling (Ca, Ce, instability) and zone of pain. On request `hubs` (most neighbours) and `bridges` (betweenness), each with `total` and `truncated` (`hubsAndBridges(graph, opts)`). |
99
+ | **Symbol location** | `definedIn` | `definedIn(graph, symbol)` / `definedInTool(args)` | Where an identifier is defined or exported: file path and exact start/end lines. |
100
+ | **Imports** | `imports` | `importsOf(graph, file)` / `imports(args)` | Which files and modules a given file imports directly. |
101
+ | **Dependents** | `importedBy` | `importersOf(graph, file)` / `importedBy(args)` | Which files import the given file (fan-in analysis). |
102
+ | **Exports** | `exports` | `exportsOf(graph, file)` / `exportsTool(args)` | Complete sorted list of exported functions, variables and types of a file. |
103
+ | **File check** | `exists` | `fileLookup(graph, file)` / `fileExists(args)` | Checks whether a file is in the project graph; suggests matches for typos or moved folders. |
104
+ | **Graph search** | `graph_query` | `graph_query(args)` / `rankGraphNodes(graph, query)` | Semantic and keyword search through the graph by relevance score, IDF weighting and relations. |
105
+ | **Interactive search** | `searchView` | `searchView(args)` | Advanced search with regex, case sensitivity, file type filter (code, doc, test) and path globs. |
106
+ | **Text and regex** | `grep` | `grep(args)` | Fast regex search through code, honouring `.gitignore` and project exclusions. |
107
+ | **Config search** | `config_grep` | `grep(args)` + config filter | Searches only project and configuration files, such as `.csproj` and reference-manager XML. |
108
+ | **Config references** | `config_references` | `grep(args)` + config filter | Finds which config files mention a package, project or Siemens functional block. |
109
+ | **Config update** | `config_update` | `fs` + `createGraphSync().touch()` | Replaces one config file, optionally checks a SHA-256 and refreshes the graph facts. |
110
+ | **Path matching** | `glob` | `glob(args)` | Finds repository paths by glob pattern (e.g. `core/**/*.js`). |
111
+ | **AST chunk reader** | `read_chunk` | `read_chunk(args)` | Reads one AST chunk (class/function) or a range of lines. Large files return a compact summary. |
112
+ | **Decisions and discussions** | `discussion_save`, `discussion_query`, etc. | `saveDiscussion`, `loadDiscussions`, `queryDiscussions` | Manages architecture decisions and discussions, with frontmatter links to code nodes. |
113
+ | **Multi-repo management** | `repo_list`, `repo_add`, `repo_remove` | `registerRepo`, `unregisterRepo`, `listRegisteredRepos` | Manages several projects in the central Ladybug database registry. |
114
+ | **Graph sync** | `repo_sync` | `createGraphSync(options).sync()` | Scans the project incrementally (by size and mtime) or fully (`mode: 'full'`). Records the branch and commit and reports `commitsSince`. With `branch: '<name>'` another branch is indexed into the scope `branch:<name>` without checking it out. |
115
+ | **Branch difference** | `branch_diff` | `branchDiff({ from, to, root })` | What `to` changes since its merge-base with `from`: files (added, removed, modified, renamed) and functions (added, removed, modified, renamed) and changed import and call relations. |
116
+ | **Diff impact** | `diff_impact` | `diffImpact(args)` / `changedFunctions({ from, to, git, readFile })` | The functions a diff changes (the work not committed yet, or `from`..`to`) with callers, tests, bound/unbound call counts, complexity and test gaps; riskiest first, with `total` and `truncated`. |
117
+ | **Search over projects** | `cross_repo_search` | `crossRepoSearch(args)` | `searchView` over every registered project or `repos: [...]`, project after project; unregistered names in `unknown`. |
118
+ | **Tool metadata** | (all tools) | `RESEARCH_TOOL_SCHEMAS`, `buildMcpToolSchemas()` | Every schema has `readOnly` (MCP `annotations.readOnlyHint`); the discussion tools carry `usedBy: ['/discuss', '/research']` so a host such as Kura gives them only to those consumers. |
119
+ | **Branch impact** | `branch_impact` | `branchImpact({ change, against, root })` | What a change on one branch (e.g. a bugfix on `release`) means for another: functions still used there (file and line), overlap, shared files and text merge conflicts. |
120
+ | **Commit inspection** | `commit_show` | `commitShow({ commit, root })` | What one commit changed (files and functions against its first parent); for a merge commit, what the merge brought in. |
121
+ | **Function history** | `function_history` | `functionHistory({ name, file, ref, max, root })` | Commits that added, modified or removed one function; without `name` every commit that touched the file. Name based: a renamed function starts a new history. |
122
+
123
+ ### Branches and commits
124
+
125
+ The graph knows which branch and commit it was built on:
126
+
127
+ - After every sync a `Branch` node points to its `Commit` (`HEAD_AT`). `repo_sync` reports how many commits came in since the previous sync on that branch. A commit that changed no file is recorded too.
128
+ - A saved discussion gets `CREATED_AT` (commit) and `ON_BRANCH` (branch). If you switch to a branch where the source file does not exist, the discussion stays; `discussion_query` shows the source as "not on this branch" and on which branch the file does exist. Switching back and syncing restores the link by itself.
129
+ - `repo_sync({ branch: 'feature-x' })` reads that branch with `git ls-tree` and `git cat-file --batch` into its own scope `branch:feature-x`. The working copy, `HEAD` and the project scope stay unchanged. A second call only reads what changed since the stored commit. This scope has no Mendix contributions and no co-change signal.
130
+ - `branch_diff`, `branch_impact`, `commit_show` and `function_history` read git directly and check nothing out. Functions are compared by name and content (hash of the body); a function whose name changed but whose body is alike (same file, or a renamed file) shows as `renamed` with `oldName`, and `branch_diff` also lists added and removed import and call relations (`relations`). `branch_impact` finds callers with `git grep` (at most 20 references per function; for a renamed function it searches the old name) and uses `git merge-tree --write-tree` (git 2.38 or newer) for conflicts.
131
+ - All git calls go through `core/git` (`createGit({ root, run })`); a test checks that git is started nowhere else. `createFakeGit(state)` is an in-memory git for tests; `test/gitPort.contract.test.js` runs the same scenario on both and compares the answers.
132
+
133
+ ---
134
+
135
+ ## 3. Configuration through `config.json`
136
+
137
+ All `lady-lens` settings can be set in one central **`config.json`** file in the root of the project.
138
+
139
+ ### Automatic detection
140
+ `lady-lens` looks for configuration files in this order:
141
+ 1. A file given with `--config <path>` or the environment variable `LENS_SETTINGS_PATH`.
142
+ 2. `config.json` (recommended default)
143
+ 3. `lens.config.json`
144
+ 4. `.lady-lens.json`
145
+ 5. `.lady-lens.yaml`
146
+
147
+ ### Complete example of `config.json`
148
+
149
+ ```json
150
+ {
151
+ "project": {
152
+ "graph_roots": ["."],
153
+ "exclude_dirs": [
154
+ ".git",
155
+ ".memory",
156
+ "node_modules",
157
+ "outputs",
158
+ "coverage",
159
+ "dist",
160
+ "build",
161
+ "target",
162
+ ".vs",
163
+ ".idea"
164
+ ],
165
+ "graph_extensions": [
166
+ ".js",
167
+ ".mjs",
168
+ ".ts",
169
+ ".jsx",
170
+ ".tsx",
171
+ ".cs",
172
+ ".csproj",
173
+ ".sln",
174
+ ".sql",
175
+ ".ps1",
176
+ ".md",
177
+ ".yaml",
178
+ ".yml",
179
+ ".json"
180
+ ]
181
+ },
182
+ "graph": {
183
+ "ast": {
184
+ "enabled": true
185
+ },
186
+ "documentation": {
187
+ "enabled": true
188
+ },
189
+ "links": {
190
+ "enabled": true
191
+ },
192
+ "freshness": {
193
+ "default_max_age_days": 30
194
+ }
195
+ },
196
+ "mcp": {
197
+ "port": 4318,
198
+ "uiPort": 4317
199
+ },
200
+ "database": ".memory/graph/project.lbdb",
201
+ "env": {
202
+ "TOOL_RESULT_CHARS": "6000",
203
+ "READ_CHUNK_MAX_CHARS": "12000",
204
+ "READ_CHUNK_MAX_LINES": "400",
205
+ "GREP_MAX_MATCHES": "50",
206
+ "DEBUG_LEVEL": "2",
207
+ "DEBUG_LOG_FILE": ""
208
+ }
209
+ }
210
+ ```
211
+
212
+ ### Configuration sections
213
+
214
+ 1. **`project`**:
215
+ - `graph_roots`: folders to index (default `["."]`).
216
+ - `exclude_dirs`: folders ignored during sync, glob and grep.
217
+ - `graph_extensions`: file extensions included in the code graph.
218
+ 2. **`graph`**:
219
+ - `ast.enabled`: generate AST chunks and symbol definitions.
220
+ - `documentation.enabled`: index markdown documents and link frontmatter.
221
+ - `links.enabled`: link import and call relations automatically.
222
+ - `freshness.default_max_age_days`: maximum age before automatic re-indexing.
223
+ 3. **`mcp`**:
224
+ - `port`: HTTP/SSE port of the MCP server (default `4318`).
225
+ - `uiPort`: web UI dashboard port (default `4317`).
226
+ 4. **`database`**:
227
+ - Path to the LadybugDB database file. If not set, lens uses `~/.lady-lens/repos/<id>/graph.lbdb`.
228
+ 5. **`env`**:
229
+ - Sets lens environment variables directly (such as `TOOL_RESULT_CHARS`, `DEBUG_LEVEL`).
230
+
231
+ ---
232
+
233
+ ## 4. Using it as an npm package
234
+
235
+ Install the package locally or as a dependency (see [section 0](#0-installation-and-setup); it is not on npmjs.org, so install the `.tgz` from `dist`):
236
+
237
+ ```bash
238
+ npm install ..\lady-lens\dist\lady-lens-<version>.tgz
239
+ ```
240
+
241
+ ### Direct imports (main entry)
242
+
243
+ Every port is available from the root export:
244
+
245
+ ```javascript
246
+ import {
247
+ createGraphSync,
248
+ functionViewTool,
249
+ folderViewTool,
250
+ healthTool,
251
+ definedInTool,
252
+ graph_query,
253
+ grep,
254
+ glob,
255
+ read_chunk,
256
+ RESEARCH_TOOLS,
257
+ loadProjectSettingsSync
258
+ } from 'lady-lens';
259
+
260
+ // 1. Read the settings (reads config.json automatically)
261
+ const settings = loadProjectSettingsSync();
262
+
263
+ // 2. Incremental sync of the repository
264
+ const syncResult = await createGraphSync().sync({ mode: 'incremental' });
265
+ console.log(`Graph synced: ${syncResult.nodes} nodes`);
266
+
267
+ // 3. Ask for a function view
268
+ const fnDetails = await functionViewTool({ symbol: 'createGraphSync' });
269
+ console.log('Callers of createGraphSync:', fnDetails.callers);
270
+
271
+ // 4. Inspect code health
272
+ const health = await healthTool({ limit: 5 });
273
+ console.log('Top hotspots:', health.hotspots);
274
+
275
+ // 5. Semantic graph query
276
+ const queryResult = await graph_query({ query: 'database storage' });
277
+ console.log('Nodes found:', queryResult.nodes);
278
+ ```
279
+
280
+ ### Modular subpath imports
281
+
282
+ Specialised scenarios can use subpath imports:
283
+
284
+ ```javascript
285
+ import { createGraph, createGraphRepository } from 'lady-lens/graph';
286
+ import { RESEARCH_TOOLS, grep, glob } from 'lady-lens/search';
287
+ import { createLadyLensMcpServer, createMcpHttpServer } from 'lady-lens/mcp';
288
+ import { listRegisteredRepos, registerRepo } from 'lady-lens/repository';
289
+ import { createProfiler, globalProfiler } from 'lady-lens/observability';
290
+ ```
291
+
292
+ ---
293
+
294
+ ## 5. Using it as an MCP server
295
+
296
+ Start the background service with the CLI:
297
+
298
+ ```bash
299
+ lens mcp -d
300
+ ```
301
+
302
+ This starts:
303
+ - The **Streamable HTTP MCP server** on `http://127.0.0.1:4318/mcp`
304
+ - The legacy **SSE MCP server** on `http://127.0.0.1:4318/sse`
305
+ - The **UI dashboard** on `http://127.0.0.1:4317`
306
+
307
+ ### AI assistant configuration
308
+
309
+ Add the server to your MCP configuration file (for example in Antigravity, Claude Desktop, Cursor or VS Code):
310
+
311
+ #### Streamable HTTP mode (recommended)
312
+ ```json
313
+ {
314
+ "mcpServers": {
315
+ "lady-lens": {
316
+ "url": "http://127.0.0.1:4318/mcp"
317
+ }
318
+ }
319
+ }
320
+ ```
321
+
322
+ Use `/sse` only for older clients that do not support Streamable HTTP.
323
+
324
+ ### Configuration files through MCP
325
+
326
+ No extra setting in `config.json` is needed. The agent uses these tools:
327
+
328
+ ```json
329
+ {
330
+ "name": "config_references",
331
+ "arguments": { "reference": "PUREQU_OP" }
332
+ }
333
+ ```
334
+
335
+ This returns, among other things, `referenceManager.xml`, the line number and the matching text. Use `config_references` for this, not `imports` or `importedBy`.
336
+
337
+ Read the file before changing it. Then pass the complete new content to `config_update`. Use the SHA-256 of the content you read as `expectedHash`; a stale update is refused.
338
+
339
+ ```json
340
+ {
341
+ "name": "config_update",
342
+ "arguments": {
343
+ "path": "App/App.csproj",
344
+ "content": "<Project>...</Project>",
345
+ "expectedHash": "<sha256>"
346
+ }
347
+ }
348
+ ```
349
+
350
+ Supported: `.csproj`, `.sln`, `.props`, `.targets`, `.xml`, `.ini`, `.yaml`, `.yml`, `.toml` and `package.json`. After an update an incremental graph sync runs.
351
+
352
+ ### Agent instruction
353
+
354
+ Use this text in the agent chat:
355
+
356
+ > Use Lady Lens MCP. First pick the right repo with `repo` or register it with `lens add`. Use `config_references` for questions like: who references `PUREQU_OP`? Do not use `imports` or `importedBy`. Then read the config files found. Use `config_update` with the complete new content and `expectedHash`. Do not write directly outside `config_update`.
357
+
358
+ #### One daemon, several projects
359
+ One daemon serves every registered project (`lens add <folder>`). Pick the project per client in the URL:
360
+
361
+ ```json
362
+ { "mcpServers": { "lady-lens": { "url": "http://127.0.0.1:4318/mcp?repo=C:/git/my-project" } } }
363
+ ```
364
+
365
+ - `repo` is a registered folder or id; the `X-Lens-Repo` header works too.
366
+ - An unregistered repo is refused (HTTP 403): run `lens add <folder>` first.
367
+ - Without `repo` the folder where `lens mcp -d` was started applies; a tool call can override that with its `repo` argument.
368
+ - Tool calls run one after another, so simultaneous requests for different projects do not affect each other.
369
+ - The UI dashboard that starts with `lens mcp -d` works the same way: `http://127.0.0.1:4317/?repo=<folder or id>` shows that project (not registered: HTTP 403); with more than one registered project a dropdown appears.
370
+
371
+ #### Direct stdio mode
372
+ ```json
373
+ {
374
+ "mcpServers": {
375
+ "lady-lens": {
376
+ "command": "node",
377
+ "args": ["C:/git/lady-lens/bin/lens.mjs", "mcp", "--stdio"]
378
+ }
379
+ }
380
+ }
381
+ ```
382
+
383
+ ---
384
+
385
+ ## 6. CLI command reference
386
+
387
+ The command line interface `lens` gives direct access to every feature:
388
+
389
+ | Command | Description |
390
+ | :--- | :--- |
391
+ | `lens sync [--repo <dir>] [--full]` | Sync the graph for the current project or a target folder. |
392
+ | `lens ask <tool> '<json>'` | Call one of the research tools directly (e.g. `lens ask functionView '{"symbol":"createProfiler"}'`). |
393
+ | `lens mcp [-d]` | Start the MCP server (optionally in the background with `-d`). |
394
+ | `lens stop [pid]` | End the background daemon and release ports and locks, or only the given PID. |
395
+ | `lens ps` | Show the tracked daemon PIDs per folder. |
396
+ | `lens status` | Show whether the background daemon is running. |
397
+ | `lens ui [--port 4317]` | Start the interactive graph visualisation in the browser. |
398
+ | `lens list` | Overview of all registered repositories and their database paths. |
399
+ | `lens add <dir>` | Register a new project and run the first sync right away. |
400
+ | `lens remove <id\|dir>` | Remove a repository from the registry. |
401
+ | `lens tools` | Show all available tools with their schemas and parameters. |
402
+ | `lens install [agent...]` | Install the MCP stdio configuration in detected agents. |
403
+ | `lens install --skill` | Install the Lady-lens workflow skill, write `~/.lady-lens/lens-instructions.md`, and add one marked line pointing to it in `~/.claude/CLAUDE.md`, `~/.copilot/copilot-instructions.md`, `~/.codex/AGENTS.md` and `~/.vibe/AGENTS.md`; own rules files for VS Code and Antigravity. |
404
+ | `lens uninstall [agent...]` | Remove the MCP entry from the agents. |
405
+ | `lens uninstall --skill` | Remove the skill, the marked line and the two rules files. |
406
+ | `lens install --mendix` | Install the `lady-lens-mendix` skill in the detected Claude, Copilot and Agents skill directories: search Mendix pages, widgets and flows in `.mxcli/mdl` (written by `lens sync` from mxcli's catalog), change them with `mxcli`. `lens uninstall --mendix` removes it. |
407
+ | `lens v` / `lens version` | Show the installed package version. |
408
+ | `.\scripts\update-lens.ps1 [-Pack] [-Source <source>]` | Stop lens, install the newest package from `dist` (or `-Source`) globally and start `lens mcp -d` again. |