Orchestrator/bahn/beam-mcp

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

cd beam-mcp
npm install
npm run build

---

Konfiguration

Optional: Kopiere .env.example nach .env um die Standard-URLs anzupassen:

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:

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:

{
  "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:

{
  "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.