Orchestrator/bahn/beam-mcp/.kiro/steering/add-beam-tool.md

inclusion

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:

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():

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:

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:

const LC: Record<string, string> = {
  // ... bestehende Einträge
  newValue: "Neuer Wert",
};

4. Build & Test

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