Orchestrator/bahn/beam-mcp/README.md

*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.