✓ Gutes Beispiel

Neues MCP Tool implementieren

TYPO3 FAL API – CreateFolderTool mit Plan-First-Ansatz
📁 Projekt: typo3-mcp-server 📄 Log: new mcp tool folders 💬 3 Austausche ⏱ ~20 Minuten
Legende:
Vorbildlich
Problematisch
Achtung / Hinweis
Lerntipp

📋 Hintergrund

In einem TYPO3 MCP Server-Projekt soll ein neues Tool hinzugefügt werden, das Ordner in TYPO3-File-Storages erstellt. Die Besonderheit: Das Tool muss ausschließlich offizielle TYPO3-FAL-APIs verwenden (kein direkter Filesystem- oder Datenbankzugriff) und sich nahtlos in die bestehende Extension-Architektur einfügen. Die Session zeigt das Plan-First-Muster: Copilot analysiert zuerst die Architektur, erstellt einen detaillierten Plan – und implementiert dann autonom inklusive Tests.

ℹ

Besonderheit dieser Session: Der erste "start the implementation"-Prompt scheiterte, weil Copilot sich im Plan-Modus befand und keine Write-Tools hatte. Der zweite Versuch (nach Moduswechsel) war erfolgreich: 10 Tests, 28 Assertions – alles grün.

💬 Session-Austausche

Austausch 1 — Plan erstellen
Entwickler
I need a new tool that allows to create folders in 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.
✓Drei Constraints explizit genannt. "TYPO3 coding guidelines", "integrates seamlessly into current architecture", "only official TYPO3 APIs" – diese drei Einschränkungen verhindern, dass Copilot eine schnelle aber architektur-fremde Lösung liefert.
✓"Make an implementation plan" – Plan First. Statt sofort zu implementieren, wird zuerst ein Plan angefordert. Das gibt die Chance, den Ansatz zu prüfen und zu korrigieren, bevor Code geschrieben wird.
💡Englisch in technischen Projekten. Bei Code-nahen Aufgaben ist Englisch sinnvoll: Klassen-, Methoden- und API-Namen stimmen mit dem Prompt überein, Copilot "denkt" in der Sprache der Codebase.
Copilot
Ich werde zunächst die bestehende Architektur analysieren, um einen fundierten Implementierungsplan zu erstellen.

[analysiert ListFilesTool, ListStoragesTool, AbstractTool, Services.yaml, Teststruktur]

Plan: CreateFolder MCP Tool

Ein neues CreateFolderTool im File/-Namespace, das über die offizielle TYPO3 FAL Storage-API Ordner erstellt. Folgt exakt dem Muster der bestehenden File-Tools und nutzt ResourceStorage::createFolder().

Steps:
1. CreateFolderTool.php – Validierung, ResourceFactory, hasFolderInFolder()-Check, createFolder(), Exception-Handling
2. CreateFolderToolTest.php – 7 Test-Cases: Erfolg, Sub-Folder, Idempotenz, Invalid storageUid, leerer Name, unbekannter Parent, nicht-schreibbarer Storage

Further Considerations: Keine Änderung an Services.yaml nötig (autoconfigure: true + AutoconfigureTag).
✓Architektur-Analyse vor dem Plan. Copilot liest ListFilesTool, AbstractTool und die Teststruktur, bevor er einen Plan erstellt. So bleibt der Plan konsistent mit dem bestehenden Code.
✓Autoconfigure-Hinweis. Copilot erkennt selbstständig, dass durch autoconfigure: true kein manueller Services.yaml-Eintrag nötig ist. Das zeigt tiefes TYPO3-Symfony-Verständnis.
✓Idempotenz im Plan berücksichtigt. "Bereits existierender Ordner gibt kein Fehler, sondern Info-Nachricht" – das ist eine Production-Quality-Entscheidung, die Copilot aus dem Architektur-Kontext ableitet.
Austausch 2 — Implementierungsversuch (falscher Modus)
✗

Plan-Modus vs. Agent-Modus: Dieser Austausch scheiterte, weil der Chat noch im Plan-Modus war. Copilot hatte keine Write-Tools und musste den Code als Textblöcke ausgeben. Lösung: In den Agent-Modus wechseln.

Entwickler
start the implementation – don't use a recursive parameter but create recursive folders when the user sends a foldername containing /
✓Kluge API-Design-Entscheidung. "Kein expliziter recursive-Parameter, aber automatische Rekursion bei Slash im Namen" – das macht die API einfacher zu benutzen und vermeidet unnötige Parameterflut.
✗Falscher Chat-Modus. Der Prompt wurde im Plan-Modus abgesetzt. Copilot hatte dort keine Write-Tools und konnte nur Code-Blöcke ausgeben. Für Implementierungen immer den Agent-Modus nutzen.
Copilot
Leider habe ich kein Dateierstellungs-Tool zur Verfügung. Im Plan-Modus wurde bereits ein Plan erstellt – jetzt soll ich implementieren, aber ich habe nur Lese- und Suchwerkzeuge verfügbar. Lassen Sie mich die Dateien als Code-Blöcke bereitstellen, die Sie erstellen müssen.

[gibt vollständigen PHP-Code für CreateFolderTool.php als Textblock aus]
⚠Ehrliche Fehlermeldung. Copilot erklärt transparent, dass er keine Write-Tools hat, statt zu halluzinieren oder eine fehlerhafte Implementierung vorzutäuschen. Das ist korrekt – aber unbequem.
💡Plan-Modus = nur Analyse und Planung. In PhpStorm: Chat-Panel → oben rechts Modus-Dropdown → "Agent" wählen, damit Copilot tatsächlich schreiben kann.
Austausch 3 — Implementierung (korrekter Modus)
Entwickler
start the implementation – don't use a recursive parameter but create recursive folders when the user sends a foldername containing /
✓Identischer Prompt, neuer Modus. Nach dem Wechsel in den Agent-Modus reicht der gleiche Prompt. Kein Umbau nötig. Copilot hat den Plan noch im Kontext.
Copilot
Ich starte die Implementierung. Ich habe bereits den gesamten nötigen Kontext aus der vorherigen Analyse. Ich erstelle jetzt das Tool und den Functional Test.

[erstellt CreateFolderTool.php mit rekursiver Slash-Logik]
[erstellt CreateFolderToolTest.php mit 10 Test-Cases]
[führt Syntax-Check aus: keine Fehler]
[führt Functional Tests aus]

Alle 10 Tests bestanden mit 28 Assertions.

Neue Dateien:
– Classes/MCP/Tool/File/CreateFolderTool.php: Rekursive Ordner-Erstellung bei Slash, Idempotenz, Pfad-Traversal-Schutz, Race-Condition-sicher
– Tests/Functional/MCP/Tool/CreateFolderToolTest.php: 10 Tests inkl. verschachtelte Pfade, ungültige Eingaben, Berechtigungsprüfung
✓Plan-Kontext bleibt erhalten. Copilot nutzt die Architektur-Analyse aus Austausch 1, ohne alles neu zu analysieren. Der Plan-First-Ansatz zahlt sich hier aus.
✓Tests direkt miterstellt und ausgeführt. Copilot erstellt nicht nur das Tool, sondern auch den Functional Test und führt ihn direkt aus. 10 Tests, 28 Assertions – das ist eigenständige Qualitätssicherung.
✓Production-Quality-Details. Race-Condition-Schutz (ExistingTargetFolderException), Pfad-Traversal-Prüfung (..), Idempotenz – alle diese Details kamen aus dem Plan und wurden korrekt implementiert.
💡Autoconfigure spart Services.yaml-Einträge. Dank #[AutoconfigureTag('mcp.tool')] auf dem Interface wird das neue Tool automatisch registriert. Copilot hat das im Plan erkannt und keinen manuellen Eintrag erstellt.

🎯 Fazit

✓ Plan-First als Qualitätsstrategie

Diese Session zeigt, warum der Plan-First-Ansatz bei komplexen Features so wertvoll ist. Copilot analysiert zuerst die bestehende Architektur und entwickelt daraus einen Plan, der von Anfang an passt: richtiger Namespace, richtiges Basis-Interface, gleiche Teststrategie, kein überflüssiger Services.yaml-Eintrag.

Der Zwischenfall mit dem falschen Modus ist ein typisches PhpStorm-Copilot-Problem: Plan-Modus und Agent-Modus haben unterschiedliche Tool-Sets. Für Implementierungen ist der Agent-Modus zwingend erforderlich. Der gleiche Prompt funktioniert im richtigen Modus einwandfrei.

Das Ergebnis: 10 Functional Tests, 28 Assertions, alle grün – ohne dass der Entwickler eine einzige Zeile manuell angepasst hat. Das ist das Optimum für Feature-Entwicklung mit Copilot.

🎓 Learnings

💡

6 Learnings aus Session E

1

Plan First – besonders bei Architektur-Constraints

Wenn ein Feature bestehende Architektur-Konventionen einhalten muss, zuerst einen Plan anfragen. Copilot analysiert die bestehenden Patterns (AbstractTool, Namespace, Test-Fixtures) und liefert einen Plan, der von Anfang an kompatibel ist.

2

Constraints explizit nennen – nicht annehmen

"Only use official TYPO3 APIs that respect user permissions" ist nicht selbstverständlich. Ohne diesen Hinweis hätte Copilot möglicherweise mkdir() oder direkte Datenbankabfragen verwendet. Constraints gehören in den ersten Prompt.

3

Plan-Modus ≠ Agent-Modus

In PhpStorm hat jeder Chat-Modus andere Tools. Plan-Modus: nur Lesen und Analysieren. Agent-Modus: Lesen, Schreiben, Ausführen. Implementierungsaufgaben immer im Agent-Modus starten.

4

API-Design-Entscheidungen im Prompt treffen

"Don't use a recursive parameter but create recursive folders when the user sends a foldername containing /" – das ist eine Design-Entscheidung, die im Prompt getroffen wurde. Copilot setzt sie 1:1 um. Je klarer das gewünschte Verhalten, desto weniger Nacharbeit.

5

Symfony-Autoconfigure kennen und nutzen

TYPO3 12+ nutzt Symfony Dependency Injection mit autoconfigure: true. Neue Tools werden durch Tags automatisch registriert. Copilot kennt dieses Muster – man muss nur sicherstellen, dass er die bestehende Services.yaml analysiert hat.

6

Tests gehören zur Implementierung – nicht danach

Copilot erstellt Functional Tests zusammen mit dem Tool, nicht als Nachschritt. Das ist richtig: Wer Tests nach der Implementierung schreibt, schreibt Tests, die bestehende Bugs mitdokumentieren. Immer "create tool AND test" fordern.

📊 Session-Qualität im Überblick

ElementQualitätAnmerkung
Austausch 1 – Prompt✓ Sehr gutPlan-First, drei explizite Constraints, Architektur-Konformität gefordert
Austausch 1 – Antwort✓ Sehr gutArchitektur-Analyse vor Plan, Autoconfigure-Detail erkannt, 7 Test-Cases geplant
Austausch 2 – Prompt✓ Sehr gutKluge API-Design-Entscheidung (Slash statt recursive-Parameter)
Austausch 2 – Antwort⚠ EinschränkungKorrekt transparent – aber kein Ergebnis wegen Plan-Modus-Limitation
Austausch 3 – Prompt✓ Sehr gutIdentischer Prompt, richtiger Modus – funktioniert sofort
Austausch 3 – Antwort✓ ExzellentVollständige Implementierung, Tests ausgeführt, 10/10 grün, Production-Quality-Details

🔗 Weitere Walk-Throughs