@stellisoft/stellify-mcp 0.1.35 → 0.1.36

package/README.md

@@ -374,12 +374,80 @@ Create a new UI element. Provide either `page` (route UUID) for root elements, o
 **Parameters:**
 - `type` (required): Element type - one of:
   - HTML5: `s-wrapper`, `s-input`, `s-form`, `s-svg`, `s-shape`, `s-media`, `s-iframe`
-  - Components: `s-loop`, `s-transition`, `s-freestyle`, `s-motion`
+  - Components: `s-transition`, `s-freestyle`, `s-motion`
   - Blade: `s-directive`
   - Shadcn/ui: `s-chart`, `s-table`, `s-combobox`, `s-accordion`, `s-calendar`, `s-contiguous`
 - `page` (optional): UUID of the page/route (for root elements)
 - `parent` (optional): UUID of the parent element (for child elements)
 
+**Using `s-directive` for Blade Conditionals:**
+
+`s-directive` elements output Blade directives (like `@if`, `@foreach`, `@endif`). They are **sibling elements** — they don't wrap children. To conditionally render content:
+
+1. Create an `s-directive` element with a statement for the opening directive (e.g., `@if(...)`)
+2. Create the content element(s) as the **next sibling(s)**
+3. Create another `s-directive` element with a statement for the closing directive (e.g., `@endif`)
+
+Example — conditionally showing an image:
+```
+// 1. Create statement for @if
+create_statement_with_code({
+  file: "<file-uuid>",
+  code: "@if($item->featured_image)"
+})
+
+// 2. Create opening directive element and set its statement
+create_element({ type: "s-directive", page: "<route-uuid>" })
+update_element({ uuid: "<if-directive-uuid>", data: { "statement": "<if-statement-uuid>" } })
+
+// 3. Create the image as the next sibling
+html_to_elements({ page: "<route-uuid>", elements: "<img class=\"w-full\" />" })
+// Then update with dynamic src:
+update_element({ uuid: "<img-uuid>", data: { "srcField": "featured_image" } })
+
+// 4. Create statement for @endif
+create_statement_with_code({ file: "<file-uuid>", code: "@endif" })
+
+// 5. Create closing directive element
+create_element({ type: "s-directive", page: "<route-uuid>" })
+update_element({ uuid: "<endif-directive-uuid>", data: { "statement": "<endif-statement-uuid>" } })
+```
+
+The three elements render in order as siblings:
+```blade
+@if($item->featured_image)
+<img class="w-full" src="{{ $item->featured_image }}" />
+@endif
+```
+
+**Using `s-directive` for Loops:**
+
+```
+// 1. Create @foreach directive
+create_statement_with_code({ file: "<file-uuid>", code: "@foreach($posts as $item)" })
+create_element({ type: "s-directive", page: "<route-uuid>" })
+update_element({ uuid: "<foreach-uuid>", data: { "statement": "<foreach-statement-uuid>" } })
+
+// 2. Create loop content (article with dynamic fields)
+html_to_elements({ page: "<route-uuid>", elements: "<article><h2></h2><p></p></article>" })
+// Update elements to use loop item fields:
+update_element({ uuid: "<h2-uuid>", data: { "textField": "title" } })  // → {{ $item->title }}
+update_element({ uuid: "<p-uuid>", data: { "textField": "excerpt" } }) // → {{ $item->excerpt }}
+
+// 3. Create @endforeach directive
+create_statement_with_code({ file: "<file-uuid>", code: "@endforeach" })
+create_element({ type: "s-directive", page: "<route-uuid>" })
+update_element({ uuid: "<endforeach-uuid>", data: { "statement": "<endforeach-statement-uuid>" } })
+```
+
+**Loop Item Attributes:**
+Inside `@foreach` loops, use these attributes on elements to reference `$item`:
+- `textField: "fieldName"` → outputs `{{ $item->fieldName }}`
+- `hrefField: "fieldName"` → outputs `href="{{ $item->fieldName }}"`
+- `srcField: "fieldName"` → outputs `src="{{ $item->fieldName }}"`
+- `hrefExpression: "{{ route('posts.show', $item->slug) }}"` → for complex expressions
+- `srcExpression`, `altExpression` → same pattern for other attributes
+
 ---
 
 #### `update_element`
@@ -397,7 +465,18 @@ Update an existing UI element.
 - `locked`: Prevent editing (boolean)
 - `tag`: HTML tag (div, input, button, etc.)
 - `classes`: CSS classes array `["class1", "class2"]`
-- `text`: Element text content
+- `text`: Static text content
+- `statements`: Array of statement UUIDs for dynamic Blade content
+
+**Loop item fields** (for elements inside `@foreach` loops, references `$item`):
+- `textField`: Field name → outputs `{{ $item->fieldName }}`
+- `hrefField`: Field name → outputs `href="{{ $item->fieldName }}"`
+- `srcField`: Field name → outputs `src="{{ $item->fieldName }}"`
+
+**Expression attributes** (for complex Blade expressions):
+- `hrefExpression`: Full Blade expression for href (e.g., `"{{ route('posts.show', $item->slug) }}"`)
+- `srcExpression`: Full Blade expression for src
+- `altExpression`: Full Blade expression for alt
 
 **Event handlers** (set value to method UUID):
 - `click`: @click
@@ -480,11 +559,6 @@ html_to_elements(page: routeUUID, elements: "<main>...</main>")
 html_to_elements(page: routeUUID, elements: "<footer>...</footer>")
 ```
 
-**Alternative approach (wrap in a single container):**
-```
-html_to_elements(page: routeUUID, elements: "<div class='min-h-screen flex flex-col'><header>...</header><main>...</main><footer>...</footer></div>")
-```
-
 **Features:**
 - Parses HTML structure
 - Creates all elements with proper nesting

package/dist/index.js

@@ -569,16 +569,15 @@ Use the returned UUID with html_to_elements (page parameter) or get_route for fu
     },
     {
         name: 'create_element',
-        description: `Create a UI element. Provide page (route UUID) for root elements, or parent (element UUID) for children. Use s-loop for v-for elements.`,
+        description: `Create a UI element. Provide page (route UUID) for root elements, or parent (element UUID) for children.`,
         inputSchema: {
             type: 'object',
             properties: {
                 type: {
                     type: 'string',
                     enum: [
-                        's-wrapper', 's-input', 's-form', 's-svg', 's-shape', 's-media', 's-iframe',
-                        's-loop', 's-transition', 's-freestyle', 's-motion',
-                        's-directive'
+                        's-wrapper', 's-input', 's-form', 's-svg', 's-shape', 's-media',
+                        's-freestyle', 's-directive'
                     ],
                     description: 'Element type - must be one of the valid Stellify element types',
                 },
@@ -596,7 +595,24 @@ Use the returned UUID with html_to_elements (page parameter) or get_route for fu
     },
     {
         name: 'update_element',
-        description: `Update a UI element. Data object: tag, classes, text, event handlers (method UUIDs), classBindings. Set 'name' on root elements to create Blade views (e.g., name="notes.index" for view('notes.index')).`,
+        description: `Update a UI element. Data object: tag, classes, text, event handlers (method UUIDs), classBindings. Set 'name' on root elements to create Blade views (e.g., name="notes.index" for view('notes.index')).
+
+**For elements inside @foreach loops (SSR/Blade):**
+Use these attributes to reference the loop variable (defaults to \`$item\`):
+- \`textField\`: Field name for text content → outputs \`{{ $item->fieldName }}\`
+- \`hrefField\`: Field name for href → outputs \`href="{{ $item->fieldName }}"\`
+- \`srcField\`: Field name for src → outputs \`src="{{ $item->fieldName }}"\`
+
+**For complex Blade expressions in attributes:**
+Use expression attributes when you need more than simple field access (e.g., route helpers, method calls):
+- \`hrefExpression\`: Blade expression for href → outputs \`href="..."\` with the expression
+- \`srcExpression\`: Blade expression for src → outputs \`src="..."\` with the expression
+- \`altExpression\`: Blade expression for alt → outputs \`alt="..."\` with the expression
+
+Example: \`hrefExpression: "{{ route('posts.show', $item->slug) }}"\`
+
+**For Blade text content:**
+Use the \`statements\` array with statement UUIDs containing Blade code. The statement's \`code\` property will be output directly for Blade to evaluate.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -718,12 +734,16 @@ When HTML contains multiple root-level elements (e.g., <header>, <main>, <footer
 **@click auto-wiring:** Pass 'file' UUID to auto-resolve @click="methodName" handlers. Methods must exist in the file first.
 
 **Blade Syntax Handling:**
-When element text or attributes contain Blade syntax like \`{{ $post->title }}\` or \`{!! $post->content !!}\`, do NOT store them as literal text. Instead:
-- Parse the Blade expression and create a statement/clause for it
-- Store the statement UUID in the element's \`statements\` array
-- The SSR assembler will evaluate these at render time
+For SSR/Blade pages, do NOT pass raw Blade expressions in text or attributes. The HTML parser stores them literally which causes rendering issues. Instead:
+
+1. **For static HTML:** Pass clean HTML without Blade syntax, then use \`update_element\` to add dynamic behavior
+2. **For loop content:** After creating elements, use \`update_element\` with:
+   - \`textField\`, \`hrefField\`, \`srcField\` for simple field access (outputs \`{{ $item->field }}\`)
+   - \`hrefExpression\`, \`srcExpression\`, \`altExpression\` for complex expressions
+   - \`statements\` array with statement UUIDs for text content with Blade code
+3. **For conditionals:** Use \`s-directive\` elements as siblings (see update_element docs)
 
-For example, \`{{ $post->title }}\` should become a statement that references the \`$post\` variable and accesses its \`title\` property.
+**Loop variable:** Inside \`@foreach\` loops created with \`s-directive\`, the default loop variable is \`$item\`. Use \`textField: "title"\` to output \`{{ $item->title }}\`.
 
 Prefer SVG icons over emoji (encoding issues).`,
         inputSchema: {
@@ -1477,7 +1497,7 @@ const SERVER_INSTRUCTIONS = `Stellify is a coding platform where code is stored
 // Create MCP server
 const server = new Server({
     name: 'stellify-mcp',
-    version: '0.1.35',
+    version: '0.1.36',
 }, {
     capabilities: {
         tools: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellisoft/stellify-mcp",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "mcpName": "io.github.MattStellisoft/stellify-mcp",
   "description": "MCP server for Stellify - AI-native code generation platform",
   "main": "dist/index.js",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/Stellify-Software-Ltd/stellify-mcp",
     "source": "github"
   },
-  "version": "0.1.35",
+  "version": "0.1.36",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@stellisoft/stellify-mcp",
-      "version": "0.1.35",
+      "version": "0.1.36",
       "transport": {
         "type": "stdio"
       },

package/skills/wordpress-import.md

@@ -12,10 +12,6 @@ You are importing a WordPress site into Stellify by reading its PHP theme files
 
 **Match the rendering approach of the WordPress site.** If content is server-rendered in WordPress (which most of it will be — posts, pages, archives, navigation), create Blade templates. If a feature uses JavaScript for client-side interactivity (AJAX forms, dynamic filtering, live search, infinite scroll, modals, sliders), create a Vue component for that specific piece. The default is Blade — only reach for Vue when the WordPress source is doing something that genuinely requires JS.
 
-## Step 0 — Discover Tools
-
-List all available Stellify MCP tools. Understand what each tool does, what parameters it requires, and any dependencies between them (e.g. you need a file before you can add methods to it, you need a method before you can add statements). Print a summary of the tools and their creation order.
-
 ## Step 1 — Identify the Active Theme
 
 Look in `./wp-content/themes/` to find the active theme. If there are multiple themes, check for the most recently modified one, or the one with the most template files. If unsure, ask which theme to import.
@@ -60,60 +56,13 @@ Read functions.php thoroughly. Extract:
 
 ## Step 4 — Plan the Laravel Structure
 
-Before calling any Stellify tools, write out the full plan:
-
-### Models
-- Post (always — WordPress core)
-- Page (always — WordPress core)
-- Category, Tag (if used)
-- Any custom post types found in Step 3
-- User (if the theme has author pages)
-
-### Controllers
-- PostController (index, show) — handles blog listing and single posts
-- PageController (show) — handles static pages
-- One controller per custom post type
-- HomeController — if front-page.php or a static homepage exists
-- SearchController — if search.php exists
-
-### Routes (web.php)
-Map the WordPress URL structure:
-- `/` → HomeController or PostController@index
-- `/blog` or `/posts` → PostController@index (if static homepage)
-- `/{post-slug}` → PostController@show
-- `/{page-slug}` → PageController@show
-- `/category/{slug}` → PostController@index (filtered)
-- `/tag/{slug}` → PostController@index (filtered)
-- `/search` → SearchController@index
-- Custom post type archives and singles
-
-### Blade Views
-Everything is Blade. The directory structure should be:
-```
-layouts/
-  app.blade.php          ← from header.php + footer.php
-posts/
-  index.blade.php        ← from archive.php or index.php
-  show.blade.php         ← from single.php
-pages/
-  show.blade.php         ← from page.php
-partials/
-  nav.blade.php          ← from wp_nav_menu output
-  sidebar.blade.php      ← from sidebar.php
-  post-card.blade.php    ← from template-parts/content.php
-  comments.blade.php     ← from comments.php
-  search-form.blade.php  ← from searchform.php
-errors/
-  404.blade.php          ← from 404.php
-```
-
-### Migrations (Mode B only)
-If the user chose Mode B (fresh database), plan one migration per model with fields derived from:
-- WordPress core fields: title, slug, content, excerpt, featured_image, status, published_at
-- Custom fields from `get_post_meta()` calls found in templates
-- Any ACF or custom meta boxes registered in functions.php
+Before calling any Stellify tools, plan:
 
-If the user chose Mode A (existing database), skip migrations entirely — the tables already exist.
+- **Models:** One per post type (Post, Page, plus any custom types from Step 3)
+- **Controllers:** One per model with index/show actions
+- **Routes:** Match WordPress URL structure (archive at `/`, singles at `/{slug}`, taxonomies at `/category/{slug}`)
+- **Views:** Mirror WordPress template hierarchy — layout from header+footer, index/show views per post type, partials from template-parts
+- **Migrations (Mode B only):** One per model with fields from WordPress core + any custom fields found in templates
 
 ## Step 5 — Build in Stellify (Order of Operations)
 
@@ -211,52 +160,58 @@ Translate WordPress functions to Blade:
 - `language_attributes()` → `lang="{{ str_replace('_', '-', app()->getLocale()) }}"`
 
 ### 5e. Create Blade Views
-For each WordPress template file, read the PHP and create the equivalent Blade view. **All views use `@extends('layouts.app')` and `@section('content')`.**
+For each WordPress template file, read the PHP and create the equivalent Blade view using `html_to_elements`. **All views use `@extends('layouts.app')` and `@section('content')`.**
+
+**⚠️ Multiple Root Elements:** When converting HTML with multiple root-level elements (e.g., `<header>`, `<main>`, `<footer>`), only the first root element gets attached to the route. Make separate `html_to_elements` calls for each root element.
 
 **WordPress → Blade translation guide:**
 
-The Blade column depends on which database mode was chosen. Mode A uses WordPress column names directly; Mode B uses clean Laravel names.
-
-| WordPress | Blade (Mode A — existing DB) | Blade (Mode B — fresh DB) |
-|-----------|------------------------------|---------------------------|
-| `the_title()` | `{{ $post->post_title }}` | `{{ $post->title }}` |
-| `the_content()` | `{!! $post->post_content !!}` | `{!! $post->content !!}` |
-| `the_excerpt()` | `{{ $post->post_excerpt }}` | `{{ $post->excerpt }}` |
-| `the_permalink()` | `{{ route('posts.show', $post->post_name) }}` | `{{ route('posts.show', $post->slug) }}` |
-| `the_post_thumbnail()` | via `wp_postmeta` lookup | `<img src="{{ asset('storage/' . $post->featured_image) }}" />` |
-| `the_date()` / `the_time()` | `{{ \Carbon\Carbon::parse($post->post_date)->format('d M Y') }}` | `{{ $post->published_at->format('d M Y') }}` |
-| `the_author()` | `{{ $post->author->display_name }}` | `{{ $post->author->name }}` |
-| `comments_template()` | `@include('partials.comments', ['post' => $post])` | same |
-| `get_template_part('content')` | `@include('partials.post-card', ['post' => $post])` | same |
-| `have_posts() / the_post()` | Use an `s-loop` element (see below) | same |
-| `wp_link_pages()` | `{{ $posts->links() }}` | same |
-| `get_search_form()` | `@include('partials.search-form')` | same |
-| `wp_nav_menu()` | `@include('partials.nav')` | same |
-| `get_header()` / `get_footer()` | handled by `@extends('layouts.app')` | same |
-| `esc_html()` / `esc_attr()` | `{{ }}` (Blade auto-escapes) | same |
-| `wp_kses_post()` | `{!! !!}` (for trusted HTML content) | same |
-
-**Stellify `s-loop` elements for iteration:**
-
-WordPress's "The Loop" (`have_posts() / the_post()`) requires two things in Stellify:
-
-1. **Set the element type to `s-loop`** using `update_element` with `type: "s-loop"` and `variable` set to the collection name from the controller's return array. This tells Stellify to iterate over that variable and pass each item as `$item` to child elements.
-
-2. **Write the `@foreach` in the Blade template as well.** The Blade content inside the element still needs the `@foreach` loop.
-
-Example: If the controller returns `['posts' => Post::paginate(10)]`, the element that lists posts should be updated to:
-```json
-{
-  "uuid": "<element-uuid>",
-  "data": {
-    "type": "s-loop",
-    "variable": "posts"
-  }
-}
-```
-And the Blade content inside uses `@foreach($posts as $post)` ... `@endforeach` as normal.
+Mode A uses WordPress column names; Mode B uses clean Laravel names.
+
+**IMPORTANT:** Inside `@foreach` loops, use `$item` as the loop variable. This matches the Stellify assembler's expectations for `textField`, `hrefField`, `srcField` attributes.
 
-This applies to any listing — post archives, category pages, search results, related posts, comment lists, navigation menu items, etc.
+| WordPress | Blade (Mode A) | Blade (Mode B) | Stellify Attribute |
+|-----------|----------------|----------------|-------------------|
+| `the_title()` | `{{ $item->post_title }}` | `{{ $item->title }}` | `textField: "title"` |
+| `the_content()` | `{!! $item->post_content !!}` | `{!! $item->content !!}` | statement with code |
+| `the_excerpt()` | `{{ $item->post_excerpt }}` | `{{ $item->excerpt }}` | `textField: "excerpt"` |
+| `the_permalink()` | `{{ route('posts.show', $item->post_name) }}` | `{{ route('posts.show', $item->slug) }}` | `hrefExpression: "..."` |
+| `the_date()` | `{{ $item->post_date->format('d M Y') }}` | `{{ $item->published_at->format('d M Y') }}` | statement with code |
+| `the_author()` | `{{ $item->author->display_name }}` | `{{ $item->author->name }}` | statement with code |
+| `get_template_part()` | `@include('partials.post-card', ['post' => $item])` | same | s-directive |
+| `have_posts()` | `@foreach($posts as $item)` | same | s-directive pair |
+
+**Conditional Rendering with `s-directive`:**
+
+WordPress blocks that render conditionally (like `<!-- wp:post-featured-image -->`) use `s-directive` elements. See the MCP tool documentation for the sibling pattern — create an opening directive, content elements, then a closing directive as siblings.
+
+Common WordPress conditionals to convert (use `$item` inside loops):
+- `<!-- wp:post-featured-image -->` → `@if($item->featured_image)` ... `@endif`
+- `<!-- wp:post-excerpt -->` → `@if($item->post_excerpt)` ... `@endif`
+- `<!-- wp:post-comments -->` → `@if($item->comments->count() > 0)` ... `@endif`
+- `<!-- wp:query-no-results -->` → `@if($posts->isEmpty())` ... `@endif` (outside loop)
+
+**Iteration (The Loop):**
+
+WordPress's "The Loop" (`have_posts() / the_post()`) maps to `@foreach` directives. Use `s-directive` elements for the opening `@foreach` and closing `@endforeach`.
+
+**IMPORTANT - Loop Variable:** The default loop variable is `$item`. When creating elements inside a loop:
+1. Do NOT pass raw Blade syntax to `html_to_elements` — it will be stored literally
+2. Create clean HTML first, then use `update_element` to add dynamic attributes:
+   - `textField: "title"` → outputs `{{ $item->title }}`
+   - `hrefField: "slug"` → outputs `href="{{ $item->slug }}"`
+   - `srcField: "featured_image"` → outputs `src="{{ $item->featured_image }}"`
+3. For complex expressions (route helpers, method calls), use:
+   - `hrefExpression: "{{ route('posts.show', $item->slug) }}"`
+   - `srcExpression: "{{ $item->featured_image }}"`
+4. For text with Blade code, create a statement with `create_statement_with_code`, then add its UUID to the element's `statements` array via `update_element`
+
+Example loop structure using `s-directive` siblings:
+```
+1. s-directive with statement: "@foreach($posts as $item)"
+2. article element (content to repeat)
+3. s-directive with statement: "@endforeach"
+```
 
 ### 5f. Create Partials & Components
 Convert template-parts/ files into Blade partials using `@include`. Static partials receive data via the second argument: `@include('partials.post-card', ['post' => $post])`. If a template part relies on JavaScript for interactivity (e.g. a slider, a filterable gallery, a live search form), create a Vue component instead and ensure it is registered and mounted in `app.js`.
@@ -267,18 +222,9 @@ Do not try to port WordPress CSS. Read the visual intent from the theme's CSS/th
 - WordPress navigation → `<nav class="flex items-center gap-6">`
 - WordPress post grid → `<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">`
 
-## Step 6 — Review
-
-After building everything, print a summary:
-- Database mode chosen (A or B)
-- Total models created (and which WordPress tables they map to, if Mode A)
-- Total controllers and methods
-- Total routes
-- Total Blade views and partials
-- Total Vue components (if any) and why each was needed
-- Any WordPress features that could NOT be mapped (e.g. specific plugins, shortcodes with no equivalent)
-- If Mode B: provide a SQL migration query or artisan command to copy content from the WordPress database to the new schema
-- Suggestions for manual follow-up
+## Step 6 — Review (Optional)
+
+If requested, summarize what was created and note any WordPress features that couldn't be mapped.
 
 ## Important Rules