Session MCP3 – FAL-Lese-Tools implementieren

Legende:

Vorbildlich

Problematisch

Achtung / Hinweis

Lerntipp

📋 Hintergrund

Diese Session ist die Implementierungs-Session der FAL-Lese-Tools. Der Feature-Brief ist identisch mit Session MCP1, aber jetzt im Agent-Modus: Copilot schlägt zunächst einen verfeinerten Plan vor (schlanker als MCP1, kein separater FileAccessService, BrowseFolderTool umbenannt zu ListFilesTool), und implementiert dann auf Abruf alle drei Tools inklusive Tests, CSV-Fixtures und Dokumentations-Update.

✓

Was diese Session besonders macht: Copilot entdeckt während der Implementierung, dass getDescription() nicht als Methode existiert und weicht auf getStorageRecord() aus – eigenständige API-Verifikation ohne menschliche Intervention.

💬 Session-Austausche

Austausch 1 — Plan (verfeinert)

Entwickler

I need a new tool that give access to the assets and metadata of TYPO3 storages and folders. make an implementation plan of this feature that follows TYPO3 coding guidelines and best practices and integrates seamlessly into the current extension architecture. Only use official TYPO3 APIs that respect user permissions, no direct access to the filesystem or database. the consuming AI shall be able to navigate through storages and folders, list assets and read their localized metadata.

✓Selber Prompt, andere Session – anderes Ergebnis. Der identische Prompt aus MCP1 liefert hier einen anderen, schlankeren Plan. Copilot analysiert die aktuelle Codebase neu und entwickelt einen einfacheren Ansatz ohne überflüssige Service-Schicht.

💡Prompts sind nicht deterministisch. Der gleiche Prompt kann in verschiedenen Sessions unterschiedliche (und unterschiedlich gute) Pläne produzieren. Erste Pläne sind Entwürfe, nicht finale Specs.

Copilot

Ich beginne mit der Recherche der bestehenden Architektur, um einen fundierten Plan erstellen zu können.

[analysiert AbstractTool, GetPageTreeTool, ListTablesToolTest, Services.yaml, bestehende Test-Fixtures]

Plan: FAL Storage & File Metadata MCP Tools

Drei neue read-only Tools, die ausschließlich offizielle TYPO3-FAL-APIs nutzen:

Steps:
1. ListStoragesTool – StorageRepository::findAll() gefiltert auf browsbare Storages; gibt uid, name, description, driver, isOnline, isWritable zurück
2. ListFilesTool – akzeptiert storageUid + folderPath; nutzt $storage→getFolder() → getSubfolders() + getFiles(); paginiert über limit/offset
3. GetFileMetadataTool – akzeptiert fileUid oder Combined-Identifier; liefert Basis-Properties + lokalisierte sys_file_metadata-Felder via language-ISO-Parameter
4. Registrierung – Keine manuelle Services.yaml-Anpassung nötig (AutoconfigureTag)
5. Tests – 3 Testklassen mit CSV-Fixtures für sys_file_storage, sys_file, sys_file_metadata
6. TECHNICAL_OVERVIEW.md aktualisieren

Further Considerations: Combined-Identifier-Support, Kategorie-Auflösung, rekursives Listing nur auf Abruf.

✓Schlanker als MCP1-Plan. Kein separater FileAccessService, kein FileFormattingUtility. Copilot erkennt, dass die FAL-APIs direkt in den Tools verwendbar sind – konsistent mit dem Stil der bestehenden Record-Tools.

✓Limit/Offset-Paginierung von Anfang an. Copilot plant die Paginierung in ListFilesTool ohne explizite Aufforderung – aus der "Further Considerations" der Analyse in MCP1 gelernt.

✓Docs-Update im Plan. TECHNICAL_OVERVIEW.md-Update als expliziter Plan-Schritt. Dokumentation als Teil der Implementierung, nicht als Nachschritt.

Austausch 2 — Implementierung

Entwickler

Start implementation

✓Minimaler Implementierungs-Trigger. "Start implementation" – zwei Wörter genügen. Der Plan-Kontext aus Austausch 1 ist noch aktiv. Copilot weiß genau, was zu tun ist.

Copilot

Ich starte die Implementierung der drei neuen FAL-Tools. Zuerst lese ich noch einige existierende Dateien, um die Patterns genau zu treffen.

[liest GetPageTreeTool, ListTablesToolTest als Pattern-Referenz, sys_file_storage.csv-Fixture]

Schritt 1: ListStoragesTool.php
[erstellt Classes/MCP/Tool/File/ListStoragesTool.php]
Problem: getDescription() existiert nicht als Methode auf ResourceStorage → Verwende getStorageRecord()['description'] stattdessen.

Schritt 2: ListFilesTool.php
[erstellt Classes/MCP/Tool/File/ListFilesTool.php]
Verifikation: getFiles($start, $numberOfItems) – Parameter-Reihenfolge und Rückgabe-Typ (assoziatives File[]-Array) via ResourceStorage-Quellcode bestätigt. ✓

Schritt 3: GetFileMetadataTool.php
[analysiert MetaDataRepository-API, prüft ob getType() int oder Enum zurückgibt]
Ergebnis: getType() gibt bereits int zurück ($this->getFileType()->value) – keine Enum-Konvertierung nötig.
[erstellt Classes/MCP/Tool/File/GetFileMetadataTool.php]

Schritt 4: CSV-Fixtures erstellen
[erstellt sys_file_storage.csv, sys_file.csv, sys_file_metadata.csv]
Konsistenz-Check: sys_file.csv zeigt identifier=/test.jpg mit storage=1, Tests erstellen physische Datei unter fileadmin/test.jpg. ✓

Schritt 5: 3 Test-Dateien erstellen
[erstellt ListStoragesToolTest.php, ListFilesToolTest.php, GetFileMetadataToolTest.php]

Schritt 6: TECHNICAL_OVERVIEW.md aktualisieren
[ergänzt "File & Asset Discovery" Abschnitt]

Syntaxprüfung: RC=0 auf allen neuen Dateien. IDE-Warnungen sind nur fehlende dev-Abhängigkeit typo3/testing-framework – kein echter Fehler, identisch mit bestehenden Tests.

✓API-Verifikation in Echtzeit. Copilot liest den ResourceStorage-Quellcode, um zu prüfen ob getDescription() existiert (tut es nicht) und ob getType() int oder Enum zurückgibt (int). Das verhindert Laufzeitfehler.

✓Fixture-Konsistenz-Check. Copilot prüft aktiv, ob der Datei-Identifier in der CSV (/test.jpg) mit dem physischen Pfad übereinstimmt, den der Test anlegt (fileadmin/test.jpg). Das ist präventive Testqualitätssicherung.

⚠Terminal-Ausgabe fehlt. Copilot kann den Syntaxcheck-Output nicht lesen (Terminal liefert keine Ausgabe) und fällt auf direktes Lesen der Dateien zurück. Funktioniert, ist aber ein Zeichen, dass das Terminal-Tool in dieser PhpStorm-Session instabil ist.

✓Alle 6 Plan-Schritte abgearbeitet. Copilot hält sich exakt an den Plan aus Austausch 1 – inklusive Docs-Update. Kein Schritt vergessen.

🎯 Fazit

✓ Schlanke Architektur durch iterative Planung

Der Plan in dieser Session ist merklich schlanker als der erste Entwurf in MCP1: kein separater FileAccessService, direktere API-Nutzung in den Tools. Das ist ein Beispiel dafür, dass zweite Pläne oft besser sind als erste – Copilot hatte mehr Kontext durch die Analyse in MCP1.

Die eigenständige API-Verifikation während der Implementierung (Prüfen ob getDescription() existiert, ob getType() int oder Enum zurückgibt) ist ein Qualitätsmerkmal. Copilot halluziniert keine API-Methoden, sondern liest den Source-Code der TYPO3-Klassen.

Das instabile Terminal ist das einzige Problem dieser Session – es erzwingt einen Workaround (Dateien direkt lesen statt Syntaxcheck-Output), der funktioniert aber langsamer ist.

🎓 Learnings

💡

5 Learnings aus Session MCP3

Zweite Pläne sind oft besser

Der Plan in MCP3 ist schlanker als in MCP1 – kein überflüssiger Service-Layer. Das liegt daran, dass Copilot in MCP1 mehr Pattern-Referenzen hatte. Wenn ein erster Plan zu komplex erscheint, lohnt es sich, ihn in einer neuen Session mit mehr Kontext zu wiederholen.

API-Verifikation vor der Implementierung

Copilot liest TYPO3-Kernklassen (ResourceStorage, MetaDataRepository), um API-Signaturen zu verifizieren, bevor es Code schreibt. Dieser Schritt verhindert häufige Fehler wie "Methode existiert nicht" oder "falscher Rückgabe-Typ". Bei fremden Bibliotheken sollte man Copilot explizit bitten, die API vorher zu prüfen.

Fixture-Konsistenz ist kritisch für Tests

Copilot prüft, ob der FAL-Identifier in der CSV-Fixture (/test.jpg) mit dem physisch angelegten Pfad im Test übereinstimmt (fileadmin/test.jpg). Fehler in Fixture-Konsistenz sind häufige Ursachen für mysteriöse Test-Failures – diese proaktive Prüfung verhindert sie.

Dokumentation als Plan-Schritt, nicht als Nachschritt

Das Update der TECHNICAL_OVERVIEW.md ist als expliziter Plan-Schritt 6 enthalten und wird konsequent ausgeführt. Dokumentation, die als Nachschritt geplant wird, bleibt oft aus. Als Plan-Schritt wird sie als Teil der Implementierung behandelt.

Instabiles Terminal – Workaround kennen

Wenn das Terminal in PhpStorm keine Ausgabe liefert (ein bekanntes Problem), kann Copilot Syntaxfehler nicht per php -l prüfen. Der Workaround: Copilot liest die erstellten Dateien nochmals direkt und prüft sie visuell. Langsamer, aber zuverlässig.

📊 Session-Qualität im Überblick

Element	Qualität	Anmerkung
Austausch 1 – Prompt	✓ Sehr gut	Vollständiger Feature-Brief mit 4 Dimensionen (identisch MCP1, aber jetzt im Agent-Modus)
Austausch 1 – Antwort	✓ Exzellent	Schlanker Plan ohne überflüssige Abstraktionsschichten, Paginierung eingeplant, Docs-Update als Schritt
Austausch 2 – Prompt	✓ Gut	"Start implementation" – minimaler Trigger, Plan-Kontext ausreichend
Austausch 2 – Antwort	✓ Exzellent	API-Verifikation, Fixture-Konsistenz-Check, alle 6 Plan-Schritte, Docs-Update, eigenständiger Workaround für Terminal-Problem

🔗 Weitere Walk-Throughs

→ Extension-Analyse & FAL-Plan → MCP Tool implementieren → FileReference-Support WriteTable → UploadFile & SetFileMetadata