📋 Analyse & Plan

Extension-Analyse & FAL-Tools Plan

TYPO3 MCP Server – Architektur verstehen, FAL-Feature planen
📁 Projekt: typo3-mcp-server 📄 Log: typo3-mcp1 💬 2 Austausche ⏱ ~25 Minuten
Legende:
Vorbildlich
Problematisch
Achtung / Hinweis
Lerntipp

📋 Hintergrund

Diese Session ist der Ausgangspunkt des gesamten FAL-Feature-Zweigs. Jens hat Copilot zunächst gebeten, die bestehende Extension vollständig zu analysieren – eine klassische Onboarding-Strategie für Copilot in einem neuen Projekt. Danach folgte sofort das erste Feature-Planning: ein Toolset, das der KI Zugang zu TYPO3-Storages, Ordnern und Datei-Metadaten gibt.

Plan-Modus von Anfang an. Beide Austausche fanden im Plan-Modus statt – Copilot hat ausschließlich analysiert und geplant, aber noch keinen Code geschrieben. Die Implementierung erfolgte in separaten Sessions (MCP3–MCP5).

💬 Session-Austausche

Austausch 1 — Extension-Analyse
Entwickler
analyze this extension
Sehr kurzer Prompt – aber hier okay. "analyze this extension" ist maximal vage. Copilot muss selbst entscheiden, was "analysieren" bedeutet. Das funktioniert nur, weil Copilot den geöffneten Workspace als Kontext hat. In einem generellen Chat ohne Dateikontext wäre dieser Prompt wertlos.
💡Analyse-First als Onboarding-Strategie. Vor dem ersten Feature-Prompt in einem unbekannten Projekt eine vollständige Analyse anzufragen ist eine gute Praxis. Copilot erstellt dabei implizit eine mentale Karte der Codebase, die alle Folge-Prompts präziser macht.
Copilot
I'll analyze the typo3-mcp-server extension by gathering comprehensive context about its structure, purpose, and implementation.

[liest ext_emconf.php, composer.json, README, Architecture-Docs, alle Tool-Klassen, Services.yaml, OAuth-Flow, Test-Struktur]

Plan: Comprehensive TYPO3 MCP Server Extension Analysis

Dieses TYPO3 Extension stellt einen MCP-Server bereit, der KI-Assistenten (Claude, ChatGPT etc.) sicheren Zugriff auf TYPO3-Inhalte ermöglicht. Kernarchitektur:

  • 9 MCP-Tools: GetPageTree, GetPage, ListTables, GetTableSchema, GetFlexFormSchema, ReadTable, Search, WriteTable
  • Dual-Transport: stdio (CLI) und HTTP (OAuth 2.0 mit PKCE)
  • Workspace-Transparenz: Custom Restriction + UID-Auflösung, damit KI nicht zwischen Live- und Workspace-UIDs unterscheiden muss
  • Dual-Test-Strategie: PHPUnit Functional Tests + echte LLM-Tests via OpenRouter API

Further Considerations: Extension ist als "beta" markiert. Fehlend: Fileadmin-Support, Workspace-Auswahl-UI.
Breite, strukturierte Analyse. Copilot liest nicht nur die Tool-Klassen, sondern auch Docs, OAuth-Service, Test-Struktur und ext_emconf.php. Das ist echtes Architektur-Verständnis, kein oberflächliches Dateilisten.
"Further Considerations" zeigen kritischen Blick. Copilot identifiziert eigenständig Lücken (kein Fileadmin-Support, beta-Status) – also genau die Features, die in den Folge-Sessions gebaut werden.
💡Plan-Modus produziert strukturierte Analysen. Im Plan-Modus erstellt Copilot einen formellen Plan mit Steps und Further Considerations. Das ist für Analyse-Aufgaben ideal – kein Overhead durch Tool-Aufrufe, klare Struktur.
Austausch 2 — FAL-Feature planen
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.
Vier Dimensionen im Prompt. (1) Was gebaut wird, (2) Architektur-Constraint ("integrates seamlessly"), (3) API-Constraint ("only official TYPO3 APIs"), (4) Nutzerperspektive ("the consuming AI shall be able to"). Das ist ein vollständiger Feature-Brief.
Typo ("codeing") stört nicht. Tippfehler im Prompt haben keinerlei Auswirkung auf die Qualität der Antwort – Copilot versteht den Kontext korrekt.
"The consuming AI" – wichtige Perspektive. Dieser Hinweis – dass die API von einer KI konsumiert wird, nicht von einem Menschen – ist subtil, aber wichtig. Er beeinflusst das Tool-Design: Datenstrukturen müssen KI-lesbar sein, nicht menschlich-ergonomisch.
Copilot
I'll create a comprehensive implementation plan for a new MCP tool that provides access to TYPO3 file storages, folders, and assets through official TYPO3 APIs.

[analysiert bestehende Tool-Klassen, Services.yaml, TableAccessService, RecordFormattingUtility, Test-Struktur]

Plan: TYPO3 FAL Integration for MCP Server

Drei neue read-only Tools über offizielle FAL-APIs (ResourceFactory, FileRepository, StorageRepository).

Steps:
1. FileAccessService – Singleton-Service, der FAL-APIs kapselt: getAccessibleStorages(), getFolder(), resolvePathToFolder(), canAccessFile()
2. ListStoragesTool – Listet browsbare Storages mit uid, name, driver, is_writable etc.
3. BrowseFolderTool – Navigiert Ordner/Dateien, akzeptiert storage+path, recursive-Flag
4. GetFileMetadataTool – Liest Basis-Properties + lokalisierte sys_file_metadata-Felder
5. FileFormattingUtility – Analg zu RecordFormattingUtility für Datei-Darstellung
6. Tests & Registrierung – Functional Tests, LLM-Integrationstest, Services.yaml

Further Considerations: Sicherheit (Pfad-Traversal), Performance (Limit-Parameter), Extended Metadata (EXIF, sys_file_reference).
Service Layer als Abstraktion. Copilot schlägt einen FileAccessService vor – analog zum bestehenden TableAccessService. Das zeigt, dass Copilot das Architektur-Pattern aus der Analyse erkannt und konsequent anwendet.
Sicherheit proaktiv berücksichtigt. Pfad-Traversal-Schutz und is_browsable-Prüfung werden in "Further Considerations" erwähnt – ohne dass der Prompt danach fragt. Das ist Production-Quality-Denken.
Plan weicht in Folge-Session ab. In Session MCP3 wird dieser Plan überarbeitet: BrowseFolderTool wird zu ListFilesTool, FileAccessService entfällt als separate Schicht. Der Plan hier ist ein guter erster Entwurf, nicht das finale Design.

🎯 Fazit

📋 Analyse-First als Projektstart-Strategie

Diese Session illustriert eine bewährte Copilot-Strategie für neue Projekte: Zuerst eine vollständige Extension-Analyse anfordern, dann erst Features planen. Copilot baut sich dabei eine interne Karte der Codebase auf – die Qualität aller Folge-Prompts profitiert davon.

Der FAL-Plan in Austausch 2 ist ein gutes Beispiel dafür, wie detaillierte Constraints ("TYPO3 coding guidelines", "official TYPO3 APIs", "consuming AI") die Antwort-Qualität prägen. Copilot spiegelt den Plan exakt in der Architektursprache der bestehenden Extension.

Wichtige Erkenntnis: Pläne aus dem Plan-Modus sind Entwürfe, keine finalen Specs. Der tatsächlich implementierte Plan (Session MCP3) ist schlanker und eleganter. Das ist normal – Planung ist iterativ.

🎓 Learnings

💡

5 Learnings aus Session MCP1

1

Analyse-First in neuen Projekten

Vor dem ersten Feature-Prompt eine vollständige Codebase-Analyse anzufragen ("analyze this extension") ist eine effektive Onboarding-Strategie. Copilot versteht danach Architektur-Patterns, Namespace-Konventionen und Teststrategien – und wendet sie in Folge-Prompts automatisch an.

2

Vier Dimensionen im Feature-Brief

Ein vollständiger Feature-Prompt enthält: (1) Was gebaut wird, (2) Architektur-Constraints, (3) API/technische Constraints, (4) die Nutzerperspektive. Alle vier Dimensionen sind im Prompt "I need a new tool that..." enthalten – das ist warum Copilot einen so präzisen Plan liefert.

3

"The consuming AI" – Nutzerperspektive ist Design-Constraint

Der Hinweis, dass die Toolset-API von einer KI konsumiert wird, ist kein Marketing-Sprech. Er beeinflusst konkret das Interface-Design: Welche Felder werden zurückgegeben? Wie werden sie formatiert? Copilot berücksichtigt diesen Kontext bei Feldauswahl und Textformatierung.

4

Pläne sind Entwürfe – Iteration ist normal

Der hier erstellte Plan (mit FileAccessService, BrowseFolderTool, FileFormattingUtility) weicht vom tatsächlich implementierten Design ab. Das ist kein Fehler. Erste Pläne sind zu komplex, Implementierungen sind oft schlanker. Plan-Iteration ist Teil des Prozesses.

5

Further Considerations = unausgesprochene Anforderungen

Copilots "Further Considerations" in Plänen enthalten oft wichtige unausgesprochene Anforderungen: Sicherheit (Pfad-Traversal), Performance (Paginierung), Erweiterbarkeit (EXIF, sys_file_reference). Diese sollte man aktiv lesen und entscheiden, welche davon in den Scope aufgenommen werden.

📊 Session-Qualität im Überblick

ElementQualitätAnmerkung
Austausch 1 – Prompt⚠ AusreichendSehr kurz ("analyze this extension") – funktioniert nur mit Workspace-Kontext
Austausch 1 – Antwort✓ Sehr gutBreite Analyse: Tools, Auth, Workspace-Transparenz, Tests, Beta-Status
Austausch 2 – Prompt✓ Sehr gutVier Dimensionen: Was, Architektur, API, Nutzerperspektive
Austausch 2 – Antwort✓ GutKonsistenter Service-Layer-Ansatz, gute Sicherheits-Überlegungen – aber Plan wird in MCP3 überarbeitet

🔗 Weitere Walk-Throughs