@michelabboud/visual-forge-mcp 0.5.6 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/CHANGELOG.md +814 -0
  2. package/dist/types/generation.d.ts +7 -1
  3. package/dist/types/generation.d.ts.map +1 -1
  4. package/dist/utils/image-optimizer.d.ts +91 -0
  5. package/dist/utils/image-optimizer.d.ts.map +1 -0
  6. package/dist/utils/image-optimizer.js +241 -0
  7. package/dist/utils/image-optimizer.js.map +1 -0
  8. package/dist/utils/index.d.ts +1 -0
  9. package/dist/utils/index.d.ts.map +1 -1
  10. package/dist/utils/index.js +1 -0
  11. package/dist/utils/index.js.map +1 -1
  12. package/dist/workflow/workflow-orchestrator.d.ts.map +1 -1
  13. package/dist/workflow/workflow-orchestrator.js +34 -1
  14. package/dist/workflow/workflow-orchestrator.js.map +1 -1
  15. package/docs/guides/README.md +24 -0
  16. package/docs/guides/backup-system-flow.md +511 -0
  17. package/docs/guides/backup-system.md +688 -0
  18. package/docs/guides/development-testing.md +338 -0
  19. package/docs/guides/html-support.md +548 -0
  20. package/docs/guides/image-optimization.md +370 -0
  21. package/docs/guides/testing.md +279 -0
  22. package/docs/guides/usage-examples.md +101 -0
  23. package/docs/guides/vf-workflow.md +112 -0
  24. package/docs/guides/workflow-with-backups.md +471 -0
  25. package/package.json +15 -3
  26. package/dist/.gitkeep +0 -0
package/docs/guides/html-support.md ADDED
@@ -0,0 +1,548 @@
1
+ # Visual Forge MCP - HTML File Support
2
+
3
+ ## Overview
4
+
5
+ Visual Forge MCP now supports HTML files in addition to Markdown! You can add image generation specifications directly in your HTML files using HTML comments or `<img>` tag attributes.
6
+
7
+ ## Supported Formats
8
+
9
+ - **HTML** (`.html`, `.htm`)
10
+ - **Markdown** (`.md`, `.markdown`)
11
+ - **Future**: `.docx`, `.pptx` (planned)
12
+
13
+ ## HTML Image Specification Methods
14
+
15
+ Visual Forge supports two methods for specifying images in HTML files:
16
+
17
+ ### Method 1: HTML Comments (Recommended)
18
+
19
+ Use HTML comments with JSON specifications:
20
+
21
+ ```html
22
+ <!DOCTYPE html>
23
+ <html>
24
+ <body>
25
+ <h1>Network Architecture</h1>
26
+
27
+ <!-- VF_IMAGE: {"type": "diagram", "prompt": "Kubernetes cluster architecture with 3 nodes", "aspectRatio": "16:9"} -->
28
+ <img id="k8s-diagram" src="placeholder.png" alt="Kubernetes Architecture" />
29
+
30
+ <!-- VF_IMAGE: {"type": "flowchart", "prompt": "User authentication flow from login to dashboard"} -->
31
+ <img id="auth-flow" src="placeholder.png" alt="Auth Flow" />
32
+ </body>
33
+ </html>
34
+ ```
35
+
36
+ **Supported Fields:**
37
+ - `type`: Image type (diagram, flowchart, chart, illustration, etc.)
38
+ - `prompt`: AI generation prompt
39
+ - `aspectRatio`: "16:9", "4:3", "1:1", "21:9", etc.
40
+ - `section`: Section name (for organization)
41
+ - `alt`: Alt text for accessibility
42
+ - `caption`: Image caption
43
+ - `keywords`: Comma-separated keywords
44
+ - `priority`: "high", "medium", or "low"
45
+
46
+ ### Method 2: Data Attributes
47
+
48
+ Use `data-vf-*` attributes directly on `<img>` tags:
49
+
50
+ ```html
51
+ <!DOCTYPE html>
52
+ <html>
53
+ <body>
54
+ <img
55
+ data-vf-type="chart"
56
+ data-vf-prompt="Monthly sales data bar chart with trend line"
57
+ data-vf-aspect-ratio="16:9"
58
+ data-vf-section="Sales Dashboard"
59
+ alt="Sales Chart"
60
+ />
61
+
62
+ <img
63
+ data-vf-type="icon"
64
+ data-vf-prompt="User profile icon, minimalist style"
65
+ data-vf-aspect-ratio="1:1"
66
+ alt="Profile Icon"
67
+ />
68
+ </body>
69
+ </html>
70
+ ```
71
+
72
+ **Supported Attributes:**
73
+ - `data-vf-type`: Image type
74
+ - `data-vf-prompt`: AI generation prompt (required)
75
+ - `data-vf-aspect-ratio`: Aspect ratio
76
+ - `data-vf-section`: Section name
77
+ - `data-vf-caption`: Image caption
78
+ - `data-vf-keywords`: Comma-separated keywords
79
+ - `data-vf-priority`: Generation priority
80
+
81
+ ## Workflow
82
+
83
+ ### 1. Add Specifications to HTML
84
+
85
+ Add image specifications using either method:
86
+
87
+ ```html
88
+ <!DOCTYPE html>
89
+ <html>
90
+ <head>
91
+ <title>Technical Documentation</title>
92
+ </head>
93
+ <body>
94
+ <h1>System Architecture</h1>
95
+
96
+ <!-- VF_IMAGE: {"type": "architecture", "prompt": "Microservices architecture with API gateway, auth service, and database"} -->
97
+ <img id="architecture" src="temp.png" alt="System Architecture" />
98
+
99
+ <h2>Data Flow</h2>
100
+
101
+ <img
102
+ data-vf-type="flowchart"
103
+ data-vf-prompt="Data processing pipeline from ingestion to storage"
104
+ alt="Data Flow"
105
+ />
106
+ </body>
107
+ </html>
108
+ ```
109
+
110
+ ### 2. Parse HTML File
111
+
112
+ Use the MCP tool `parse_markdown` (works for both HTML and Markdown):
113
+
114
+ ```json
115
+ {
116
+ "tool": "parse_markdown",
117
+ "arguments": {
118
+ "filePaths": ["docs/architecture.html"]
119
+ }
120
+ }
121
+ ```
122
+
123
+ **Response:**
124
+ ```json
125
+ {
126
+ "success": true,
127
+ "message": "Parsed 2 image specifications",
128
+ "specs": [
129
+ {
130
+ "id": "uuid-1",
131
+ "type": "architecture",
132
+ "prompt": "Microservices architecture...",
133
+ "sourceFile": "docs/architecture.html",
134
+ "aspectRatio": "16:9"
135
+ },
136
+ {
137
+ "id": "uuid-2",
138
+ "type": "flowchart",
139
+ "prompt": "Data processing pipeline...",
140
+ "sourceFile": "docs/architecture.html",
141
+ "aspectRatio": "16:9"
142
+ }
143
+ ]
144
+ }
145
+ ```
146
+
147
+ ### 3. Generate Images
148
+
149
+ Use `generate_image` or `start_workflow` to generate images:
150
+
151
+ ```json
152
+ {
153
+ "tool": "generate_image",
154
+ "arguments": {
155
+ "imageId": "uuid-1",
156
+ "provider": "gemini"
157
+ }
158
+ }
159
+ ```
160
+
161
+ ### 4. Images Inserted Automatically
162
+
163
+ Visual Forge automatically updates your HTML file with generated image paths:
164
+
165
+ **Before:**
166
+ ```html
167
+ <img data-vf-id="uuid-1" data-vf-type="architecture" data-vf-prompt="..." src="temp.png" />
168
+ ```
169
+
170
+ **After:**
171
+ ```html
172
+ <img data-vf-id="uuid-1" src="../generated-images/architecture-001.png" alt="System Architecture" />
173
+ ```
174
+
175
+ The `data-vf-*` attributes (except `data-vf-id`) are removed after generation for clean HTML.
176
+
177
+ ## Image Types
178
+
179
+ Supported image types:
180
+
181
+ - `diagram` - Technical diagrams
182
+ - `flowchart` - Process flowcharts
183
+ - `architecture` - Architecture diagrams
184
+ - `chart` - Data charts/graphs
185
+ - `screenshot` - UI screenshots
186
+ - `illustration` - General illustrations
187
+ - `icon` - Icons/small graphics
188
+ - `hero` - Hero/header images
189
+
190
+ ## Aspect Ratios
191
+
192
+ Supported aspect ratios:
193
+
194
+ - `16:9` - Widescreen (default)
195
+ - `4:3` - Standard
196
+ - `1:1` - Square
197
+ - `21:9` - Ultrawide
198
+ - `3:2` - Photo
199
+ - `9:16` - Portrait/mobile
200
+
201
+ ## Best Practices
202
+
203
+ ### 1. Use Descriptive Prompts
204
+
205
+ ```html
206
+ <!-- Good -->
207
+ <!-- VF_IMAGE: {"type": "diagram", "prompt": "AWS Lambda function triggered by S3 event, processing data and storing in DynamoDB"} -->
208
+
209
+ <!-- Too vague -->
210
+ <!-- VF_IMAGE: {"type": "diagram", "prompt": "Lambda diagram"} -->
211
+ ```
212
+
213
+ ### 2. Include Context in Prompts
214
+
215
+ ```html
216
+ <!-- Better with context -->
217
+ <img
218
+ data-vf-type="flowchart"
219
+ data-vf-prompt="E-commerce checkout flow: cart review → shipping info → payment → confirmation email"
220
+ />
221
+ ```
222
+
223
+ ### 3. Set Appropriate Aspect Ratios
224
+
225
+ ```html
226
+ <!-- Wide diagrams -->
227
+ <img data-vf-type="architecture" data-vf-aspect-ratio="21:9" data-vf-prompt="..." />
228
+
229
+ <!-- Square icons -->
230
+ <img data-vf-type="icon" data-vf-aspect-ratio="1:1" data-vf-prompt="..." />
231
+
232
+ <!-- Portrait mobile screenshots -->
233
+ <img data-vf-type="screenshot" data-vf-aspect-ratio="9:16" data-vf-prompt="..." />
234
+ ```
235
+
236
+ ### 4. Use Semantic HTML
237
+
238
+ ```html
239
+ <figure>
240
+ <img data-vf-type="chart" data-vf-prompt="Q4 revenue growth chart" alt="Revenue Growth" />
241
+ <figcaption>Q4 2025 Revenue Growth</figcaption>
242
+ </figure>
243
+ ```
244
+
245
+ ### 5. Organize with Sections
246
+
247
+ ```html
248
+ <section id="architecture">
249
+ <h2>System Architecture</h2>
250
+ <!-- VF_IMAGE: {"type": "architecture", "prompt": "...", "section": "Architecture"} -->
251
+ </section>
252
+
253
+ <section id="api">
254
+ <h2>API Design</h2>
255
+ <!-- VF_IMAGE: {"type": "diagram", "prompt": "...", "section": "API"} -->
256
+ </section>
257
+ ```
258
+
259
+ ## Complete Example
260
+
261
+ ```html
262
+ <!DOCTYPE html>
263
+ <html lang="en">
264
+ <head>
265
+ <meta charset="UTF-8">
266
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
267
+ <title>Product Documentation</title>
268
+ <style>
269
+ figure { margin: 2rem 0; }
270
+ img { max-width: 100%; height: auto; }
271
+ </style>
272
+ </head>
273
+ <body>
274
+ <h1>Product Documentation</h1>
275
+
276
+ <section id="overview">
277
+ <h2>Overview</h2>
278
+ <p>Our product provides a comprehensive solution for...</p>
279
+
280
+ <!-- VF_IMAGE: {"type": "hero", "prompt": "Modern SaaS dashboard interface showing analytics and metrics", "aspectRatio": "16:9"} -->
281
+ <figure>
282
+ <img id="hero-image" src="temp.png" alt="Product Dashboard" />
283
+ <figcaption>Product Dashboard Overview</figcaption>
284
+ </figure>
285
+ </section>
286
+
287
+ <section id="architecture">
288
+ <h2>Architecture</h2>
289
+
290
+ <img
291
+ data-vf-type="architecture"
292
+ data-vf-prompt="Cloud-native architecture: React frontend, Node.js API, PostgreSQL database, Redis cache, deployed on AWS"
293
+ data-vf-aspect-ratio="16:9"
294
+ data-vf-section="Architecture"
295
+ alt="System Architecture"
296
+ />
297
+ </section>
298
+
299
+ <section id="workflow">
300
+ <h2>User Workflow</h2>
301
+
302
+ <!-- VF_IMAGE: {"type": "flowchart", "prompt": "User onboarding flow: sign up → verify email → profile setup → dashboard", "aspectRatio": "4:3"} -->
303
+ <img id="workflow-diagram" src="temp.png" alt="User Workflow" />
304
+ </section>
305
+
306
+ <section id="metrics">
307
+ <h2>Performance Metrics</h2>
308
+
309
+ <img
310
+ data-vf-type="chart"
311
+ data-vf-prompt="Line chart showing response time trends over 30 days with 95th percentile highlighted"
312
+ data-vf-aspect-ratio="16:9"
313
+ data-vf-caption="Response Time Trends"
314
+ alt="Performance Chart"
315
+ />
316
+ </section>
317
+ </body>
318
+ </html>
319
+ ```
320
+
321
+ ## Mixed Format Projects
322
+
323
+ Visual Forge can handle both HTML and Markdown files in the same project:
324
+
325
+ ```json
326
+ {
327
+ "tool": "parse_markdown",
328
+ "arguments": {
329
+ "filePaths": [
330
+ "docs/README.md",
331
+ "docs/architecture.html",
332
+ "docs/api-guide.md",
333
+ "docs/dashboard.html"
334
+ ]
335
+ }
336
+ }
337
+ ```
338
+
339
+ All files are parsed using the appropriate handler automatically!
340
+
341
+ ## Backup Support
342
+
343
+ HTML files are backed up just like Markdown files:
344
+
345
+ 1. **Before Modification**: Backup created (`.vf-bak`)
346
+ 2. **After Generation**: HTML updated with image references
347
+ 3. **User Decision**:
348
+ - `approve_changes` - Keep changes, delete backups
349
+ - `restore_from_backups` - Undo all changes
350
+
351
+ See [BACKUP_SYSTEM.md](BACKUP_SYSTEM.md) for details.
352
+
353
+ ## Comparison: HTML vs Markdown
354
+
355
+ | Feature | HTML | Markdown |
356
+ |---------|------|----------|
357
+ | **Syntax** | HTML tags | Code blocks |
358
+ | **Flexibility** | High (semantic HTML) | Medium |
359
+ | **Readability** | Lower (more verbose) | Higher |
360
+ | **Styling** | Native CSS support | Limited |
361
+ | **Best For** | Web pages, complex layouts | Documentation, README files |
362
+
363
+ **Choose HTML when:**
364
+ - Building web pages or web apps
365
+ - Need complex layouts or styling
366
+ - Want semantic HTML structure
367
+ - Integrating with existing HTML projects
368
+
369
+ **Choose Markdown when:**
370
+ - Writing documentation
371
+ - Creating README files
372
+ - Want simple, readable source
373
+ - GitHub/GitLab integration
374
+
375
+ ## Limitations
376
+
377
+ ### Current Limitations
378
+
379
+ 1. **No nested HTML processing**: Only parses top-level HTML
380
+ 2. **Comment format must be valid JSON**: Strict JSON syntax required
381
+ 3. **Global context simplified**: Passed as string, not full GlobalContext object
382
+
383
+ ### Coming Soon
384
+
385
+ - `.docx` support (Microsoft Word)
386
+ - `.pptx` support (PowerPoint presentations)
387
+ - Enhanced global context for HTML
388
+ - HTML template support
389
+
390
+ ## Troubleshooting
391
+
392
+ ### Issue: Images not parsed
393
+
394
+ **Check:**
395
+ 1. JSON syntax in comments is valid
396
+ 2. `data-vf-prompt` attribute is present
397
+ 3. File extension is `.html` or `.htm`
398
+
399
+ ```bash
400
+ # Validate JSON syntax
401
+ echo '{"type": "diagram", "prompt": "test"}' | python3 -m json.tool
402
+ ```
403
+
404
+ ### Issue: Images not inserted
405
+
406
+ **Check:**
407
+ 1. `data-vf-id` attribute is present on img tags
408
+ 2. Image ID matches generated image ID
409
+ 3. File permissions allow writing
410
+
411
+ ```bash
412
+ # Check file permissions
413
+ ls -la docs/architecture.html
414
+
415
+ # Check backup files
416
+ ls -la docs/*.vf-bak
417
+ ```
418
+
419
+ ### Issue: Backup not created
420
+
421
+ **Check:**
422
+ 1. `VF_BACKUP_ENABLED` environment variable
423
+ 2. File write permissions
424
+ 3. Disk space available
425
+
426
+ ```bash
427
+ # Check backup enabled
428
+ echo $VF_BACKUP_ENABLED # Should be "true" or empty (default true)
429
+
430
+ # Check disk space
431
+ df -h
432
+ ```
433
+
434
+ ## Examples
435
+
436
+ ### Example 1: Technical Blog Post
437
+
438
+ ```html
439
+ <!DOCTYPE html>
440
+ <html>
441
+ <head>
442
+ <title>Building Scalable APIs</title>
443
+ </head>
444
+ <body>
445
+ <article>
446
+ <h1>Building Scalable APIs</h1>
447
+
448
+ <!-- VF_IMAGE: {"type": "architecture", "prompt": "RESTful API architecture with load balancer, API servers, and database cluster"} -->
449
+ <img class="article-image" src="temp.png" alt="API Architecture" />
450
+
451
+ <p>In this post, we'll explore...</p>
452
+ </article>
453
+ </body>
454
+ </html>
455
+ ```
456
+
457
+ ### Example 2: Product Landing Page
458
+
459
+ ```html
460
+ <!DOCTYPE html>
461
+ <html>
462
+ <head>
463
+ <title>Product Landing</title>
464
+ </head>
465
+ <body>
466
+ <header>
467
+ <h1>Welcome to Our Product</h1>
468
+ <img
469
+ data-vf-type="hero"
470
+ data-vf-prompt="Modern SaaS product hero image with dashboard mockup on laptop"
471
+ data-vf-aspect-ratio="21:9"
472
+ class="hero-image"
473
+ alt="Product Hero"
474
+ />
475
+ </header>
476
+
477
+ <section id="features">
478
+ <div class="feature">
479
+ <img data-vf-type="icon" data-vf-prompt="Lightning bolt icon for speed" data-vf-aspect-ratio="1:1" />
480
+ <h3>Fast</h3>
481
+ </div>
482
+ </section>
483
+ </body>
484
+ </html>
485
+ ```
486
+
487
+ ### Example 3: Internal Documentation
488
+
489
+ ```html
490
+ <!DOCTYPE html>
491
+ <html>
492
+ <body>
493
+ <h1>Deployment Guide</h1>
494
+
495
+ <!-- VF_IMAGE: {"type": "flowchart", "prompt": "CI/CD pipeline: commit → build → test → deploy to staging → approval → deploy to production"} -->
496
+ <img src="temp.png" alt="Deployment Flow" />
497
+
498
+ <!-- VF_IMAGE: {"type": "diagram", "prompt": "Kubernetes deployment with ingress, services, and pods"} -->
499
+ <img src="temp.png" alt="K8s Deployment" />
500
+ </body>
501
+ </html>
502
+ ```
503
+
504
+ ## API Reference
505
+
506
+ ### parse_markdown Tool
507
+
508
+ **Supports both HTML and Markdown files**
509
+
510
+ ```typescript
511
+ {
512
+ tool: "parse_markdown",
513
+ arguments: {
514
+ filePaths: string[] // Can include .html, .htm, .md, .markdown
515
+ }
516
+ }
517
+ ```
518
+
519
+ ### DocumentParser Class
520
+
521
+ ```typescript
522
+ class DocumentParser {
523
+ // Parse single file (auto-detects format)
524
+ async parseFile(filePath: string, globalContext?: string): Promise<ImageSpec[]>
525
+
526
+ // Parse multiple files (mixed formats supported)
527
+ async parseFiles(filePaths: string[], globalContext?: string): Promise<ImageSpec[]>
528
+
529
+ // Insert generated images
530
+ async insertImages(filePath: string, images: GeneratedImageReference[]): Promise<void>
531
+
532
+ // Get supported extensions
533
+ getSupportedExtensions(): string[] // Returns ['.md', '.markdown', '.html', '.htm']
534
+ }
535
+ ```
536
+
537
+ ---
538
+
539
+ **See Also:**
540
+ - [README.md](../README.md) - Main documentation
541
+ - [BACKUP_SYSTEM.md](BACKUP_SYSTEM.md) - Backup system documentation
542
+ - [WORKFLOW_WITH_BACKUPS.md](WORKFLOW_WITH_BACKUPS.md) - Complete workflow guide
543
+
544
+ ---
545
+
546
+ **Last Updated**: 2026-01-13
547
+ **Version**: 0.3.0
548
+ **Status**: ✅ Implemented and Tested