Architecture Decision Record · 0011

`mcp_server` behalten und `mcp_tools` selektiv portieren

TL;DR — drupal/mcp_server bleibt der lokale MCP-Server; drupal/mcp_tools wird nicht installiert, sondern nur als Referenz für selektives Porting in solcom_mcp_tools genutzt. SDK-Inkompatibilität erzwingt diese Trennung.

Kontext

ADR-0010 etablierte drupal/mcp_server als lokales Dev-only-Tooling für STDIO-MCP-Zugriff aus Claude-Clients auf Drupal. Ein Zwischenstand dieses ADRs wollte drupal/mcp_server vollständig durch drupal/mcp_tools ersetzen, weil mcp_tools eine deutlich breitere Out-of-the-box-Tool-Surface mitbringt.

Diese Richtung wurde nach erneuter Implementierung verworfen. Der lokale Stack erzwingt jetzt wieder drupal/mcp_server:2.x-dev mit mcp/sdk:^0.5.0, mcp_server_tool_bridge und den SOLCOM-eigenen drupal/tool-Plugins in solcom_mcp_tools. Die SDK-0.5-Inkompatibilität des aktuellen mcp_server-Heads wird lokal im Custom-Modul über einen kleinen Compatibility-Layer und eine SDK-0.5-kompatible Server-Factory abgefangen.

drupal/mcp_tools bleibt fachlich wichtig: Es ist das „batteries-included" Referenzprojekt für Drupal-MCP-Tooling mit Tool-Slices für Analysis, Batch, Blocks, Cache, Config, Content, Cron, Image Styles, Layout Builder, Media, Menus, Metatag, Migration, Moderation, Pathauto, Recipes, Redirect, Scheduler, Search API, Structure, Templates, Theme, Users, Views und Webform. Direkt installieren lässt es sich im aktuellen Stack nicht sauber, weil mcp_tools mcp/sdk:^0.2.2 verlangt, während mcp_server mcp/sdk:^0.5.0 nutzt.

Entscheidung

drupal/mcp_server bleibt der lokale MCP-Server; drupal/mcp_tools wird nicht installiert, sondern als Referenz für selektives Porting in solcom_mcp_tools genutzt. Konkret:

drupal/mcp_server, mcp_server_ui, mcp_server_tool_bridge und solcom_mcp_tools bleiben im dev-Config-Split.
drupal/tool bleibt als generische Plugin-Plattform im Default-Sync aktiv.
solcom_mcp_tools stellt die SOLCOM- und Drupal-Read-Tools als drupal/tool-Plugins bereit; mcp_server_tool_bridge exponiert sie als MCP-Tools.
drupal/mcp_tools wird außerhalb des Repo als Ideengeber inspiziert. Tool-Ideen, Input-/Output-Formen und kleine Implementierungsdetails dürfen selektiv nachgebaut oder adaptiert werden, aber ohne die mcp_tools-Runtime als Dependency einzuführen.
Übernommener oder eng adaptierter Code bekommt eine knappe Provenance-Angabe im jeweiligen Service/Plugin.
V1 (Phase 1) war read-only. Phase 2 fügt explizite Write-Tools für den dev-only Kontext hinzu (Navigation, Canvas Page Building). Write-Tools haben einen confirm/Dry-Run-Mechanismus, prüfen die administer mcp server-Permission und bleiben im dev-Config-Split.
Keine Write-Tools ohne confirm-Flag — Dry-Run ist Pflicht, bevor geschrieben wird.
Generische „execute arbitrary PHP/SQL/Drush"-Tools werden nicht gebaut.

Die priorisierte Tool-Surface für solcom_mcp_tools:

Drupal Inventory: Site-Status, aktive Extensions, Routes, Permissions.
Entity/Content Read: Entity-Typen, Bundles, Bundle-Fields, limitierte Entity-Queries, Einzel-Entity-Lookup.
SOLCOM Frontend: SDC-Details, Canvas-Komponenten, Canvas-Templates, Canvas-Template-Tree, SDC-Canvas-Usages.
Vacancy/Personio: Vacancy-Modell, Vacancy-Liste, Vacancy-Detail, Migration-Status, Required-Field-Checks.
Ops Read: Cron-Status, Migrationsliste, Migration-Messages, Watchdog-Errors, Pending-DB-Updates.
Navigation Write: Menu-Struktur lesen, Menu-Items erstellen/updaten/löschen/verschieben (Phase 2).
Canvas Write: ContentTemplate-Validierung, Preview, Erstellung und Löschen. Granulare Node-Manipulation mit rekursiver Child-bereinigung (Phase 2).

Rejected alternatives

Expand each rejected option to see the rationale.

drupal/mcp_tools direkt installieren rejected

Fachlich attraktiv, weil die breite Tool-Surface sofort verfügbar wäre. Verworfen, weil der Composer-Vertrag mit mcp/sdk:^0.2.2 nicht zum erzwungenen SDK-0.5-Stack passt und die aktuelle lokale Reparatur wieder rückgängig machen würde.

Vendor-Fork von mcp_tools in web/modules/custom importieren rejected

Würde kurzfristig viele Tools bringen, aber fremde Runtime-Annahmen, code-wheel/*-Abhängigkeiten, Update-Reibung und hohe Review-Last in das Custom-Modul ziehen. Selektives Porting ist kleiner und besser testbar.

Beide MCP-Server parallel betreiben rejected

Würde zwei Server, zwei SDK-Versionen, zwei Tool-Konventionen und zwei Auth-/Transport-Flächen erzeugen. Composer-seitig ist es ohnehin konfliktträchtig.

Generisches Drush/PHP/SQL-Ausführungstool bauen rejected

Maximal flexibel, aber sicherheitlich falsch: Es macht den MCP-Server zur Remote-Shell. Stattdessen entstehen explizite, kleine Tools mit klaren Inputs, Limits und Tests.

mcp_server_examples aktivieren rejected

Die Beispiele (EchoTool, ContentLookupTool) sind Demo-Material. Für SOLCOM bauen wir produktive dev-only Tools über drupal/tool, nicht über das Beispielmodul.

Consequences

Keine fertigen ~190 Tools out of the box. Die breite mcp_tools-Surface wird nicht automatisch verfügbar. Wir gewinnen dafür Kontrolle über Umfang, Sicherheit, Tests und Wartung.
solcom_mcp_tools wird zum lokalen Agent-Parity-Layer. Alles, was ein Agent im Drupal-Dev-Workflow sehen oder tun soll, bekommt ein explizites Tool-Plugin statt impliziter Shell-Ausführung.
Porting ist bewusst und nachweisbar. mcp_tools bleibt Referenz, aber jeder übernommene Slice wird auf unseren Stack, unsere Field-Modelle, Canvas-Konfiguration und dev-only Grenzen angepasst.
SDK-0.5-Kompatibilität ist lokale Verantwortung. Solange upstream mcp_server und mcp/sdk auseinanderlaufen, hält solcom_mcp_tools den Compatibility-Layer. Bei einem upstream-Fix muss dieser Layer entfernt oder stark vereinfacht werden.
Stage/Prod bleiben geschützt. Der bestehende dev-Split aus ADR-0010 bleibt die Schutzmauer. Ohne aktivierten Split verschwinden MCP-Server, Bridge und SOLCOM-Tools aus der Active Config.
Doku muss den Zwischenstand überschreiben. CONTEXT.md, ADR-0010 und alte Plan-Dokumente dürfen nicht mehr behaupten, mcp_tools sei die aktive Server-Implementierung. ADR-0011 ist ab jetzt die aktuelle Entscheidung.