coretik-block-generator-mcp 1.0.0

package/CLAUDE_INSTRUCTIONS.md

@@ -0,0 +1,30 @@
+# Coretik Page Builder — Instructions pour l'IA
+
+## Contexte
+Ce projet WordPress utilise le framework Coretik et Coretik Page Builder pour construire des pages via un système de blocs ACF.
+
+## Workflow de génération de bloc
+
+Quand on te demande de créer un nouveau bloc Page Builder :
+
+1. **Appelle `get_conventions`** pour charger les patterns de code Coretik
+2. **Appelle `scan_blocks`** pour voir les blocs existants et s'inspirer du style du projet
+3. **Appelle `read_block`** sur un bloc similaire existant si pertinent
+4. **Appelle `generate_block`** en `dryRun: true` pour montrer le code au développeur
+5. Après validation, appelle `generate_block` en `dryRun: false` pour écrire les fichiers
+
+## Conventions importantes
+
+- Noms de blocs en kebab-case : `text-image`, `hero-banner`
+- BEM pour le CSS : `.block-text-image__title`
+- Les images ACF renvoient un ID (`returnFormat: 'id'`), utiliser `wp_get_attachment_image()`
+- Les liens ACF renvoient un array (`returnFormat: 'array'`) avec `url`, `title`, `target`
+- Le WYSIWYG n'est PAS échappé dans le template (il contient du HTML)
+- Toujours wrapper les champs optionnels dans `<?php if (!empty($var)) : ?>`
+- Le SCSS est un partial préfixé `_` dans `assets/styles/components/blocks/`
+
+## Types de blocs
+
+- **Component** : brique réutilisable (pas visible dans la bibliothèque utilisateur)
+- **Block** : bloc autonome complet
+- **Composite** : assemblage de Components existants

package/README.md

@@ -0,0 +1,193 @@
+# Coretik Block Generator MCP Server
+
+Un serveur MCP (Model Context Protocol) qui permet de générer des blocs [Coretik Page Builder](https://github.com/idetik/coretik-page-builder) complets à partir d'une description en langage naturel.
+
+## Ce que ça fait
+
+Demandez simplement : *"Crée un bloc Texte et image avec un titre H2, un wysiwyg et une image à droite"* et le serveur génère **tous les fichiers** :
+
+| Fichier | Chemin |
+|---------|--------|
+| Classe PHP | `src/Services/PageBuilder/Blocks/Block/TextImageBlock.php` |
+| Template HTML | `templates/blocks/block/text-image.php` |
+| SCSS | `assets/styles/components/blocks/_text-image.scss` |
+| Thumbnail ACF | `assets/images/admin/acf/text-image.svg` |
+
+## Prérequis
+
+- Node.js ≥ 18
+- Un projet WordPress avec Coretik Page Builder installé
+
+## Installation
+
+```bash
+npm install -g coretik-block-generator-mcp
+```
+
+Ou utilisez directement via `npx` sans installation (voir configuration ci-dessous).
+
+## Configuration
+
+### Pour les projets wp-cubi
+
+Un fichier `.mcp.json` est inclus à la racine des projets wp-cubi. Il suffit d'adapter le chemin du thème dans la variable `CORETIK_PROJECT_ROOT`.
+
+### Pour Claude Desktop
+
+Ajoutez dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows) :
+
+```json
+{
+  "mcpServers": {
+    "coretik-blocks": {
+      "command": "npx",
+      "args": ["coretik-block-generator-mcp"],
+      "env": {
+        "CORETIK_PROJECT_ROOT": "/chemin/vers/votre-theme-wordpress"
+      }
+    }
+  }
+}
+```
+
+### Pour VS Code (avec extension MCP)
+
+Dans `.vscode/mcp.json` à la racine de votre projet :
+
+```json
+{
+  "servers": {
+    "coretik-blocks": {
+      "command": "npx",
+      "args": ["coretik-block-generator-mcp"],
+      "env": {
+        "CORETIK_PROJECT_ROOT": "${workspaceFolder}/web/app/themes/mon-theme"
+      }
+    }
+  }
+}
+```
+
+### Pour Claude Code
+
+Dans `.mcp.json` à la racine de votre projet :
+
+```json
+{
+  "mcpServers": {
+    "coretik-blocks": {
+      "command": "npx",
+      "args": ["coretik-block-generator-mcp"],
+      "env": {
+        "CORETIK_PROJECT_ROOT": "./web/app/themes/mon-theme"
+      }
+    }
+  }
+}
+```
+
+Ou via la CLI :
+
+```bash
+claude mcp add coretik-blocks \
+  npx coretik-block-generator-mcp \
+  -e CORETIK_PROJECT_ROOT=./web/app/themes/mon-theme
+```
+
+### Variables d'environnement
+
+| Variable | Défaut | Description |
+|----------|--------|-------------|
+| `CORETIK_PROJECT_ROOT` | Répertoire courant | Racine du thème WordPress |
+| `CORETIK_ROOT_NAMESPACE` | `App\Services\PageBuilder\Blocks` | Namespace PHP des blocs |
+| `CORETIK_BLOCKS_PHP_DIR` | `src/Services/PageBuilder/Blocks` | Dossier des classes PHP |
+| `CORETIK_TEMPLATES_DIR` | `templates/blocks` | Dossier des templates |
+| `CORETIK_SCSS_DIR` | `assets/styles/components/blocks` | Dossier des fichiers SCSS |
+| `CORETIK_THUMBNAILS_DIR` | `assets/images/admin/acf` | Dossier des thumbnails admin |
+| `CORETIK_ACF_ADMIN_DIR` | `templates/acf` | Dossier des fichiers admin ACF |
+
+## Outils disponibles
+
+### `get_conventions`
+
+Renvoie les conventions et patterns de code Coretik Page Builder. L'IA appelle cet outil en premier pour comprendre la structure attendue.
+
+### `scan_blocks`
+
+Analyse le projet et liste tous les blocs existants avec leur type, leur nom et l'état de leurs fichiers (template ✓/✗, SCSS ✓/✗).
+
+### `read_block`
+
+Lit tous les fichiers d'un bloc existant (PHP, template, SCSS) pour s'en inspirer.
+
+### `generate_block`
+
+Génère les 4 fichiers d'un nouveau bloc. Paramètres :
+
+- `name` : Nom en kebab-case (`text-image`)
+- `label` : Label lisible (`"Texte et image"`)
+- `type` : `component`, `block`, ou `composite`
+- `fields` : Définition des champs ACF
+- `components` : Sous-composants (pour les composites)
+- `dryRun` : Prévisualiser sans écrire (`true`/`false`)
+
+### `get_project_config`
+
+Affiche la configuration courante du serveur et vérifie l'existence des dossiers.
+
+## Exemples d'utilisation
+
+### Scénario 1 : Bloc simple via conversation
+
+> **Vous :** Crée un bloc "Hero banner" avec un titre, un sous-titre, une image de fond et un bouton CTA.
+
+L'IA va :
+1. Appeler `get_conventions` pour charger les patterns
+2. Appeler `scan_blocks` pour voir le style existant
+3. Appeler `generate_block` avec les bons champs ACF
+4. Vous confirmer les fichiers créés
+
+### Scénario 2 : Bloc composite
+
+> **Vous :** J'ai besoin d'un bloc FAQ composé d'un TitleComponent et d'un repeater de questions/réponses.
+
+### Scénario 3 : Dry-run pour valider
+
+> **Vous :** Montre-moi le code que tu génèrerais pour un bloc "Témoignages" avec photo, nom, rôle et citation, sans écrire les fichiers.
+
+### Scénario 4 : S'inspirer d'un bloc existant
+
+> **Vous :** Lis le bloc `block.hero` et crée un bloc similaire mais avec une vidéo en fond au lieu d'une image.
+
+## Structure des champs supportés
+
+Le générateur supporte tous les types de champs ACF courants :
+
+```
+text, textarea, wysiwyg, image, file, gallery, number, url, email,
+link, oembed, true_false, radio, select, checkbox, repeater, group,
+post_object, relationship, page_link, color_picker
+```
+
+Chaque champ accepte les options : `required`, `instructions`, `defaultValue`, `returnFormat`, `choices`, `width`, `conditional`, `subFields` (pour group/repeater).
+
+## Développement
+
+```bash
+# Mode watch pendant le développement
+npm run dev
+
+# Tester le serveur (affiche la config)
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
+```
+
+## Roadmap
+
+- [ ] Support de l'analyse de maquettes (image → bloc)
+- [ ] Génération des fichiers ACF admin (CSS/JS preview)
+- [ ] Import/export de définitions de blocs (JSON)
+- [ ] Intégration WP-CLI pour `wp page-builder build-block-types`
+
+## Licence
+
+GPL-3.0 — Compatible avec Coretik et WordPress.

package/dist/constants.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Coretik Page Builder conventions and default paths.
+ * These can be overridden via the MCP tool parameters.
+ */
+export declare const DEFAULT_CONFIG: {
+    /** PHP class directory relative to theme root */
+    readonly blocksSrcDirectory: "src/Services/PageBuilder/Blocks/";
+    /** HTML template directory relative to theme root */
+    readonly blocksTemplateDirectory: "templates/blocks/";
+    /** SCSS directory relative to theme root */
+    readonly blocksScssDirectory: "assets/styles/components/blocks/";
+    /** ACF admin files directory relative to theme root */
+    readonly blocksAcfDirectory: "templates/acf/";
+    /** ACF thumbnails directory relative to theme root */
+    readonly blocksThumbnailDirectory: "assets/images/admin/acf/";
+    /** Root PHP namespace */
+    readonly rootNamespace: "App\\Services\\PageBuilder\\Blocks";
+};
+/** Block types supported by the generator */
+export type BlockType = 'component' | 'block' | 'composite';
+/** ACF field types commonly used in Coretik blocks */
+export declare const ACF_FIELD_TYPES: readonly ["text", "textarea", "wysiwyg", "image", "gallery", "file", "select", "radio", "checkbox", "true_false", "link", "url", "number", "range", "email", "password", "repeater", "group", "relationship", "post_object", "taxonomy", "user", "color_picker", "date_picker", "date_time_picker", "time_picker", "oembed"];
+export type AcfFieldType = typeof ACF_FIELD_TYPES[number];
+/** Block field definition */
+export interface BlockField {
+    name: string;
+    type: AcfFieldType;
+    label: string;
+    required?: boolean;
+    defaultValue?: string;
+    choices?: string[];
+    instructions?: string;
+    /** For repeater / group: sub-fields */
+    subFields?: BlockField[];
+}
+/** Complete block specification */
+export interface BlockSpec {
+    /** Human label, e.g. "Text and Image" */
+    label: string;
+    /** Block name override (auto-generated if empty) */
+    name?: string;
+    /** Block type: component, block, or composite */
+    type: BlockType;
+    /** ACF fields definition */
+    fields: BlockField[];
+    /** For composites: list of component names to compose */
+    components?: string[];
+    /** CSS classes to use in HTML template */
+    cssClasses?: string[];
+    /** Brief description of the block's purpose */
+    description?: string;
+    /** Whether to implement ShouldBuildBlockType interface */
+    blockTypeSupport?: boolean;
+}
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,cAAc;IACzB,iDAAiD;;IAGjD,qDAAqD;;IAGrD,4CAA4C;;IAG5C,uDAAuD;;IAGvD,sDAAsD;;IAGtD,yBAAyB;;CAEjB,CAAC;AAEX,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;AAE5D,sDAAsD;AACtD,eAAO,MAAM,eAAe,8TAMlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;AAE1D,6BAA6B;AAC7B,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,SAAS,CAAC,EAAE,UAAU,EAAE,CAAC;CAC1B;AAED,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,EAAE,SAAS,CAAC;IAChB,4BAA4B;IAC5B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B"}

package/dist/constants.js

@@ -0,0 +1,27 @@
+/**
+ * Coretik Page Builder conventions and default paths.
+ * These can be overridden via the MCP tool parameters.
+ */
+export const DEFAULT_CONFIG = {
+    /** PHP class directory relative to theme root */
+    blocksSrcDirectory: 'src/Services/PageBuilder/Blocks/',
+    /** HTML template directory relative to theme root */
+    blocksTemplateDirectory: 'templates/blocks/',
+    /** SCSS directory relative to theme root */
+    blocksScssDirectory: 'assets/styles/components/blocks/',
+    /** ACF admin files directory relative to theme root */
+    blocksAcfDirectory: 'templates/acf/',
+    /** ACF thumbnails directory relative to theme root */
+    blocksThumbnailDirectory: 'assets/images/admin/acf/',
+    /** Root PHP namespace */
+    rootNamespace: 'App\\Services\\PageBuilder\\Blocks',
+};
+/** ACF field types commonly used in Coretik blocks */
+export const ACF_FIELD_TYPES = [
+    'text', 'textarea', 'wysiwyg', 'image', 'gallery', 'file',
+    'select', 'radio', 'checkbox', 'true_false', 'link', 'url',
+    'number', 'range', 'email', 'password', 'repeater', 'group',
+    'relationship', 'post_object', 'taxonomy', 'user', 'color_picker',
+    'date_picker', 'date_time_picker', 'time_picker', 'oembed',
+];
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,iDAAiD;IACjD,kBAAkB,EAAE,kCAAkC;IAEtD,qDAAqD;IACrD,uBAAuB,EAAE,mBAAmB;IAE5C,4CAA4C;IAC5C,mBAAmB,EAAE,kCAAkC;IAEvD,uDAAuD;IACvD,kBAAkB,EAAE,gBAAgB;IAEpC,sDAAsD;IACtD,wBAAwB,EAAE,0BAA0B;IAEpD,yBAAyB;IACzB,aAAa,EAAE,oCAAoC;CAC3C,CAAC;AAKX,sDAAsD;AACtD,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM;IACzD,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK;IAC1D,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO;IAC3D,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc;IACjE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,QAAQ;CAClD,CAAC"}

package/dist/conventions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Coretik Page Builder conventions documentation.
+ * Exposed as MCP resources and via the get_conventions tool.
+ */
+export declare const CONVENTIONS: {
+    readonly overview: "# Coretik Page Builder — Overview\n\nCoretik Page Builder is a WordPress page builder based on ACF (Advanced Custom Fields).\nBlocks are PHP classes that define ACF fields and render HTML templates.\n\nThere are two primary block types:\n- **Component** — Small reusable UI pieces (title, button, image, CTA, text box…)\n- **Composite** — Blocks that compose multiple components into a complete section\n\nComposites live in the Block/ directory and are the main building blocks of pages.\nComponents are reused across multiple composites.";
+    readonly fileStructure: "# File Structure\n\nA typical Coretik block consists of:\n- PHP class: src/Services/PageBuilder/Blocks/{Type}/{PascalName}{Suffix}.php\n- HTML template: templates/blocks/{type}/{kebab-name}.php\n- SCSS stylesheet: assets/styles/60-components/blocks/{kebab-name}.scss (or _kebab-name.scss)\n- ACF thumbnail: assets/images/admin/acf/{kebab-name}.svg\n\nDirectory layout:\n- Component/ — Small reusable UI components (PascalNameComponent.php)\n- Block/     — Composite blocks that compose components (PascalNameComposite.php)\n\nSCSS uses ITCSS architecture:\n- assets/styles/60-components/blocks.scss — imports all block SCSS partials\n- assets/styles/60-components/blocks/{block-name}.scss — individual block styles";
+    readonly phpClassPattern: "# PHP Class Pattern\n\nEach block extends a base class:\n- Component → extends BlockComponent\n- Composite → extends BlockComposite\n\nRequired constants:\n- NAME  — dot-notation identifier, e.g. \"component.title\", \"block.text-image\"\n- LABEL — human-readable label, e.g. \"Texte et image\"\n\nComponent methods:\n- fieldsBuilder(): FieldsBuilder — defines ACF fields using StoutLogic\\AcfBuilder\n- toArray(): array — returns field values for template rendering\n- getPlainHtml(array $parameters): string — optional HTML output override\n\nComposite methods:\n- prepareComponents(): array — returns component class references\n- getPlainHtml(array $parameters): string — arranges rendered components\n\nComponent composition helpers:\n- tap(Component::class, fn) — modify a component's field configuration\n- repeat(Component::class, [...]) — repeat a component in a repeater\n- OnTheFlyComponent::named('label')->with('key', Component::class)->build() — inline composition\n\nOptional interfaces:\n- ShouldBuildBlockType — adds Gutenberg block type support (use BlockType trait)\n\nCommon trait:\n- Components — provides $this->component(Name::NAME) for nested component access";
+    readonly compositePattern: "# Composite Pattern\n\nComposites compose multiple components into a single block.\nThey live in the Block/ directory and are named *Composite.\n\nprepareComponents() returns an associative array:\n  'key' => ComponentClass::class             — simple reference\n  'key' => tap(ComponentClass::class, fn)    — modify field config\n  'key' => repeat(ComponentClass::class, []) — repeater\n  'key' => OnTheFlyComponent::named(...)->build() — inline\n\nTemplate variables are component instances with methods:\n  $component->render()              — renders the component HTML\n  $component->getParameters()       — returns the component's data array\n  $component->toArray()             — returns the raw array\n  $component->withCssClasses('cls') — adds CSS classes before rendering\n  $image->imageTag('large', [...])  — renders an image tag with size and attributes\n\nSettings support:\n  $this->addSettings([$this, 'blockSettings'], priority)\n  $this->block — access block-level settings in toArray()";
+    readonly templatePattern: "# Template Pattern\n\nComponent templates receive simple PHP variables from toArray().\nComposite templates receive component instances with method calls.\n\nConventions:\n- Use short echo: <?= $var ?> (not <?php echo)\n- Composites use <section> wrapper, components use <div>\n- Use dynamic classlist with context: $classlist = ['block-name'];\n- Support container context: BlockContextType::CONTAINER->name\n- Check !empty() before rendering optional fields\n- Use $component->render() to output sub-components\n- Use $image->imageTag('size', ['class' => '...']) for images\n- Use $cta->withCssClasses('btn btn--link') for styled CTAs\n- Support aria-labelledby for accessibility with $uniqId";
+    readonly scssPattern: "# SCSS Pattern\n\n- ITCSS architecture: 60-components/blocks.scss imports block partials\n- One file per block: blocks/{kebab-name}.scss\n- BEM methodology: .block-name { &__element { } &--modifier { } }\n- Use $spacing-unit for spacing (e.g., $spacing-unit * 4)\n- Use color() function: color('primary', 'base'), color('secondary', 'lighten-2')\n- Use responsive mixins: @include media-breakpoint-up(medium)\n- Use SCSS placeholders %name for shared styles across components\n- Parent selector caching: $self: &; for complex nesting";
+    readonly acfFieldTypes: "# ACF Field Types\n\nCommon field types and their PHP return values:\n- text, textarea, email, url → string\n- wysiwyg → string (HTML)\n- number, range → int|float\n- image, file → int (ID) or array\n- gallery → array of int|array\n- link → array with keys: url, title, target\n- select, radio → string\n- checkbox → array\n- true_false → bool\n- repeater, group → array\n- relationship, post_object → int|WP_Post\n- oembed → string (HTML embed code)";
+    readonly namingConventions: "# Naming Conventions\n\n- Component NAME: \"component.{kebab-case}\" — e.g. \"component.title\"\n- Composite NAME: \"block.{kebab-case}\" — e.g. \"block.text-image\"\n- Component class: PascalCase + Component — e.g. \"TitleComponent\"\n- Composite class: PascalCase + Composite — e.g. \"TextImageComposite\"\n- Template file: {kebab-case}.php — e.g. \"text-image.php\"\n- SCSS file: {kebab-case}.scss — e.g. \"text-image.scss\"\n- CSS class: block-{kebab-case} or {kebab-case}-component\n- PHP namespace: {RootNamespace}\\Component or {RootNamespace}\\Block";
+    readonly registrationPattern: "# Block Registration\n\nBlocks are registered via the Coretik container in a config/dependencies file:\n\n$container->extend('pageBuilder.library', function ($blocks, $c) {\n    $our_blocks = [\n        Namespace\\Component\\TitleComponent::class,\n        Namespace\\Block\\TextImageComposite::class,\n        // ...\n    ];\n    foreach ($our_blocks as $class) {\n        $blocks->push($class);\n    }\n    return $blocks;\n});\n\nSCSS partials are imported in the ITCSS blocks aggregator:\n@import 'blocks/text-image';\n@import 'blocks/testimonials';";
+};
+export type ConventionSection = keyof typeof CONVENTIONS;
+export declare function getConventionSection(section: ConventionSection): string;
+export declare function getFullConventions(): string;
+//# sourceMappingURL=conventions.d.ts.map

package/dist/conventions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,WAAW;;;;;;;;;;CA0Jd,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,WAAW,CAAC;AAEzD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAEvE;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/conventions.js

@@ -0,0 +1,158 @@
+/**
+ * Coretik Page Builder conventions documentation.
+ * Exposed as MCP resources and via the get_conventions tool.
+ */
+export const CONVENTIONS = {
+    overview: `# Coretik Page Builder — Overview
+
+Coretik Page Builder is a WordPress page builder based on ACF (Advanced Custom Fields).
+Blocks are PHP classes that define ACF fields and render HTML templates.
+
+There are two primary block types:
+- **Component** — Small reusable UI pieces (title, button, image, CTA, text box…)
+- **Composite** — Blocks that compose multiple components into a complete section
+
+Composites live in the Block/ directory and are the main building blocks of pages.
+Components are reused across multiple composites.`,
+    fileStructure: `# File Structure
+
+A typical Coretik block consists of:
+- PHP class: src/Services/PageBuilder/Blocks/{Type}/{PascalName}{Suffix}.php
+- HTML template: templates/blocks/{type}/{kebab-name}.php
+- SCSS stylesheet: assets/styles/60-components/blocks/{kebab-name}.scss (or _kebab-name.scss)
+- ACF thumbnail: assets/images/admin/acf/{kebab-name}.svg
+
+Directory layout:
+- Component/ — Small reusable UI components (PascalNameComponent.php)
+- Block/     — Composite blocks that compose components (PascalNameComposite.php)
+
+SCSS uses ITCSS architecture:
+- assets/styles/60-components/blocks.scss — imports all block SCSS partials
+- assets/styles/60-components/blocks/{block-name}.scss — individual block styles`,
+    phpClassPattern: `# PHP Class Pattern
+
+Each block extends a base class:
+- Component → extends BlockComponent
+- Composite → extends BlockComposite
+
+Required constants:
+- NAME  — dot-notation identifier, e.g. "component.title", "block.text-image"
+- LABEL — human-readable label, e.g. "Texte et image"
+
+Component methods:
+- fieldsBuilder(): FieldsBuilder — defines ACF fields using StoutLogic\\AcfBuilder
+- toArray(): array — returns field values for template rendering
+- getPlainHtml(array $parameters): string — optional HTML output override
+
+Composite methods:
+- prepareComponents(): array — returns component class references
+- getPlainHtml(array $parameters): string — arranges rendered components
+
+Component composition helpers:
+- tap(Component::class, fn) — modify a component's field configuration
+- repeat(Component::class, [...]) — repeat a component in a repeater
+- OnTheFlyComponent::named('label')->with('key', Component::class)->build() — inline composition
+
+Optional interfaces:
+- ShouldBuildBlockType — adds Gutenberg block type support (use BlockType trait)
+
+Common trait:
+- Components — provides $this->component(Name::NAME) for nested component access`,
+    compositePattern: `# Composite Pattern
+
+Composites compose multiple components into a single block.
+They live in the Block/ directory and are named *Composite.
+
+prepareComponents() returns an associative array:
+  'key' => ComponentClass::class             — simple reference
+  'key' => tap(ComponentClass::class, fn)    — modify field config
+  'key' => repeat(ComponentClass::class, []) — repeater
+  'key' => OnTheFlyComponent::named(...)->build() — inline
+
+Template variables are component instances with methods:
+  $component->render()              — renders the component HTML
+  $component->getParameters()       — returns the component's data array
+  $component->toArray()             — returns the raw array
+  $component->withCssClasses('cls') — adds CSS classes before rendering
+  $image->imageTag('large', [...])  — renders an image tag with size and attributes
+
+Settings support:
+  $this->addSettings([$this, 'blockSettings'], priority)
+  $this->block — access block-level settings in toArray()`,
+    templatePattern: `# Template Pattern
+
+Component templates receive simple PHP variables from toArray().
+Composite templates receive component instances with method calls.
+
+Conventions:
+- Use short echo: <?= $var ?> (not <?php echo)
+- Composites use <section> wrapper, components use <div>
+- Use dynamic classlist with context: $classlist = ['block-name'];
+- Support container context: BlockContextType::CONTAINER->name
+- Check !empty() before rendering optional fields
+- Use $component->render() to output sub-components
+- Use $image->imageTag('size', ['class' => '...']) for images
+- Use $cta->withCssClasses('btn btn--link') for styled CTAs
+- Support aria-labelledby for accessibility with $uniqId`,
+    scssPattern: `# SCSS Pattern
+
+- ITCSS architecture: 60-components/blocks.scss imports block partials
+- One file per block: blocks/{kebab-name}.scss
+- BEM methodology: .block-name { &__element { } &--modifier { } }
+- Use $spacing-unit for spacing (e.g., $spacing-unit * 4)
+- Use color() function: color('primary', 'base'), color('secondary', 'lighten-2')
+- Use responsive mixins: @include media-breakpoint-up(medium)
+- Use SCSS placeholders %name for shared styles across components
+- Parent selector caching: $self: &; for complex nesting`,
+    acfFieldTypes: `# ACF Field Types
+
+Common field types and their PHP return values:
+- text, textarea, email, url → string
+- wysiwyg → string (HTML)
+- number, range → int|float
+- image, file → int (ID) or array
+- gallery → array of int|array
+- link → array with keys: url, title, target
+- select, radio → string
+- checkbox → array
+- true_false → bool
+- repeater, group → array
+- relationship, post_object → int|WP_Post
+- oembed → string (HTML embed code)`,
+    namingConventions: `# Naming Conventions
+
+- Component NAME: "component.{kebab-case}" — e.g. "component.title"
+- Composite NAME: "block.{kebab-case}" — e.g. "block.text-image"
+- Component class: PascalCase + Component — e.g. "TitleComponent"
+- Composite class: PascalCase + Composite — e.g. "TextImageComposite"
+- Template file: {kebab-case}.php — e.g. "text-image.php"
+- SCSS file: {kebab-case}.scss — e.g. "text-image.scss"
+- CSS class: block-{kebab-case} or {kebab-case}-component
+- PHP namespace: {RootNamespace}\\Component or {RootNamespace}\\Block`,
+    registrationPattern: `# Block Registration
+
+Blocks are registered via the Coretik container in a config/dependencies file:
+
+$container->extend('pageBuilder.library', function ($blocks, $c) {
+    $our_blocks = [
+        Namespace\\Component\\TitleComponent::class,
+        Namespace\\Block\\TextImageComposite::class,
+        // ...
+    ];
+    foreach ($our_blocks as $class) {
+        $blocks->push($class);
+    }
+    return $blocks;
+});
+
+SCSS partials are imported in the ITCSS blocks aggregator:
+@import 'blocks/text-image';
+@import 'blocks/testimonials';`,
+};
+export function getConventionSection(section) {
+    return CONVENTIONS[section] ?? '';
+}
+export function getFullConventions() {
+    return Object.values(CONVENTIONS).join('\n\n---\n\n');
+}
+//# sourceMappingURL=conventions.js.map

package/dist/conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,QAAQ,EAAE;;;;;;;;;;kDAUsC;IAEhD,aAAa,EAAE;;;;;;;;;;;;;;iFAcgE;IAE/E,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;iFA4B8D;IAE/E,gBAAgB,EAAE;;;;;;;;;;;;;;;;;;;;0DAoBsC;IAExD,eAAe,EAAE;;;;;;;;;;;;;;yDAcsC;IAEvD,WAAW,EAAE;;;;;;;;;yDAS0C;IAEvD,aAAa,EAAE;;;;;;;;;;;;;;oCAcmB;IAElC,iBAAiB,EAAE;;;;;;;;;sEASiD;IAEpE,mBAAmB,EAAE;;;;;;;;;;;;;;;;;;+BAkBQ;CACrB,CAAC;AAIX,MAAM,UAAU,oBAAoB,CAAC,OAA0B;IAC7D,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Coretik Block Generator MCP Server
+ *
+ * An MCP server that provides tools for generating Coretik Page Builder blocks.
+ * Exposes conventions as resources and block generation as tools.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}