@noyrax/documentation-system-plugin 1.0.4-beta.2 → 1.0.4-beta.4

package/MCP_SERVER_SETUP.md

@@ -1,371 +0,0 @@
-# MCP Server Setup für LLM-Agenten
-
-## Übersicht
-
-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.
-
-## Voraussetzungen
-
-⚠️ **KRITISCH: System-Kopplung**
-
-**Das Documentation System Plugin (Noyrax) und das 5D Database Plugin müssen beide installiert und konfiguriert sein!**
-
-```
-1. Documentation System Plugin (Noyrax) → generiert docs/
-2. 5D Database Plugin → ingestiert docs/ in SQLite-DBs
-3. MCP-Server → ermöglicht LLM-Agenten-Zugriff
-```
-
-## Installation
-
-### Option 1: Via VS Code Extension (Development)
-
-```bash
-# 1. Extension kompilieren
-cd 5d-database-plugin
-npm install
-npm run compile
-
-# 2. MCP-Server direkt starten
-node out/cli/mcp-server-cli.js /path/to/workspace
-```
-
-### Option 2: Via npm Package (wenn veröffentlicht)
-
-```bash
-# 1. Package installieren
-npm install -g @noyrax/5d-database-plugin
-
-# 2. MCP-Server starten
-noyrax-5d-database-mcp /path/to/workspace
-```
-
-### Option 3: Via npx (ohne Installation)
-
-```bash
-npx -y @noyrax/5d-database-plugin mcp-server /path/to/workspace
-```
-
-## CLI-Tools für direkten Zugriff (AI-Agenten)
-
-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:
-
-### Query-CLI (Datenbank-Queries)
-
-Direkter Zugriff auf Datenbank-Queries:
-
-```bash
-# Query Module
-noyrax-5d-database-query <workspace-root> modules <filePath>
-
-# Query Symbols
-noyrax-5d-database-query <workspace-root> symbols <path|symbolId>
-
-# Query Dependencies
-noyrax-5d-database-query <workspace-root> dependencies --from <path>
-noyrax-5d-database-query <workspace-root> dependencies --to <path>
-
-# Query ADRs
-noyrax-5d-database-query <workspace-root> adrs --number <num>
-noyrax-5d-database-query <workspace-root> adrs --path <path>
-
-# Query Changes
-noyrax-5d-database-query <workspace-root> changes
-```
-
-### Tool-CLI (MCP-Tools direkt)
-
-Direkter Zugriff auf MCP-Tools ohne Server:
-
-```bash
-# Bootstrap
-noyrax-5d-database-tool <workspace-root> bootstrap
-
-# Semantic Discovery
-noyrax-5d-database-tool <workspace-root> semantic_discovery "How does ingestion work?" [limit]
-
-# System Explanation
-noyrax-5d-database-tool <workspace-root> system_explanation
-
-# Learning Path
-noyrax-5d-database-tool <workspace-root> learning_path <topic>
-
-# Cross Analysis
-noyrax-5d-database-tool <workspace-root> cross_analysis <filePath>
-
-# Gap Analysis (ab Version 0.1.8)
-noyrax-5d-database-tool <workspace-root> gap_analysis [--min-deps N] [--limit N]
-
-# Architecture Mining (ab Version 0.1.8)
-noyrax-5d-database-tool <workspace-root> architecture_mining [filePath]
-```
-
-### Semantic-Search-CLI (V-Dimension)
-
-Direkter Zugriff auf Semantic Search:
-
-```bash
-# Semantic Search
-noyrax-5d-database-search <workspace-root> "How does the MCP server work?" --limit 10
-
-# Mit spezifischen Dimensionen
-noyrax-5d-database-search <workspace-root> "ingestion" --dimensions X,W --limit 5
-```
-
-**Vorteile für AI-Agenten:**
-- Schneller als MCP-Server (kein JSON-RPC-Overhead)
-- Direkter API-Zugriff
-- JSON-Output einfach zu parsen
-- Keine zusätzliche Infrastruktur nötig
-
-## Konfiguration für LLM-Agenten
-
-### Claude Desktop
-
-Konfiguriere den MCP Server in `claude_desktop_config.json`:
-
-**Windows:**
-```
-%APPDATA%\Claude\claude_desktop_config.json
-```
-
-**macOS:**
-```
-~/Library/Application Support/Claude/claude_desktop_config.json
-```
-
-**Linux:**
-```
-~/.config/Claude/claude_desktop_config.json
-```
-
-#### Konfiguration (Entwicklung - lokaler Pfad):
-
-```json
-{
-  "mcpServers": {
-    "5d-database": {
-      "command": "node",
-      "args": [
-        "D:/path/to/5d-database-plugin/out/cli/mcp-server-cli.js",
-        "${workspaceFolder}"
-      ]
-    }
-  }
-}
-```
-
-#### Konfiguration (Production - npm Package):
-
-```json
-{
-  "mcpServers": {
-    "5d-database": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@noyrax/5d-database-plugin",
-        "mcp-server",
-        "${workspaceFolder}"
-      ]
-    }
-  }
-}
-```
-
-### Andere LLM-Agenten
-
-Der MCP-Server kommuniziert via stdin/stdout (JSON-RPC 2.0). Jeder MCP-kompatible Agent kann den Server nutzen, indem er:
-
-1. Den Server als Child-Process startet: `node out/cli/mcp-server-cli.js <workspace-root>`
-2. JSON-RPC 2.0 Requests via stdin sendet
-3. JSON-RPC 2.0 Responses via stdout empfängt
-
-## Verfügbare Tools
-
-Der MCP-Server stellt folgende Tools bereit:
-
-| Tool | Beschreibung | Parameter |
-|------|--------------|-----------|
-| `bootstrap` | Erste Anlaufstelle für Agenten ohne Vorwissen | `pluginId` |
-| `semantic_discovery` | Semantic Search in natürlicher Sprache | `query`, `pluginId`, `limit?` |
-| `system_explanation` | System-Übersicht, Entry Points, Architecture ADRs | `pluginId` |
-| `learning_path` | Geführter Lernpfad für ein Topic | `topic`, `pluginId` |
-| `query_modules` | Query Module nach filePath | `filePath`, `pluginId` |
-| `query_symbols` | Query Symbols nach path oder symbolId | `path?`, `symbolId?`, `pluginId` |
-| `query_dependencies` | Query Dependencies nach fromModule oder toModule | `fromModule?`, `toModule?`, `pluginId` |
-| `cross_analysis` | Cross-Dimension-Analyse für filePath | `filePath`, `pluginId` |
-| `gap_analysis` | Findet Dokumentationslücken (Module mit vielen Dependencies aber wenigen ADRs) | `pluginId`, `minDependencies?` (default: 5), `limit?` (default: 50) |
-| `architecture_mining` | Leitet Architektur-Entscheidungen aus Code-Struktur ab | `pluginId`, `filePath?` (optional, für spezifische Datei) |
-
-## Verfügbare Resources
-
-| Resource | Beschreibung | URI Format |
-|----------|--------------|------------|
-| Modules | Alle Module (X-Dimension) | `db://modules/{pluginId}` |
-| Symbols | Alle Symbols (Y-Dimension) | `db://symbols/{pluginId}` |
-| Dependencies | Alle Dependencies (Z-Dimension) | `db://dependencies/{pluginId}` |
-| ADRs | Alle ADRs (W-Dimension) | `db://adrs/{pluginId}` |
-| Changes | Alle Change Reports (T-Dimension) | `db://changes/{pluginId}` |
-
-## Workflow
-
-### 1. Dokumentation generieren (Noyrax)
-
-```bash
-# Documentation System Plugin ausführen
-noyrax-documentation generate /path/to/workspace
-# Erstellt docs/ Ordner mit allen 5 Dimensionen
-```
-
-### 2. Ingestion ausführen (5D Database Plugin)
-
-```bash
-# 5D Database Plugin ausführen
-noyrax-5d-database ingest /path/to/workspace
-# Liest docs/ und speichert in SQLite-DBs (.database-plugin/)
-```
-
-### 3. MCP-Server starten
-
-```bash
-# MCP-Server starten (für LLM-Agenten)
-noyrax-5d-database-mcp /path/to/workspace
-```
-
-### 4. LLM-Agent nutzen
-
-Der LLM-Agent kann nun:
-- `bootstrap` Tool aufrufen, um System zu verstehen
-- `semantic_discovery` Tool nutzen, um relevante Code-Entitäten zu finden
-- `system_explanation` Tool nutzen, um Entry Points zu finden
-- `learning_path` Tool nutzen, um geführte Lernpfade zu generieren
-- Resources lesen, um auf Datenbanken zuzugreifen
-
-## Troubleshooting
-
-### "docs/ directory not found"
-
-**Problem:** Documentation System Plugin wurde nicht ausgeführt.
-
-**Lösung:**
-```bash
-# Schritt 1: Dokumentation generieren
-noyrax-documentation generate /path/to/workspace
-```
-
-### "No modules found in database"
-
-**Problem:** Ingestion wurde nicht ausgeführt.
-
-**Lösung:**
-```bash
-# Schritt 2: Ingestion ausführen
-noyrax-5d-database ingest /path/to/workspace
-```
-
-### "MCP Server connection failed"
-
-**Problem:** MCP-Server konnte nicht gestartet werden.
-
-**Lösung:**
-1. Prüfe ob beide Plugins installiert sind (Noyrax + 5D Database)
-2. Prüfe ob `docs/` existiert
-3. Prüfe ob Ingestion ausgeführt wurde
-4. Prüfe MCP-Server-Konfiguration in Claude Desktop
-
-### "Permission denied" beim Starten des Servers
-
-**Problem:** Node.js-Script ist nicht ausführbar.
-
-**Lösung (Linux/macOS):**
-```bash
-chmod +x out/cli/mcp-server-cli.js
-```
-
-## Beispiel-Interaktion
-
-### 1. Bootstrap (First Contact)
-
-**LLM-Agent fragt:**
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "bootstrap",
-    "arguments": {
-      "pluginId": "a1b2c3d4e5f6g7h8"
-    }
-  }
-}
-```
-
-**Server antwortet:**
-```json
-{
-  "content": [{
-    "type": "text",
-    "text": "{\"what_am_i\": \"...\", \"where_to_start\": [...], ...}"
-  }]
-}
-```
-
-### 2. Semantic Discovery
-
-**LLM-Agent fragt:**
-```json
-{
-  "method": "tools/call",
-  "params": {
-    "name": "semantic_discovery",
-    "arguments": {
-      "query": "How does ingestion work?",
-      "pluginId": "a1b2c3d4e5f6g7h8",
-      "limit": 10
-    }
-  }
-}
-```
-
-**Server antwortet:**
-```json
-{
-  "content": [{
-    "type": "text",
-    "text": "{\"entities\": [...], \"context\": {...}}"
-  }]
-}
-```
-
-## CLI-Tools vs. MCP-Server
-
-**MCP-Server** ist für externe LLM-Agenten gedacht, die keine direkte Codebase-Zugriff haben (z.B. Claude Desktop).
-
-**CLI-Tools** sind für AI-Agenten gedacht, die direkten Codebase-Zugriff haben (z.B. Cursor AI):
-
-- `noyrax-5d-database-query` - Direkte Datenbank-Queries
-- `noyrax-5d-database-tool` - MCP-Tools direkt nutzen
-- `noyrax-5d-database-search` - Semantic Search direkt
-
-**Vorteile CLI-Tools:**
-- Schneller (kein JSON-RPC-Overhead)
-- Einfacher zu nutzen (direkter API-Zugriff)
-- Kein Server-Prozess nötig
-
-**Wann MCP-Server nutzen:**
-- Externe LLM-Agenten (Claude Desktop, etc.)
-- Standardisiertes Protokoll (JSON-RPC 2.0)
-- Tool-Integration in Agent-UIs
-
-## Weitere Informationen
-
-- Siehe `SETUP_NEW_PROJECT.md` für vollständigen Setup-Workflow
-- Siehe `README.md` für allgemeine Plugin-Dokumentation
-- Siehe ADR-007 für MCP-Server-Architektur-Details
-- Siehe ADR-028 für Semantic Brain MCP-Tools
-- Siehe ADR-033 für MCP-Server CLI-Integration und System-Kopplung
-- Siehe ADR-034 für Gap Analysis Tool
-- Siehe ADR-035 für Architecture Mining Tool
-
-**Hinweis:** Die Tools `gap_analysis` und `architecture_mining` sind ab Version 0.1.8 verfügbar.
-

package/assets/icon.svg

@@ -1,27 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
-  <defs>
-    <linearGradient id="noyraxGradient" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" style="stop-color:#2563EB;stop-opacity:1" />
-      <stop offset="100%" style="stop-color:#1E3A5F;stop-opacity:1" />
-    </linearGradient>
-  </defs>
-  
-  <!-- Shield Background -->
-  <path d="M64 8 L112 24 L112 56 C112 88 92 108 64 120 C36 108 16 88 16 56 L16 24 Z" 
-        fill="url(#noyraxGradient)" 
-        stroke="#1E3A5F" 
-        stroke-width="2"/>
-  
-  <!-- Document Icon -->
-  <rect x="40" y="36" width="48" height="56" rx="4" fill="white" opacity="0.95"/>
-  
-  <!-- Document Lines -->
-  <line x1="48" y1="52" x2="80" y2="52" stroke="#2563EB" stroke-width="3" stroke-linecap="round"/>
-  <line x1="48" y1="64" x2="72" y2="64" stroke="#64748B" stroke-width="2" stroke-linecap="round"/>
-  <line x1="48" y1="74" x2="76" y2="74" stroke="#64748B" stroke-width="2" stroke-linecap="round"/>
-  
-  <!-- Checkmark -->
-  <circle cx="76" cy="82" r="12" fill="#10B981"/>
-  <path d="M70 82 L74 86 L82 78" stroke="white" stroke-width="2.5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
-</svg>
-

package/docs/LINKEDIN_ANTWORT_SEQUENZDIAGRAMME.md

@@ -1,190 +0,0 @@
-# LinkedIn-Antwort: Sequenzdiagramme aus automatisierter Dokumentation
-
-## Kontext
-Ein LinkedIn-Nutzer fragte, ob das Dokumentations-System auch komplexe Sequenzdiagramme (z.B. für Payment-Flows) generieren kann, oder ob dafür noch manuelle Arbeit nötig ist.
-
----
-
-## Beweis-Zusammenfassung (mit echten Daten)
-
-### Was ich gemacht habe:
-
-1. **Gelesen**: 
-   - `docs/system/DEPENDENCIES.md` (330 Zeilen Import-Übersicht)
-   - `docs/system/DEPENDENCY_GRAPH.md` (281 Zeilen Mermaid-Graph, 119 Knoten)
-   - `docs/index/symbols.jsonl` (548 Symbole mit Dependencies)
-   - `docs/modules/*.md` (70+ Modul-Dokumentationen)
-
-2. **Identifiziert**: 
-   - Einstiegspunkt `scanSystemTs()` aus `src/extension.ts`
-   - 22 direkte Dependencies (aus symbols.jsonl Zeile 417)
-
-3. **Rekonstruiert**: 
-   - Vollständige Aufrufkette über 14 beteiligte Module
-   - Alle Signaturen und Datentypen aus den Modul-Dokus
-
-4. **Generiert**: 
-   - Mermaid-Sequenzdiagramm mit 6 Phasen und 15 Teilnehmern
-   - Zweites Diagramm für den Validierungs-Flow
-
-### Konkrete Zahlen:
-
-| Artefakt | Inhalt |
-|----------|--------|
-| `DEPENDENCIES.md` | 330 Zeilen, alle Import-Beziehungen |
-| `DEPENDENCY_GRAPH.md` | 119 Knoten, 160+ Kanten |
-| `symbols.jsonl` | 548 Symbole mit Dependencies |
-| `modules/*.md` | 70+ Dateien mit Signaturen |
-
----
-
-## Antwort-Vorschlag für LinkedIn
-
-> **Genau das habe ich gerade praktisch bewiesen – mit echten Daten aus dem System!**
->
-> Ich habe aus den automatisch generierten Dokumentations-Artefakten ein vollständiges Sequenzdiagramm für den "System-Scan"-Flow abgeleitet:
->
-> **Die Quellen:**
-> - `docs/system/DEPENDENCIES.md` → 330 Zeilen Import-Übersicht
-> - `docs/system/DEPENDENCY_GRAPH.md` → Mermaid-Graph mit 119 Knoten
-> - `docs/index/symbols.jsonl` → 548 Symbole mit ihren Dependencies
-> - `docs/modules/*.md` → 70+ Modul-Dokumentationen mit Signaturen
->
-> **Das Ergebnis:**
-> - 14 beteiligte Module identifiziert
-> - 6 Phasen im Ablauf (Scan → Parse → Cache → Generate → Save → Validate)
-> - Vollständiges Mermaid-Sequenzdiagramm mit allen Aufrufen
->
-> **Der Trick ist:**
-> - Jedes Symbol in `symbols.jsonl` hat ein `dependencies`-Array
-> - Die Signaturen in `docs/modules/` zeigen Parameter und Rückgabewerte
-> - Aus beidem ergibt sich die Aufrufkette
->
-> **Für ein Payment-System würde das so aussehen:**
-> 1. `npm run scan` auf der Codebasis ausführen
-> 2. In `symbols.jsonl` nach `processPayment` o.ä. filtern
-> 3. Dependencies aus dem Array ablesen (PaypalAdapter, TransactionLogger, ...)
-> 4. Signaturen aus `docs/modules/` holen
-> 5. Sequenzdiagramm generieren
->
-> **Was noch fehlt für 100% Automatisierung:**
-> - Domänen-spezifische Annotationen ("dies ist ein externer API-Call")
-> - Business-Varianten (Erfolg/Fehler-Pfade)
->
-> Aber der **technische Kontext** kommt reproduzierbar aus dem Code – das ist der große Unterschied zu "alles jedes Mal neu prompten".
->
-> 📎 Beweis-Dokument mit allen Quellen: [docs/SEQUENZDIAGRAMM_BEWEIS.md]
-
----
-
-## Kernargumente (für die Diskussion)
-
-### 1. Strukturierte Wissensbasis statt Ad-hoc-Prompts
-```
-VORHER: "Hey KI, hier sind 15 Dateien, erkläre mir den Payment-Flow"
-NACHHER: "Zeige mir den Flow ab processPayment() – alle Dependencies stehen in symbols.jsonl"
-```
-
-### 2. Determinismus
-```
-Gleicher Code-Stand 
-    → npm run scan 
-    → Gleiche docs/*-Artefakte 
-    → Gleiches Sequenzdiagramm
-```
-
-### 3. Skalierbarkeit
-- `symbols.jsonl` mit 548 Symbolen → funktioniert genauso mit 5.000
-- Kein manuelles "Context-Stuffing" mehr nötig
-
-### 4. Erweiterbarkeit
-- Domänen-Views als zusätzliche Layer ergänzbar
-- Basis-Kontext bleibt automatisch aktuell
-
----
-
-## Technische Details (für Interessierte)
-
-### Wie die Dependencies in symbols.jsonl aussehen:
-
-```json
-{
-  "symbol_id": "ts://src/extension.ts#activate(f93629ec84e52398)",
-  "path": "src/extension.ts",
-  "kind": "function",
-  "name": "activate",
-  "dependencies": [
-    "./cache/ast-cache",
-    "./cache/signature-cache",
-    "./core/scanner",
-    "./generator/index",
-    "./validator/index",
-    // ... 17 weitere Module
-  ]
-}
-```
-
-### Wie eine Modul-Doku aussieht:
-
-```markdown
-# Modul: src/validator/index.ts
-
-### function: validateSymbols
-\`\`\`ts
-validateSymbols(symbols: ParsedSymbol[]): ValidationReport
-\`\`\`
-
-### interface: ValidationReport
-\`\`\`ts
-interface ValidationReport {
-  totalSymbols: number;
-  errors: string[];
-  warnings: string[];
-  status?: StatusReport;
-}
-\`\`\`
-```
-
-### Wie der Dependency-Graph aussieht:
-
-```mermaid
-graph TD
-    N98["src/extension.ts"]
-    N110["src/validator/index.ts"]
-    N111["src/validator/signature-matching.ts"]
-    
-    N98 --> N110
-    N110 --> N111
-```
-
----
-
-## Nächste Schritte (optional)
-
-Falls gewünscht, könnte das System erweitert werden um:
-
-1. **Automatische Sequenzdiagramm-Generierung**
-   - Input: Use-Case-Name + Einstiegspunkt-Symbol
-   - Output: Mermaid-Diagramm
-
-2. **Domänen-Annotationen**
-   - Markierung von externen Calls, DB-Zugriffen, etc.
-   - Automatische `alt`/`opt`-Blöcke für Fehlerpfade
-
-3. **Interaktive Exploration**
-   - "Zeige mir den Flow von X nach Y"
-   - Tiefe/Breite konfigurierbar
-
----
-
-## Fazit
-
-**Das System liefert genau die strukturierte Wissensbasis, die für automatische Architektur-Diagramme nötig ist:**
-
-| Was | Woher |
-|-----|-------|
-| Alle Module und ihre Beziehungen | `DEPENDENCIES.md`, `DEPENDENCY_GRAPH.md` |
-| Alle Symbole mit Dependencies | `symbols.jsonl` |
-| Alle Signaturen und Typen | `docs/modules/*.md` |
-
-**Ergebnis: Sequenzdiagramme sind deterministisch aus diesen Artefakten ableitbar.**