@stellisoft/stellify-mcp 0.1.19 → 0.1.21

package/dist/index.js

@@ -197,6 +197,42 @@ const stellify = new StellifyClient({
 //   Embed: create,store,compare,nearest,search,toJSON
 //   Diff: chars,words,lines,apply,createPatch,similarity
 //
+// -----------------------------------------------------------------------------
+// COMMON PITFALLS - AVOID THESE MISTAKES
+// -----------------------------------------------------------------------------
+// 1. v-model requires ref(), NOT Form class
+//    WRONG: const form = Form.create({title: ''}) with v-model="form.title"
+//    RIGHT: const formData = ref({title: ''}) with v-model="formData.title"
+//
+// 2. List.from() returns List instance, not array - use .toArray() for v-for
+//    WRONG: notes.value = List.from(response.data)
+//    RIGHT: notes.value = List.from(response.data).toArray()
+//
+// 3. add_method_body APPENDS, doesn't replace - create new method to replace
+//
+// 4. Use 'inputType' not 'type' for HTML type attribute on elements
+//
+// 5. Statements go in 'statements' array, methods go in 'data' array in save_file
+//
+// 6. Always wire click handlers to METHOD UUIDs, not file UUIDs
+//
+// 7. For buttons in forms, set inputType: "button" to prevent auto-submit
+//
+// -----------------------------------------------------------------------------
+// ERROR HANDLING
+// -----------------------------------------------------------------------------
+// If a tool call fails, check:
+// - UUID validity: Is the file/method/element UUID correct and exists?
+// - Required fields: Did you provide all required parameters?
+// - Order of operations: Did you create the parent before the child?
+// - Array contents: Are you passing statement UUIDs to 'statements' (not 'data')?
+//
+// Common error scenarios:
+// - "File not found" → The file UUID is invalid or was deleted
+// - "Method not found" → The method UUID doesn't exist in that file
+// - "Invalid element type" → Use valid types like s-wrapper, s-input, s-form
+// - Empty response → Operation succeeded but returned no data (normal for deletes)
+//
 // =============================================================================
 // Define MCP tools
 // Stellify Framework API - full method reference for AI code generation
@@ -253,6 +289,14 @@ Use this tool when you need to:
 - Verify method names before generating code
 - Understand the full API surface
 
+IMPORTANT - List class and Vue reactivity:
+The List class methods return List instances, NOT plain arrays.
+Vue's v-for directive cannot iterate over List instances directly.
+
+When assigning to a Vue ref that will be used with v-for, call .toArray():
+- CORRECT: notes.value = List.from(response.data).toArray();
+- INCORRECT (v-for won't work): notes.value = List.from(response.data);
+
 Example response:
 {
   "Form": ["create", "set", "get", "validate", "store", "update", "delete", ...],
@@ -434,7 +478,14 @@ Example response includes:
     },
     {
         name: 'add_method_body',
-        description: 'Parse and add PHP code to a method body. Provide the method implementation code (without the function declaration). Stellify will parse it into structured statements.',
+        description: `Parse and add PHP code to a method body. Provide the method implementation code (without the function declaration). Stellify will parse it into structured statements.
+
+IMPORTANT: This APPENDS to existing method statements. To REPLACE a method's code:
+1. Create a NEW method with create_method
+2. Add body with add_method_body
+3. Update the file's 'data' array to include new method UUID (remove old one)
+4. Update any element click handlers to reference the new method UUID
+5. Optionally delete the old method with delete_method`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -456,15 +507,24 @@ Example response includes:
     },
     {
         name: 'save_method',
-        description: `Update an existing method's properties (name, visibility, returnType, nullable, parameters).
+        description: `Update an existing method's properties (name, visibility, returnType, nullable, parameters, data).
 
 Use this to modify a method after creation. For updating the method body, use add_method_body instead.
 
-Example:
+Parameters:
+- data: Array of statement UUIDs that form the method body. Use this to reorder statements or remove unwanted statements from the method.
+
+Example - Update return type:
 {
   "uuid": "method-uuid",
   "returnType": "object",
   "nullable": true
+}
+
+Example - Remove duplicate/unwanted statements:
+{
+  "uuid": "method-uuid",
+  "data": ["statement-uuid-1", "statement-uuid-2"]  // Only keep these statements
 }`,
         inputSchema: {
             type: 'object',
@@ -499,6 +559,11 @@ Example:
                     description: 'Array of parameter clause UUIDs',
                     items: { type: 'string' },
                 },
+                data: {
+                    type: 'array',
+                    description: 'Array of statement UUIDs that form the method body. Use to reorder or remove statements.',
+                    items: { type: 'string' },
+                },
             },
             required: ['uuid'],
         },
@@ -520,6 +585,34 @@ Example:
             },
         },
     },
+    {
+        name: 'delete_method',
+        description: 'Delete a method from a file by UUID. This permanently removes the method and all its code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: {
+                    type: 'string',
+                    description: 'UUID of the method to delete',
+                },
+            },
+            required: ['uuid'],
+        },
+    },
+    {
+        name: 'get_method',
+        description: 'Get a method by UUID. Returns the method data including its parameters and body.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: {
+                    type: 'string',
+                    description: 'UUID of the method to retrieve',
+                },
+            },
+            required: ['uuid'],
+        },
+    },
     {
         name: 'search_files',
         description: 'Search for files in the project by name or type',
@@ -562,7 +655,16 @@ EXAMPLE - Create an API route wired to a controller:
 WORKFLOW for API endpoints:
 1. Create controller with create_file (type: "controller") or create_resources
 2. Create methods with create_method + add_method_body
-3. Create route with create_route, passing controller and controller_method UUIDs`,
+3. Create route with create_route, passing controller and controller_method UUIDs
+
+ROUTE PARAMETERS:
+Route parameters like {id} in "/api/notes/{id}" are automatically injected into controller method parameters when the parameter name matches.
+
+Example: Route "/api/notes/{id}" (DELETE) with controller method destroy($id)
+The $id parameter receives the value from the URL automatically.
+
+When creating methods with create_method, include the parameter:
+{ "name": "destroy", "parameters": [{ "name": "id", "datatype": "int" }] }`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -694,6 +796,22 @@ Available fields:
             required: ['uuid'],
         },
     },
+    {
+        name: 'delete_route',
+        description: `Delete a route/page from the project by UUID. This permanently removes the route.
+
+WARNING: This is destructive and cannot be undone. Any elements attached to this route will become orphaned.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: {
+                    type: 'string',
+                    description: 'UUID of the route to delete',
+                },
+            },
+            required: ['uuid'],
+        },
+    },
     {
         name: 'search_routes',
         description: `Search for routes/pages in the project by name. Use this to find existing routes before creating new ones.
@@ -727,7 +845,17 @@ Valid element types:
 - HTML5: s-wrapper, s-input, s-form, s-svg, s-shape, s-media, s-iframe
 - Components: s-loop, s-transition, s-freestyle, s-motion
 - Blade: s-directive
-- Shadcn/ui: s-chart, s-table, s-combobox, s-accordion, s-calendar, s-contiguous`,
+- Shadcn/ui: s-chart, s-table, s-combobox, s-accordion, s-calendar, s-contiguous
+
+s-loop ELEMENT TYPE:
+Use s-loop for elements that should render with v-for directive.
+Required attributes (set via update_element after creation):
+- loop: The v-for expression (e.g., "note in notes", "item in items")
+- key: The :key binding (e.g., "note.id", "item.id")
+
+Example: After creating s-loop, update it with:
+{ "tag": "div", "loop": "note in notes", "key": "note.id", "classes": ["card", "p-4"] }
+Generates: <div class="card p-4" v-for="note in notes" :key="note.id">`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -767,6 +895,19 @@ Special Stellify fields:
 - classes: CSS classes array ["class1", "class2"]
 - text: Element text content
 
+V-MODEL BINDING (for s-input elements):
+- variable: Set this to bind v-model to a reactive variable
+- Example: { "variable": "formData.title" } renders as <input v-model="formData.title" />
+- IMPORTANT: The variable must reference a Vue ref() object, NOT a Form class instance
+- CORRECT: const formData = ref({ title: '', content: '' }) → v-model="formData.title"
+- WRONG: const form = Form.create({ title: '' }) → Form class is not reactive for v-model
+
+INPUT TYPE ATTRIBUTE:
+- Use 'inputType' (not 'type') to set the HTML type attribute on buttons/inputs
+- Example: { "inputType": "button" } renders as type="button"
+- Example: { "inputType": "textarea" } renders as <textarea> instead of <input>
+- For buttons inside <form> elements, always set inputType: "button" to prevent form submission on click
+
 EVENT HANDLERS (set value to method UUID):
 - click: @click - buttons, links, any clickable element
 - submit: @submit - form submission
@@ -779,6 +920,11 @@ EVENT HANDLERS (set value to method UUID):
 - mouseenter: @mouseenter - mouse enters element
 - mouseleave: @mouseleave - mouse leaves element
 
+EVENT HANDLER ARGUMENTS:
+When wiring click handlers that need arguments (e.g., from v-for loops), use clickArgs:
+- { "click": "delete-method-uuid", "clickArgs": "item.id" } → @click="deleteItem(item.id)"
+- { "click": "edit-method-uuid", "clickArgs": "item" } → @click="editItem(item)"
+
 Example wiring a button click to a method:
 {
   "uuid": "button-element-uuid",
@@ -898,6 +1044,12 @@ Text like {{ count }} is automatically detected and:
 For Vue components: Omit 'page' - elements are created standalone for the component template.
 For page content: Provide 'page' (route UUID) to attach elements directly.
 
+ICONS - Best practices:
+- Prefer SVG icons or icon fonts (Heroicons, Font Awesome) over emoji
+- Use HTML entities where available (e.g., &times; for ×)
+- Avoid raw emoji characters as they may have encoding issues
+- Example: <button><svg>...</svg></button> instead of <button>🗑️</button>
+
 IMPORTANT: Use the returned root element UUID in save_file's template array.`,
         inputSchema: {
             type: 'object',
@@ -951,7 +1103,7 @@ Use cases:
 - PHP: Class properties, use statements, constants
 - JS/Vue: Variable declarations, imports, reactive refs
 
-For Vue components, include the returned statement UUID in save_file's 'data' array.`,
+For Vue components, include the returned statement UUID in save_file's 'statements' array (NOT 'data' - that's for methods).`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -994,6 +1146,38 @@ Examples:
             required: ['file', 'statement', 'code'],
         },
     },
+    {
+        name: 'delete_statement',
+        description: 'Delete a statement from a file by UUID. This permanently removes the statement (import, variable, ref, etc.).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: {
+                    type: 'string',
+                    description: 'UUID of the statement to delete',
+                },
+            },
+            required: ['uuid'],
+        },
+    },
+    {
+        name: 'save_statement',
+        description: 'Update an existing statement. Use this to modify statement properties after creation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: {
+                    type: 'string',
+                    description: 'UUID of the statement to update',
+                },
+                data: {
+                    type: 'object',
+                    description: 'Statement data to update',
+                },
+            },
+            required: ['uuid'],
+        },
+    },
     {
         name: 'save_file',
         description: `Save/update a file with its full configuration. This FINALIZES the file after create_file.
@@ -1063,6 +1247,11 @@ For <script setup> content, the order in statements array determines output orde
                     items: { type: 'string' },
                     description: 'Array of file UUIDs to import',
                 },
+                models: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of model file UUIDs that this controller uses (required for model class loading)',
+                },
             },
             required: ['uuid', 'name', 'type'],
         },
@@ -1081,6 +1270,22 @@ For <script setup> content, the order in statements array determines output orde
             required: ['uuid'],
         },
     },
+    {
+        name: 'delete_file',
+        description: `Delete a file from the project by UUID. This permanently removes the file and all its methods/statements.
+
+WARNING: This is destructive and cannot be undone. Make sure the file is not referenced elsewhere before deleting.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: {
+                    type: 'string',
+                    description: 'UUID of the file to delete',
+                },
+            },
+            required: ['uuid'],
+        },
+    },
     {
         name: 'get_directory',
         description: `Get a directory by UUID to see its contents.
@@ -1119,6 +1324,24 @@ IMPORTANT: Check existing directories first using get_project and get_directory
             required: ['name'],
         },
     },
+    {
+        name: 'save_directory',
+        description: 'Update an existing directory. Use this to rename or modify directory properties.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: {
+                    type: 'string',
+                    description: 'UUID of the directory to update',
+                },
+                name: {
+                    type: 'string',
+                    description: 'New directory name',
+                },
+            },
+            required: ['uuid'],
+        },
+    },
     {
         name: 'broadcast_element_command',
         description: `Broadcast a real-time command to update UI elements via WebSocket.
@@ -1605,7 +1828,7 @@ Example module names: "user-auth", "blog-posts", "product-catalog", "order-manag
 // Create MCP server
 const server = new Server({
     name: 'stellify-mcp',
-    version: '0.1.0',
+    version: '0.1.21',
 }, {
     capabilities: {
         tools: {},
@@ -1742,6 +1965,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'delete_method': {
+                const { uuid } = args;
+                const result = await stellify.deleteMethod(uuid);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Deleted method ${uuid}`,
+                                data: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'get_method': {
+                const { uuid } = args;
+                const result = await stellify.getMethod(uuid);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                method: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'search_files': {
                 const result = await stellify.searchFiles(args);
                 return {
@@ -1805,6 +2059,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'delete_route': {
+                const { uuid } = args;
+                const result = await stellify.deleteRoute(uuid);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Deleted route ${uuid}`,
+                                data: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'search_routes': {
                 const result = await stellify.searchRoutes(args);
                 const routes = result.data || result;
@@ -1982,6 +2252,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'delete_statement': {
+                const { uuid } = args;
+                const result = await stellify.deleteStatement(uuid);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Deleted statement ${uuid}`,
+                                data: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'save_statement': {
+                const { uuid, ...data } = args;
+                const result = await stellify.saveStatement(uuid, data);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Saved statement ${uuid}`,
+                                statement: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'save_file': {
                 const { uuid, ...data } = args;
                 const result = await stellify.saveFile(uuid, { uuid, ...data });
@@ -2013,6 +2315,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'delete_file': {
+                const { uuid } = args;
+                const result = await stellify.deleteFile(uuid);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Deleted file ${uuid}`,
+                                data: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'get_directory': {
                 const result = await stellify.getDirectory(args.uuid);
                 const dirData = result.data || result;
@@ -2047,6 +2365,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'save_directory': {
+                const { uuid, ...data } = args;
+                const result = await stellify.saveDirectory(uuid, data);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Saved directory ${uuid}`,
+                                directory: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'broadcast_element_command': {
                 const result = await stellify.broadcastElementCommand(args);
                 return {

package/dist/stellify-client.d.ts

@@ -76,17 +76,21 @@ 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>;
     getMethod(method: string): Promise<any>;
     saveMethod(method: string, data: any): Promise<any>;
+    deleteMethod(method: string): Promise<any>;
     createStatement(params: {
         file?: string;
         method?: string;
     }): Promise<any>;
     getStatement(statement: string): Promise<any>;
+    deleteStatement(statement: string): Promise<any>;
     saveStatement(statement: string, data: any): Promise<any>;
     createRoute(params: CreateRouteParams): Promise<any>;
     getRoute(route: string): Promise<any>;
     saveRoute(route: string, data: any): Promise<any>;
+    deleteRoute(route: string): Promise<any>;
     searchRoutes(params: {
         search?: string;
         type?: string;

package/dist/stellify-client.js

@@ -43,6 +43,10 @@ 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}`);
+        return response.data;
+    }
     async getMethod(method) {
         const response = await this.client.get(`/method/${method}`);
         return response.data;
@@ -51,6 +55,10 @@ 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}`);
+        return response.data;
+    }
     async createStatement(params) {
         const response = await this.client.post('/statement', params);
         return response.data;
@@ -59,6 +67,10 @@ 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}`);
+        return response.data;
+    }
     async saveStatement(statement, data) {
         const response = await this.client.put(`/statement/${statement}`, data);
         return response.data;
@@ -75,6 +87,10 @@ export class StellifyClient {
         const response = await this.client.put(`/route/${route}`, { uuid: route, ...data });
         return response.data;
     }
+    async deleteRoute(route) {
+        const response = await this.client.delete(`/route/${route}`);
+        return response.data;
+    }
     async searchRoutes(params) {
         const response = await this.client.get('/route/search', { params });
         return response.data;

package/package.json

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