fix(pluggable-widgets-mcp): fix property types, resource URIs, and add update-widget-prop tool

Author: rahmanunver

package-lock.json

@@ -34,10 +34,13 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
 export function registerMyTools(server: McpServer): void {
-    server.tool(
+    server.registerTool(
         "my-tool",
-        "Description shown to LLM",
-        z.object({ param: z.string().describe("Parameter description") }),
+        {
+            title: "My Tool",
+            description: "Description shown to LLM",
+            inputSchema: z.object({ param: z.string().describe("Parameter description") })
+        },
         async ({ param }) => ({
             content: [{ type: "text", text: "Success" }]
         })

packages/pluggable-widgets-mcp/AGENTS.md

@@ -10,7 +10,7 @@ A Model Context Protocol (MCP) server that enables AI assistants to scaffold Men
 pnpm install
 pnpm build          # Build the server
 pnpm start          # STDIO mode (default)
-pnpm start:stdio    # HTTP mode
+pnpm start:stdio    # STDIO mode
 ```
 
 ## Global Installation
@@ -120,18 +120,24 @@ Generated widgets are placed in `generations/` directory within this package.
 
 ### File Operation Tools
 
-| Tool                       | Description                                                  |
-| -------------------------- | ------------------------------------------------------------ |
-| `list-widget-files`        | Lists all files in a widget directory, grouped by type       |
-| `read-widget-file`         | Reads the contents of a file from a widget directory         |
-| `write-widget-file`        | Writes content to a file (creates parent dirs automatically) |
-| `batch-write-widget-files` | Writes multiple files atomically                             |
+| Tool                | Description                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------- |
+| `list-widget-files` | Lists all files in a widget directory, grouped by type                                |
+| `read-widget-file`  | Reads the contents of a file from a widget directory                                  |
+| `write-widget-file` | Writes content to a file (creates parent dirs). Supports single-file and batch modes. |
 
 **Security:** All file operations are protected by `src/security/guardrails.ts`:
 
 - Path traversal is blocked (no `..` escapes)
 - Extension whitelist: `.tsx`, `.ts`, `.xml`, `.scss`, `.css`, `.json`, `.md`
 
+### Code Generation Tools
+
+| Tool                       | Description                                                                                                         |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `generate-widget-code`     | Generates widget XML + TSX + SCSS from property definitions. Saves a `.widget-definition.json` snapshot.            |
+| `update-widget-properties` | Incrementally adds, removes, or modifies widget properties. Requires `generate-widget-code` to have been run first. |
+
 ### build-widget
 
 Builds a widget using `pluggable-widgets-tools`, producing an `.mpk` file.
@@ -193,7 +199,7 @@ npx @modelcontextprotocol/inspector
     }
     ```
 4. Click "Execute" and watch progress notifications as the widget is scaffolded
-5. Check `generations/testwidget/` for the created widget
+5. Check `generations/testWidget/` for the created widget
 
 This is useful for verifying tool behavior without needing a full AI client integration.
 
@@ -243,7 +249,7 @@ This means:
 **During widget scaffolding:**
 
 - Chat shows: "Starting scaffolding..." → (wait) → "Widget created at `/path`"
-- Inspector shows: Step-by-step progress notifications for all 14 prompts
+- Inspector shows: Progress notifications (start → installing dependencies → complete)
 
 **During widget building:**
 
@@ -256,10 +262,13 @@ This means:
 - [x] HTTP transport
 - [x] STDIO transport
 - [x] Progress notifications
-- [x] File operations (list, read, write, batch-write)
+- [x] File operations (list, read, write)
 - [x] Build tool (`build-widget`)
 - [x] Guideline resources (property-types, widget-patterns)
-- [ ] Widget property editing (XML manipulation)
+- [x] Code generation (`generate-widget-code`)
+- [x] Incremental property update tool (`update-widget-properties`)
+- [ ] Batch widget generation
+- [ ] Widget testing helpers
 - [ ] TypeScript error recovery suggestions
 
 ## License

packages/pluggable-widgets-mcp/README.md

@@ -2,6 +2,8 @@
 
 This document defines all available property types for Mendix pluggable widgets. Use this reference when defining properties in the JSON schema for XML generation.
 
+> **Note:** XML is generated automatically by the `generate-widget-code` tool. You only need to provide JSON property definitions — no XML knowledge required.
+
 ## Property Definition Schema
 
 When defining properties for the XML generator, use this JSON structure:
@@ -35,15 +37,6 @@ Simple text input.
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="label" type="string" defaultValue="Click me">
-    <caption>Label</caption>
-    <description>Text label for the widget</description>
-</property>
-```
-
 ---
 
 ### boolean
@@ -60,15 +53,6 @@ True/false toggle.
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="showIcon" type="boolean" defaultValue="true">
-    <caption>Show icon</caption>
-    <description>Display an icon next to the text</description>
-</property>
-```
-
 ---
 
 ### integer
@@ -85,15 +69,6 @@ Whole number input.
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="maxItems" type="integer" defaultValue="10">
-    <caption>Maximum items</caption>
-    <description>Maximum number of items to display</description>
-</property>
-```
-
 ---
 
 ### decimal
@@ -128,15 +103,6 @@ Text with parameter substitution. Allows dynamic text with placeholders.
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="legend" type="textTemplate" required="false">
-    <caption>Legend</caption>
-    <description>Text template with parameters</description>
-</property>
-```
-
 ---
 
 ### expression
@@ -164,15 +130,6 @@ Dynamic expression that can reference attributes and return computed values.
 }
 ```
 
-**XML Output (with returnType):**
-
-```xml
-<property key="valueExpression" type="expression">
-    <caption>Value</caption>
-    <returnType type="String" />
-</property>
-```
-
 ---
 
 ## Action Types
@@ -191,15 +148,6 @@ Event handler that triggers actions (microflows, nanoflows, etc.).
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="onClick" type="action" required="false">
-    <caption>On click</caption>
-    <description>Action to execute when clicked</description>
-</property>
-```
-
 ---
 
 ## Data Types
@@ -229,18 +177,6 @@ Links to an entity attribute. Must specify allowed attribute types.
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="value" type="attribute" required="true">
-    <caption>Value</caption>
-    <description>Attribute to store the value</description>
-    <attributeTypes>
-        <attributeType name="String" />
-    </attributeTypes>
-</property>
-```
-
 **Valid attributeTypes:**
 
 - `String`
@@ -271,15 +207,6 @@ Data source for list-based widgets.
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="dataSource" type="datasource" isList="true" required="false">
-    <caption>Data source</caption>
-    <description>Source of items to display</description>
-</property>
-```
-
 ---
 
 ### association
@@ -297,15 +224,25 @@ Links to an entity association.
 
 ---
 
-### entity
+### selection
 
-Entity selector.
+Represents the selection mode for a widget (e.g., for data grids).
+
+| Field       | Type        | Required | Description                 |
+| ----------- | ----------- | -------- | --------------------------- |
+| key         | string      | ✅       | camelCase identifier        |
+| type        | "selection" | ✅       | Must be "selection"         |
+| caption     | string      | ✅       | Display label in Studio Pro |
+| description | string      |          | Help text                   |
+| required    | boolean     |          | Whether required            |
+
+**Example:**
 
 ```json
 {
-    "key": "targetEntity",
-    "type": "entity",
-    "caption": "Target entity"
+    "key": "selection",
+    "type": "selection",
+    "caption": "Selection"
 }
 ```
 
@@ -331,19 +268,6 @@ Dropdown with predefined options. Must include `enumValues` array.
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="alignment" type="enumeration" defaultValue="left">
-    <caption>Alignment</caption>
-    <enumerationValues>
-        <enumerationValue key="left">Left</enumerationValue>
-        <enumerationValue key="center">Center</enumerationValue>
-        <enumerationValue key="right">Right</enumerationValue>
-    </enumerationValues>
-</property>
-```
-
 ---
 
 ### icon
@@ -416,15 +340,6 @@ Container for child widgets. Used to create widget slots.
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="content" type="widgets">
-    <caption>Content</caption>
-    <description>Widgets to display inside</description>
-</property>
-```
-
 ---
 
 ### object
@@ -453,24 +368,6 @@ Complex nested property with sub-properties. Used for repeating structures.
 }
 ```
 
-**XML Output:**
-
-```xml
-<property key="columns" type="object" isList="true">
-    <caption>Columns</caption>
-    <properties>
-        <propertyGroup caption="Column">
-            <property key="header" type="textTemplate">
-                <caption>Header</caption>
-            </property>
-            <property key="width" type="integer" defaultValue="100">
-                <caption>Width</caption>
-            </property>
-        </propertyGroup>
-    </properties>
-</property>
-```
-
 ---
 
 ## System Properties
@@ -489,18 +386,6 @@ System properties are predefined by Mendix. Reference them by key only.
 - `TabIndex` - Tab order for accessibility
 - `Visibility` - Conditional visibility settings
 
-**XML Output:**
-
-```xml
-<propertyGroup caption="Common">
-    <systemProperty key="Name" />
-    <systemProperty key="TabIndex" />
-</propertyGroup>
-<propertyGroup caption="Visibility">
-    <systemProperty key="Visibility" />
-</propertyGroup>
-```
-
 ---
 
 ## Property Groups
@@ -524,6 +409,31 @@ Properties can be organized into groups for better Studio Pro UI.
 
 ---
 
+## Property Organization
+
+### Auto-Grouping Behavior
+
+If `propertyGroups` is omitted from the widget definition, the `generate-widget-code` tool applies automatic grouping:
+
+- Non-action properties (all types except `action`) are placed in a **"General"** group.
+- Action properties (`type: "action"`) are placed in an **"Events"** group.
+
+This means you rarely need to define `propertyGroups` explicitly for simple widgets. Only add it when you need custom group names or a specific ordering of groups.
+
+### Incrementally Updating Properties
+
+Once a widget has been generated with `generate-widget-code`, you do not need to regenerate all files to change the property list. Use the `update-widget-properties` tool to:
+
+- **Add** new properties to an existing widget
+- **Remove** properties that are no longer needed
+- **Modify** property attributes (e.g., change a caption or default value)
+
+The `update-widget-properties` tool reads the `.widget-definition.json` snapshot saved during `generate-widget-code` and applies only the requested delta, then regenerates the affected files.
+
+> **Requirement:** `generate-widget-code` must have been run at least once before `update-widget-properties` can be used, because it depends on the `.widget-definition.json` snapshot.
+
+---
+
 ## Full Widget Definition Example
 
 ```json
@@ -586,3 +496,4 @@ Properties can be organized into groups for better Studio Pro UI.
 | `icon`         | Icon picker      | -                       |
 | `image`        | Image picker     | -                       |
 | `association`  | Entity relation  | -                       |
+| `selection`    | Selection mode   | -                       |