@stellisoft/stellify-mcp 0.1.30 → 0.1.32

package/dist/index.js

@@ -89,7 +89,11 @@ const tools = [
 For PHP: type='class', 'model', 'controller', or 'middleware'.
 For Vue: type='js', extension='vue'. Auto-creates app.js and template route.
 
-Pass 'includes' array for framework class dependencies (auto-resolved to UUIDs). Use 'models' array in save_file for project models.`,
+Pass 'includes' array for framework class dependencies (auto-resolved to UUIDs). Use 'models' array in save_file for project models.
+
+**IMPORTANT - Check appJs response for Vue components:**
+- If \`appJs.action_required === "create_or_select_mount_file"\`: No mount file exists. You MUST ask the user if they want to create a new app.js mount file before proceeding.
+- If \`appJs.action_required === "register_component"\`: Mount file exists but component isn't registered. Call save_file on the mount file to add the component UUID to its includes array.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -164,12 +168,12 @@ Pass 'includes' array for framework class dependencies (auto-resolved to UUIDs).
                 },
                 parameters: {
                     type: 'array',
-                    description: 'Method parameters (created as clauses)',
+                    description: 'Method parameters (created as clauses). Include datatype for TypeScript annotations.',
                     items: {
                         type: 'object',
                         properties: {
                             name: { type: 'string', description: 'Parameter name' },
-                            datatype: { type: 'string', description: 'Data type' },
+                            datatype: { type: 'string', description: 'TypeScript type (e.g., "number", "string", "MouseEvent", "User"). Outputs as: (param: Type)' },
                             type: { type: 'string', description: 'Clause type (default: variable)' },
                             value: { type: 'string', description: 'Default value' },
                         },
@@ -210,6 +214,8 @@ Pass 'includes' array for framework class dependencies (auto-resolved to UUIDs).
 
 **Nested code is handled correctly.** The parser tracks brace/bracket/paren depth and only splits on semicolons at the top level. Arrow functions with block bodies, computed properties, and other nested constructs work as single statements.
 
+Pass 'types' to specify TypeScript types for variables declared in the code.
+
 IMPORTANT: This APPENDS to existing method statements. To REPLACE a method's code entirely:
 1. Create a NEW method with create_method (with body parameter)
 2. Update the file's 'data' array to include new method UUID (remove old one)
@@ -230,6 +236,11 @@ IMPORTANT: This APPENDS to existing method statements. To REPLACE a method's cod
                     type: 'string',
                     description: 'PHP code for the method body (just the statements, no function declaration). Example: "return $a + $b;"',
                 },
+                types: {
+                    type: 'object',
+                    description: 'Map of variable names to their base TypeScript types (e.g., { "result": "Todo" }). The assembler infers full types from code structure.',
+                    additionalProperties: { type: 'string' },
+                },
             },
             required: ['file', 'method', 'code'],
         },
@@ -515,7 +526,7 @@ Use this to look up a route you created or to find existing routes in the projec
         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.`,
+WARNING: This is destructive and cannot be undone. Any elements attached to this route will be deleted also.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -563,8 +574,7 @@ Use the returned UUID with html_to_elements (page parameter) or get_route for fu
                     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-chart', 's-table', 's-combobox', 's-accordion', 's-calendar', 's-contiguous'
+                        's-directive'
                     ],
                     description: 'Element type - must be one of the valid Stellify element types',
                 },
@@ -741,7 +751,12 @@ Prefer SVG icons over emoji (encoding issues).`,
     },
     {
         name: 'create_statement_with_code',
-        description: `Create a statement with code in one call. Preferred over two-step create_statement + add_statement_code.`,
+        description: `Create a statement with code in one call. Preferred over two-step create_statement + add_statement_code.
+
+Pass 'types' to specify TypeScript types for variables. The assembler infers the full type from code structure:
+- \`ref([])\` + type "Todo" → outputs \`const todos: Ref<Todo[]>\`
+- \`ref(0)\` + type "number" → outputs \`const count: Ref<number>\`
+- \`reactive({})\` + type "State" → outputs \`const state: State\``,
         inputSchema: {
             type: 'object',
             properties: {
@@ -757,6 +772,11 @@ Prefer SVG icons over emoji (encoding issues).`,
                     type: 'string',
                     description: 'UUID of the method to add the statement to (optional, for method body statements)',
                 },
+                types: {
+                    type: 'object',
+                    description: 'Map of variable names to their base TypeScript types (e.g., { "todos": "Todo", "count": "number" }). The assembler infers Ref<>, arrays, etc. from the code structure.',
+                    additionalProperties: { type: 'string' },
+                },
             },
             required: ['file', 'code'],
         },
@@ -874,13 +894,18 @@ Required: uuid, name, type. For significant changes, include context fields: sum
                 includes: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: 'Framework class UUIDs or namespaces. Use models array for project models.',
+                    description: 'File UUIDs for local imports (e.g., Vue components imported by app.js) AND framework class UUIDs/namespaces. CRITICAL: For JS mount files, add imported Vue component UUIDs here or they won\'t be bundled. Use models array for project models.',
                 },
                 models: {
                     type: 'array',
                     items: { type: 'string' },
                     description: 'Project model UUIDs (auto-namespaced). Do NOT duplicate in includes.',
                 },
+                frameworkImports: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Stellify framework modules to import (e.g., ["Http", "Form", "Collection"]). Auto-generates: import { Http, Form, Collection } from \'stellify-framework\';',
+                },
                 summary: {
                     type: 'string',
                     description: 'Context: What this file does and why it exists',
@@ -1348,141 +1373,59 @@ Use this to discover what patterns are available before building UI components.`
             properties: {},
         },
     },
+    {
+        name: 'get_assembled_code',
+        description: `Get the assembled source code for a file. Returns the actual Vue SFC or PHP class as it would be rendered.
+
+Use this after save_file to verify the component was built correctly:
+- Check that all methods are included
+- Verify @click handlers are wired to methods
+- Confirm imports and reactive state are present
+- Spot any missing pieces before deployment`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: {
+                    type: 'string',
+                    description: 'UUID of the file to get assembled code for',
+                },
+            },
+            required: ['uuid'],
+        },
+    },
 ];
 // Server instructions for tool discovery (used by MCP Tool Search)
-const SERVER_INSTRUCTIONS = `Stellify is a coding platform where you code alongside AI on a codebase maintained and curated by AI. Build Laravel, stellify-framework, and Vue.js applications.
-
-Use Stellify tools when:
-- Building PHP controllers, models, middleware, or classes
-- Creating Vue.js components with reactive state and UI
-- Managing UI elements (HTML stored as structured JSON)
-- Working with a Stellify project (user will mention "Stellify" or provide project UUID)
-
-Key concepts:
-- Code is stored as structured JSON, enabling surgical AI edits at the statement level
-- Files contain methods and statements (code outside methods)
-- Vue components link to UI elements via the 'template' field
-- Event handlers (click, submit) wire UI elements to methods by UUID
-
-## General Workflow (all file types)
-
-1. create_file → empty shell, returns file UUID
-2. create_method → signature only, returns method UUID
-3. add_method_body → implementation code
-4. create_statement + add_statement_code → for imports, variables, refs
-5. save_file → finalize with template/data/statements arrays
+const SERVER_INSTRUCTIONS = `Stellify is a coding platform where code is stored as structured JSON in a database, enabling surgical AI edits. Build Laravel (PHP) applications with StellifyJS (a front-end Laravel extension framework that has adaptors for reactive frameworks such as Vue, React and library wrappers for chart.js etc.).
 
-## Vue Component Workflow
+## Architecture
 
-1. get_project → find 'js' directory UUID (or create it)
-2. create_file → type='js', extension='vue' for the component
-   - **Auto-creates app.js** and **template route** (check response for appJs and templateRoute fields)
-3. Create statements for imports using **create_statement_with_code** (ONE call each):
-   - create_statement_with_code(file, "import { ref, onMounted } from 'vue';")
-   - create_statement_with_code(file, "import { Http } from 'stellify-framework';")
-4. Create statements for reactive data: create_statement_with_code(file, "const notes = ref([]);")
-5. **create_method with body** (async auto-detected from \`await\`). Example:
-   \`\`\`
-   create_method({
-     file: fileUuid,
-     name: "fetchNotes",
-     body: "const response = await Http.get('/api/notes');\\nnotes.value = response.data || [];"
-   })
-   \`\`\`
-6. Create statement for onMounted: create_statement_with_code(file, "onMounted(fetchData);")
-7. **Create UI interaction methods** for any button that changes state:
-   \`\`\`
-   create_method({ file: fileUuid, name: "openModal", body: "showModal.value = true;" })
-   create_method({ file: fileUuid, name: "closeModal", body: "showModal.value = false;" })
-   \`\`\`
-8. html_to_elements with @click handlers auto-wired:
-   \`\`\`
-   html_to_elements({
-     elements: '<button @click="openModal">Open</button>',
-     page: templateRoute.uuid,
-     file: fileUuid  // Auto-wires @click="openModal" to the method UUID
-   })
-   \`\`\`
-9. save_file with: extension='vue', template=[elementUuid], data=[methodUuids], statements=[importUuids, refUuids, onMountedUuid]
-11. Create web route for the display page (e.g., "/notes")
-12. Add \`<div id="app"></div>\` to the display page: html_to_elements(page=routeUuid, elements='<div id="app"></div>')
+- Files are stored as json. The json has a data key that references its methods (using uuids), and each method has a data key that references statements, and each statement has a data key that references clauses.
 
-## Fetching Paginated Data
+## Example Workflow
+1. Research: Call the get_project tool to understand the current project structure, existing files, and directories. This helps avoid duplicates and informs where to create new files.
+2. Plan: If the user is in plan mode, create a plan and prompt the user to accept before starting.
+3. Execute: Map out the solution in full before calling any tools. Use the tools to verify assumptions and gather information about the project as needed.
+4. Create: create_file, create_method (with body), create_statement_with_code
+5. Wire: html_to_elements (pass file UUID to auto-wire @click handlers)
+6. Finalize: save_file with template/data/statements arrays
+7. Verify: Call \`get_assembled_code\` to see the actual rendered output and fix any issues
+8. Test: Use run_code to execute methods and verify behavior. For UI components, use broadcast_element_command to demonstrate functionality in real-time.
 
-Use \`Http.items()\` for paginated endpoints - it auto-extracts the array from Laravel responses:
+## Component Response Handling (IMPORTANT)
 
-\`\`\`javascript
-// Recommended - auto-extracts .data from paginated response
-notes.value = await Http.items('/api/notes');
+When creating Vue/ React etc. components, ALWAYS check the \`appJs\` field in the response:
 
-// Alternative - manual extraction
-const response = await Http.get('/api/notes');
-notes.value = response.data || [];
-\`\`\`
+1. **appJs.action_required === "create_or_select_mount_file"**: No mount file exists. You MUST immediately ask the user: "Would you like me to create an app.js mount file for this component?" Do NOT proceed without user confirmation.
 
-## Editing Existing Code
+2. **appJs.action_required === "register_component"**: Mount file exists but component isn't registered. Call save_file on the mount file (appJs.uuid) to add the component UUID to its includes array.
 
-- **Edit at the right level:** To change code, edit the statement or clause - never delete an entire method just to change a line.
-
-## Common Pitfalls
-
-- **@click auto-wiring:** Pass the file UUID to html_to_elements to auto-wire @click handlers. Methods must be created BEFORE calling html_to_elements.
-- **Stellify imports:** Use "stellify-framework" package (NOT @stellify/core)
-  CORRECT: import { Http, Collection, Form } from 'stellify-framework';
-  WRONG: import { Http } from '@stellify/core';
-- v-model requires ref(), NOT Form class: const formData = ref({title: ''})
-- Collection is iterable and works directly with v-for (no .toArray() needed)
-- 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:** Auto-detected when body contains \`await\`. Response includes \`is_async: true\` if detected.
-- **onMounted:** Use direct method reference: "onMounted(fetchNotes);"
-  The assembler automatically outputs lifecycle hooks after method definitions.
-
-## Nullable Refs: Use explicit v-if, NOT v-else
-
-When using nullable refs (e.g., \`const editingItem = ref(null)\`) with v-model, use explicit v-if guards:
-- WRONG: \`<template v-else><input v-model="editingItem.title"/></template>\`
-- CORRECT: \`<template v-if="editingItem && editingItem.id === item.id"><input v-model="editingItem.title"/></template>\`
-
-Vue evaluates v-model bindings before v-else is applied, causing "Cannot read properties of null" errors.
-
-## Stack and Business Logic
-
-**Default stack:** Laravel (PHP), stellify-framework (JS), and Vue.js. Available capabilities (optional packages/libraries) are returned by \`get_project\`. Use \`get_stellify_framework_api\` for the stellify-framework API reference.
-
-**All business logic** (controllers, models, middleware, etc.) goes in the tenant DB via MCP tools. If a required capability is not available, use \`request_capability\` to log it.
-
-**Prefer Laravel methods:** When Laravel provides a helper (Str, Arr, Hash, Number, Collection), use it instead of native PHP functions.
-
-## JavaScript Entry File (app.js) - Auto-Generated
-
-When you create a Vue component, **app.js is automatically created/updated** with component registration. The create_file response will confirm this with an \`appJs\` field.
-
-**Page mount point:** Each page using Vue needs \`<div id="app"></div>\`:
-- html_to_elements(page=routeUuid, elements='<div id="app"></div>')
-
-## Context Documentation
-
-Add context fields to significant changes (methods, files, routes, elements) to help future AI sessions understand the application.
-
-**When to add context:** New features, significant changes, multi-entity implementations.
-**Skip context for:** Trivial changes, temporary code, unchanged context.
-
-**Context fields** (flat in data object, used with save_method, save_file, save_route, update_element):
-- \`summary\`: What this does
-- \`rationale\`: Why it was built this way
-- \`references\`: [{uuid, type, relationship, note}] - links to related entities
-- \`decisions\`: Array of design decisions
-
-Reference types: model, route, method, file, setting, element
-Relationships: uses, creates, updates, calls, contains, triggers
-
-Context is preserved across updates - the backend merges fields.`;
+3. **No action_required**: Component is already registered in a mount file. Proceed normally.
+`;
+// Legacy detailed instructions preserved as comments for reference if needed
 // Create MCP server
 const server = new Server({
     name: 'stellify-mcp',
-    version: '0.1.30',
+    version: '0.1.32',
 }, {
     capabilities: {
         tools: {},
@@ -2349,6 +2292,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'get_assembled_code': {
+                const result = await stellify.getAssembledCode(args.uuid);
+                // Return just the code content for easy reading
+                const code = result.files?.[0]?.content || result.data?.code || 'No code available';
+                const fileName = result.files?.[0]?.path || result.entryPoint || 'unknown';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `// ${fileName}\n\n${code}`,
+                        },
+                    ],
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/dist/stellify-client.d.ts

@@ -32,6 +32,7 @@ export interface AddMethodBodyParams {
     file: string;
     method: string;
     code: string;
+    types?: Record<string, string>;
 }
 export interface SearchMethodsParams {
     name?: string;
@@ -93,6 +94,7 @@ export declare class StellifyClient {
         file: string;
         code: string;
         method?: string;
+        types?: Record<string, string>;
     }): Promise<any>;
     getStatement(statement: string): Promise<any>;
     deleteStatement(file: string, method: string, statement: string): Promise<any>;
@@ -195,4 +197,5 @@ export declare class StellifyClient {
         example?: string;
     }): Promise<any>;
     listPatterns(): Promise<any>;
+    getAssembledCode(uuid: string): Promise<any>;
 }

package/dist/stellify-client.js

@@ -238,4 +238,9 @@ export class StellifyClient {
         const response = await this.client.get('/pattern');
         return response.data;
     }
+    // Code Assembly - get rendered source code for a file
+    async getAssembledCode(uuid) {
+        const response = await this.client.get(`/file/${uuid}/source`);
+        return response.data;
+    }
 }

package/package.json

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