Architecture Decision Record · 0010

`mcp_server`-Familie als dev-only Modul-Set via `config_split`

TL;DR — mcp_server und verwandte Submodule werden ausschließlich über einen config_split-Override (machine-name: dev) aktiviert — per settings.local.php lokal eingeschaltet, im Default-Sync deaktiviert, damit Stage/Prod das Modul nie sieht.

Status (2026-05-04): Config-Split-Pattern weiterhin gültig. ADR-0011 wurde auf die aktuelle Server-Entscheidung korrigiert: mcp_server bleibt der lokale Dev-only-Server, mcp_tools dient nur noch als Referenz für selektives Porting in solcom_mcp_tools. Das hier beschriebene Config-Split-Pattern bleibt die Schutzmauer für Stage/Prod.

Kontext

drupal/mcp_server exponiert Drupal-Capabilities über das Model Context Protocol an LLM-Clients wie Claude Code und Claude Desktop. Im Solcom-Projekt soll das Modul als lokales Dev-Tooling dienen — primärer Use-Case ist STDIO-Transport (drush mcp:server) zwischen einem Claude-Client und dem DDEV-Drupal des Entwicklers.

Das Modul-Set hat drei Eigenschaften, die seine produktive Aktivierung problematisch machen:

Pre-stable Status. mcp_server hat keine stable Release — nur 1.x-dev und 2.x-dev. Damit gibt es keine Security-Coverage unter der Drupal-Security-Advisory-Policy. Die Tool-API (drupal/tool) ist 1.0.0-beta1. Die zugrundeliegende Composer-Library mcp/sdk ^0.5.0 ist semantisch 0.x.
Sicherheits-Surface. Das Modul ist darauf ausgelegt, Drupal-Funktionen an externe Prozesse auszuliefern. Das HTTP-Submodul (mcp_server_oauth) wäre ein authentifizierter externer Endpunkt. Selbst die STDIO-Variante exponiert den Tool-Bridge-Mechanismus.
Use-Case ist Per-Entwickler. Es gibt keine Site-globale Funktion, die mcp_server in Stage/Prod erfüllen würde — der Konsument ist immer ein lokaler MCP-Client.

Standard-Drupal-Configuration-Management exportiert Modul-Aktivierungen in core.extension.yml und importiert sie auf jeder Site, die drush config:import ausführt. Ohne Trennung würde mcp_server auch in Stage/Prod aktiv sein. Das Repo hatte vor dieser Entscheidung kein Environment-Trennungs-Pattern.

Entscheidung

Die mcp_server-Modul-Familie wird ausschließlich über einen config_split-Override mit Status inactive im Sync und Status active nur in lokalen DDEV-Setups aktiviert. Konkret:

drupal/config_split (^2.0) wird als Infrastruktur-Modul installiert und in der Sync-Konfig aktiv.
Ein einziger Split mit Machine-Name dev wird angelegt, mit Folder ../config/splits/dev (Repo-Root: config/splits/dev/). Status im Sync: inactive.
mcp_server, mcp_server_ui, mcp_server_tool_bridge werden im Split als „Complete Split" deklariert. Damit landen ihre Modul-Aktivierungen und Konfig-Entitäten im Split-Folder, nicht im Default-Sync.
Lokale Aktivierung erfolgt über web/sites/default/settings.local.php: $config['config_split.config_split.dev']['status'] = TRUE; — settings.local.php ist gitignored und wird per Hand pro Maschine angelegt.
Die Tool-API drupal/tool selbst bleibt im Default-Sync aktiv, nicht im Split. Sie ist als generisches Framework auch für nicht-MCP-Use-Cases sinnvoll und blockiert nichts in Prod.
Submodule mcp_server_oauth und mcp_server_examples werden nicht aktiviert — das HTTP-/OAuth-Setup ist explizit out-of-scope.

config:import ohne aktiven Split (also: Stage/Prod) sieht im Default-Sync kein mcp_server in core.extension.yml und würde es deaktivieren. Die Migration zu Stage/Prod ist fail-safe.

Rejected alternatives

Expand each rejected option to see the rationale.

Modul global aktivieren + Config exportieren („Standard-Workflow") rejected

Lässt das Modul nach jeder drush config:import auch in Stage/Prod aktiv sein. Da das Modul pre-stable und security-uncovered ist, ist die Verbreitungs-Surface in Prod-Environments inakzeptabel.

Modul aktivieren, Config nicht exportieren rejected

Wäre minimaler Eingriff. Bricht aber das Drupal-CMS-Konfig-Management-Pattern: (a) Drift zwischen Sync und Active-Config, (b) die Tool-Bridge-Konfiguration wäre nicht reproduzierbar.

Settings-basierter Toggle ($settings['mcp_server.enabled'] = TRUE) rejected

Würde das Modul-Aktivierungs-Verhalten an Settings koppeln statt an Config. Drupal hat dafür kein etabliertes Pattern; wir müssten eigene Logik schreiben, die config_split als Framework-Fertiglösung ersetzt.

environment_indicator plus manueller Process rejected

environment_indicator markiert visuell die Umgebung, trennt aber keine Module. Kombiniert mit Config-nicht-exportieren — derselbe Settings-vs-Config-Bruch.

HTTP-Transport mit mcp_server_oauth aktivieren rejected

Out-of-scope für die aktuelle Use-Case-Definition (lokales Dev-Tooling). Ein OAuth-2.1-Setup ist ein eigener Plan, der von dieser Entscheidung nicht präjudiziert wird.

Branch 1.x-dev statt 2.x-dev von mcp_server rejected

2.x nutzt mcp/sdk ^0.5.0 (aktuelle, von Acquia gesponserte Weiterentwicklung) und ist die aktive Schiene, in die zukünftige Stable-Releases fließen werden.

Consequences

Phasenweise Repo-Topologie ändert sich. Es entstehen zwei Sync-Wurzeln: config/sync/ (Default, alle Environments) und config/splits/dev/ (Override, nur lokal aktiv). Jede Konfig-Änderung muss bewusst in einem der beiden landen. Config-Reviewer im PR-Review müssen wissen, welches Verzeichnis welchen Geltungsbereich hat.
settings.local.php wird Pflicht-Datei für lokale Dev-Setups, in denen MCP genutzt werden soll. Da die Datei gitignored ist, muss jeder Entwickler sie einmalig manuell anlegen. Ohne diese Datei ist der lokale Site-Status inkonsistent — drush config:status würde melden.
Drift-Risiko zwischen Splits. Wenn mcp_server-Konfig sich ändert, passiert das im aktiven Split-Folder (config/splits/dev/). Auf Stage/Prod (Split inactive) gibt es das Mapping nicht. Das ist per Definition richtig. Wenn die Familie irgendwann in Prod wandern soll, müssen Split-Folder-Inhalte explizit in den Default-Sync migriert werden.
Zukünftige dev-only-Module landen im selben Split. Die Entscheidung etabliert den dev-Split als kanonisches Sammelbecken für lokale Dev-Tools. Andere Module mit ähnlichem Profil (z. B. devel, webprofiler) sollten ohne weitere ADR demselben Pattern folgen.
drupal/config_split ist jetzt eine permanente Production-Dependency, auch wenn der Dev-Split selbst auf Stage/Prod inactive ist. Das Modul ist seit Jahren stable und Standard im Drupal-Ökosystem.
Cherry-Pick-Reibung gegen Upstream-Drupal-CMS. drupal/cms als Project-Template enthält keine Splits-Topologie; ein Update von Drupal CMS würde unsere Config-Topologie nicht beeinflussen. Pragmatisch akzeptiert.
PR-Review-Aufwand für mcp_server-Bumps. Jedes composer update drupal/mcp_server (dev-Branch → neuer dev-Commit) kann Schema-Änderungen mitbringen — der Diff landet in config/splits/dev/. Reviewer müssen prüfen, ob die neuen Konfig-Entitäten erwartbar sind.
Verifikation-Pfad: Mit Split inactive zeigt drush config:status (kein settings.local.php aktiv) mcp_server als „to be uninstalled". Das ist der Soll-Zustand für Stage/Prod-Verifikations-Runs.
HTTP-Endpoint kommt später als eigene Entscheidung. Wenn mcp_server_oauth aktiviert werden soll, entsteht ein eigener ADR mit der OAuth-2.1-Konfig, Public-Key-Management, Scope-Design und Threat-Model.