@noyrax/5d-database-plugin 0.1.0

package/KNOWN_ISSUES.md

@@ -0,0 +1,210 @@
+# Bekannte Probleme und Einschränkungen
+
+**Datum:** 2025-12-29  
+**System:** 5D Database Plugin + Semantic Brain  
+**Status:** Alle Probleme sind nicht-kritisch, System ist produktionsbereit
+
+## Warnungen (nicht kritisch)
+
+### 1. ChromaDB DefaultEmbeddingFunction Warnung
+
+**Symptom:**
+```
+Cannot instantiate a collection with the DefaultEmbeddingFunction. 
+Please install @chroma-core/default-embed, or provide a different embedding function
+```
+
+**Ursache:**
+- ChromaDB erwartet `@chroma-core/default-embed` Package für DefaultEmbeddingFunction
+- System nutzt manuelle Embedding-Generierung via OpenAI API
+
+**Impact:**
+- ⚠️ Warnung wird angezeigt
+- ✅ **Funktioniert trotzdem** - Fallback auf manuelle Embeddings
+- ✅ Keine Funktionsbeeinträchtigung
+
+**Lösung:**
+- System nutzt bereits manuelle Embedding-Generierung
+- Warnung kann ignoriert werden
+- Optional: `@chroma-core/default-embed` installieren (nicht erforderlich)
+
+**Status:** ✅ Funktioniert, Warnung kann ignoriert werden
+
+---
+
+### 2. SQLite VSS auf Windows nicht verfügbar
+
+**Symptom:**
+```
+[VssLoader] Failed to get VSS path from sqlite-vss package: 
+Error: Loadable extension for sqlite-vss not found. 
+Was the sqlite-vss-windows-x64 package installed?
+```
+
+**Ursache:**
+- SQLite VSS Extension ist auf Windows nicht verfügbar
+- System nutzt ChromaDB als Fallback
+
+**Impact:**
+- ⚠️ SQLite VSS nicht verfügbar
+- ✅ **ChromaDB-Fallback funktioniert**
+- ✅ Keine Funktionsbeeinträchtigung
+
+**Lösung:**
+- ChromaDB wird automatisch auf Windows verwendet
+- Siehe `CHROMADB_SETUP.md` für Installation
+- System funktioniert vollständig mit ChromaDB
+
+**Status:** ✅ Funktioniert mit ChromaDB-Fallback
+
+---
+
+### 3. Path-Encoding mit Umlauten
+
+**Symptom:**
+```
+Set-Location : Der Pfad "D:\Datenbank fǟr Noyrax" kann nicht gefunden werden
+```
+
+**Ursache:**
+- Workspace-Pfad enthält Umlaute (z.B. "für")
+- PowerShell/Node.js Encoding-Handling kann Probleme verursachen
+
+**Impact:**
+- ⚠️ Warnung wird angezeigt
+- ✅ **Funktioniert trotzdem** - Encoding-Handling vorhanden
+- ⚠️ Minimale Performance-Einbußen möglich
+
+**Lösung:**
+- System hat Encoding-Handling implementiert
+- Funktioniert trotz Warnung
+- Optional: Workspace-Pfad ohne Umlaute verwenden (falls möglich)
+
+**Status:** ✅ Funktioniert, Warnung kann ignoriert werden
+
+---
+
+## Keine kritischen Fehler
+
+**Status:** ✅ **Keine kritischen Fehler gefunden** - System ist produktionsbereit
+
+Alle bekannten Probleme sind Warnungen, die die Funktionalität nicht beeinträchtigen.
+
+## Workarounds
+
+### Für ChromaDB DefaultEmbeddingFunction
+
+**Option 1: Ignorieren (empfohlen)**
+- System funktioniert trotz Warnung
+- Manuelle Embedding-Generierung wird verwendet
+
+**Option 2: Package installieren**
+```bash
+npm install @chroma-core/default-embed
+```
+- Nicht erforderlich, aber kann Warnung entfernen
+
+### Für SQLite VSS auf Windows
+
+**Lösung: ChromaDB nutzen**
+```bash
+# ChromaDB installieren
+pip install chromadb
+
+# ChromaDB Server starten (optional)
+chroma run --host localhost --port 8000
+```
+- System nutzt automatisch ChromaDB auf Windows
+- Siehe `CHROMADB_SETUP.md` für Details
+
+### Für Path-Encoding
+
+**Option 1: Ignorieren (empfohlen)**
+- System funktioniert trotz Warnung
+- Encoding-Handling ist implementiert
+
+**Option 2: Workspace-Pfad ändern**
+- Workspace ohne Umlaute verwenden (falls möglich)
+- Nicht erforderlich, aber kann Warnung entfernen
+
+## Monitoring
+
+### Empfohlene Überwachung
+
+1. **Embedding-Kosten**
+   - OpenAI API-Kosten überwachen
+   - Besonders bei großen Codebases
+
+2. **Performance**
+   - Ingestion-Zeit überwachen
+   - Embedding-Generierung kann langsam sein
+
+3. **Datenbank-Größe**
+   - SQLite-Datenbanken können groß werden
+   - Regelmäßige Bereinigung erwägen
+
+4. **ChromaDB-Status**
+   - Server-Status überwachen (falls verwendet)
+   - Verbindungsfehler prüfen
+
+## Fehlerbehandlung
+
+### Bei Ingestion-Fehlern
+
+1. **Prüfe `docs/` Ordner**
+   ```bash
+   Test-Path docs/modules
+   Test-Path docs/index/symbols.jsonl
+   ```
+
+2. **Prüfe Logs**
+   - Output-Channel in VS Code
+   - Terminal-Output bei CLI-Nutzung
+
+3. **Vollständige Re-Ingestion**
+   ```bash
+   noyrax-5d-database ingest . --full
+   ```
+
+### Bei MCP-Server-Fehlern
+
+1. **Prüfe Workspace-Root**
+   ```bash
+   noyrax-5d-database-mcp <workspace-root>
+   ```
+
+2. **Prüfe `docs/` Existenz**
+   - MCP-Server erfordert `docs/` Ordner
+
+3. **Prüfe Ingestion**
+   - SQLite-Datenbanken müssen existieren
+
+### Bei Semantic Search-Fehlern
+
+1. **Prüfe Embeddings**
+   ```bash
+   noyrax-5d-database-embedding .
+   ```
+
+2. **Prüfe ChromaDB**
+   - Server läuft? (falls verwendet)
+   - Verbindung erfolgreich?
+
+3. **Prüfe OpenAI API Key**
+   - `.env` Datei vorhanden?
+   - `OPENAI_API_KEY` gesetzt?
+
+## Verweise
+
+- `CHROMADB_SETUP.md` - ChromaDB-Installation und Troubleshooting
+- `MCP_SERVER_SETUP.md` - MCP-Server-Konfiguration
+- `SETUP_NEW_PROJECT.md` - Vollständiger Setup-Workflow
+- `INSTALLATION_READINESS.md` - Installation-Readiness-Report
+
+## Update-Log
+
+**2025-12-29:**
+- Dokumentation erstellt
+- Alle bekannten Probleme als nicht-kritisch klassifiziert
+- Workarounds dokumentiert
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Noyrax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MCP_SERVER_SETUP.md

@@ -0,0 +1,359 @@
+# 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>
+```
+
+### 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` |
+
+## 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
+