Implementation Plan · solcom

Write-MCP-Tools: Navigation und Canvas Page Building

Kontext Aktuell sind alle MCP-Tools in solcom_mcp_tools read-only (ToolOperation::Read). Nächster Schritt: schreibende Tools für Navigation (Menü-System, stabile Entity-API) und Canvas Page Building (Config-Entities, Custom Constraints). Alle Write-Tools erhalten confirm-Dry-Run-Mechanismus und administer mcp server-Permission-Guard.
Status
Draft
Phasen
3 (A / B / C)
Neue Tools
11
Dev-Split
solcom_mcp_tools
01

Milestones

Drei Phasen, je unabhängig deploybar. Phase A liefert alle Navigation-Write-Tools. Phase B die Canvas-Tools. Phase C ist optional.

Phase A

Navigation-Tools (jetzt)

ADR-0011 auf Write-Erweiterung aktualisieren. SolcomToolBase::checkAccess schreibsensitiv machen. 6 Menu-Tool-Plugins + Services + Tests bauen. Dry-Run-Mechanismus (confirm: false) für alle Write-Operationen.

solcom_mcp_toolsmenu_link_contentUnit/Kernel-Tests
Phase B

Canvas-Tools (nächster Schritt)

Read-Tools list_available_component_versions, validate_canvas_tree, preview_canvas_page zuerst. Danach Write-Tools create_canvas_page und delete_canvas_page mit Dry-Run und Permission-Guard. Besondere Vorsicht: component_version-Match und StaticPropSource-Constraint.

canvas.component_treeContentTemplateValidComponentTreeItem
Phase C

Canvas-Erweiterungen (optional)

update_canvas_page (Tree-Elemente add/remove/reorder) und Canvas Page Regions Support. Nur wenn Phase B stabil und real gebraucht wird.

optionalupdate_canvas_pageregions
02

Tool-Inventar

11 neue Tools aufgeteilt auf zwei Domänen. Navigation nutzt Standard-Entity-API; Canvas-Tools operieren auf Config-Entities mit Canvas-Constraints.

A · Navigation (Menu-System) — 6 Tools
  • list_menus — Read: alle verfügbaren Menüs
  • list_menu_items — Read: Links eines Menüs (menu_name, limit)
  • create_menu_item — Write: neuer Link (menu_name, title, link, parent?, weight?, confirm)
  • update_menu_item — Write: Link ändern (id, title?, link?, weight?, confirm)
  • delete_menu_item — Write: Link löschen (id, confirm)
  • reorder_menu_items — Write: Reihenfolge/Parent (menu_name, ids[], confirm)
B · Canvas Page Building — 5 Tools
  • list_available_component_versions — Read: Component-IDs + aktuelle version
  • validate_canvas_tree — Read: Baum prüfen vor dem Schreiben
  • preview_canvas_page — Read: Diff anzeigen was erzeugt würde
  • create_canvas_page — Write: ContentTemplate anlegen (confirm)
  • delete_canvas_page — Write: ContentTemplate entfernen (confirm)
03

Key Code

Die zwei kritischsten Stellen: checkAccess-Erweiterung für Write-Guards und Canvas-Component-Tree-Node-Struktur mit Pflichtfeld component_version.

web/modules/custom/solcom_mcp_tools/src/Tool/SolcomToolBase.php
protected function checkAccess(
  array $values,
  AccountInterface $account,
  bool $return_as_object = FALSE
): bool|AccessResultInterface {
  if ($this->getPluginDefinition()
      ?->getOperation()
      ?->isModifying()) {
    return AccessResult::allowedIf(
      $account->hasPermission(
        'administer mcp server'
      )
    )->cachePerPermissions();
  }
  return AccessResult::allowed();
}
Canvas Component-Tree-Node (Struktur)
# Jeder Node im component_tree:
uuid: "generated-uuid"
parent_uuid: ~         # oder UUID des Parents
slot: ~                # oder Slot-Name
component_id: "sdc.byte_theme.button"
component_version: "7f0a1c9ded3eab0e"
  # = active_version der Component-Config
  # muss mit canvas.component.*.active_version
  # übereinstimmen — sonst Constraint-Fehler
inputs: '{"label":"Click","href":"/"}'
  # nur StaticPropSource erlaubt in Config-Trees
label: "Optional label"
04

Risks & Mitigations

Risk
Sev
Mitigation
component_version stimmt nicht mit canvas.component.*.active_version überein — Canvas-Constraint-Fehler beim Import.
HIGH
validate_canvas_tree (Read-Tool) prüft vor jedem Write alle Versions-Matches explizit. Write-Tool rejected bei Validation-Fehler mit klarem Message.
Agent übergibt Entity-Field-Referenzen als Canvas-Input — Canvas erlaubt das nicht in Config-definierten Trees.
HIGH
Tool-Docstring explizit: nur StaticPropSource. validate_canvas_tree prüft Input-Typ. Fehler-Response nennt die erlaubte Alternative (Editor).
Write-Tool wird ohne Dry-Run aufgerufen und produziert ungewollte Entities.
MED
confirm: false ist Default. Nur bei confirm: true wird geschrieben. Dry-Run-Response zeigt exakt was passieren würde.
Dev-Split-Grenzen werden verletzt — Write-Tools landen im Default-Sync und werden auf Prod aktiv.
MED
solcom_mcp_tools bleibt im dev-Config-Split. Reviewer-Agent (drupal-config-architecture-reviewer) prüft das bei jedem PR.
Navigation-Tools stören Menu-Cache bei häufigen Writes (invalidation flood).
LOW
Dev-only, max. 3–5 Menu-Entities auf der Site. Kein Cache-Performance-Problem im Dev-Kontext.
05

Open Questions

Canvas-Permission: administer mcp server oder administer content templates?
Canvas-Write-Tools brauchen möglicherweise eine eigene feinere Permission (administer content templates) statt der generischen MCP-Permission. Entscheidung beeinflusst Phase B.
Entscheiden vor Phase B · marc
ADR-0011: Wann kommt der aktualisierte Stand ins Repo?
ADR-0011 hat aktuell „V1 bleibt read-only." — muss auf Write-Erweiterung aktualisiert werden, bevor Phase A gemergt wird. Sonst Config-Architecture-Reviewer-Finding.
Erledigen in Phase A · marc