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