Implementation Plan · solcom

Plan: mcp_server durch mcp_tools ersetzen + Solcom-Eigen-Tools

Kontext drupal/mcp_server (mcp/sdk ^0.5.0) hat einen unauflösbaren Composer-Konflikt mit anderen Abhängigkeiten. Ersatz durch drupal/mcp_tools 1.0.0-beta7 (mcp/sdk ^0.2.2), Transport via STDIO. Danach: 3 Solcom-Eigen-Tools (list_sdc_components, get_brand_tokens, find_component_usages) als Custom-Modul solcom_mcp_tools im Dev-Split. Source PRD: docs/brainstorms/…prd.html.
Status
Draft
Phasen
6
Eigen-Tools
3
mcp_tools Submodule
28
01

Milestones

6 Phasen als Tracer-Bullets: jede Phase produziert einen lauffähigen Endzustand. Phase 1 ist Blocker für alle anderen.

Phase 1

Foundation: mcp_server raus, mcp_tools + STDIO rein

Vertikaler Tracer-Bullet: pm:uninstall mcp_server, composer remove, composer require mcp_tools:^1.0@beta, pm:enable mcp_tools + mcp_tools_stdio, config:export. Beweist SDK-Versions-Konflikt-Resolution. Rollback-Pfad dokumentiert.

mcp_toolsmcp_tools_stdiocomposerconfig-split
Phase 2

Tool-Surface: 28 Submodule + Auth-Dev-Preset

Aktivierung aller 28 ausgewählten mcp_tools_*-Submodule (analysis, batch, blocks, cache, config, content, …). Auth-Preset auf Development (read/write/admin). Auth-Konfig im dev-Split. Ziel: ≥ 195 Tools in tools/list.

28 Submoduleauth-dev-presetdev-split
Phase 3

Eigen-Tool 1: list_sdc_components

Modul-Skeleton solcom_mcp_tools, Service SdcCatalogReader, Tool-Plugin mit #[Tool]-Attribut (id: list_sdc_components, operation: Read). Inputs: theme (default: byte_theme), include_metadata. Service-Unit-Test + Tool-Kernel-Test.

solcom_mcp_toolsSdcCatalogReaderPHPUnit
Phase 4

Eigen-Tool 2: get_brand_tokens

Service BrandTokenParser parst CSS-Custom-Properties aus theme.brand.css + theme.css. ADR-0003-Drift-Detection: Soll-Werte gegen geparste CSS-Werte halten, Drift im message-Feld melden. Input: category (colors|gradients|typography|all).

BrandTokenParserADR-0003-DriftCSS-Custom-Properties
Phase 5

Eigen-Tool 3: find_component_usages

Service TwigReferenceFinder: rekursiver Grep über *.twig nach include/embed/use/extends. Namespace-Alias-Resolution (@byte_theme/components/…). Output: {file_path, line, match_type, match_text}. 0 Treffer = regulärer Erfolgsfall.

TwigReferenceFindernamespace-aliasgrep-over-twig
Phase 6

ADR-0011 + Onboarding-Doku

ADR-0011 (mcp_server → mcp_tools, Composer-Konflikt-Begründung, 28 Submodule, 3 Eigen-Tools). ADR-0010 erhält Status-Header mit Verweis auf ADR-0011. CLAUDE.md-Update: mcp_tools statt mcp_server referenzieren.

ADR-0011ADR-0010-Status-HeaderCLAUDE.md
02

Architektur-Entscheidungen

Durable Decisions, die über alle Phasen gelten — nicht verhandelbar ohne neues ADR.

Modul-Topologie + Custom-Modul-Pfad
  • Transport: ausschließlich mcp_tools_stdio
  • Eigen-Tools: web/modules/custom/solcom_mcp_tools/
  • Plugin-Discovery: src/Plugin/tool/Tool/ via Drupal\tool\Attribute\Tool
  • solcom_mcp_tools im Dev-Split (NICHT im Default-Sync wie drupal/tool)
  • Nicht aktivierte Submodule: entity_clone, paragraphs, ultimate_cron (Drupal-Dep fehlt); remote, mcp_server (Use-Case-Entscheidung)
Service-Layer + Tool-Response-Shape
  • SdcCatalogReader — liest *.component.yml aus Theme-root
  • BrandTokenParser — parst CSS-Custom-Properties, DI-Konstruktor-Argumente für Quell-Pfade
  • TwigReferenceFinder — Grep über *.twig, Namespace-Alias-tolerant
  • Response-Shape: { success: bool, message: string, data: array }
  • Out-of-scope V1: HTTP/Remote-Transport, OAuth-2.1, Tool-Whitelisting, Multi-Theme-Tests
03

Key Code

Kritischste Stellen: Tool-Plugin-Schema (Phase 3 als Vorlage für 4+5) und Phase-1-Migrationssequenz.

ListSdcComponents.php — Tool-Plugin-Schema
#[Tool(
  id: 'list_sdc_components',
  label: 'List SDC Components',
  operation: ToolOperation::Read,
)]
class ListSdcComponents extends SolcomToolBase {

  public function execute(array $values): array {
    $theme = $values['theme'] ?? 'byte_theme';
    $meta  = $values['include_metadata'] ?? true;

    return [
      'success' => true,
      'message' => '',
      'data'    => $this->catalog
        ->getComponents($theme, $meta),
    ];
  }
}
Phase-1-Migrationssequenz (Drush-Befehle)
# 1. Alten Server deinstallieren
ddev drush pm:uninstall \
  mcp_server_ui mcp_server_tool_bridge mcp_server

# 2. Config exportieren (mcp_server* weg)
ddev drush config:export --yes

# 3. Package-Switch
ddev composer remove drupal/mcp_server
ddev composer require drupal/mcp_tools:^1.0@beta

# 4. Neue Module aktivieren (Phase 1: nur Core)
ddev drush pm:enable --yes mcp_tools mcp_tools_stdio

# 5. Config exportieren (mcp_tools/* rein)
ddev drush config:export --yes

# Verify: mcp/sdk 0.2.x, kein 0.5.x mehr
composer info mcp/sdk
04

Risks & Mitigations

Risk
Sev
Mitigation
composer.lock-Konflikt bleibt auch nach mcp_server-Remove (andere Dep hält mcp/sdk ^0.5.0).
HIGH
Phase 1 ist explizit ein Tracer-Bullet zum Beweis der Konflikt-Resolution. Bei Fehlschlag: Analyse der verbleibenden Constraints, ggf. Patch oder Locking auf Konkrete Version.
Submodul-Aktivierungsreihenfolge schlägt fehl (Abhängigkeitskonflikte unter den 28 Submodulen).
MED
Open Question 4 aus PRD: mehrstufige Aktivierung falls drush pm:enable mit allen 26 in einem Befehl nicht reicht. Im PR dokumentieren.
solcom_mcp_tools landet versehentlich im Default-Sync statt im Dev-Split.
MED
Acceptance Criteria Phase 3: git diff config/sync/core.extension.yml zeigt KEIN solcom_mcp_tools. drupal-config-architecture-reviewer prüft das bei jedem PR.
BrandTokenParser parst falsche CSS-Werte wegen SCSS-Nesting oder Kommentaren.
LOW
Service-Unit-Test mit Fixture-CSS. ADR-0003-Drift-Detection gibt sofortiges Signal wenn Soll-Werte nicht gefunden werden.
05

Open Questions

Auth-Preset-Aktivierung: drush config:set oder Admin-UI?
Auth-Preset auf Development läuft entweder über mcp_tools.settings.yml per drush config:set oder über /admin/config/services/mcp-tools. Im PR dokumentieren welche Methode reproducible ist. Betrifft Phase 2.
Klären in Phase 2 · marc
Drush-Befehl-Name des STDIO-Transports
Vermutet: mcp_tools:serve. Muss in Phase 1 aus mcp_tools_stdio/drush.services.yml abgelesen werden. Drush-Befehl-Name wird in Phase-1-PR dokumentiert und in Onboarding-Doku (Phase 6) übernommen.
Klären in Phase 1 · marc