@stellisoft/stellify-mcp 0.1.17 → 0.1.19

package/dist/index.js

@@ -91,6 +91,39 @@ const stellify = new StellifyClient({
 //   - includes: Array of file UUIDs to import
 //
 // -----------------------------------------------------------------------------
+// VUE COMPONENT + ROUTE PATTERN (for visual editing)
+// -----------------------------------------------------------------------------
+// When building Vue components, use TWO routes to enable visual editing:
+//
+// 1. TEMPLATE ROUTE - Holds the component's UI elements for editing
+//    - create_route: name='NotesTemplate', path='/notes-template', type='web'
+//    - html_to_elements: page=templateRouteUuid, elements='<div>...</div>'
+//    - Users can visually edit these elements in the route editor
+//
+// 2. DISPLAY ROUTE - The actual page that renders the component
+//    - create_route: name='Notes', path='/notes', type='web'
+//    - html_to_elements: page=displayRouteUuid, elements='<NotesApp />'
+//    - This embeds the Vue component on the page
+//
+// 3. VUE COMPONENT FILE - Links to template route elements
+//    - create_file: type='js', extension='vue', name='NotesApp'
+//    - save_file: template=[elementUuidsFromTemplateRoute]
+//
+// WHY THIS PATTERN?
+//   - Template elements need a route to be viewable/editable in the UI
+//   - The display route keeps the clean component embedding pattern
+//   - Component logic (methods, state) stays in the .vue file
+//
+// EXAMPLE WORKFLOW:
+//   1. Create template route: '/notes-template' (for editing)
+//   2. Create display route: '/notes' (for viewing)
+//   3. html_to_elements on template route (creates editable elements)
+//   4. html_to_elements on display route with '<NotesApp />'
+//   5. create_file for NotesApp.vue
+//   6. Add methods, statements, wire events
+//   7. save_file with template pointing to template route's root element
+//
+// -----------------------------------------------------------------------------
 // ELEMENT EVENT HANDLERS (for frontend files)
 // -----------------------------------------------------------------------------
 // Elements can have these event properties (value is method UUID):
@@ -105,9 +138,137 @@ const stellify = new StellifyClient({
 //   - mouseenter: Fires on mouse enter (@mouseenter)
 //   - mouseleave: Fires on mouse leave (@mouseleave)
 //
+// -----------------------------------------------------------------------------
+// STELLIFY FRAMEWORK (frontend library for Vue/JS files)
+// -----------------------------------------------------------------------------
+// Stellify Framework is an AI-friendly frontend library with constrained APIs.
+// Use these modules in Vue components for common frontend tasks.
+//
+// IMPORT PATTERN:
+//   import { Form, Http, Table } from 'stellify-framework'
+//
+// DATA & FORMS:
+//   Form.create({name:'',email:''}).validate({...}).store('/api/users')
+//   Table.create(data).addColumn('name').sort('name').paginate(10)
+//   List.create(items).add(item).remove(id).filter(fn).map(fn)
+//   Tree.create().setRoot(data).addChild(parentId,child).traverse(fn)
+//
+// NETWORK:
+//   Http.create('/api').withToken(t).get('/users').post('/users',data)
+//   Socket.create('wss://...').on('message',fn).connect().send(data)
+//   Auth.create('/api').login(creds).logout().getUser().isAuthenticated()
+//   Stream.create('/api/chat').onChunk(fn).onComplete(fn).post(data)
+//
+// GRAPHICS:
+//   Svg.create(800,600).rect(0,0,100,50).circle(50,50,20).text('Hi',10,10)
+//   Canvas.create(800,600).rect(0,0,100,50).circle(50,50,20).toDataURL()
+//   Graph.create().addNode('a').addNode('b').addEdge('a','b').layout('force')
+//   Scale.linear().domain([0,100]).range([0,500]).value(50) // returns 250
+//   Motion.tween(0,100,{duration:500}).onUpdate(fn).start()
+//
+// PLATFORM:
+//   Router.create().register('/users',component).navigate('/users')
+//   Storage.local().set('key',val).get('key').remove('key')
+//   Events.create().on('event',fn).emit('event',data)
+//   Clipboard.copy('text').paste()
+//   Notify.request().send('Title',{body:'Message'})
+//   Geo.getPosition().then(pos=>...).watchPosition(fn)
+//   Media.selectFile({accept:'image/*'}).resize(800,600).toBase64()
+//   DB.create('mydb').store({name:'items'}).open().put('items',obj)
+//   Worker.fromFunction(fn).run(data).terminate()
+//
+// AI & LANGUAGE:
+//   Speech.create().onResult(fn).listen({continuous:true})
+//   Speech.create().speak('Hello',{voice:'...'})
+//   Chat.create().addUser('Hi').addAssistant('Hello').getMessages()
+//   Embed.create().store('id',vector,meta).nearest(queryVec,5)
+//   Diff.lines(old,new) // [{type:'equal'|'insert'|'delete',value:'...'}]
+//
+// UTILITIES:
+//   Time.now().format('YYYY-MM-DD').add(7,'days').relative()
+//
+// KEY METHODS PER MODULE (max 7 each - AI-friendly constraint):
+//   Form: create,set,get,validate,store,update,delete
+//   Table: create,setData,addColumn,sort,filter,paginate
+//   Http: create,get,post,put,delete,withToken
+//   Stream: create,post,onChunk,onComplete,abort,getBuffer
+//   Speech: create,listen,speak,stopListening,getVoices,onResult
+//   Chat: create,addMessage,getHistory,clear,fork,truncate
+//   Embed: create,store,compare,nearest,search,toJSON
+//   Diff: chars,words,lines,apply,createPatch,similarity
+//
 // =============================================================================
 // Define MCP tools
+// Stellify Framework API - full method reference for AI code generation
+const STELLIFY_FRAMEWORK_API = {
+    // Data & Forms
+    Form: ['create', 'set', 'get', 'getData', 'validate', 'isValid', 'getErrors', 'getError', 'reset', 'store', 'update', 'delete'],
+    Table: ['create', 'setData', 'addColumn', 'removeColumn', 'sort', 'filter', 'clearFilter', 'paginate', 'page', 'getData', 'getAllData', 'getColumns', 'getColumn', 'getTotalRows', 'getTotalPages', 'getCurrentPage', 'getPageSize', 'getSortKey', 'getSortDirection'],
+    List: ['create', 'from', 'range', 'add', 'remove', 'removeWhere', 'set', 'get', 'first', 'last', 'sort', 'sortBy', 'reverse', 'filter', 'find', 'findIndex', 'map', 'reduce', 'forEach', 'includes', 'indexOf', 'every', 'some', 'slice', 'take', 'skip', 'chunk', 'unique', 'uniqueBy', 'groupBy', 'flatten', 'concat', 'isEmpty', 'isNotEmpty', 'count', 'clear', 'toArray', 'toJSON', 'clone', 'sum', 'avg', 'min', 'max'],
+    Tree: ['create', 'setRoot', 'addChild', 'removeNode', 'getNode', 'getRoot', 'getChildren', 'getParent', 'getSiblings', 'getAncestors', 'getDescendants', 'getDepth', 'getPath', 'traverse', 'find', 'findAll', 'move', 'toArray', 'size'],
+    // Network
+    Http: ['create', 'get', 'post', 'put', 'patch', 'delete', 'withHeaders', 'withToken', 'withTimeout'],
+    Socket: ['create', 'connect', 'disconnect', 'send', 'sendEvent', 'on', 'off', 'once', 'isConnected', 'getState'],
+    Auth: ['create', 'login', 'logout', 'fetchUser', 'getUser', 'getToken', 'isAuthenticated', 'setToken', 'setUser', 'refresh', 'onAuthChange', 'offAuthChange', 'getAuthHeader'],
+    Stream: ['create', 'headers', 'withToken', 'onChunk', 'onComplete', 'onError', 'get', 'post', 'abort', 'getBuffer', 'getChunks', 'isStreaming', 'clear'],
+    // Graphics & Visualization
+    Svg: ['create', 'select', 'find', 'attr', 'attrs', 'getAttr', 'addClass', 'removeClass', 'text', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon', 'path', 'textElement', 'group', 'clear', 'remove', 'toString', 'toElement', 'getWidth', 'getHeight'],
+    Canvas: ['create', 'fromElement', 'fromSelector', 'size', 'getWidth', 'getHeight', 'style', 'save', 'restore', 'clear', 'fill', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon', 'arc', 'path', 'text', 'measureText', 'drawImage', 'translate', 'rotate', 'scale', 'resetTransform', 'getPixel', 'setPixel', 'getImageData', 'putImageData', 'toDataURL', 'toBlob', 'getElement', 'getContext', 'appendTo'],
+    Graph: ['create', 'size', 'addNode', 'removeNode', 'addEdge', 'removeEdge', 'getNode', 'getNodes', 'getEdges', 'getEdgesWithPositions', 'getNeighbors', 'layout'],
+    Scale: ['linear', 'log', 'time', 'band', 'domain', 'range', 'getDomain', 'getRange', 'value', 'invert', 'ticks', 'clamp', 'padding', 'bandwidth'],
+    Axis: ['create', 'orientation', 'ticks', 'tickFormat', 'tickSize', 'getTicks', 'getOrientation', 'getTickSize', 'getRange', 'isHorizontal', 'isVertical'],
+    Motion: ['tween', 'spring', 'easing', 'onUpdate', 'onComplete', 'start', 'stop', 'isRunning', 'valueAt'],
+    // Platform APIs
+    Router: ['create', 'register', 'navigate', 'back', 'forward', 'getParams', 'getQuery', 'getCurrent', 'getState', 'onNavigate', 'offNavigate', 'start'],
+    Storage: ['local', 'session', 'set', 'get', 'remove', 'clear', 'has', 'keys', 'getAll', 'size'],
+    Events: ['create', 'on', 'off', 'once', 'emit', 'clear', 'listenerCount', 'eventNames'],
+    Clipboard: ['copy', 'paste', 'copyImage', 'copyHtml', 'isSupported', 'isWriteSupported'],
+    Notify: ['request', 'send', 'getPermission', 'isSupported', 'isGranted', 'isDenied'],
+    Geo: ['getPosition', 'watchPosition', 'stopWatching', 'stopAllWatching', 'isSupported', 'distance'],
+    Media: ['selectFile', 'selectFiles', 'capture', 'getMetadata', 'resize', 'toBase64', 'toArrayBuffer', 'toText', 'formatSize', 'isImage', 'isVideo', 'isAudio'],
+    DB: ['create', 'store', 'open', 'close', 'put', 'add', 'get', 'getAll', 'find', 'delete', 'clear', 'count', 'keys', 'update', 'batch', 'deleteDatabase', 'databases'],
+    Worker: ['create', 'fromFunction', 'fromCode', 'run', 'post', 'onMessage', 'onError', 'terminate', 'isRunning', 'getPendingCount'],
+    WorkerPool: ['create', 'fromFunction', 'run', 'map', 'terminate', 'getSize', 'getActiveCount', 'getQueueLength'],
+    // AI & Language
+    Speech: ['create', 'isSupported', 'listen', 'stopListening', 'onResult', 'onInterim', 'onEnd', 'onError', 'speak', 'stopSpeaking', 'pause', 'resume', 'getVoices', 'getVoicesByLanguage', 'isSpeaking', 'isListening'],
+    Chat: ['create', 'fromHistory', 'addMessage', 'addUser', 'addAssistant', 'addSystem', 'getMessage', 'getHistory', 'getMessages', 'getLastMessage', 'getLastUserMessage', 'getLastAssistantMessage', 'updateMessage', 'removeMessage', 'clear', 'clearAll', 'fork', 'truncate', 'count', 'countTokensEstimate', 'toJSON'],
+    Embed: ['create', 'store', 'storeMany', 'get', 'remove', 'clear', 'count', 'compare', 'nearest', 'search', 'cosineSimilarity', 'euclideanDistance', 'dotProduct', 'normalize', 'average', 'toJSON', 'fromJSON'],
+    Diff: ['chars', 'words', 'lines', 'apply', 'createPatch', 'distance', 'similarity', 'commonPrefix', 'commonSuffix'],
+    // Utilities
+    Time: ['now', 'create', 'parse', 'format', 'toISO', 'toDate', 'toTimestamp', 'toUnix', 'add', 'subtract', 'diff', 'isBefore', 'isAfter', 'isSame', 'isBetween', 'startOf', 'endOf', 'year', 'month', 'day', 'weekday', 'hour', 'minute', 'second', 'relative', 'clone'],
+    // Adapters
+    useStellify: ['(generic adapter for any module)'],
+    useForm: ['bind'],
+    useTable: ['(reactive table adapter)'],
+};
 const tools = [
+    {
+        name: 'get_stellify_framework_api',
+        description: `Get the complete Stellify Framework API reference for Vue/JS development.
+
+Returns all modules and their methods for AI-friendly frontend code generation.
+
+Use this tool when you need to:
+- Look up available methods for a Stellify module
+- Verify method names before generating code
+- Understand the full API surface
+
+Example response:
+{
+  "Form": ["create", "set", "get", "validate", "store", "update", "delete", ...],
+  "Http": ["create", "get", "post", "put", "delete", "withToken", ...],
+  ...
+}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                module: {
+                    type: 'string',
+                    description: 'Optional: specific module to get API for (e.g., "Form", "Http"). Omit to get all modules.',
+                },
+            },
+        },
+    },
     {
         name: 'get_project',
         description: `Get the active Stellify project for the authenticated user.
@@ -378,7 +539,30 @@ Example:
     },
     {
         name: 'create_route',
-        description: 'Create a new route/page in a Stellify project',
+        description: `Create a new route/page in a Stellify project.
+
+IMPORTANT - WIRING ROUTES TO CONTROLLERS:
+For API routes to execute code, you MUST connect them to a controller and method:
+- controller: UUID of the controller file (e.g., NoteController)
+- controller_method: UUID of the method to execute (e.g., index, store, update, destroy)
+
+Without these fields, the route exists but won't execute any code!
+
+EXAMPLE - Create an API route wired to a controller:
+{
+  "project_id": "project-uuid",
+  "name": "notes.index",
+  "path": "/api/notes",
+  "method": "GET",
+  "type": "api",
+  "controller": "controller-file-uuid",
+  "controller_method": "index-method-uuid"
+}
+
+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`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -388,11 +572,11 @@ Example:
                 },
                 name: {
                     type: 'string',
-                    description: 'Route/page name (e.g., "Home", "Counter", "About")',
+                    description: 'Route/page name (e.g., "Home", "Counter", "notes.index")',
                 },
                 path: {
                     type: 'string',
-                    description: 'URL path (e.g., "/", "/counter", "/about")',
+                    description: 'URL path (e.g., "/", "/counter", "/api/notes")',
                 },
                 method: {
                     type: 'string',
@@ -406,6 +590,14 @@ Example:
                     description: 'Route type: "web" for pages, "api" for API endpoints',
                     default: 'web',
                 },
+                controller: {
+                    type: 'string',
+                    description: 'UUID of the controller file to handle this route. Required for API routes to execute code.',
+                },
+                controller_method: {
+                    type: 'string',
+                    description: 'UUID of the method within the controller to execute. Required for API routes to execute code.',
+                },
                 data: {
                     type: 'object',
                     description: 'Additional route data (title, description, element UUIDs)',
@@ -434,6 +626,74 @@ Use this to look up a route you created or to find existing routes in the projec
             required: ['uuid'],
         },
     },
+    {
+        name: 'save_route',
+        description: `Update an existing route/page. Use this to wire a route to a controller method.
+
+IMPORTANT: This is how you connect API routes to controller methods!
+
+Example - Wire an API route to a controller method:
+{
+  "uuid": "route-uuid",
+  "controller": "controller-file-uuid",
+  "controller_method": "method-uuid"
+}
+
+Available fields:
+- controller: UUID of the controller file
+- controller_method: UUID of the method to execute
+- path: URL path
+- name: Route name
+- type: "web" or "api"
+- method: HTTP method (GET, POST, PUT, DELETE, PATCH)
+- middleware: Array of middleware names
+- public: Whether the route is public (no auth required)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: {
+                    type: 'string',
+                    description: 'UUID of the route to update',
+                },
+                controller: {
+                    type: 'string',
+                    description: 'UUID of the controller file to handle this route',
+                },
+                controller_method: {
+                    type: 'string',
+                    description: 'UUID of the method within the controller to execute',
+                },
+                path: {
+                    type: 'string',
+                    description: 'URL path (e.g., "/api/notes")',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Route name',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['web', 'api'],
+                    description: 'Route type',
+                },
+                method: {
+                    type: 'string',
+                    enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
+                    description: 'HTTP method',
+                },
+                middleware: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of middleware names',
+                },
+                public: {
+                    type: 'boolean',
+                    description: 'Whether the route is public (no auth required)',
+                },
+            },
+            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.
@@ -973,6 +1233,30 @@ RELATIONSHIP TYPES:
 - belongsTo: Inverse of hasOne/hasMany (Post belongsTo User)
 - belongsToMany: Many-to-many (User belongsToMany Roles)
 
+IMPORTANT - WIRING ROUTES TO CONTROLLERS:
+This tool creates controller methods but does NOT automatically wire routes to them.
+After calling create_resources, you must MANUALLY wire routes using create_route:
+
+1. Note the returned controller UUID and method UUIDs from the response
+2. For each API route, call create_route with:
+   - controller: the controller file UUID
+   - controller_method: the specific method UUID (index, store, update, destroy)
+
+Example response structure:
+{
+  "controller": {
+    "uuid": "controller-uuid",
+    "methods": [
+      { "uuid": "index-method-uuid", "name": "index" },
+      { "uuid": "store-method-uuid", "name": "store" },
+      ...
+    ]
+  }
+}
+
+Then create routes:
+create_route({ path: "/api/notes", method: "GET", controller: "controller-uuid", controller_method: "index-method-uuid" })
+
 Returns UUIDs for all created files so you can customize them further if needed.`,
         inputSchema: {
             type: 'object',
@@ -1340,6 +1624,30 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     try {
         switch (name) {
+            case 'get_stellify_framework_api': {
+                const moduleName = args.module;
+                let result;
+                if (moduleName) {
+                    const moduleApi = STELLIFY_FRAMEWORK_API[moduleName];
+                    if (moduleApi) {
+                        result = { [moduleName]: moduleApi };
+                    }
+                    else {
+                        result = { error: `Module "${moduleName}" not found. Available: ${Object.keys(STELLIFY_FRAMEWORK_API).join(', ')}` };
+                    }
+                }
+                else {
+                    result = STELLIFY_FRAMEWORK_API;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'get_project': {
                 const result = await stellify.getProject();
                 const projectData = result.data || result;
@@ -1480,6 +1788,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'save_route': {
+                const { uuid, ...updateData } = args;
+                const result = await stellify.saveRoute(uuid, updateData);
+                const routeData = result.data || result;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Updated route "${uuid}"${updateData.controller ? ' with controller wiring' : ''}`,
+                                route: routeData,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'search_routes': {
                 const result = await stellify.searchRoutes(args);
                 const routes = result.data || result;

package/dist/stellify-client.d.ts

@@ -52,6 +52,8 @@ export interface CreateRouteParams {
     path: string;
     method: string;
     type?: string;
+    controller?: string;
+    controller_method?: string;
     data?: any;
 }
 export interface CreateElementParams {
@@ -84,6 +86,7 @@ export declare class StellifyClient {
     saveStatement(statement: string, data: any): Promise<any>;
     createRoute(params: CreateRouteParams): Promise<any>;
     getRoute(route: string): Promise<any>;
+    saveRoute(route: string, data: any): Promise<any>;
     searchRoutes(params: {
         search?: string;
         type?: string;

package/dist/stellify-client.js

@@ -71,6 +71,10 @@ export class StellifyClient {
         const response = await this.client.get(`/route/${route}`);
         return response.data;
     }
+    async saveRoute(route, data) {
+        const response = await this.client.put(`/route/${route}`, { uuid: route, ...data });
+        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.17",
+  "version": "0.1.19",
   "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.2",
+  "version": "0.1.18",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@stellisoft/stellify-mcp",
-      "version": "0.1.2",
+      "version": "0.1.18",
       "transport": {
         "type": "stdio"
       },