Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.
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.
| Methode | Pfad | Genutzt von |
|---|---|---|
| GET | /api/tickets-get.php/{number}.json |
osticket_get_ticket |
| GET | /api/tickets-search.php mit query, status, departmentId, limit, offset |
osticket_list_tickets, osticket_search_tickets |
| GET | /api/tickets-stats.php |
osticket_get_stats, Zustandsprüfung beim Start |
| GET | /api/tickets-statuses.php |
Auflösung von Statusnamen |
| POST | /api/wildcard/tickets.json |
osticket_create_ticket |
| PATCH | /api/tickets-update.php/{number}.json |
osticket_update_ticket |
| DELETE | /api/tickets-delete.php/{number}.json |
osticket_delete_ticket |
| GET | /api/tickets-subtickets-parent.php/{number}.json |
osticket_get_parent_ticket |
| GET | /api/tickets-subtickets-list.php/{number}.json |
osticket_get_child_tickets |
| POST | /api/tickets-subtickets-create.php/{parentNumber}.json |
osticket_create_subticket_link |
| DELETE | /api/tickets-subtickets-unlink.php/{number}.json |
osticket_unlink_subticket |
| GET | /api/tickets-attachment-download.php/{file_id}.json |
osticket_download_attachment |
Bei der Suche sendet der Server den Abteilungsfilter als Abfrageparameter
departmentId. Das Plugin liest an dieser Stelle nurdepartment, der Filter vonosticket_list_ticketsbleibt deshalb ohne Wirkung.query,status,limitundoffsetstimmen 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.
Der Server wiederholt eine Anfrage bis zu zweimal, wenn:
502, 503 oder 504 antwortet,ECONNRESET oder ECONNREFUSED scheitert,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.
Jedes Tool fängt Fehler ab und gibt sie als Text mit gesetztem Fehlerflag zurück. Die Zeile heißt Error: <Aktion> - <Hinweis>.
| Fall | Hinweis |
|---|---|
osTicket antwortet mit 401 |
Prüfen, ob der Key gültig und aktiv ist |
osTicket antwortet mit 403 |
Die Berechtigung des Keys fehlt |
osTicket antwortet mit 404 |
Ticket nicht gefunden |
osTicket antwortet mit 501 |
Das Subticket-Plugin ist nicht verfügbar |
| Anderer HTTP-Fehler | Die Meldung aus dem Body von osTicket (message, sonst error), sonst ein Standardtext zum Statuscode |
| Timeout, Verbindungsfehler, Host nicht gefunden, TLS-Fehler | Jeweils ein eigener Satz |
| Ungültige Ticketnummer | Die Meldung Invalid ticket number mit Kontext |
| Alle anderen Fehler | Unexpected error occurred. Check server logs for details. |
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.
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.
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.
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.