ankn
a5f8fb49ab
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.
138 lines
3.5 KiB
Markdown
138 lines
3.5 KiB
Markdown
---
|
|
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
|