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