@noyrax/documentation-system-plugin 1.0.4-beta.1 → 1.0.4-beta.11

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 (144) hide show
  1. package/out/cli/generate-cli.js +58 -0
  2. package/out/cli/generate-cli.js.map +1 -1
  3. package/out/cli/scan-cli.js +6 -0
  4. package/out/cli/scan-cli.js.map +1 -1
  5. package/out/core/scanner.js +9 -1
  6. package/out/core/scanner.js.map +1 -1
  7. package/out/generator/system-metadata.js +202 -0
  8. package/out/generator/system-metadata.js.map +1 -0
  9. package/out/index/index.js +14 -0
  10. package/out/index/index.js.map +1 -1
  11. package/out/parsers/json-yaml.js +35 -4
  12. package/out/parsers/json-yaml.js.map +1 -1
  13. package/out/parsers/ts-js.js +208 -7
  14. package/out/parsers/ts-js.js.map +1 -1
  15. package/package.json +11 -4
  16. package/scripts/verify-adrs.js +74 -2
  17. package/scripts/verify-architecture.js +94 -9
  18. package/scripts/verify-imports.js +73 -9
  19. package/.vscodeignore +0 -41
  20. package/MCP_SERVER_SETUP.md +0 -371
  21. package/assets/icon.svg +0 -27
  22. package/docs/LINKEDIN_ANTWORT_SEQUENZDIAGRAMME.md +0 -190
  23. package/docs/SEQUENZDIAGRAMM_BEWEIS.md +0 -469
  24. package/docs/SEQUENZDIAGRAMM_VALIDATE_FLOW.md +0 -282
  25. package/docs/adr/001-signatur-abweichung-fix.md +0 -54
  26. package/docs/adr/002-file-specific-validation-1.0.1.md +0 -45
  27. package/docs/adr/003-documentation-generation-bugs.md +0 -134
  28. package/docs/adr/004-validator-signature-matching-fix.md +0 -121
  29. package/docs/adr/005-validator-generic-simplification-tightening.md +0 -35
  30. package/docs/adr/006-parser-variable-type-extraction.md +0 -33
  31. package/docs/adr/007-ts-parser-load-libs-for-accurate-types.md +0 -31
  32. package/docs/adr/008-dependencies-cache-phase1.md +0 -133
  33. package/docs/adr/009-consolidation-union-logic-phase1-2.md +0 -147
  34. package/docs/adr/010-extension-union-integration-phase1-3-and-phase2.md +0 -179
  35. package/docs/adr/011-module-doc-change-tracking-phase3.md +0 -190
  36. package/docs/adr/012-git-deletions-change-report-phase4.md +0 -235
  37. package/docs/adr/013-system-functionality-fixes.md +0 -279
  38. package/docs/adr/014-rules-migration-und-mcp-integration.md +0 -113
  39. package/docs/adr/015-global-agent-package.md +0 -158
  40. package/docs/adr/016-produktisierung-docguard.md +0 -193
  41. package/docs/adr/017-signature-matching-optional-fields.md +0 -128
  42. package/docs/adr/018-rebranding-docguard-to-noyrax.md +0 -109
  43. package/docs/adr/019-system-schwachstellen-analyse-und-fixes.md +0 -204
  44. package/docs/adr/020-api-doc-tiefe-und-signatureformatter.md +0 -74
  45. package/docs/adr/021-semantic-api-docs-and-symbol-classifier.md +0 -125
  46. package/docs/adr/022-semantic-class-and-constants-rendering.md +0 -82
  47. package/docs/adr/023-adr-verknuepfung-modul-doku.md +0 -54
  48. package/docs/adr/024-cursor-rules-mehrdimensionaler-raum.md +0 -230
  49. package/docs/adr/025-mcp-tools-scan-validate-cli-bridge.md +0 -202
  50. package/docs/adr/026-reality-driven-development-system.md +0 -173
  51. package/docs/adr/027-scanner-excludes-and-union-logic-fix.md +0 -189
  52. package/docs/adr/028-src-coverage-union-resync.md +0 -124
  53. package/docs/adr/029-parser-flow-kopplung-und-sync-drift-modi.md +0 -102
  54. package/docs/adr/030-dependency-import-symbol-names-preservation.md +0 -123
  55. package/docs/adr/031-generate-cli-vollstaendige-dokumentation.md +0 -99
  56. package/docs/adr/032-windows-optimized-verification-scripts.md +0 -165
  57. package/docs/adr/036-enhanced-dependency-metadata.md +0 -190
  58. package/docs/adr/TEMPLATE.md +0 -76
  59. package/docs/index/symbols.jsonl +0 -31
  60. package/docs/modules/action__action.yml.md +0 -50
  61. package/docs/modules/documentation.config.schema.json.md +0 -37
  62. package/docs/modules/mcp__package.json.md +0 -130
  63. package/docs/modules/mcp__src__resources__docs.ts.md +0 -94
  64. package/docs/modules/mcp__src__server.ts.md +0 -15
  65. package/docs/modules/mcp__src__tools__drift.ts.md +0 -110
  66. package/docs/modules/mcp__src__tools__impact.ts.md +0 -127
  67. package/docs/modules/mcp__src__tools__scan.ts.md +0 -75
  68. package/docs/modules/mcp__src__tools__validate.ts.md +0 -116
  69. package/docs/modules/mcp__src__tools__verify-adrs.ts.md +0 -106
  70. package/docs/modules/mcp__tsconfig.json.md +0 -22
  71. package/docs/modules/package.json.md +0 -131
  72. package/docs/modules/packages__doc-system-agent__examples__basic-project__package.json.md +0 -43
  73. package/docs/modules/packages__doc-system-agent__examples__basic-project__src__calculator.ts.md +0 -81
  74. package/docs/modules/packages__doc-system-agent__package.json.md +0 -154
  75. package/docs/modules/packages__doc-system-agent__src__cli__index.ts.md +0 -8
  76. package/docs/modules/packages__doc-system-agent__src__cli__init.ts.md +0 -93
  77. package/docs/modules/packages__doc-system-agent__src__cli__update.ts.md +0 -113
  78. package/docs/modules/packages__doc-system-agent__src__constants.ts.md +0 -29
  79. package/docs/modules/packages__doc-system-agent__src__index.ts.md +0 -234
  80. package/docs/modules/packages__doc-system-agent__src__mcp__resources__docs.ts.md +0 -94
  81. package/docs/modules/packages__doc-system-agent__src__mcp__server.ts.md +0 -17
  82. package/docs/modules/packages__doc-system-agent__src__mcp__tools__drift.ts.md +0 -38
  83. package/docs/modules/packages__doc-system-agent__src__mcp__tools__impact.ts.md +0 -75
  84. package/docs/modules/packages__doc-system-agent__src__mcp__tools__scan.ts.md +0 -23
  85. package/docs/modules/packages__doc-system-agent__src__mcp__tools__validate.ts.md +0 -23
  86. package/docs/modules/packages__doc-system-agent__src__mcp__tools__verify-adrs.ts.md +0 -106
  87. package/docs/modules/packages__doc-system-agent__src__mcp__types.ts.md +0 -355
  88. package/docs/modules/packages__doc-system-agent__tsconfig.json.md +0 -22
  89. package/docs/modules/scripts__verify-adrs.js.md +0 -97
  90. package/docs/modules/scripts__verify-architecture.js.md +0 -93
  91. package/docs/modules/scripts__verify-imports.js.md +0 -114
  92. package/docs/modules/src____tests____setup.ts.md +0 -8
  93. package/docs/modules/src____tests____signature-formatter.test.ts.md +0 -16
  94. package/docs/modules/src____tests____snapshot-doc-generation.test.ts.md +0 -8
  95. package/docs/modules/src____tests____symbol-classifier.test.ts.md +0 -16
  96. package/docs/modules/src__cache__ast-cache.ts.md +0 -91
  97. package/docs/modules/src__cache__dependencies-cache.ts.md +0 -89
  98. package/docs/modules/src__cache__output-cache.ts.md +0 -91
  99. package/docs/modules/src__cache__signature-cache.ts.md +0 -76
  100. package/docs/modules/src__cli__generate-cli.ts.md +0 -130
  101. package/docs/modules/src__cli__scan-cli.ts.md +0 -99
  102. package/docs/modules/src__cli__validate-cli.ts.md +0 -144
  103. package/docs/modules/src__core__async.ts.md +0 -18
  104. package/docs/modules/src__core__consolidation.ts.md +0 -158
  105. package/docs/modules/src__core__git.ts.md +0 -35
  106. package/docs/modules/src__core__language-detection.ts.md +0 -31
  107. package/docs/modules/src__core__scanner.ts.md +0 -101
  108. package/docs/modules/src__core__signature-formatter.ts.md +0 -232
  109. package/docs/modules/src__core__symbol-classifier.ts.md +0 -178
  110. package/docs/modules/src__core__symbols.ts.md +0 -31
  111. package/docs/modules/src__drift__index.ts.md +0 -53
  112. package/docs/modules/src__extension.ts.md +0 -418
  113. package/docs/modules/src__generator__adr-linker.ts.md +0 -154
  114. package/docs/modules/src__generator__change-report.ts.md +0 -85
  115. package/docs/modules/src__generator__dependency-graph.ts.md +0 -63
  116. package/docs/modules/src__generator__index.ts.md +0 -40
  117. package/docs/modules/src__generator__module-doc.ts.md +0 -242
  118. package/docs/modules/src__index__index.ts.md +0 -141
  119. package/docs/modules/src__logging__index.ts.md +0 -87
  120. package/docs/modules/src__parsers__dependencies.ts.md +0 -69
  121. package/docs/modules/src__parsers__json-yaml.ts.md +0 -81
  122. package/docs/modules/src__parsers__python.ts.md +0 -73
  123. package/docs/modules/src__parsers__ts-js.ts.md +0 -48
  124. package/docs/modules/src__parsers__types.ts.md +0 -99
  125. package/docs/modules/src__ui__commands-provider.ts.md +0 -70
  126. package/docs/modules/src__ui__status-bar.ts.md +0 -79
  127. package/docs/modules/src__validator__index.ts.md +0 -211
  128. package/docs/modules/src__validator__signature-matching.ts.md +0 -209
  129. package/docs/modules/src__validator__status.ts.md +0 -72
  130. package/docs/modules/test-mcp-resources.js.md +0 -27
  131. package/docs/modules/tsconfig.json.md +0 -22
  132. package/docs/system/CHANGE_REPORT.md +0 -19
  133. package/docs/system/DEPENDENCIES.md +0 -430
  134. package/docs/system/DEPENDENCY_GRAPH.md +0 -368
  135. package/docs/system/NAVIGATION_SPACE_ANALYSIS.md +0 -244
  136. package/docs/system/NPX_CACHE_FIX.md +0 -85
  137. package/docs/system/NPX_LOCAL_USAGE.md +0 -66
  138. package/docs/system/PLUGIN_ECOSYSTEM_STATUS.md +0 -465
  139. package/docs/system/PLUGIN_UPDATE_GUIDE.md +0 -212
  140. package/docs/system/RULES_UPDATE_GUIDE.md +0 -182
  141. package/docs/system/SYSTEM_ANALYSIS.md +0 -947
  142. package/documentation.config.schema.json +0 -77
  143. package/noyrax-5d-database-plugin-0.1.8.tgz +0 -0
  144. package/publish.ps1 +0 -21
@@ -16,14 +16,54 @@ const { execSync } = require('child_process');
16
16
  const errors = [];
17
17
  const warnings = [];
18
18
 
19
+ /**
20
+ * Findet ein Verzeichnis durch intelligente Suche.
21
+ * Sucht im gegebenen Verzeichnis und in Parent-Verzeichnissen (max. 5 Ebenen).
22
+ *
23
+ * @param startDir Das Verzeichnis, von dem aus gesucht werden soll
24
+ * @param targetPath Relativer Pfad zum gesuchten Verzeichnis (z.B. 'mcp/src' oder 'package.json')
25
+ * @param maxDepth Maximale Anzahl von Parent-Ebenen, die durchsucht werden sollen (default: 5)
26
+ * @returns Der Pfad zum Verzeichnis/File oder null, wenn nicht gefunden
27
+ */
28
+ function findDirectoryOrFile(startDir, targetPath, maxDepth = 5) {
29
+ let currentDir = path.resolve(startDir);
30
+ let depth = 0;
31
+
32
+ while (depth < maxDepth) {
33
+ const targetFullPath = path.join(currentDir, targetPath);
34
+ if (fs.existsSync(targetFullPath)) {
35
+ return targetFullPath;
36
+ }
37
+
38
+ const parentDir = path.dirname(currentDir);
39
+
40
+ // Stop if we've reached the root (parent equals current)
41
+ if (parentDir === currentDir) {
42
+ break;
43
+ }
44
+
45
+ currentDir = parentDir;
46
+ depth++;
47
+ }
48
+
49
+ return null;
50
+ }
51
+
19
52
  /**
20
53
  * Prüft ob mcp/ direkt nach src/ importiert
21
54
  */
22
- function checkMcpToSrcImports() {
55
+ function checkMcpToSrcImports(workspaceRoot) {
23
56
  console.log('🔍 Checking for invalid imports from mcp/ to src/...');
24
57
 
25
- const mcpSrcDir = path.join(__dirname, '..', 'mcp', 'src');
26
- if (!fs.existsSync(mcpSrcDir)) {
58
+ // Suche mcp/src relativ zu workspaceRoot
59
+ let mcpSrcDir = findDirectoryOrFile(workspaceRoot, 'mcp/src');
60
+ if (!mcpSrcDir) {
61
+ // Fallback: Versuche __dirname + '/..' (Plugin-interne Suche)
62
+ const fallbackRoot = path.join(__dirname, '..');
63
+ mcpSrcDir = findDirectoryOrFile(fallbackRoot, 'mcp/src');
64
+ }
65
+
66
+ if (!mcpSrcDir) {
27
67
  console.log('⚠️ mcp/src directory not found, skipping check');
28
68
  return;
29
69
  }
@@ -82,13 +122,30 @@ function checkImportDirections() {
82
122
  /**
83
123
  * Prüft package.json type Feld
84
124
  */
85
- function checkPackageJsonType() {
125
+ function checkPackageJsonType(workspaceRoot) {
86
126
  console.log('🔍 Checking package.json type fields...');
87
127
 
88
- const rootPackageJson = path.join(__dirname, '..', 'package.json');
89
- const mcpPackageJson = path.join(__dirname, '..', 'mcp', 'package.json');
128
+ // Suche package.json relativ zu workspaceRoot
129
+ let rootPackageJson = findDirectoryOrFile(workspaceRoot, 'package.json');
130
+ if (!rootPackageJson) {
131
+ // Fallback: Versuche __dirname + '/..' (Plugin-interne Suche)
132
+ const fallbackRoot = path.join(__dirname, '..');
133
+ rootPackageJson = findDirectoryOrFile(fallbackRoot, 'package.json');
134
+ }
90
135
 
91
- if (fs.existsSync(rootPackageJson)) {
136
+ let mcpPackageJson = findDirectoryOrFile(workspaceRoot, 'mcp/package.json');
137
+ if (!mcpPackageJson && rootPackageJson) {
138
+ // Wenn rootPackageJson gefunden wurde, versuche mcp/package.json relativ dazu
139
+ const rootDir = path.dirname(rootPackageJson);
140
+ mcpPackageJson = findDirectoryOrFile(rootDir, 'mcp/package.json');
141
+ }
142
+ if (!mcpPackageJson) {
143
+ // Fallback: Versuche __dirname + '/..' (Plugin-interne Suche)
144
+ const fallbackRoot = path.join(__dirname, '..');
145
+ mcpPackageJson = findDirectoryOrFile(fallbackRoot, 'mcp/package.json');
146
+ }
147
+
148
+ if (rootPackageJson && fs.existsSync(rootPackageJson)) {
92
149
  const rootPkg = JSON.parse(fs.readFileSync(rootPackageJson, 'utf8'));
93
150
  if (!rootPkg.type) {
94
151
  console.log('✅ Root package.json has no type field (defaults to CommonJS)');
@@ -141,11 +198,39 @@ function getAllTsFiles(dir) {
141
198
  * Hauptfunktion
142
199
  */
143
200
  function main() {
201
+ // Workspace-Root bestimmen:
202
+ // 1. Falls als erstes Argument übergeben, verwenden
203
+ // 2. Sonst process.cwd() verwenden (wird vom MCP-Tool als cwd gesetzt)
204
+ // 3. Fallback: __dirname + '/..' (für Kompatibilität mit direktem Aufruf)
205
+ let workspaceRoot;
206
+
207
+ if (process.argv.length >= 3 && process.argv[2] !== '--' && process.argv[2] !== '--verbose') {
208
+ // Erstes Argument ist Workspace-Root (vor -- oder --verbose)
209
+ workspaceRoot = path.resolve(process.argv[2]);
210
+ // Argument aus process.argv entfernen, damit --verbose weiterhin funktioniert
211
+ process.argv.splice(2, 1);
212
+ } else {
213
+ // Standard: process.cwd() (wird vom MCP-Tool als cwd gesetzt)
214
+ workspaceRoot = process.cwd();
215
+
216
+ // Fallback: __dirname + '/..' (nur wenn process.cwd() nicht das richtige Verzeichnis ist)
217
+ // Prüfe, ob package.json in process.cwd() gefunden werden kann
218
+ const packageJsonFromCwd = findDirectoryOrFile(workspaceRoot, 'package.json');
219
+ if (!packageJsonFromCwd) {
220
+ // Fallback: Versuche __dirname + '/..'
221
+ const fallbackRoot = path.join(__dirname, '..');
222
+ const packageJsonFromFallback = findDirectoryOrFile(fallbackRoot, 'package.json');
223
+ if (packageJsonFromFallback) {
224
+ workspaceRoot = fallbackRoot;
225
+ }
226
+ }
227
+ }
228
+
144
229
  console.log('🚀 Starting architecture verification...\n');
145
230
 
146
- checkMcpToSrcImports();
231
+ checkMcpToSrcImports(workspaceRoot);
147
232
  checkImportDirections();
148
- checkPackageJsonType();
233
+ checkPackageJsonType(workspaceRoot);
149
234
 
150
235
  console.log('\n📊 Verification Summary:');
151
236
  console.log(` Errors: ${errors.length}`);
@@ -88,11 +88,45 @@ function extractExports(filePath) {
88
88
  return exports;
89
89
  }
90
90
 
91
+ /**
92
+ * Findet das src/ Verzeichnis durch intelligente Suche.
93
+ * Sucht im gegebenen Verzeichnis und in Parent-Verzeichnissen (max. 5 Ebenen).
94
+ *
95
+ * @param startDir Das Verzeichnis, von dem aus gesucht werden soll
96
+ * @param maxDepth Maximale Anzahl von Parent-Ebenen, die durchsucht werden sollen (default: 5)
97
+ * @returns Der Pfad zum src/ Verzeichnis oder null, wenn nicht gefunden
98
+ */
99
+ function findSrcDirectory(startDir, maxDepth = 5) {
100
+ let currentDir = path.resolve(startDir);
101
+ let depth = 0;
102
+
103
+ while (depth < maxDepth) {
104
+ const srcPath = path.join(currentDir, 'src');
105
+ if (fs.existsSync(srcPath)) {
106
+ const stats = fs.statSync(srcPath);
107
+ if (stats.isDirectory()) {
108
+ return srcPath;
109
+ }
110
+ }
111
+
112
+ const parentDir = path.dirname(currentDir);
113
+
114
+ // Stop if we've reached the root (parent equals current)
115
+ if (parentDir === currentDir) {
116
+ break;
117
+ }
118
+
119
+ currentDir = parentDir;
120
+ depth++;
121
+ }
122
+
123
+ return null;
124
+ }
125
+
91
126
  /**
92
127
  * Prüft ob ein Import verfügbar ist
93
128
  */
94
- function checkImport(importPath, importedName, fromFile) {
95
- const workspaceRoot = path.join(__dirname, '..');
129
+ function checkImport(importPath, importedName, fromFile, workspaceRoot) {
96
130
 
97
131
  // Resolve import path
98
132
  let targetFile;
@@ -196,7 +230,7 @@ function checkFileImports(filePath, workspaceRoot) {
196
230
 
197
231
  // Check each imported name
198
232
  importedNames.forEach(name => {
199
- checkImport(importPath, name, filePath);
233
+ checkImport(importPath, name, filePath, workspaceRoot);
200
234
  });
201
235
  }
202
236
  }
@@ -205,16 +239,46 @@ function checkFileImports(filePath, workspaceRoot) {
205
239
  * Hauptfunktion
206
240
  */
207
241
  function main() {
208
- const workspaceRoot = path.join(__dirname, '..');
209
-
210
- console.log('🚀 Starting import verification...\n');
242
+ // Workspace-Root bestimmen:
243
+ // 1. Falls als erstes Argument übergeben, verwenden
244
+ // 2. Sonst process.cwd() verwenden (wird vom MCP-Tool als cwd gesetzt)
245
+ // 3. Fallback: __dirname + '/..' (für Kompatibilität mit direktem Aufruf)
246
+ let workspaceRoot;
211
247
 
212
- // Check src/ directory
213
- const srcDir = path.join(workspaceRoot, 'src');
214
- if (!fs.existsSync(srcDir)) {
248
+ if (process.argv.length >= 3 && process.argv[2] !== '--' && process.argv[2] !== '--verbose') {
249
+ // Erstes Argument ist Workspace-Root (vor -- oder --verbose)
250
+ workspaceRoot = path.resolve(process.argv[2]);
251
+ // Argument aus process.argv entfernen, damit --verbose weiterhin funktioniert
252
+ process.argv.splice(2, 1);
253
+ } else {
254
+ // Standard: process.cwd() (wird vom MCP-Tool als cwd gesetzt)
255
+ workspaceRoot = process.cwd();
256
+
257
+ // Fallback: __dirname + '/..' (nur wenn process.cwd() nicht das richtige Verzeichnis ist)
258
+ // Prüfe, ob src/ in process.cwd() gefunden werden kann
259
+ const srcFromCwd = findSrcDirectory(workspaceRoot);
260
+ if (!srcFromCwd) {
261
+ // Fallback: Versuche __dirname + '/..'
262
+ const fallbackRoot = path.join(__dirname, '..');
263
+ const srcFromFallback = findSrcDirectory(fallbackRoot);
264
+ if (srcFromFallback) {
265
+ workspaceRoot = fallbackRoot;
266
+ }
267
+ }
268
+ }
269
+
270
+ // src/ Verzeichnis finden (intelligente Suche)
271
+ const srcDir = findSrcDirectory(workspaceRoot);
272
+ if (!srcDir) {
215
273
  console.log('⚠️ src/ directory not found, skipping verification');
274
+ console.log(` Searched from: ${workspaceRoot}`);
216
275
  process.exit(0);
217
276
  }
277
+
278
+ // workspaceRoot auf Basis des gefundenen src/ korrigieren
279
+ workspaceRoot = path.dirname(srcDir);
280
+
281
+ console.log('🚀 Starting import verification...\n');
218
282
 
219
283
  const files = getAllTsFiles(srcDir);
220
284
  console.log(`📁 Found ${files.length} TypeScript files\n`);
package/.vscodeignore DELETED
@@ -1,41 +0,0 @@
1
- # Source Maps und Type Definitions nicht benötigt
2
- out/**/*.map
3
- out/**/*.d.ts
4
- dist/**
5
- test-corpus/**
6
-
7
- # Source Files nicht benötigt (nur kompilierte out/ Dateien)
8
- src/**
9
-
10
- # Demo-Projekt nicht ins VSIX packen
11
- demo/**
12
-
13
- # Website / Marketing
14
- website/**
15
-
16
- # Interne Pläne und Editor-/Agent-Metadaten
17
- plans-archive/**
18
- .cursor/**
19
- .ai-agent-context/**
20
- .ai-agent-rules.json
21
-
22
- # Generierte Dokumentation nicht ins VSIX packen
23
- docs/**
24
-
25
- # MCP Server und Packages nicht ins VSIX packen (separate Projekte)
26
- mcp/**
27
- packages/**
28
-
29
- # GitHub Actions nicht ins VSIX packen
30
- action/**
31
-
32
- # Lokale Build-/Cache-Artefakte
33
- *.vsix
34
- *.zip
35
- temp-vsix-extract/**
36
- temp-check/**
37
- temp-*/**
38
- *.log
39
-
40
- # node_modules wird von vsce automatisch eingebunden (nur dependencies, nicht devDependencies)
41
- # Daher NICHT ausschließen - vsce kümmert sich darum
@@ -1,371 +0,0 @@
1
- # MCP Server Setup für LLM-Agenten
2
-
3
- ## Übersicht
4
-
5
- Der 5D Database Plugin MCP Server ermöglicht es LLM-Agenten (Claude, GPT, Cursor AI), über das Model Context Protocol (MCP) auf die Datenbanken zuzugreifen.
6
-
7
- ## Voraussetzungen
8
-
9
- ⚠️ **KRITISCH: System-Kopplung**
10
-
11
- **Das Documentation System Plugin (Noyrax) und das 5D Database Plugin müssen beide installiert und konfiguriert sein!**
12
-
13
- ```
14
- 1. Documentation System Plugin (Noyrax) → generiert docs/
15
- 2. 5D Database Plugin → ingestiert docs/ in SQLite-DBs
16
- 3. MCP-Server → ermöglicht LLM-Agenten-Zugriff
17
- ```
18
-
19
- ## Installation
20
-
21
- ### Option 1: Via VS Code Extension (Development)
22
-
23
- ```bash
24
- # 1. Extension kompilieren
25
- cd 5d-database-plugin
26
- npm install
27
- npm run compile
28
-
29
- # 2. MCP-Server direkt starten
30
- node out/cli/mcp-server-cli.js /path/to/workspace
31
- ```
32
-
33
- ### Option 2: Via npm Package (wenn veröffentlicht)
34
-
35
- ```bash
36
- # 1. Package installieren
37
- npm install -g @noyrax/5d-database-plugin
38
-
39
- # 2. MCP-Server starten
40
- noyrax-5d-database-mcp /path/to/workspace
41
- ```
42
-
43
- ### Option 3: Via npx (ohne Installation)
44
-
45
- ```bash
46
- npx -y @noyrax/5d-database-plugin mcp-server /path/to/workspace
47
- ```
48
-
49
- ## CLI-Tools für direkten Zugriff (AI-Agenten)
50
-
51
- Für AI-Agenten (wie Cursor AI) stehen zusätzliche CLI-Tools zur Verfügung, die direkten Zugriff auf Datenbanken und Tools bieten, ohne MCP-Server-Prozess:
52
-
53
- ### Query-CLI (Datenbank-Queries)
54
-
55
- Direkter Zugriff auf Datenbank-Queries:
56
-
57
- ```bash
58
- # Query Module
59
- noyrax-5d-database-query <workspace-root> modules <filePath>
60
-
61
- # Query Symbols
62
- noyrax-5d-database-query <workspace-root> symbols <path|symbolId>
63
-
64
- # Query Dependencies
65
- noyrax-5d-database-query <workspace-root> dependencies --from <path>
66
- noyrax-5d-database-query <workspace-root> dependencies --to <path>
67
-
68
- # Query ADRs
69
- noyrax-5d-database-query <workspace-root> adrs --number <num>
70
- noyrax-5d-database-query <workspace-root> adrs --path <path>
71
-
72
- # Query Changes
73
- noyrax-5d-database-query <workspace-root> changes
74
- ```
75
-
76
- ### Tool-CLI (MCP-Tools direkt)
77
-
78
- Direkter Zugriff auf MCP-Tools ohne Server:
79
-
80
- ```bash
81
- # Bootstrap
82
- noyrax-5d-database-tool <workspace-root> bootstrap
83
-
84
- # Semantic Discovery
85
- noyrax-5d-database-tool <workspace-root> semantic_discovery "How does ingestion work?" [limit]
86
-
87
- # System Explanation
88
- noyrax-5d-database-tool <workspace-root> system_explanation
89
-
90
- # Learning Path
91
- noyrax-5d-database-tool <workspace-root> learning_path <topic>
92
-
93
- # Cross Analysis
94
- noyrax-5d-database-tool <workspace-root> cross_analysis <filePath>
95
-
96
- # Gap Analysis (ab Version 0.1.8)
97
- noyrax-5d-database-tool <workspace-root> gap_analysis [--min-deps N] [--limit N]
98
-
99
- # Architecture Mining (ab Version 0.1.8)
100
- noyrax-5d-database-tool <workspace-root> architecture_mining [filePath]
101
- ```
102
-
103
- ### Semantic-Search-CLI (V-Dimension)
104
-
105
- Direkter Zugriff auf Semantic Search:
106
-
107
- ```bash
108
- # Semantic Search
109
- noyrax-5d-database-search <workspace-root> "How does the MCP server work?" --limit 10
110
-
111
- # Mit spezifischen Dimensionen
112
- noyrax-5d-database-search <workspace-root> "ingestion" --dimensions X,W --limit 5
113
- ```
114
-
115
- **Vorteile für AI-Agenten:**
116
- - Schneller als MCP-Server (kein JSON-RPC-Overhead)
117
- - Direkter API-Zugriff
118
- - JSON-Output einfach zu parsen
119
- - Keine zusätzliche Infrastruktur nötig
120
-
121
- ## Konfiguration für LLM-Agenten
122
-
123
- ### Claude Desktop
124
-
125
- Konfiguriere den MCP Server in `claude_desktop_config.json`:
126
-
127
- **Windows:**
128
- ```
129
- %APPDATA%\Claude\claude_desktop_config.json
130
- ```
131
-
132
- **macOS:**
133
- ```
134
- ~/Library/Application Support/Claude/claude_desktop_config.json
135
- ```
136
-
137
- **Linux:**
138
- ```
139
- ~/.config/Claude/claude_desktop_config.json
140
- ```
141
-
142
- #### Konfiguration (Entwicklung - lokaler Pfad):
143
-
144
- ```json
145
- {
146
- "mcpServers": {
147
- "5d-database": {
148
- "command": "node",
149
- "args": [
150
- "D:/path/to/5d-database-plugin/out/cli/mcp-server-cli.js",
151
- "${workspaceFolder}"
152
- ]
153
- }
154
- }
155
- }
156
- ```
157
-
158
- #### Konfiguration (Production - npm Package):
159
-
160
- ```json
161
- {
162
- "mcpServers": {
163
- "5d-database": {
164
- "command": "npx",
165
- "args": [
166
- "-y",
167
- "@noyrax/5d-database-plugin",
168
- "mcp-server",
169
- "${workspaceFolder}"
170
- ]
171
- }
172
- }
173
- }
174
- ```
175
-
176
- ### Andere LLM-Agenten
177
-
178
- Der MCP-Server kommuniziert via stdin/stdout (JSON-RPC 2.0). Jeder MCP-kompatible Agent kann den Server nutzen, indem er:
179
-
180
- 1. Den Server als Child-Process startet: `node out/cli/mcp-server-cli.js <workspace-root>`
181
- 2. JSON-RPC 2.0 Requests via stdin sendet
182
- 3. JSON-RPC 2.0 Responses via stdout empfängt
183
-
184
- ## Verfügbare Tools
185
-
186
- Der MCP-Server stellt folgende Tools bereit:
187
-
188
- | Tool | Beschreibung | Parameter |
189
- |------|--------------|-----------|
190
- | `bootstrap` | Erste Anlaufstelle für Agenten ohne Vorwissen | `pluginId` |
191
- | `semantic_discovery` | Semantic Search in natürlicher Sprache | `query`, `pluginId`, `limit?` |
192
- | `system_explanation` | System-Übersicht, Entry Points, Architecture ADRs | `pluginId` |
193
- | `learning_path` | Geführter Lernpfad für ein Topic | `topic`, `pluginId` |
194
- | `query_modules` | Query Module nach filePath | `filePath`, `pluginId` |
195
- | `query_symbols` | Query Symbols nach path oder symbolId | `path?`, `symbolId?`, `pluginId` |
196
- | `query_dependencies` | Query Dependencies nach fromModule oder toModule | `fromModule?`, `toModule?`, `pluginId` |
197
- | `cross_analysis` | Cross-Dimension-Analyse für filePath | `filePath`, `pluginId` |
198
- | `gap_analysis` | Findet Dokumentationslücken (Module mit vielen Dependencies aber wenigen ADRs) | `pluginId`, `minDependencies?` (default: 5), `limit?` (default: 50) |
199
- | `architecture_mining` | Leitet Architektur-Entscheidungen aus Code-Struktur ab | `pluginId`, `filePath?` (optional, für spezifische Datei) |
200
-
201
- ## Verfügbare Resources
202
-
203
- | Resource | Beschreibung | URI Format |
204
- |----------|--------------|------------|
205
- | Modules | Alle Module (X-Dimension) | `db://modules/{pluginId}` |
206
- | Symbols | Alle Symbols (Y-Dimension) | `db://symbols/{pluginId}` |
207
- | Dependencies | Alle Dependencies (Z-Dimension) | `db://dependencies/{pluginId}` |
208
- | ADRs | Alle ADRs (W-Dimension) | `db://adrs/{pluginId}` |
209
- | Changes | Alle Change Reports (T-Dimension) | `db://changes/{pluginId}` |
210
-
211
- ## Workflow
212
-
213
- ### 1. Dokumentation generieren (Noyrax)
214
-
215
- ```bash
216
- # Documentation System Plugin ausführen
217
- noyrax-documentation generate /path/to/workspace
218
- # Erstellt docs/ Ordner mit allen 5 Dimensionen
219
- ```
220
-
221
- ### 2. Ingestion ausführen (5D Database Plugin)
222
-
223
- ```bash
224
- # 5D Database Plugin ausführen
225
- noyrax-5d-database ingest /path/to/workspace
226
- # Liest docs/ und speichert in SQLite-DBs (.database-plugin/)
227
- ```
228
-
229
- ### 3. MCP-Server starten
230
-
231
- ```bash
232
- # MCP-Server starten (für LLM-Agenten)
233
- noyrax-5d-database-mcp /path/to/workspace
234
- ```
235
-
236
- ### 4. LLM-Agent nutzen
237
-
238
- Der LLM-Agent kann nun:
239
- - `bootstrap` Tool aufrufen, um System zu verstehen
240
- - `semantic_discovery` Tool nutzen, um relevante Code-Entitäten zu finden
241
- - `system_explanation` Tool nutzen, um Entry Points zu finden
242
- - `learning_path` Tool nutzen, um geführte Lernpfade zu generieren
243
- - Resources lesen, um auf Datenbanken zuzugreifen
244
-
245
- ## Troubleshooting
246
-
247
- ### "docs/ directory not found"
248
-
249
- **Problem:** Documentation System Plugin wurde nicht ausgeführt.
250
-
251
- **Lösung:**
252
- ```bash
253
- # Schritt 1: Dokumentation generieren
254
- noyrax-documentation generate /path/to/workspace
255
- ```
256
-
257
- ### "No modules found in database"
258
-
259
- **Problem:** Ingestion wurde nicht ausgeführt.
260
-
261
- **Lösung:**
262
- ```bash
263
- # Schritt 2: Ingestion ausführen
264
- noyrax-5d-database ingest /path/to/workspace
265
- ```
266
-
267
- ### "MCP Server connection failed"
268
-
269
- **Problem:** MCP-Server konnte nicht gestartet werden.
270
-
271
- **Lösung:**
272
- 1. Prüfe ob beide Plugins installiert sind (Noyrax + 5D Database)
273
- 2. Prüfe ob `docs/` existiert
274
- 3. Prüfe ob Ingestion ausgeführt wurde
275
- 4. Prüfe MCP-Server-Konfiguration in Claude Desktop
276
-
277
- ### "Permission denied" beim Starten des Servers
278
-
279
- **Problem:** Node.js-Script ist nicht ausführbar.
280
-
281
- **Lösung (Linux/macOS):**
282
- ```bash
283
- chmod +x out/cli/mcp-server-cli.js
284
- ```
285
-
286
- ## Beispiel-Interaktion
287
-
288
- ### 1. Bootstrap (First Contact)
289
-
290
- **LLM-Agent fragt:**
291
- ```json
292
- {
293
- "method": "tools/call",
294
- "params": {
295
- "name": "bootstrap",
296
- "arguments": {
297
- "pluginId": "a1b2c3d4e5f6g7h8"
298
- }
299
- }
300
- }
301
- ```
302
-
303
- **Server antwortet:**
304
- ```json
305
- {
306
- "content": [{
307
- "type": "text",
308
- "text": "{\"what_am_i\": \"...\", \"where_to_start\": [...], ...}"
309
- }]
310
- }
311
- ```
312
-
313
- ### 2. Semantic Discovery
314
-
315
- **LLM-Agent fragt:**
316
- ```json
317
- {
318
- "method": "tools/call",
319
- "params": {
320
- "name": "semantic_discovery",
321
- "arguments": {
322
- "query": "How does ingestion work?",
323
- "pluginId": "a1b2c3d4e5f6g7h8",
324
- "limit": 10
325
- }
326
- }
327
- }
328
- ```
329
-
330
- **Server antwortet:**
331
- ```json
332
- {
333
- "content": [{
334
- "type": "text",
335
- "text": "{\"entities\": [...], \"context\": {...}}"
336
- }]
337
- }
338
- ```
339
-
340
- ## CLI-Tools vs. MCP-Server
341
-
342
- **MCP-Server** ist für externe LLM-Agenten gedacht, die keine direkte Codebase-Zugriff haben (z.B. Claude Desktop).
343
-
344
- **CLI-Tools** sind für AI-Agenten gedacht, die direkten Codebase-Zugriff haben (z.B. Cursor AI):
345
-
346
- - `noyrax-5d-database-query` - Direkte Datenbank-Queries
347
- - `noyrax-5d-database-tool` - MCP-Tools direkt nutzen
348
- - `noyrax-5d-database-search` - Semantic Search direkt
349
-
350
- **Vorteile CLI-Tools:**
351
- - Schneller (kein JSON-RPC-Overhead)
352
- - Einfacher zu nutzen (direkter API-Zugriff)
353
- - Kein Server-Prozess nötig
354
-
355
- **Wann MCP-Server nutzen:**
356
- - Externe LLM-Agenten (Claude Desktop, etc.)
357
- - Standardisiertes Protokoll (JSON-RPC 2.0)
358
- - Tool-Integration in Agent-UIs
359
-
360
- ## Weitere Informationen
361
-
362
- - Siehe `SETUP_NEW_PROJECT.md` für vollständigen Setup-Workflow
363
- - Siehe `README.md` für allgemeine Plugin-Dokumentation
364
- - Siehe ADR-007 für MCP-Server-Architektur-Details
365
- - Siehe ADR-028 für Semantic Brain MCP-Tools
366
- - Siehe ADR-033 für MCP-Server CLI-Integration und System-Kopplung
367
- - Siehe ADR-034 für Gap Analysis Tool
368
- - Siehe ADR-035 für Architecture Mining Tool
369
-
370
- **Hinweis:** Die Tools `gap_analysis` und `architecture_mining` sind ab Version 0.1.8 verfügbar.
371
-
package/assets/icon.svg DELETED
@@ -1,27 +0,0 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
2
- <defs>
3
- <linearGradient id="noyraxGradient" x1="0%" y1="0%" x2="100%" y2="100%">
4
- <stop offset="0%" style="stop-color:#2563EB;stop-opacity:1" />
5
- <stop offset="100%" style="stop-color:#1E3A5F;stop-opacity:1" />
6
- </linearGradient>
7
- </defs>
8
-
9
- <!-- Shield Background -->
10
- <path d="M64 8 L112 24 L112 56 C112 88 92 108 64 120 C36 108 16 88 16 56 L16 24 Z"
11
- fill="url(#noyraxGradient)"
12
- stroke="#1E3A5F"
13
- stroke-width="2"/>
14
-
15
- <!-- Document Icon -->
16
- <rect x="40" y="36" width="48" height="56" rx="4" fill="white" opacity="0.95"/>
17
-
18
- <!-- Document Lines -->
19
- <line x1="48" y1="52" x2="80" y2="52" stroke="#2563EB" stroke-width="3" stroke-linecap="round"/>
20
- <line x1="48" y1="64" x2="72" y2="64" stroke="#64748B" stroke-width="2" stroke-linecap="round"/>
21
- <line x1="48" y1="74" x2="76" y2="74" stroke="#64748B" stroke-width="2" stroke-linecap="round"/>
22
-
23
- <!-- Checkmark -->
24
- <circle cx="76" cy="82" r="12" fill="#10B981"/>
25
- <path d="M70 82 L74 86 L82 78" stroke="white" stroke-width="2.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
26
- </svg>
27
-