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