English Version

Zurück zur Übersicht

osTicket MCP Server: Tools

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

Der Server stellt 12 Tools bereit. Alle Namen tragen das Präfix osticket_. Erfolgreiche Aufrufe liefern JSON als Text, Fehler kommen mit gesetztem Fehlerflag und einer Zeile der Form Error: <Aktion> - <Hinweis> zurück, siehe Fehlerbehebung.

Übersicht

Zusätzlich fragt osticket_update_ticket mit einem Statusnamen die Statusliste über GET /api/tickets-statuses.php ab (can_read_stats oder can_read_tickets). Beim Start ruft der Server GET /api/tickets-stats.php für die Zustandsprüfung auf.

Die Berechtigungen setzt du im osTicket-Admin-Panel unter Verwalten → Plugins → API Endpoints → Configure, siehe die Konfiguration des Plugins. Die Subticket-Tools brauchen außerdem das Plugin Subticket Manager.

Ticketnummern sind in allen Tools Strings aus 1 bis 20 Ziffern, zum Beispiel "680284".

osticket_get_ticket

Ruft ein Ticket mit Thread, Benutzer, Mitarbeiter und Anhang-Metadaten ab.

Sind beide angegeben, gilt number. Rückgabe: { "ticket": { ... } } mit dem Objekt des Plugins.

Eine id sendet der Server als Ticketnummer. Das Plugin sucht zuerst ein Ticket mit dieser Nummer und nimmt erst danach die interne ID. Trägt ein anderes Ticket zufällig diese Nummer, bekommst du dieses.

osticket_list_tickets

Listet Ticket-Zusammenfassungen ohne Thread.

Rückgabe: tickets, count, offset, has_more und bei weiteren Seiten next_offset. has_more ist wahr, wenn genau limit Einträge zurückkamen. Eine Gesamtzahl liefert das Tool nicht. Wurde die Antwort wegen der Zeichengrenze gekürzt, stehen truncated und truncation_message dabei.

Der Parameter departmentId existiert im Tool, filtert aber nicht. Der Server sendet ihn als Abfrageparameter departmentId, das Plugin liest jedoch nur department. Die Liste kommt deshalb ungefiltert zurück. Filtere nach Abteilung bis auf Weiteres nicht über dieses Tool.

Das Plugin ignoriert außerdem einen status-Namen, der keinem Status der Instanz entspricht, und filtert dann gar nicht. Prüfe mit osticket_get_stats, ob die Zahlen plausibel sind, wenn eine Liste unerwartet groß ausfällt.

osticket_search_tickets

Sucht im Betreff der Tickets.

Rückgabe: tickets, count, total, query und has_more. total ist die Zahl der zurückgegebenen Treffer, nicht die Zahl aller Treffer in osTicket. Das Tool hat keinen offset.

osticket_get_stats

Keine Parameter. Rückgabe: { "statistics": { ... } } mit den Werten des Plugins: total, open, closed, overdue, by_department und by_staff.

osticket_create_ticket

Erstellt ein Ticket über den Endpunkt /api/wildcard/tickets.json.

Fehlen sowohl name als auch OSTICKET_DEFAULT_NAME, bricht das Tool mit einer Fehlermeldung ab. Dasselbe gilt für die E-Mail-Adresse. Der Server sendet immer alert=false und autorespond=false: Weder das Team noch der Absender bekommen eine Benachrichtigung durch osTicket.

Rückgabe: success, ticketNumber, projectContext (oder null), bei Anhängen attachments mit einer Zusammenfassung, und message.

Der Tool-Text weist Claude an, bei fehlender Projektangabe nach dem Projekt zu fragen. Der Code erzwingt das nicht: Ohne projectContext wird das Ticket ohne Projektzeile erstellt.

osticket_update_ticket

Ändert Eigenschaften eines Tickets und kann eine interne Notiz anlegen.

Nur der Status wird im Server aufgelöst: Ein Name wird gegen die Statusliste von osTicket verglichen, ohne Beachtung der Groß-/Kleinschreibung, und die Liste wird 5 Minuten zwischengespeichert. Eine Zeichenkette, die mit einer Zahl beginnt, gilt als ID. Abteilung, Hilfethema, Mitarbeiter und SLA müssen als Zahl oder Zifferstring übergeben werden. Ein Name führt zu einem Fehler.

Das Schema verlangt number plus mindestens ein weiteres Feld, aber noteFormat hat einen Standardwert und zählt deshalb immer als gesetzt. Ein Aufruf nur mit number wird deshalb nicht abgelehnt und ändert nichts am Ticket.

Rückgabe: success, ticket (die Antwort von osTicket, laut Plugin-Dokumentation die Ticketnummer), bei Anhängen attachments und message.

osticket_delete_ticket

Das Löschen ist endgültig. Ticket und Thread verschwinden aus der Datenbank. Die Berechtigung can_delete_tickets ist im Plugin standardmäßig für jeden Key aus. Ein Wechsel auf einen geschlossenen Status mit osticket_update_ticket ist meist die bessere Wahl.

Rückgabe: success und message.

osticket_get_parent_ticket

Rückgabe: success, parent (mit ticket_id, number, subject, status, oder null ohne Elternticket) und message.

osticket_get_child_tickets

Rückgabe: success, children (Liste mit ticket_id, number, subject, status), total und message.

osticket_create_subticket_link

Macht ein bestehendes Ticket zum Kind eines anderen. Der Server sendet die Kindnummer als childId.

Rückgabe: success, parent, child und message. Das Plugin lehnt eine Verknüpfung mit sich selbst mit 400 ab, eine bestehende Verknüpfung oder ein Kind mit anderem Elternticket mit 422.

osticket_unlink_subticket

Rückgabe: success, child und message. Hat das Ticket kein Elternticket, antwortet das Plugin mit 404.

osticket_download_attachment

Lädt einen Anhang und speichert ihn im temporären Verzeichnis des Betriebssystems.

Rückgabe: success, filePath, filename, size und mime_type. Der Dateiname lautet <8 Hex-Zeichen>_<Dateiname>, wobei alle Zeichen außer Buchstaben, Ziffern, Punkt, Unterstrich und Bindestrich durch _ ersetzt werden. Der Server löscht die Datei nicht wieder. Die Antwort von osTicket enthält die Datei Base64-kodiert und darf höchstens 10 MB groß sein, daher scheitern Dateien ab etwa 7,5 MB.