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,137 @@
+---
+inclusion: manual
+---
+
+# Neues BEAM Tool hinzufügen
+
+Schritt-für-Schritt Anleitung zum Erweitern des beam-mcp-servers um ein neues Tool.
+
+## 1. API-Funktion in `src/api.ts`
+
+Neue Datenabfragen gehören in `api.ts`. Nutze die bestehende `gql()`-Funktion für GraphQL-Queries:
+
+```typescript
+export async function myNewFunction(param: string) {
+  // UUID-Erkennung: wenn keine UUID, per Suche auflösen
+  let uuid = param;
+  if (!param.match(/^[0-9a-f-]{36}$/i)) {
+    const results = await searchFactSheets(param);
+    if (!results.length) throw new Error(`No factsheet found for: ${param}`);
+    uuid = results[0].id as string;
+  }
+
+  const data = (await gql(
+    `query MyQuery($id: ID!) {
+      factSheet(id: $id) {
+        id name type
+        ... on Application {
+          // gewünschte Felder
+        }
+      }
+    }`,
+    { id: uuid }
+  )) as { factSheet: Record<string, unknown> };
+
+  return data.factSheet;
+}
+```
+
+Für REST-Endpunkte (z.B. Bookmarks API) nutze `fetch` mit `getToken()`:
+
+```typescript
+const token = await getToken();
+const res = await fetch(`${BEAM_BASE_URL}/services/pathfinder/v1/endpoint/${id}`, {
+  headers: { Authorization: `Bearer ${token}` },
+});
+```
+
+## 2. Tool registrieren in `src/index.ts`
+
+Importiere die neue Funktion und registriere das Tool:
+
+```typescript
+import { myNewFunction } from "./api.js";
+
+server.registerTool(
+  "beam_my_new_tool",  // beam_ Prefix + snake_case
+  {
+    title: "Kurzer deutscher Titel",
+    description: `Ausführliche Beschreibung was das Tool tut.
+
+Args:
+  - param1 (string, required): Beschreibung
+  - param2 (string, optional): Beschreibung
+
+Returns:
+  Was zurückgegeben wird.
+
+Examples:
+  - param1="Beispielwert" → Was passiert`,
+    inputSchema: {
+      param1: z.string()
+        .min(1, "Darf nicht leer sein")
+        .describe("Beschreibung des Parameters"),
+      param2: z.string()
+        .optional()
+        .describe("Optionaler Parameter"),
+    },
+    annotations: {
+      readOnlyHint: true,      // true wenn nur lesend
+      destructiveHint: false,   // true wenn Daten gelöscht werden
+      idempotentHint: true,     // true wenn wiederholbar ohne Seiteneffekte
+      openWorldHint: true,      // true wenn externe Systeme angesprochen werden
+    },
+  },
+  async ({ param1, param2 }) => {
+    try {
+      const result = await myNewFunction(param1);
+      // Ergebnis formatieren...
+      const text = `## Ergebnis\n${JSON.stringify(result, null, 2)}`;
+      return { content: [{ type: "text", text: truncateIfNeeded(text) }] };
+    } catch (error) {
+      return handleError(error);
+    }
+  }
+);
+```
+
+## 3. Label-Mappings erweitern (falls nötig)
+
+Wenn neue BEAM-Werte gemappt werden müssen, die bestehenden Maps in `index.ts` erweitern:
+
+```typescript
+const LC: Record<string, string> = {
+  // ... bestehende Einträge
+  newValue: "Neuer Wert",
+};
+```
+
+## 4. Build & Test
+
+```bash
+npm run build
+```
+
+Muss fehlerfrei durchlaufen. Danach MCP-Server neu starten.
+
+## 5. README aktualisieren
+
+Neues Tool in `README.md` unter "Verfügbare Tools" dokumentieren:
+- Tool-Name mit `beam_` Prefix
+- Parameter-Tabelle
+- Annotations
+- Beispiele
+- Beispiel-Ausgabe
+
+## Checkliste
+
+- [ ] API-Funktion in `api.ts` (nicht in `index.ts`)
+- [ ] `server.registerTool()` mit title, description, inputSchema, annotations
+- [ ] Tool-Name: `beam_` + snake_case
+- [ ] Description mit Args, Returns, Examples
+- [ ] Zod-Schema mit `.describe()` und Validierung
+- [ ] Alle 4 Annotations gesetzt
+- [ ] try/catch mit `handleError()`
+- [ ] `truncateIfNeeded()` für große Responses
+- [ ] `npm run build` erfolgreich
+- [ ] README.md aktualisiert
@@ -0,0 +1,76 @@
+---
+inclusion: always
+---
+
+# BEAM Domänenwissen
+
+## Was ist BEAM?
+
+BEAM (Business Enterprise Architecture Management) ist die Architektur-Plattform der Deutschen Bahn, basierend auf LeanIX. Sie dokumentiert die IT-Landschaft mit Anwendungen, Domänen, IT-Komponenten, Schnittstellen und Diagrammen.
+
+URL: https://db.leanix.net (intern: http://db.de/beam)
+
+## Zentrale Konzepte
+
+### Fact Sheets
+
+Fact Sheets sind die Kernobjekte in BEAM. Jedes hat eine UUID und optional eine externe Beam-ID.
+
+| Typ | Beam-ID Format | Beispiel | Beschreibung |
+|-----|---------------|----------|--------------|
+| Application | A-XXXXXX | A-106614 | Anwendung/Software-System |
+| BusinessCapability | P.X.XX.XX.XX | P.F.05.05.04 | Fachliche Domäne/Capability |
+| ITComponent | — | — | Technische Infrastruktur-Komponente |
+| Interface | — | — | Schnittstelle zwischen Anwendungen |
+| DataObject | — | — | Datenobjekt |
+
+### Lebenszyklus
+
+Jedes Fact Sheet hat einen Lebenszyklus-Status:
+- `plan` → Plan
+- `phaseIn` → Einführungsphase
+- `active` → Aktiv
+- `phaseOut` → Ausgliederungsphase
+- `endOfLife` → Lebensende
+
+### Supporttyp (Domänen-Zuordnung)
+
+Anwendungen werden Domänen mit einem Supporttyp zugeordnet:
+- `leading` → Führend (Hauptanwendung der Domäne)
+- `supports` → Unterstützt (Hilfsanwendung)
+
+### Diagramme
+
+Diagramme in BEAM sind als "Bookmarks" gespeichert und enthalten mxGraph-XML (draw.io-kompatibel). Sie werden über die Documents-Relation eines Fact Sheets verknüpft. Typische Diagrammtypen:
+- System Context (C4-Modell)
+- Verteilungssicht (PROD/TST/ABN)
+- Schnittstellen
+
+## BEAM GraphQL API
+
+Endpunkt: `https://db.leanix.net/services/pathfinder/v1/graphql`
+
+Wichtige Queries:
+- `allFactSheets(filter, first)` — Suche mit Volltextfilter
+- `factSheet(id)` — Einzelnes Fact Sheet mit Relationen
+- Relationen: `relApplicationToBusinessCapability`, `relBusinessCapabilityToApplication`, `relApplicationToITComponent`, `relToSuccessor`
+
+## BEAM Bookmarks API (Diagramme)
+
+Endpunkt: `https://db.leanix.net/services/pathfinder/v1/bookmarks/{id}`
+
+Gibt ein JSON-Objekt zurück mit:
+- `data.name` — Diagrammname
+- `data.groupKey` — Typ (z.B. "freedraw")
+- `data.state.graphXml` — mxGraph-XML (draw.io-kompatibel)
+- `data.description` — Beschreibung
+- `data.referencedFactSheetIds` — Verknüpfte Fact Sheets
+
+## Terminologie-Mapping
+
+Der MCP-Server mappt LeanIX-interne Begriffe auf BEAM-Terminologie:
+- Application → Anwendung
+- BusinessCapability → Domäne
+- ITComponent → IT-Komponente
+- Interface → Integration (Schnittstelle)
+- lxState APPROVED → Bestätigt
@@ -0,0 +1,86 @@
+---
+inclusion: always
+---
+
+# Coding Standards — beam-mcp-server
+
+## Projektstruktur
+
+```
+src/
+├── index.ts     # MCP Server, Tool-Registrierung, Label-Mappings, Error-Handling
+├── api.ts       # BEAM GraphQL/REST API Client, Diagramm-Funktionen
+├── auth.ts      # Token-Management (Keychain + Playwright Browser-Login)
+└── keychain.ts  # OS-Keychain Abstraktionsschicht (macOS/Windows)
+```
+
+## TypeScript-Konventionen
+
+- ESM (`"type": "module"` in package.json), alle Imports mit `.js`-Suffix
+- Strict mode aktiviert, kein `any` — nutze `Record<string, unknown>` oder konkrete Interfaces
+- Target: ES2022, Module: Node16
+- Build: `npm run build` (tsc), Output in `dist/`
+
+## MCP Tool-Konventionen
+
+- Alle Tools nutzen `server.registerTool()` (NICHT `server.tool()`)
+- Tool-Namen: `beam_` Prefix + snake_case (z.B. `beam_search_factsheets`)
+- Jedes Tool braucht:
+  - `title`: Kurzer deutscher Titel
+  - `description`: Ausführliche Beschreibung mit Args, Returns, Examples
+  - `inputSchema`: Zod-Schemas mit `.describe()` und Validierung (`.min()`, `.max()`)
+  - `annotations`: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`
+- Jeder Tool-Handler ist in try/catch gewrappt und nutzt `handleError()` bei Fehlern
+- Große Responses werden mit `truncateIfNeeded()` auf CHARACTER_LIMIT (25k) gekürzt
+
+## Error-Handling Pattern
+
+```typescript
+async (params) => {
+  try {
+    // ... Logik ...
+    return { content: [{ type: "text", text: result }] };
+  } catch (error) {
+    return handleError(error);
+  }
+}
+```
+
+`handleError()` gibt `{ isError: true, content: [...] }` zurück mit kontextbezogenen Meldungen:
+- 401/403 → Hinweis auf `beam_get_token`
+- 404 → ID/Suchbegriff prüfen
+- 429 → Rate-Limit, warten
+
+## API-Schicht (api.ts)
+
+- `gql()` — Shared GraphQL-Client mit Auth-Header
+- Alle API-Funktionen sind `async` und werfen Errors mit HTTP-Status
+- UUID-Erkennung: `/^[0-9a-f-]{36}$/i` — alles andere wird als Beam-ID/Name per Suche aufgelöst
+- Neue API-Funktionen gehören in `api.ts`, nicht in `index.ts`
+
+## Label-Mappings (index.ts)
+
+BEAM-interne Werte werden auf deutsche Labels gemappt:
+- `LC` — Lebenszyklus (active→Aktiv, phaseOut→Ausgliederungsphase, ...)
+- `ST` — Supporttyp (leading→Führend, supports→Unterstützt)
+- `FS_TYPE` — Fact-Sheet-Typen (Application→Anwendung, ...)
+- `STATE` — Status (APPROVED→Bestätigt, ...)
+
+## Auth (auth.ts) & Keychain (keychain.ts)
+
+- Token-Priorität: In-Memory Cache → OS-Keychain → Playwright Browser-Login
+- Token wird im OS-Keychain gespeichert (macOS: Keychain Access, Windows: DPAPI)
+- Keine .env-Datei für Secrets — nur für Konfigurations-URLs
+- Gültigkeit: JWT exp-Claim minus 60s Puffer
+- Bei Invalidierung (401): Token aus Memory + Keychain gelöscht
+- Logging nur auf stderr (stdio-Transport!)
+
+## Build & Test
+
+```bash
+npm run build    # TypeScript kompilieren
+npm start        # Server starten (stdio)
+npm run login    # Manueller Browser-Login + Token im Keychain speichern
+```
+
+Nach jeder Änderung: `npm run build` muss fehlerfrei durchlaufen.