Migrate all repos into monorepo context folders

Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp, Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit, Projekt-KIQ-HP, teamlandkarte-mcp Dhive: Jury-Voting Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation) Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more Shared/references: symphony (read-only) Bahn repos remain available as independent remotes - this monorepo pulls them in via subtree, the originals are untouched.
2026-06-30 20:39:52 +02:00
parent 2f2b295531
commit a5f8fb49ab
1717 changed files with 447332 additions and 0 deletions
@@ -0,0 +1,369 @@
+*DIESER MCP SERVER DIENT NUR FÜR "EDUCATIONAL PURPOSES"! EINE AKTIVE VERWENDUNG IST NICHT GESTATTET AUFGRUND DATENSCHUTZRECHTLICHER BEDENKEN!*
+
+# BEAM MCP Server
+
+MCP Server für die Deutsche Bahn Enterprise Architektur Plattform **BEAM** (http://db.de/beam).
+Ermöglicht den direkten Zugriff auf BEAM-Daten über die LeanIX GraphQL API — ohne Browser-Navigation.
+
+## Ansprechpartner
+
+| Kontakt | E-Mail |
+|---------|--------|
+| Team DT-BETA | DBS.BS.INFRA.DS4E.DT-BETA@deutschebahn.com |
+
+## Lizenz
+
+DB Inner Source License (DBISL) - DB Systel GmbH
+
+---
+
+## Voraussetzungen
+
+- Node.js >= 18
+- Microsoft Edge (für automatischen Browser-Login)
+- Zugang zu BEAM (DB-Netz oder VPN)
+
+---
+
+## Installation
+
+```bash
+cd beam-mcp
+npm install
+npm run build
+```
+
+---
+
+## Konfiguration
+
+Optional: Kopiere `.env.example` nach `.env` um die Standard-URLs anzupassen:
+
+```bash
+cp .env.example .env
+```
+
+### Umgebungsvariablen
+
+| Variable | Beschreibung | Standard |
+|---|---|---|
+| `BEAM_BASE_URL` | Basis-URL der BEAM-Instanz | `https://db.leanix.net` |
+| `BEAM_LOGIN_URL` | Login-URL für automatischen Browser-Login | `http://db.de/beam` |
+| `BEAM_WORKSPACE` | Workspace-Name | `beam` |
+| `BEAM_HEADLESS` | Browser-Login im Headless-Modus (`true`/`false`). Bei Anmeldeproblemen auf `false` setzen, um den Browser sichtbar zu starten. | `true` |
+
+---
+
+## Authentifizierung
+
+Das BEAM-Token wird sicher im **OS-Keychain** gespeichert:
+
+- **macOS**: Keychain Access (via `security` CLI)
+- **Windows**: DPAPI-verschlüsselte Datei in `%LOCALAPPDATA%/beam-mcp/`
+
+### Automatischer Browser-Login (empfohlen)
+
+Beim ersten Aufruf eines Tools ohne gültiges Token startet der Server automatisch einen Microsoft Edge Browser, navigiert zu BEAM und meldet sich über "BEAM: DB User" an. Das Token wird anschließend im OS-Keychain gespeichert und für alle weiteren Anfragen (auch nach Server-Neustart) wiederverwendet.
+
+Falls der automatische Login fehlschlägt, kann der Browser mit `BEAM_HEADLESS=false` sichtbar gestartet werden, um das Problem zu diagnostizieren.
+
+Der Login kann auch manuell ausgelöst werden:
+
+```bash
+npm run login
+```
+
+Oder über das Tool `beam_get_token` im MCP-Client.
+
+### Token-Lebensdauer
+
+BEAM-Tokens sind zeitlich begrenzt gültig. Der Server prüft die Gültigkeit automatisch und löst bei Bedarf einen neuen Login aus. Bei einem 401-Fehler wird das gespeicherte Token aus dem Keychain gelöscht und ein neuer Login getriggert.
+
+---
+
+## Integration
+
+### Kiro
+
+In `.kiro/settings/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "beam-mcp": {
+      "command": "node",
+      "args": ["/pfad/zu/beam-mcp/dist/index.js"],
+      "env": {
+        "BEAM_BASE_URL": "https://db.leanix.net",
+        "BEAM_WORKSPACE": "beam",
+        "BEAM_HEADLESS": "true"
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+In `.opencode/opencode.json`:
+
+```json
+{
+  "mcp": {
+    "beam-mcp": {
+      "enabled": true,
+      "type": "local",
+      "command": ["node", "/pfad/zu/beam-mcp/dist/index.js"],
+      "environment": {
+        "BEAM_BASE_URL": "https://db.leanix.net",
+        "BEAM_WORKSPACE": "beam",
+        "BEAM_HEADLESS": "true"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Verfügbare Tools
+
+Alle Tools verwenden das Prefix `beam_` um Namenskonflikte mit anderen MCP-Servern zu vermeiden.
+
+### `beam_get_token`
+
+Meldet sich bei BEAM an und speichert das Token im OS-Keychain.
+Nur nötig, wenn kein gültiges Token vorhanden ist oder das Token abgelaufen ist.
+
+**Parameter:** keine
+
+**Annotations:** `readOnlyHint: false` | `idempotentHint: true`
+
+**Beispiel:**
+```
+beam_get_token()
+```
+
+**Ausgabe:**
+```
+✓ BEAM Login erfolgreich!
+Benutzer: florian.hofmann@deutschebahn.com
+Token gültig bis: 20.04.2026, 11:30:00
+Token im Keychain gespeichert.
+```
+
+---
+
+### `beam_search_factsheets`
+
+Sucht nach BEAM Fact Sheets anhand von Name, Beam-ID oder Freitext.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Beschreibung |
+|---|---|---|---|
+| `query` | String | ✓ | Suchbegriff, Beam-ID (z.B. `A-106614`) oder Name |
+| `type` | Enum | — | Einschränkung auf Fact-Sheet-Typ (siehe unten) |
+
+**Mögliche Typen:**
+- `Application` — Anwendung
+- `BusinessCapability` — Domäne
+- `ITComponent` — IT-Komponente
+- `Interface` — Integration
+- `DataObject` — Datenobjekt
+
+**Annotations:** `readOnlyHint: true` | `idempotentHint: true`
+
+**Beispiele:**
+```
+beam_search_factsheets(query: "A-106614")
+beam_search_factsheets(query: "RiM", type: "Application")
+beam_search_factsheets(query: "Personaleinsatz", type: "BusinessCapability")
+```
+
+---
+
+### `beam_get_factsheet`
+
+Ruft vollständige Details eines BEAM Fact Sheets ab.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Beschreibung |
+|---|---|---|---|
+| `id` | String | ✓ | Beam-ID (z.B. `A-106614`) oder UUID |
+
+**Unterstützte Fact-Sheet-Typen:**
+- Anwendungen (`Application`)
+- Domänen (`BusinessCapability`)
+- IT-Komponenten (`ITComponent`)
+
+**Annotations:** `readOnlyHint: true` | `idempotentHint: true`
+
+**Beispiele:**
+```
+beam_get_factsheet(id: "A-106614")
+beam_get_factsheet(id: "33cb34f7-d6fe-481e-a650-8ca42884c4eb")
+beam_get_factsheet(id: "P.F.05.05.04")
+```
+
+**Ausgabe (Anwendung):**
+```
+## A-106614 - Fahrendes Personal RiM
+Typ: Anwendung
+Status: Bestätigt
+Alias: RiM; Rail in Motion; Rim; rim
+Lebenszyklus: Ausgliederungsphase
+
+Beschreibung:
+Mit "Fahrendes Personal RiM" wird Fahrpersonalen und Triebfahrzeugführern...
+
+Tags: Bordservice, Mobile Solutions Bordpersonale
+
+### Domänen
+  • P.F.05.05.04 - Informationen bereitstellen | Supporttyp: Führend
+
+### IT-Komponenten
+  • Enterprise Cloud Managed
+
+### Nachfolger
+  • MERKUR (ID: 8c92a72a-...)
+```
+
+---
+
+### `beam_get_domain_applications`
+
+Listet alle Anwendungen einer BEAM-Domäne auf, gruppiert nach Supporttyp.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Beschreibung |
+|---|---|---|---|
+| `domain` | String | ✓ | Domänen-ID (z.B. `P.F.05.05.04`), Name oder UUID |
+
+**Annotations:** `readOnlyHint: true` | `idempotentHint: true`
+
+**Beispiele:**
+```
+beam_get_domain_applications(domain: "P.F.05.05.04")
+beam_get_domain_applications(domain: "Informationen bereitstellen")
+```
+
+---
+
+### `beam_get_diagram`
+
+Ruft Diagramme einer BEAM-Anwendung ab. Listet verfügbare Diagramme auf, zeigt eine lesbare Zusammenfassung (Systeme, Schnittstellen) und kann das Diagramm als `.drawio`-Datei speichern.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Beschreibung |
+|---|---|---|---|
+| `application` | String | ✓ | Anwendungsname, Beam-ID (z.B. `A-109410`) oder UUID |
+| `diagram_name` | String | — | Name oder Teil des Diagrammnamens zum Abrufen |
+| `save_path` | String | — | Dateipfad zum Speichern als `.drawio`-Datei |
+
+**Annotations:** `readOnlyHint: false` (kann Dateien schreiben) | `idempotentHint: true`
+
+**Beispiele:**
+
+Diagramme auflisten:
+```
+beam_get_diagram(application: "KEP_KEO_Revision")
+```
+
+Diagramm lesen:
+```
+beam_get_diagram(application: "KEP_KEO_Revision", diagram_name: "System Context")
+```
+
+Diagramm als draw.io speichern:
+```
+beam_get_diagram(application: "KEP_KEO_Revision", diagram_name: "System Context", save_path: "./kep-system-context.drawio")
+```
+
+**Ausgabe (Lesen):**
+```
+## A-109410 - KEP_KEO_Revision - System Context
+Typ: freedraw
+Beschreibung: Systemkontextdiagramm zu "Anwendung zur Integration..."
+
+### Systeme/Akteure (10)
+  • A-109410 - KEP_KEO_Revision [Software System] — Kraftwerkseinsatzoptimierung
+  • A-107939 - ETRM_Marktdatendatenbank [Software System] — Energiemarktrelevante Daten
+  ...
+
+### Schnittstellen/Verbindungen (12)
+  • Auswahl gewählter Produktionsvolumen für D und D+1
+  • Marktpreise
+  ...
+```
+
+**Ausgabe (Speichern):**
+```
+✓ Diagramm gespeichert: /pfad/zu/kep-system-context.drawio
+Die Datei kann direkt in draw.io geöffnet werden.
+```
+
+**Hinweise:**
+- Die `.drawio`-Datei enthält das originale mxGraph-XML aus BEAM und kann direkt in draw.io (Desktop oder Web) geöffnet werden.
+- Die lesbare Zusammenfassung extrahiert automatisch C4-Modell-Elemente (Systeme, Personen) und Schnittstellen.
+
+---
+
+## Fehlerbehandlung
+
+Alle Tools geben bei Fehlern strukturierte Fehlermeldungen mit `isError: true` zurück:
+
+| Fehler | Meldung | Lösung |
+|--------|---------|--------|
+| 401/403 | Authentifizierung fehlgeschlagen | `beam_get_token` aufrufen |
+| 404 | Nicht gefunden | ID oder Suchbegriff prüfen |
+| 429 | Rate-Limit erreicht | Kurz warten, erneut versuchen |
+
+Große Antworten werden automatisch auf 25.000 Zeichen gekürzt mit einem Hinweis auf spezifischere Filter.
+
+---
+
+## Architektur
+
+```
+beam-mcp/
+├── src/
+│   ├── index.ts      # MCP Server, Tool-Registrierung (registerTool), Error-Handling
+│   ├── api.ts        # BEAM GraphQL API Client, Diagramm-Export
+│   ├── auth.ts       # Authentifizierung (Keychain + Playwright Login)
+│   └── keychain.ts   # OS-Keychain Abstraktionsschicht (macOS/Windows)
+├── dist/             # Kompilierter JavaScript-Code (nach npm run build)
+├── .env.example      # Vorlage für optionale Konfiguration
+├── package.json
+└── tsconfig.json
+```
+
+### Datenfluss
+
+```
+Kiro / OpenCode / KI-Assistent
+        │
+        ▼
+   beam-mcp-server (MCP über stdio)
+        │
+        ├─► auth.ts ──► keychain.ts ──► OS-Keychain (Token lesen/schreiben)
+        │           └─► Playwright Edge Login (falls kein gültiges Token)
+        │
+        └─► api.ts ──► BEAM GraphQL API (https://db.leanix.net/services/pathfinder/v1/graphql)
+                   └─► BEAM Bookmarks API (Diagramme)
+```
+
+---
+
+## Hinweise
+
+- Das Token läuft nach einigen Stunden ab. Der Server erkennt dies automatisch und löst einen neuen Login aus.
+- Der Browser-Login benötigt Zugang zu `http://db.de/beam` (DB-Netz oder VPN).
+- Alle internen Variablen- und Feldnamen folgen der LeanIX API-Konvention; die Anzeige ist auf BEAM-Terminologie gemappt.
+- Der Server ist read-only — es werden keine Daten in BEAM verändert (außer `.drawio`-Dateien lokal speichern).
+- Alle Tools nutzen `registerTool` mit Annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
+- Tool-Namen verwenden das `beam_`-Prefix zur Vermeidung von Namenskonflikten.
+- Keine Secrets in Dateien — Token wird ausschließlich im OS-Keychain gespeichert.