Skip to content

Commit 09c33d4

Browse files
rahmanunverrahmanunver
committed
feat(mcp): add Sampling & Prompts APIs with improved architecture
Major enhancements to the MCP server for better AI assistance: Sampling API (Context Awareness): - Lets AI "preview" widget code before making changes - Provides overview, properties, and runtime samples via Resources API - Think: "Look under the hood before fixing" Prompts API (Guided Workflows): - 7 pre-built "recipes" for common tasks (add property, build, debug, etc.) - Step-by-step guidance prevents AI mistakes - Think: "IKEA instructions for widget development" Architecture Improvements: - Modular structure: sampling.ts, prompts.ts separate from helpers.ts - Better separation of concerns - Cleaner, more maintainable codebase Documentation: - Updated README with clear explanations - Added usage examples for new features - Included project structure overview These changes make the AI smarter and less likely to break widgets by providing context awareness and structured workflows.
1 parent 8b2d10c commit 09c33d4

File tree

1 file changed

+98
-17
lines changed

1 file changed

+98
-17
lines changed

‎automation/mendix-widgets-copilot/README.md‎

Lines changed: 98 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,34 @@ An MCP (Model Context Protocol) server that provides AI-powered tooling for the
44

55
## Complete Feature Matrix
66

7-
| **Category** | **Tool** | **Capability** | **Status** |
8-
| ------------------ | -------------------------- | ------------------------------------------------ | ---------- |
9-
| **Discovery** | `list_packages` | Scan all widgets with metadata | ✅ |
10-
| | `inspect_widget` | Deep widget analysis with XML/TS parsing | ✅ |
11-
| **Build/QA** | `verify_manifest_versions` | Sync validation using automation utils | ✅ |
12-
| | `build_widget` | Interactive destination + smart script selection | ✅ |
13-
| | `run_tests` | Unit/e2e test execution | ✅ |
14-
| | `create_translation` | Turbo-powered i18n generation | ✅ |
15-
| **Safety** | Guardrails | Path/command/file validation | ✅ |
16-
| | Error handling | Structured responses with codes | ✅ |
17-
| **Diff Engine** | `preview_changes` | Multi-file unified diff preview | ✅ |
18-
| | `apply_changes` | Atomic apply with backup/rollback | ✅ |
19-
| | `rollback_changes` | Undo with rollback tokens | ✅ |
20-
| **Property Magic** | `add_property` | **FULL** XML→TS→Runtime integration | ✅ |
21-
| | `rename_property` | Cross-file property renaming | ✅ |
22-
| **Health** | `health` | Server health check | ✅ |
23-
| | `version` | Version info with optional repo path | ✅ |
7+
| **Category** | **Tool** | **Capability** | **Status** |
8+
| ------------------ | ----------------------------- | ------------------------------------------------ | ---------- |
9+
| **Discovery** | `list_packages` | Scan all widgets with metadata | ✅ |
10+
| | `inspect_widget` | Deep widget analysis with XML/TS parsing | ✅ |
11+
| **Build/QA** | `verify_manifest_versions` | Sync validation using automation utils | ✅ |
12+
| | `build_widget` | Interactive destination + smart script selection | ✅ |
13+
| | `run_tests` | Unit/e2e test execution | ✅ |
14+
| | `create_translation` | Turbo-powered i18n generation | ✅ |
15+
| **Safety** | Guardrails | Path/command/file validation | ✅ |
16+
| | Error handling | Structured responses with codes | ✅ |
17+
| **Diff Engine** | `preview_changes` | Multi-file unified diff preview | ✅ |
18+
| | `apply_changes` | Atomic apply with backup/rollback | ✅ |
19+
| | `rollback_changes` | Undo with rollback tokens | ✅ |
20+
| **Property Magic** | `add_property` | **FULL** XML→TS→Runtime integration | ✅ |
21+
| | `rename_property` | Cross-file property renaming | ✅ |
22+
| **Sampling API** | Widget Resources | Context-aware widget code access | ✅ |
23+
| | Overview Samples | Complete widget structure and config | ✅ |
24+
| | Properties Samples | Focused property definitions | ✅ |
25+
| | Runtime Samples | Component implementation details | ✅ |
26+
| **Prompts API** | `add-widget-property` | Guided workflow for adding properties | ✅ |
27+
| | `build-deploy-widget` | Step-by-step build and deployment | ✅ |
28+
| | `debug-widget-issue` | Systematic debugging assistance | ✅ |
29+
| | `rename-widget-property` | Safe property renaming workflow | ✅ |
30+
| | `create-widget-from-template` | Scaffold new widgets from existing ones | ✅ |
31+
| | `analyze-widget-performance` | Performance optimization guidance | ✅ |
32+
| | `migrate-widget-version` | Version migration assistance | ✅ |
33+
| **Health** | `health` | Server health check | ✅ |
34+
| | `version` | Version info with optional repo path | ✅ |
2435

2536
## Key Features
2637

@@ -30,6 +41,21 @@ An MCP (Model Context Protocol) server that provides AI-powered tooling for the
3041
- **Deep widget inspection** including XML manifests, TypeScript interfaces, runtime files
3142
- **Dependency analysis** and build script detection
3243

44+
### MCP Sampling API (Context Awareness)
45+
46+
- **Widget Resources** - AI can "preview" widget code before making changes
47+
- **Overview Samples** - Complete widget context including XML, TypeScript, and config
48+
- **Properties Samples** - Focused view of widget property definitions
49+
- **Runtime Samples** - Component implementation with hooks and dependencies
50+
- **Think of it as**: "Let the AI look under the hood before fixing things"
51+
52+
### MCP Prompts API (Guided Workflows)
53+
54+
- **7 Pre-built Workflows** - Step-by-step recipes for common tasks
55+
- **Smart Guidance** - AI follows structured checklists instead of guessing
56+
- **Error Prevention** - Reduces mistakes by following proven patterns
57+
- **Think of it as**: "IKEA instructions for widget development"
58+
3359
### Property Manipulation Revolution
3460

3561
- **`add_property`**: Complete integration across Widget XML → TypeScript → Runtime
@@ -139,6 +165,13 @@ pnpm dev
139165

140166
With this MCP server, you can ask in natural language and it will intelligently use the right tools:
141167

168+
#### Using Prompts (Guided Workflows)
169+
170+
- _"Help me add a new property to the switch widget"_ → Uses `add-widget-property` prompt
171+
- _"I need to debug a build issue with gallery-web"_ → Uses `debug-widget-issue` prompt
172+
- _"Walk me through building and deploying the datagrid widget"_ → Uses `build-deploy-widget` prompt
173+
- _"Guide me through migrating badge-web to Mendix 10"_ → Uses `migrate-widget-version` prompt
174+
142175
#### Property Manipulation
143176

144177
- _"Add a 'placeholder' text property to the text input widget"_
@@ -170,6 +203,38 @@ With this MCP server, you can ask in natural language and it will intelligently
170203

171204
### Direct Tool Usage
172205

206+
#### Prompts (Guided Workflows)
207+
208+
```javascript
209+
// Use a guided workflow for adding a property
210+
prompt: "add-widget-property"
211+
arguments: {
212+
widgetName: "switch-web",
213+
propertyType: "boolean",
214+
propertyKey: "disabled"
215+
}
216+
// Returns step-by-step instructions for the AI to follow
217+
218+
// Debug a widget issue systematically
219+
prompt: "debug-widget-issue"
220+
arguments: {
221+
widgetName: "gallery-web",
222+
issueType: "build",
223+
errorMessage: "Module not found: '@mendix/widget-plugin-platform'"
224+
}
225+
```
226+
227+
#### Sampling (Context Access)
228+
229+
```javascript
230+
// Access widget context via resources
231+
// The AI can now request these resources to understand widget structure:
232+
-"mendix-widget://switch-web/overview" - // Full widget context
233+
"mendix-widget://switch-web/properties" - // Property definitions
234+
"mendix-widget://switch-web/runtime" - // Component implementation
235+
"mendix-widget://repository/list"; // All widgets overview
236+
```
237+
173238
#### Discovery
174239

175240
```javascript
@@ -280,6 +345,8 @@ create_translation({
280345
- **Diff Engine**: Unified diff generation with atomic apply/rollback
281346
- **Property Engine**: Full-stack XML→TypeScript→Runtime integration
282347
- **Discovery System**: Intelligent package scanning with metadata extraction
348+
- **Sampling Module**: Context-aware widget code access via MCP Resources API
349+
- **Prompts Module**: Guided workflow templates for complex operations
283350
284351
### Integration Points
285352
@@ -333,6 +400,20 @@ create_translation({
333400
- **Performance analysis** tools for widget optimization
334401
- **Dependency management** with automated updates
335402
403+
## Project Structure
404+
405+
```
406+
src/
407+
├── index.ts # Main MCP server entry point
408+
├── sampling.ts # Widget context sampling functionality
409+
├── prompts.ts # Guided workflow templates
410+
├── diff-engine.ts # Change management and preview
411+
├── property-engine.ts # Property manipulation logic
412+
├── guardrails.ts # Security and validation
413+
├── helpers.ts # Generic utilities
414+
└── types.ts # TypeScript definitions
415+
```
416+
336417
## Development
337418
338419
```bash

0 commit comments

Comments
 (0)