English Version

Zurück zur Übersicht

osTicket MCP Server: Technik

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Überblick

Der Server ist ein Node.js-Programm in TypeScript (ES-Module). Er nutzt das MCP SDK (@modelcontextprotocol/sdk) mit stdio-Transport, Zod für die Eingabeprüfung und dotenv für die Konfiguration. Er hat keine Datenbank und hält nur einen kleinen Speicher für die Statusliste.

Ablauf eines Tool-Aufrufs

graph TD
    A["MCP-Client ruft Tool auf"] --> B["Zod prüft die Parameter"]
    B --> C{"Anhänge angegeben?"}
    C -->|"Ja"| D["Dateien lesen und als Base64-Data-URI kodieren"]
    C -->|"Nein"| E["OsTicketApiClient"]
    D --> E
    E --> F{"Statusname bei update?"}
    F -->|"Ja"| G["Statusliste laden, 5 Minuten zwischengespeichert"]
    F -->|"Nein"| H["HTTP-Anfrage mit X-API-Key"]
    G --> H
    H -->|"502, 503, 504, Verbindungsfehler, Timeout"| I["Bis zu 2 Wiederholungen"]
    I --> H
    H -->|"Antwort"| J["JSON als Text oder Fehlerzeile"]

Genutzte Endpunkte

Bei der Suche sendet der Server den Abteilungsfilter als Abfrageparameter departmentId. Das Plugin liest an dieser Stelle nur department, der Filter von osticket_list_tickets bleibt deshalb ohne Wirkung. query, status, limit und offset stimmen mit dem Plugin überein.

Pfade, Methoden und Berechtigungen der tickets-*.php-Endpunkte beschreibt die API-Dokumentation des Plugins API Endpoints. Der Wildcard-Endpunkt gehört zum Plugin API Key Wildcard. Er nutzt die Ticket-Erstellung von osTicket mit einer eigenen Key-Prüfung, die auch Keys mit der IP 0.0.0.0 zulässt.

Der Server sendet bei jeder Anfrage die Header X-API-Key und Content-Type: application/json und setzt bei einem Body die Content-Length selbst, damit kein Chunked-Encoding entsteht.

Wiederholungen

Der Server wiederholt eine Anfrage bis zu zweimal, wenn:

• osTicket oder ein Proxy mit 502, 503 oder 504 antwortet,
• die Verbindung mit ECONNRESET oder ECONNREFUSED scheitert,
• das Timeout von 10 Sekunden abläuft.

Die Wartezeit verdoppelt sich: 500 ms, dann 1000 ms. Das gilt für alle Methoden, auch für POST beim Erstellen von Tickets und Verknüpfungen. Läuft eine Antwort nach dem erfolgreichen Anlegen in ein Timeout, kann ein Ticket doppelt entstehen.

Fehlerbehandlung

Jedes Tool fängt Fehler ab und gibt sie als Text mit gesetztem Fehlerflag zurück. Die Zeile heißt Error: <Aktion> - <Hinweis>.

Zu den anderen Fehlern zählen unter anderem ein unbekannter Statusname, ein Name statt einer ID bei Abteilung, Hilfethema, Mitarbeiter und SLA, nicht lesbare Anhänge und Eingaben, die die Prüfung nach dem Schema nicht bestehen. Der Server schreibt die Ursache in solchen Fällen nicht ins Log.

Statusliste

Beim ersten Aufruf mit einem Statusnamen lädt der Client die Liste von /api/tickets-statuses.php und merkt sie sich 5 Minuten. Schlägt das Neuladen fehl, bleibt die alte Liste erhalten, sonst wird sie leer. Der Vergleich ignoriert Groß- und Kleinschreibung. Ein Wert, der als Zahl beginnt, wird ohne Nachschlagen als ID verwendet.

Anhänge

Der Server liest jede Datei, bestimmt den MIME-Typ anhand der Dateiendung (bekannte Endungen für Bilder, Dokumente, Text und Archive, sonst application/octet-stream) und sendet sie als Base64-Data-URI im Format [{ "dateiname": "data:<mime>;base64,<daten>" }]. Dateien müssen vorhanden, nicht leer und höchstens 10 MB groß sein. Zusammen sind 50 MB erlaubt, bis zu 5 Dateien je Aufruf.

Dateistruktur

claude-mcp-osTicket/
├── src/
│   ├── index.ts                         # Server, Tool-Registrierung, Fehlerformat
│   ├── constants.ts                     # Limits, Servername und Version
│   ├── config/Configuration.ts          # Umgebungsvariablen und Prüfungen
│   ├── schemas/index.ts                 # Zod-Schemas der Tool-Parameter
│   ├── utils/attachments.ts             # Dateien lesen, kodieren, Downloads speichern
│   └── infrastructure/
│       ├── errors/OsTicketApiError.ts   # Fehler mit HTTP-Statuscode
│       ├── http/OsTicketApiClient.ts    # HTTP-Client, Wiederholungen, Statusliste
│       ├── http/types/                  # Typen der API-Antworten
│       └── logging/Logger.ts            # Logger mit Rotation
├── dist/                                # Build-Ausgabe (npm run build)
├── .env.example                         # Vorlage der Konfiguration
└── package.json

Der Server meldet sich als MCP-Server osticket-mcp-server an und liest seine Versionsnummer aus der package.json.