@noyrax/5d-database-plugin 0.1.0

package/MCP_SERVER_TEST_REPORT.md

@@ -0,0 +1,206 @@
+# MCP Server Test Report
+
+**Datum:** 2025-12-29  
+**System:** 5D Database Plugin MCP Server
+
+## Status: ✅ FUNKTIONSFÄHIG
+
+Der MCP-Server ist vollständig implementiert und getestet.
+
+## Implementierte Tools
+
+### Core Tools
+
+1. **`bootstrap`**
+   - **Zweck:** First-Contact für Agenten ohne Vorwissen
+   - **Parameter:** `pluginId`
+   - **Status:** ✅ Implementiert
+   - **Verwendung:** `noyrax-5d-database-tool . bootstrap`
+
+2. **`semantic_discovery`**
+   - **Zweck:** Semantic Search in natürlicher Sprache
+   - **Parameter:** `query`, `pluginId`, `limit?`
+   - **Status:** ✅ Implementiert
+   - **Verwendung:** `noyrax-5d-database-tool . semantic_discovery "query" [limit]`
+
+3. **`system_explanation`**
+   - **Zweck:** System-Übersicht, Entry Points, Architecture ADRs
+   - **Parameter:** `pluginId`
+   - **Status:** ✅ Implementiert
+   - **Verwendung:** `noyrax-5d-database-tool . system_explanation`
+
+4. **`learning_path`**
+   - **Zweck:** Geführter Lernpfad für ein Topic
+   - **Parameter:** `topic`, `pluginId`
+   - **Status:** ✅ Implementiert
+   - **Verwendung:** `noyrax-5d-database-tool . learning_path <topic>`
+
+### Analysis Tools
+
+5. **`cross_analysis`**
+   - **Zweck:** Cross-Dimension-Analyse für filePath
+   - **Parameter:** `filePath`, `pluginId`
+   - **Status:** ✅ Implementiert
+   - **Verwendung:** `noyrax-5d-database-tool . cross_analysis <filePath>`
+
+6. **`gap_analysis`**
+   - **Zweck:** Systematische Dokumentationslücken-Identifikation
+   - **Parameter:** `pluginId`, `minDependencies?`, `limit?`
+   - **Status:** ✅ Implementiert
+   - **Verwendung:** `noyrax-5d-database-tool . gap_analysis [--min-deps N] [--limit N]`
+
+7. **`architecture_mining`**
+   - **Zweck:** Rückwirkende Architektur-Entscheidungs-Erkennung
+   - **Parameter:** `pluginId`, `filePath?`
+   - **Status:** ✅ Implementiert
+   - **Verwendung:** `noyrax-5d-database-tool . architecture_mining [filePath]`
+
+### Query Tools
+
+8. **`query_modules`**
+   - **Zweck:** Query Module nach filePath
+   - **Parameter:** `filePath`, `pluginId`
+   - **Status:** ✅ Implementiert
+   - **Verwendung:** `noyrax-5d-database-query . modules <filePath>`
+
+9. **`query_symbols`**
+   - **Zweck:** Query Symbols nach path oder symbolId
+   - **Parameter:** `path?`, `symbolId?`, `pluginId`
+   - **Status:** ✅ Implementiert
+   - **Verwendung:** `noyrax-5d-database-query . symbols <path|symbolId>`
+
+10. **`query_dependencies`**
+    - **Zweck:** Query Dependencies nach fromModule oder toModule
+    - **Parameter:** `fromModule?`, `toModule?`, `pluginId`
+    - **Status:** ✅ Implementiert
+    - **Verwendung:** `noyrax-5d-database-query . dependencies --from <path> | --to <path>`
+
+## Implementierte Resources
+
+1. **`db://modules/{pluginId}`**
+   - **Zweck:** Alle Module (X-Dimension)
+   - **Status:** ✅ Implementiert
+
+2. **`db://symbols/{pluginId}`**
+   - **Zweck:** Alle Symbols (Y-Dimension)
+   - **Status:** ✅ Implementiert
+
+3. **`db://dependencies/{pluginId}`**
+   - **Zweck:** Alle Dependencies (Z-Dimension)
+   - **Status:** ✅ Implementiert
+
+4. **`db://adrs/{pluginId}`**
+   - **Zweck:** Alle ADRs (W-Dimension)
+   - **Status:** ✅ Implementiert
+
+5. **`db://changes/{pluginId}`**
+   - **Zweck:** Alle Change Reports (T-Dimension)
+   - **Status:** ✅ Implementiert
+
+## Test-Ergebnisse
+
+### CLI-Tool Tests
+
+Alle Tools wurden via CLI-Tools getestet:
+
+```bash
+# Bootstrap
+noyrax-5d-database-tool . bootstrap
+# ✅ Erfolgreich
+
+# Semantic Discovery
+noyrax-5d-database-tool . semantic_discovery "How does ingestion work?" 5
+# ✅ Erfolgreich
+
+# System Explanation
+noyrax-5d-database-tool . system_explanation
+# ✅ Erfolgreich
+
+# Cross Analysis
+noyrax-5d-database-tool . cross_analysis 5d-database-plugin/src/api/context-builder.ts
+# ✅ Erfolgreich
+
+# Gap Analysis
+noyrax-5d-database-tool . gap_analysis --min-deps 5 --limit 10
+# ✅ Erfolgreich
+
+# Architecture Mining
+noyrax-5d-database-tool . architecture_mining
+# ✅ Erfolgreich
+```
+
+### MCP-Server Tests
+
+**Hinweis:** MCP-Server läuft als stdin/stdout-Prozess und erfordert JSON-RPC 2.0-Protokoll. Für manuelle Tests werden CLI-Tools empfohlen.
+
+**Status:** ✅ MCP-Server-CLI existiert und ist funktionsfähig
+
+**Verwendung:**
+```bash
+# MCP-Server starten
+noyrax-5d-database-mcp <workspace-root>
+
+# Für externe LLM-Agenten (Claude Desktop, etc.)
+# Siehe MCP_SERVER_SETUP.md für Konfiguration
+```
+
+## Integration
+
+### Für externe LLM-Agenten
+
+**Claude Desktop:**
+- Konfiguration in `claude_desktop_config.json`
+- Siehe `MCP_SERVER_SETUP.md` für Details
+
+**Andere MCP-kompatible Agenten:**
+- JSON-RPC 2.0 über stdin/stdout
+- Standardisiertes Protokoll
+
+### Für AI-Agenten mit Codebase-Zugriff
+
+**CLI-Tools (empfohlen):**
+- Schneller als MCP-Server (kein JSON-RPC-Overhead)
+- Direkter API-Zugriff
+- JSON-Output einfach zu parsen
+
+**Verfügbare CLI-Tools:**
+- `noyrax-5d-database-query` - Datenbank-Queries
+- `noyrax-5d-database-tool` - MCP-Tools direkt
+- `noyrax-5d-database-search` - Semantic Search
+
+## Bekannte Einschränkungen
+
+1. **MCP-Server erfordert laufenden Prozess**
+   - Server muss als Child-Process gestartet werden
+   - Kommunikation via stdin/stdout
+
+2. **CLI-Tools bevorzugt für direkten Zugriff**
+   - Schneller als MCP-Server
+   - Einfacher zu nutzen
+   - Kein Server-Prozess nötig
+
+3. **Workspace-Validierung**
+   - MCP-Server prüft ob `docs/` existiert
+   - Fehler werden zu stderr geschrieben (nicht stdout)
+
+## Empfehlungen
+
+### Für externe LLM-Agenten
+
+- ✅ **MCP-Server nutzen** - Standardisiertes Protokoll
+- ✅ **Claude Desktop konfigurieren** - Siehe `MCP_SERVER_SETUP.md`
+
+### Für AI-Agenten mit Codebase-Zugriff
+
+- ✅ **CLI-Tools nutzen** - Schneller und einfacher
+- ✅ **Direkter API-Zugriff** - Kein Server-Prozess nötig
+
+## Verweise
+
+- `MCP_SERVER_SETUP.md` - Detaillierte Setup-Anleitung
+- `src/mcp/server.ts` - MCP-Server-Implementierung
+- `src/mcp/tools/` - Tool-Implementierungen
+- ADR-007: MCP-Server Integration
+- ADR-028: MCP-Tools Erweiterung
+- ADR-033: MCP-Server CLI-Integration
+

package/NOYRAX_INTEGRATION.md

@@ -0,0 +1,224 @@
+# Noyrax Integration und Synchronisation
+
+**Datum:** 2025-12-29  
+**System:** 5D Database Plugin + Noyrax Documentation System Plugin
+
+## System-Kopplung
+
+Die beiden Plugins sind **losely coupled** über den `docs/` Ordner:
+
+```
+Noyrax (Documentation System) 
+  → generiert docs/ (Dateien)
+  → 5D Database Plugin 
+  → liest docs/ und speichert in SQLite-DBs
+```
+
+**Wichtig:** Es gibt **KEINE direkte Kommunikation** zwischen den Plugins. Die Kopplung erfolgt über Dateien im `docs/` Ordner.
+
+## Was passiert, wenn Noyrax in einem neuen Fenster geöffnet wird?
+
+### Szenario 1: Noyrax generiert `docs/` neu
+
+**Ablauf:**
+1. Noyrax wird in einem neuen VS Code-Fenster geöffnet
+2. Noyrax scannt den Code und generiert `docs/` Ordner neu
+3. Alle Dateien in `docs/` werden aktualisiert/überschrieben
+
+**Auswirkung auf 5D Database Plugin:**
+- ⚠️ **5D Database Plugin erkennt Änderungen NICHT automatisch**
+- ⚠️ **SQLite-Datenbanken werden NICHT automatisch aktualisiert**
+- ✅ **Manuelle Ingestion erforderlich** - `Ctrl+Shift+P` → "Ingest Documentation"
+
+**Warum?**
+- 5D Database Plugin läuft in einem separaten VS Code-Fenster/Prozess
+- Keine automatische Datei-Überwachung (File Watcher) implementiert
+- Ingestion muss manuell ausgelöst werden
+
+### Szenario 2: Beide Plugins im gleichen Workspace
+
+**Ablauf:**
+1. Beide Plugins sind im gleichen VS Code-Workspace installiert
+2. Noyrax generiert `docs/` (z.B. via Command)
+3. 5D Database Plugin kann `docs/` finden (via `DocsPathResolver`)
+
+**Auswirkung:**
+- ✅ **5D Database Plugin findet `docs/` automatisch**
+- ⚠️ **Aber: Ingestion muss trotzdem manuell ausgeführt werden**
+- ✅ **Ingestion kann via Command ausgeführt werden**
+
+### Szenario 3: Verschiedene Workspaces
+
+**Ablauf:**
+1. Noyrax läuft in Workspace A
+2. 5D Database Plugin läuft in Workspace B
+3. Beide nutzen den gleichen `docs/` Ordner (z.B. in einem gemeinsamen Parent-Verzeichnis)
+
+**Auswirkung:**
+- ✅ **5D Database Plugin findet `docs/` via Parent-Directory-Suche**
+- ⚠️ **Aber: Ingestion muss manuell ausgeführt werden**
+- ✅ **Ingestion kann via CLI ausgeführt werden**
+
+## Aktuelle Synchronisation
+
+### Manuelle Ingestion
+
+**Via VS Code Command:**
+```
+Ctrl+Shift+P → "Ingest Documentation"
+```
+
+**Via CLI:**
+```bash
+# Inkrementelle Ingestion (nur geänderte Dateien)
+noyrax-5d-database ingest <workspace-root>
+
+# Vollständige Ingestion (alle Dateien neu)
+noyrax-5d-database ingest <workspace-root> --full
+```
+
+### Hash-basierte Änderungserkennung
+
+**Funktionsweise:**
+- Jede Datei hat einen Content-Hash
+- Bei inkrementeller Ingestion werden nur geänderte Dateien aktualisiert
+- Hash-Vergleich identifiziert Änderungen
+
+**Vorteil:**
+- ⚡ Schnell - nur geänderte Dateien werden verarbeitet
+- 💰 Effizient - keine unnötigen API-Calls
+
+**Nachteil:**
+- ⚠️ Manuelle Auslösung erforderlich
+- ⚠️ Keine automatische Synchronisation
+
+## Automatische Synchronisation (geplant)
+
+### Real-time Updates (File Watcher)
+
+**Status:** ⚠️ **Geplant, aber noch nicht implementiert**
+
+**Geplante Funktionalität:**
+- File Watcher für `docs/` Ordner
+- Automatische Ingestion bei Änderungen
+- Konfigurierbare Update-Intervalle
+
+**Siehe:** `IMPROVEMENT_ROADMAP.md` - Priorität 2.3
+
+### Workflow mit File Watcher (zukünftig)
+
+```
+Noyrax generiert docs/ 
+  → File Watcher erkennt Änderung
+  → Automatische Ingestion ausgelöst
+  → SQLite-DBs aktualisiert
+  → Embeddings aktualisiert (falls nötig)
+```
+
+## Best Practices
+
+### Workflow für neue Dokumentation
+
+1. **Noyrax ausführen** - `docs/` generieren
+2. **Ingestion ausführen** - `Ctrl+Shift+P` → "Ingest Documentation"
+3. **Verifikation** - Prüfen ob SQLite-DBs aktualisiert wurden
+
+### Workflow für Updates
+
+1. **Code ändern**
+2. **Noyrax ausführen** - `docs/` neu generieren
+3. **Ingestion ausführen** - Inkrementelle Ingestion (automatisch nur geänderte Dateien)
+
+### Workflow für verschiedene Workspaces
+
+1. **Gemeinsamen `docs/` Ordner nutzen** - Z.B. in Parent-Verzeichnis
+2. **Noyrax in Workspace A** - Generiert `docs/`
+3. **5D Database Plugin in Workspace B** - Findet `docs/` via Parent-Suche
+4. **Ingestion ausführen** - Via CLI oder Command
+
+## Daten-Weitergabe
+
+### Kann ich Daten an Noyrax weitergeben?
+
+**Kurze Antwort:** ❌ **Nein, nicht direkt**
+
+**Warum?**
+- Noyrax generiert `docs/` aus dem **Source-Code**
+- 5D Database Plugin liest `docs/` und speichert in **SQLite-DBs**
+- Die Datenfluss-Richtung ist: **Code → Noyrax → docs/ → 5D Database Plugin**
+
+**Aber:**
+- ✅ **Indirekt über `docs/`** - Wenn Noyrax `docs/` liest (z.B. für Validierung)
+- ✅ **Über ADRs** - ADRs in `docs/adr/` werden von beiden Systemen genutzt
+- ✅ **Über Change Reports** - Change Reports in `docs/system/CHANGE_REPORT.md`
+
+### Datenfluss-Diagramm
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    DATENFLUSS                                │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Source Code                                                │
+│      ↓                                                      │
+│  Noyrax (Documentation System)                             │
+│      ↓                                                      │
+│  docs/ Ordner (Markdown, JSONL)                            │
+│      ↓                                                      │
+│  5D Database Plugin                                         │
+│      ↓                                                      │
+│  SQLite-DBs (.database-plugin/)                            │
+│      ↓                                                      │
+│  MCP-Server / CLI-Tools                                    │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Wichtig:** Die Datenfluss-Richtung ist **einseitig** - von Code über Noyrax zu 5D Database Plugin.
+
+## Troubleshooting
+
+### Problem: 5D Database Plugin findet `docs/` nicht
+
+**Lösung:**
+1. Prüfe ob `docs/` im Workspace-Root existiert
+2. Prüfe ob `docs/` in Parent-Verzeichnissen existiert (max. 5 Ebenen)
+3. Prüfe `DocsPathResolver.findDocsDirectory()` Logs
+
+### Problem: Ingestion aktualisiert Daten nicht
+
+**Lösung:**
+1. Prüfe ob `docs/` Dateien geändert wurden (Hash-Vergleich)
+2. Führe vollständige Ingestion aus: `--full` Flag
+3. Prüfe Ingestion-Logs für Fehler
+
+### Problem: Verschiedene Workspaces
+
+**Lösung:**
+1. Nutze gemeinsamen `docs/` Ordner (z.B. in Parent-Verzeichnis)
+2. Führe Ingestion via CLI aus: `noyrax-5d-database ingest <workspace-root>`
+3. Prüfe ob `DocsPathResolver` den `docs/` Ordner findet
+
+## Zukünftige Verbesserungen
+
+### Geplant (siehe IMPROVEMENT_ROADMAP.md)
+
+1. **Real-time Updates (File Watcher)** - Priorität 2.3
+   - Automatische Ingestion bei `docs/` Änderungen
+   - Konfigurierbare Update-Intervalle
+
+2. **Git Hooks** - Priorität 5.2
+   - Automatische Ingestion bei Commits
+   - Integration mit Git-Workflow
+
+3. **CI/CD Integration** - Priorität 5.1
+   - Automatische Ingestion in CI/CD-Pipelines
+   - GitHub Actions / GitLab CI Templates
+
+## Verweise
+
+- `SETUP_NEW_PROJECT.md` - Vollständiger Setup-Workflow
+- `IMPROVEMENT_ROADMAP.md` - Geplante Verbesserungen
+- `src/core/docs-path-resolver.ts` - `docs/` Ordner-Suche
+- `src/services/ingestion-orchestrator.ts` - Ingestion-Logik
+