Verfügbare Tools

Der TYPO3 AI Suite MCP Server stellt derzeit 45 Tools bereit. Jedes Tool gehört zu genau einem OAuth-Scope, und ein Scope wird nur gewährt, wenn die Backend-Gruppe des Benutzers das passende AI Suite-Feature-Recht besitzt (siehe Berechtigungen & Scopes). Die Tool-Liste, die ein Model zu sehen bekommt, ist deshalb pro Benutzer unterschiedlich. Fehlt ein Recht, taucht das betroffene Tool gar nicht auf.

Die folgende Übersicht ist nach Scopes gruppiert und nennt zu jedem Tool kurz seinen Zweck. Die vollständigen Parameter liefert jeder Client selbst, weil sie als JSON-Schema Teil der Tool-Definition sind. Welche Tools eine konkrete Installation tatsächlich ausliefert, verrät readServerInfo.

Seit Version 0.7.0 liefert jeder Aufruf, der Datensätze berührt hat, die betroffenen Datensätze zusätzlich als Backend-Links zurück. Sie kommen über zwei Wege: als structuredContent.links für Clients, die Links selbst darstellen, und als Textblock „⚙ Open in TYPO3“ am Ende des Ergebnisses, wodurch sie im Chat anklickbar werden. Als Beschriftung dient der Titel des Datensatzes, sofern er einen hat.

Die Links sind nach Tabelle gruppiert, weil eine Seite und die Inhaltselemente darauf unterschiedliche Ziele sind. pages steht vorn, danach folgen die übrigen Tabellen in der Reihenfolge, in der sie berührt wurden. Die Obergrenze von sechs Links gilt pro Gruppe, damit eine geschriebene Seite nicht von den Inhaltselementen verdrängt wird, die auf ihr angelegt wurden. Das Feld omitted nennt je Gruppe, wie viele Links die Obergrenze weggelassen hat, sodass eine gekürzte Gruppe nicht mit einer vollständigen verwechselt werden kann.

Die Adressen sind absolut und enthalten bewusst keinen Route-Token. Ein Token gehört zu der Sitzung, die ihn erzeugt hat, also zur MCP-Sitzung und nicht zum Browser der Redaktion. In einem Link, der den Prozess verlässt, wäre er wertlos. TYPO3 beantwortet eine Backend-Adresse ohne Token mit einer Weiterleitung über den Login, die das ursprüngliche Ziel mitführt. Wer im Backend angemeldet ist, landet also direkt auf dem Datensatz.

Woher Schema und Host stammen, entscheidet sich in dieser Reihenfolge: zuerst die Einstellung mcpBackendBaseUrl, dann die aktuelle Anfrage, zuletzt die Site-Konfiguration. Ergibt keine davon eine vollständige Adresse, etwa beim stdio-Transport ohne konfigurierte Site, lässt die AI Suite MCP den Link weg statt ihn defekt auszugeben, und vermerkt das in aisuite_mcp_warnings.log.

Diese Tools lesen nur. Sie kosten keine Credits und rufen kein KI-Model auf.

Die erkundenden Tools dieser Gruppe gehören zu mcp:read, die schreibenden zu mcp:write. Alle Schreibvorgänge laufen über den DataHandler und damit über die üblichen TYPO3-Prüfungen, und sie folgen dem eingestellten Schreibmodus.

Seit Version 0.7.0 kann ein Eintrag in writeRecords neben fields ein Objekt translations tragen, dessen Schlüssel die ISO-Sprachkürzel sind. Damit entstehen der Datensatz und seine Übersetzungen in einem Aufruf.

{
  "records": [{
    "table": "tt_content",
    "pid": 354,
    "fields": { "CType": "text", "header": "Einstellungen" },
    "translations": { "en": { "header": "Settings" } }
  }]
}

Die Übersetzungshülle entsteht über TYPO3s eigenen localize-Befehl, also denselben Weg, den auch das Backend nimmt. Sprachfeld, Übersetzungs-Elternteil, l10n_source, l10n_state, ausgeschlossene Felder und vorhandene Inline-Kinder übernimmt damit der TYPO3-Kern. Anschließend werden die angegebenen Felder in diese Hülle geschrieben. Angelegt wird sie versteckt, genau wie TYPO3 es tut.

Derselbe Aufruf ein zweites Mal abgesetzt aktualisiert die vorhandene Übersetzung, statt eine zweite anzulegen. Ein Batch nach einem Teilfehler erneut zu senden ist also unbedenklich. translations funktioniert auch bei einem Eintrag mit uid, dann gilt dieser Datensatz als Ausgangspunkt. Verschachtelte Inline-Kinder lassen sich im selben Aufruf nicht übersetzen. Schreibe sie zuerst und übersetze sie danach über ihre UID.

Bei Übersetzungen kollidieren zwei Schreibweisen aus der TYPO3-Geschichte. tt_content hat das alte l18n_parent behalten, während pages und die meisten selbst geschriebenen Kindtabellen l10n_parent verwenden. Seit Version 0.7.0 akzeptiert die AI Suite MCP beim Lesen und beim Schreiben beide Varianten und bildet sie auf den Namen ab, den die Tabelle tatsächlich führt. Dasselbe gilt für l10n_source und l18n_source. Das Ergebnis vermerkt, wenn eine solche Umbenennung stattgefunden hat. Ein Feldname, den die Tabelle wirklich besitzt, wird nie umgeschrieben.

Diese Tools rufen die Anbieter und Models der AI Suite auf und verbrauchen dann Credits. Welche Models zur Verfügung stehen, ergibt sich aus der AI Suite-Konfiguration und den Modelrechten der Backend-Gruppe. In AI Suite MCP ist dafür keine zusätzliche Einstellung nötig.

Sie sind damit die einzigen Tools, die einen gültigen API-Key der AI Suite voraussetzen. Fehlt er oder deckt das Lizenzpaket die Funktion nicht ab, bleiben die Tools in der Tool-Liste stehen und werden vom Model auch aufgerufen. Der Aufruf endet dann mit einem Lizenzfehler. Das unterscheidet sie von den Feature-Rechten der Backend-Gruppe, die ein Tool bereits aus der Liste entfernen.

Seit Version 0.7.0 gilt das für translateRecord und translatePage nur noch dann, wenn du den optionalen Parameter model angibst. Lässt du ihn weg, legt das Tool den Übersetzungs-Datensatz an und gibt dir dessen Felder zurück, zusammen mit dem Glossar der Site und den globalen Anweisungen. Übersetzt wird dann vom Model deines Clients, es geht nichts an den AI Suite Server und es kostet keine Credits. Die Antwort nennt außerdem die Models, die dir zur Verfügung stehen, falls du doch serverseitig übersetzen willst. Kommen Felder unverändert zurück, weist das Ergebnis darauf hin, damit eine ausgebliebene Übersetzung nicht unbemerkt bleibt.

Zu unterscheiden ist das von localizeRecord unter mcp:write. Jenes legt nur die leere Übersetzungshülle an. translateRecord ohne model legt die Hülle an und reicht dir zusätzlich die zu übersetzenden Feldinhalte heraus.

Bei translateFileMetadata und den Batch-Tools gibt es diesen Weg nicht. Ohne model liefern sie lediglich die Liste der verfügbaren Models zurück, die eigentliche Übersetzung läuft dort immer über den Server und kostet Credits.

Leichte Sprache und das DeepL-Glossar der Site sind kein eigenes Tool, sondern Bestandteil der Übersetzungs-Tools. Das Glossar wird automatisch angewendet.

Dieses Tool bringt vorhandene Dateien in die Dateiverwaltung, ohne ein KI-Model zu bemühen. Es kostet keine Credits und funktioniert auch ohne gültigen API-Key der AI Suite. Es hängt an einem eigenen Scope und einem eigenen Feature-Recht, beide standardmäßig aus, weil es als einziges Tool neben generateImage eine physische Datei anlegt und deshalb nicht über einen Workspace zurückgenommen werden kann.

Nicht zu verwechseln mit copyMediaReference und replaceMediaReference. Die beiden hängen keine neue Datei ein, sondern setzen bestehende Dateireferenzen um, gehören deshalb zu mcp:write und stehen in der Datensatz-Gruppe. Zu Zielordner, Größengrenze, erlaubten Dateiendungen und der Absicherung entfernter Downloads siehe Sicherheit & Betrieb.

Batch-Tools laufen asynchron. Sie liefern sofort eine Task-ID zurück, der Fortschritt wird mit readTaskStatus abgefragt und die Ergebnisse mit readTaskResults gelesen. Geschrieben wird nichts davon automatisch. Ein Batch-Prozess erzeugt Vorschläge, und erst applyTaskResults schreibt sie in die Datensätze.

batchGenerateMetadata nimmt seine Ziele auf genau einem von zwei Wegen. Entweder pageIds als ausdrückliche UID-Liste oder rootPageId als Seite samt allem darunter. Beides zusammen ist ein Fehler, nichts davon ebenfalls. recursive entscheidet, ob ein rootPageId den ganzen Teilbaum durchläuft oder bei den direkten Kindern stehen bleibt. Die Wurzelseite ist immer dabei.

Seit Version 0.8.0 stellt der Server sieben Tools rund um Audits bereit. Gegenüber TYPO3 lesen sie nur, sie geben aber die Seiten-URL und damit den Seiteninhalt an die AutoDudes-Audit-Infrastruktur weiter. Deshalb hängen alle sieben zusätzlich an der eigenen Berechtigung enable_audit, siehe Berechtigungen & Scopes.

Die sechs prüfenden Tools erwarten in url eine absolute, öffentlich erreichbare http(s)-Adresse. TYPO3-interne Links wie t3://page?uid=1 lassen sich nicht auditieren, die öffentliche URL muss vorher aufgelöst werden. Ein keyword ist auf 200 Zeichen begrenzt.

Die vier Analyse-Tools auditQuestions, auditContentGap, auditTopicCluster und auditCompetitors nehmen darüber hinaus drei gemeinsame Parameter:

readAuditResults arbeitet stattdessen über pageId, optional eingegrenzt mit auditType und language. Gespeicherte Ergebnisse liegen je Sprache getrennt.