@stellisoft/stellify-mcp 0.1.23 → 0.1.25

package/dist/index.js

@@ -294,12 +294,13 @@ IMPORTANT: This APPENDS to existing method statements. To REPLACE a method's cod
     },
     {
         name: 'save_method',
-        description: `Update an existing method's properties (name, visibility, returnType, nullable, parameters, data).
+        description: `Update an existing method's properties (name, visibility, returnType, nullable, parameters, data, is_async).
 
 Use this to modify a method after creation. For updating the method body, use add_method_body instead.
 
 Parameters:
 - data: Array of statement UUIDs that form the method body. Use this to reorder statements or remove unwanted statements from the method.
+- is_async: Set to true for JavaScript/Vue methods that use await.
 
 Example - Update return type:
 {
@@ -308,6 +309,12 @@ Example - Update return type:
   "nullable": true
 }
 
+Example - Mark method as async (for methods using await):
+{
+  "uuid": "method-uuid",
+  "is_async": true
+}
+
 Example - Remove duplicate/unwanted statements:
 {
   "uuid": "method-uuid",
@@ -351,6 +358,10 @@ Example - Remove duplicate/unwanted statements:
                     description: 'Array of statement UUIDs that form the method body. Use to reorder or remove statements.',
                     items: { type: 'string' },
                 },
+                is_async: {
+                    type: 'boolean',
+                    description: 'Whether the method is async (JavaScript/Vue only). Set to true for methods that use await.',
+                },
             },
             required: ['uuid'],
         },
@@ -374,16 +385,20 @@ Example - Remove duplicate/unwanted statements:
     },
     {
         name: 'delete_method',
-        description: 'Delete a method from a file by UUID. This permanently removes the method and all its code.',
+        description: 'Delete a method from a file by UUID. This permanently removes the method and all its code. Requires both the file UUID and method UUID.',
         inputSchema: {
             type: 'object',
             properties: {
+                file: {
+                    type: 'string',
+                    description: 'UUID of the file containing the method (required)',
+                },
                 uuid: {
                     type: 'string',
                     description: 'UUID of the method to delete',
                 },
             },
-            required: ['uuid'],
+            required: ['file', 'uuid'],
         },
     },
     {
@@ -841,12 +856,20 @@ Examples:
         inputSchema: {
             type: 'object',
             properties: {
+                file: {
+                    type: 'string',
+                    description: 'UUID of the file containing the statement',
+                },
+                method: {
+                    type: 'string',
+                    description: 'UUID of the method containing the statement (use "file" for file-level statements)',
+                },
                 uuid: {
                     type: 'string',
                     description: 'UUID of the statement to delete',
                 },
             },
-            required: ['uuid'],
+            required: ['file', 'method', 'uuid'],
         },
     },
     {
@@ -895,7 +918,12 @@ Vue SFC example:
     statements: [importStmtUuid, refStmtUuid]  // Statement UUIDs (imports, refs)
   })
 
-For <script setup> content, the order in statements array determines output order.`,
+For <script setup> content, the order in statements array determines output order.
+
+DEPENDENCY RESOLUTION (includes array):
+The 'includes' array accepts BOTH UUIDs and namespace strings.
+Namespace strings (e.g., "Illuminate\\Http\\JsonResponse") are automatically resolved to UUIDs.
+This works the same as create_file's dependency resolution.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -934,7 +962,7 @@ For <script setup> content, the order in statements array determines output orde
                 includes: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: 'Array of file UUIDs to import',
+                    description: 'Array of file UUIDs OR namespace strings to import. Namespace strings (e.g., "Illuminate\\\\Http\\\\JsonResponse") are auto-resolved to UUIDs.',
                 },
                 models: {
                     type: 'array',
@@ -967,12 +995,16 @@ WARNING: This is destructive and cannot be undone. Make sure the file is not ref
         inputSchema: {
             type: 'object',
             properties: {
+                directory: {
+                    type: 'string',
+                    description: 'UUID of the directory containing the file (get from get_project directories array or get_file response)',
+                },
                 uuid: {
                     type: 'string',
                     description: 'UUID of the file to delete',
                 },
             },
-            required: ['uuid'],
+            required: ['directory', 'uuid'],
         },
     },
     {
@@ -1078,6 +1110,8 @@ Creates: Model ($fillable, $casts, relationships), Controller (CRUD actions), Se
 
 IMPORTANT: Routes are NOT auto-wired. After creation, use create_route with the returned controller UUID and method UUIDs.
 
+IMPORTANT: After creation, check the controller methods for return types and parameter types. If methods use classes not already in includes (e.g., JsonResponse), add those class UUIDs to the controller's includes via save_file.
+
 Response includes controller.methods array with {uuid, name} for each action (index, store, update, destroy).`,
         inputSchema: {
             type: 'object',
@@ -1396,18 +1430,30 @@ Key concepts:
 
 1. get_project → find 'js' directory UUID (or create it)
 2. create_file → type='js', extension='vue' for the component
-3. Create statements for imports:
-   - "import { ref } from 'vue';" (REQUIRED for ref())
-   - "import { Http, List } from 'stellify-framework';" (for Stellify classes)
+3. **Create a template route** for editor access:
+   - create_route with name like "notes-template" or "component-name-template"
+   - This route is NOT where the component displays - it's only for accessing the template in the Stellify visual editor
+   - The actual display route (e.g., "/notes") will have just \`<div id="app"></div>\` where Vue mounts
+4. Create statements for imports:
+   - "import { ref, onMounted } from 'vue';" (REQUIRED for ref() and lifecycle hooks)
+   - "import { Http } from 'stellify-framework';" (for API calls)
    NOTE: The npm package is "stellify-framework" (NOT @stellify/core)
-4. Create statements for data: "const count = ref(0);"
-5. create_method + add_method_body → functions
-6. html_to_elements → template (no 'page' param for components)
-7. update_element → wire click handlers to method UUIDs
-8. save_file with: extension='vue', template=[elementUuid], data=[methodUuids], statements=[importUuids, refUuids]
-9. **MANDATORY: Create app.js entry file** (see "CRITICAL: JavaScript Entry File" section below)
-10. Create web route for the page
-11. **MANDATORY: Add a div with id="app"** to the page using html_to_elements:
+5. Create statements for reactive data: "const notes = ref([]);"
+6. create_method + add_method_body for functions. Example fetchNotes body:
+   \`\`\`
+   const response = await Http.get('/api/notes');
+   notes.value = response.data || [];
+   \`\`\`
+   **THEN call save_method with is_async: true** (required for methods using await)
+7. Create statement for onMounted: "onMounted(fetchNotes);" (direct method reference, no arrow wrapper)
+8. html_to_elements → template **with page=templateRouteUuid** (attach to the template route for editor access)
+9. update_element → wire click handlers to method UUIDs
+10. save_file with: extension='vue', template=[elementUuid], data=[methodUuids], statements=[importUuids, refUuids, onMountedUuid]
+    - **data = method UUIDs only** (functions)
+    - **statements = statement UUIDs** (imports, refs, onMounted)
+11. **MANDATORY: Create app.js entry file** (see "CRITICAL: JavaScript Entry File" section below)
+12. Create web route for the display page (e.g., "/notes")
+13. **MANDATORY: Add a div with id="app"** to the display page using html_to_elements:
     - html_to_elements with page=routeUuid and elements='<div id="app"></div>'
     - This is where Vue mounts the component. Without it, nothing renders!
 
@@ -1416,8 +1462,33 @@ Key concepts:
 Use for SHOW/DISPLAY/DEMONSTRATE requests - sends instant WebSocket updates to browser.
 Use html_to_elements/update_element for permanent/saved changes.
 
+## CRITICAL: Http Response Handling (Most Common Error)
+
+**This is the #1 cause of "notes not displaying" bugs.**
+
+When fetching data from API endpoints, stellify-framework's Http class returns the JSON body DIRECTLY - it does NOT wrap responses like axios does.
+
+Laravel pagination returns: \`{ data: [...items], current_page: 1, per_page: 15, ... }\`
+
+Since Http.get() returns this JSON directly (no axios wrapper), you access the array with ONE \`.data\`:
+
+\`\`\`javascript
+// CORRECT - Http returns JSON directly, .data gets the paginated array
+const response = await Http.get('/api/notes');
+notes.value = response.data || [];
+
+// WRONG - Double .data (axios habit) - returns undefined, notes stay empty!
+const response = await Http.get('/api/notes');
+notes.value = response.data.data || [];  // BUG: response.data.data is undefined
+\`\`\`
+
+**Why this mistake happens:** With axios, you write \`response.data.data\` because axios wraps the HTTP response (\`response.data\` unwraps axios, then \`.data\` gets the pagination array). Stellify's Http skips the wrapper, so you only need ONE \`.data\`.
+
+**Symptom:** Notes exist in database, API returns them, but UI shows empty list or "No notes yet" message.
+
 ## Common Pitfalls
 
+- **Vue template editor access:** Templates MUST be attached to a route for users to edit them in the visual editor. Create a separate "template route" (e.g., "notes-template") and pass its UUID to html_to_elements. This is different from the display route where the component renders.
 - **Stellify imports:** Use "stellify-framework" package (NOT @stellify/core)
   CORRECT: import { Http, List, Form } from 'stellify-framework';
   WRONG: import { Http } from '@stellify/core';
@@ -1426,6 +1497,44 @@ Use html_to_elements/update_element for permanent/saved changes.
 - add_method_body APPENDS, doesn't replace - create new method to replace
 - 'data' array = method UUIDs, 'statements' array = import/variable UUIDs
 - For buttons in forms, set inputType: "button" to prevent auto-submit
+- **Async methods:** Methods using await MUST be marked async via save_method with is_async: true
+- **onMounted:** Use direct method reference: "onMounted(fetchNotes);"
+  The assembler automatically outputs lifecycle hooks after method definitions.
+
+## CRITICAL: Nullable Refs and v-if Guards
+
+**This causes "Cannot read properties of null" errors.**
+
+When using a nullable ref (e.g., \`const editingNote = ref(null)\`) with v-model or property access in templates, you MUST guard with an explicit v-if that checks the ref is not null.
+
+**WRONG - v-else does NOT protect against null evaluation:**
+\`\`\`html
+<template v-if="!editingItem">
+  <!-- view mode -->
+</template>
+<template v-else>
+  <input v-model="editingItem.title" />  <!-- ERROR: editingItem could be null -->
+</template>
+\`\`\`
+
+**CORRECT - explicit v-if with null check:**
+\`\`\`html
+<template v-if="!editingItem || editingItem.id !== item.id">
+  <!-- view mode -->
+</template>
+<template v-if="editingItem && editingItem.id === item.id">
+  <input v-model="editingItem.title" />  <!-- Safe: editingItem is guaranteed non-null -->
+</template>
+\`\`\`
+
+**Why v-else fails:** Vue evaluates v-model bindings during compilation/render setup, before the v-else condition is fully applied. The explicit v-if with \`editingItem &&\` ensures the binding is only evaluated when the ref exists.
+
+**Inline editing pattern (CRUD apps):**
+1. Create ref: \`const editingItem = ref(null);\`
+2. View template: \`v-if="!editingItem || editingItem.id !== item.id"\`
+3. Edit template: \`v-if="editingItem && editingItem.id === item.id"\` (NOT v-else!)
+4. Start editing: \`editingItem.value = { ...item };\`
+5. Cancel/save: \`editingItem.value = null;\`
 
 ## Framework Capabilities (Libraries/Packages)
 
@@ -1468,25 +1577,24 @@ Modules are auto-created if they don't exist. This helps users see all code rela
 **You MUST have a JS entry file to register Vue components for use on pages.**
 
 ### First component in a project:
-1. Create app.js in the 'js' directory:
-   - create_file with type='js', extension='js', name='app'
-2. Add statements:
+1. Create app.js in the 'js' directory with the component in includes array:
+   - create_file with type='js', extension='js', name='app', includes=[component-file-uuid]
+2. Add statements for NAMED imports only:
    - "import { createApp } from 'vue';"
-   - "import NotesApp from './NotesApp.vue';"
    - "createApp(NotesApp).mount('#app');"
-3. save_file with all statement UUIDs
+   NOTE: The component import (NotesApp) is handled by the includes array, NOT a statement!
+3. save_file with statement UUIDs
 
 ### Adding more components (app.js already exists):
 1. **search_files** for "app" to find existing app.js
-2. **get_file** to retrieve current statements
-3. Add ONLY the new import statement:
-   - "import Counter from './Counter.vue';"
+2. **get_file** to retrieve current includes and statements
+3. Add the new component UUID to the includes array via save_file
 4. Update the mount code to register the new component:
    - Create new statement: "app.component('Counter', Counter);"
-   - Or recreate the initialization to include all components
-5. save_file with updated statements array
+5. save_file with updated includes and statements arrays
 
 **DO NOT create duplicate app.js files or duplicate createApp imports!**
+**DO NOT use statements for file imports - use the includes array!**
 
 ### Page mount point (div#app):
 Each page that uses Vue components needs a \`<div id="app"></div>\`.
@@ -1496,17 +1604,13 @@ Each page that uses Vue components needs a \`<div id="app"></div>\`.
 
 **Without app.js AND div#app, Vue components will NOT render!**
 
-Example app.js with multiple components:
-\`\`\`javascript
-import { createApp } from 'vue';
-import NotesApp from './NotesApp.vue';
-import Counter from './Counter.vue';
-
-const app = createApp({});
-app.component('NotesApp', NotesApp);
-app.component('Counter', Counter);
-app.mount('#app');
-\`\`\`
+### Import types summary:
+- **File imports (components, classes):** Use \`includes\` array with file UUIDs
+- **Named imports (vue, stellify-framework):** Use statements with add_statement_code
+
+Example app.js structure:
+- includes: [notesAppFileUuid, counterFileUuid]
+- statements: ["import { createApp } from 'vue';", "const app = createApp({});", "app.component('NotesApp', NotesApp);", "app.component('Counter', Counter);", "app.mount('#app');"]
 
 ## Efficiency Tips
 
@@ -1517,7 +1621,7 @@ app.mount('#app');
 // Create MCP server
 const server = new Server({
     name: 'stellify-mcp',
-    version: '0.1.23',
+    version: '0.1.25',
 }, {
     capabilities: {
         tools: {},
@@ -1655,15 +1759,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'delete_method': {
-                const { uuid } = args;
-                const result = await stellify.deleteMethod(uuid);
+                const { file, uuid } = args;
+                const result = await stellify.deleteMethod(file, uuid);
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
                                 success: true,
-                                message: `Deleted method ${uuid}`,
+                                message: `Deleted method ${uuid} from file ${file}`,
                                 data: result,
                             }, null, 2),
                         },
@@ -1942,8 +2046,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'delete_statement': {
-                const { uuid } = args;
-                const result = await stellify.deleteStatement(uuid);
+                const { file, method, uuid } = args;
+                const result = await stellify.deleteStatement(file, method, uuid);
                 return {
                     content: [
                         {
@@ -2005,15 +2109,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'delete_file': {
-                const { uuid } = args;
-                const result = await stellify.deleteFile(uuid);
+                const { directory, uuid } = args;
+                const result = await stellify.deleteFile(directory, uuid);
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
                                 success: true,
-                                message: `Deleted file ${uuid}`,
+                                message: `Deleted file ${uuid} from directory ${directory}`,
                                 data: result,
                             }, null, 2),
                         },

package/dist/stellify-client.d.ts

@@ -76,16 +76,16 @@ export declare class StellifyClient {
     searchFiles(params: SearchFilesParams): Promise<any>;
     getFile(file: string): Promise<any>;
     saveFile(file: string, data: any): Promise<any>;
-    deleteFile(file: string): Promise<any>;
+    deleteFile(directory: string, file: string): Promise<any>;
     getMethod(method: string): Promise<any>;
     saveMethod(method: string, data: any): Promise<any>;
-    deleteMethod(method: string): Promise<any>;
+    deleteMethod(file: string, method: string): Promise<any>;
     createStatement(params: {
         file?: string;
         method?: string;
     }): Promise<any>;
     getStatement(statement: string): Promise<any>;
-    deleteStatement(statement: string): Promise<any>;
+    deleteStatement(file: string, method: string, statement: string): Promise<any>;
     saveStatement(statement: string, data: any): Promise<any>;
     createRoute(params: CreateRouteParams): Promise<any>;
     getRoute(route: string): Promise<any>;

package/dist/stellify-client.js

@@ -43,8 +43,8 @@ export class StellifyClient {
         const response = await this.client.put(`/file/${file}`, data);
         return response.data;
     }
-    async deleteFile(file) {
-        const response = await this.client.delete(`/file/${file}`);
+    async deleteFile(directory, file) {
+        const response = await this.client.delete(`/file/${directory}/${file}`);
         return response.data;
     }
     async getMethod(method) {
@@ -55,8 +55,8 @@ export class StellifyClient {
         const response = await this.client.put(`/method/${method}`, data);
         return response.data;
     }
-    async deleteMethod(method) {
-        const response = await this.client.delete(`/method/${method}`);
+    async deleteMethod(file, method) {
+        const response = await this.client.delete(`/method/${file}/${method}`);
         return response.data;
     }
     async createStatement(params) {
@@ -67,8 +67,8 @@ export class StellifyClient {
         const response = await this.client.get(`/statement/${statement}`);
         return response.data;
     }
-    async deleteStatement(statement) {
-        const response = await this.client.delete(`/statement/${statement}`);
+    async deleteStatement(file, method, statement) {
+        const response = await this.client.delete(`/statement/${file}/${method}/${statement}`);
         return response.data;
     }
     async saveStatement(statement, data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellisoft/stellify-mcp",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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.23",
+  "version": "0.1.25",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@stellisoft/stellify-mcp",
-      "version": "0.1.23",
+      "version": "0.1.25",
       "transport": {
         "type": "stdio"
       },