@efectoapp/mcp-server 0.1.24 → 0.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@efectoapp/mcp-server",
-  "version": "0.1.24",
+  "version": "0.1.27",
   "description": "MCP server for Efecto - create stunning visual designs with ASCII effects, glitch art, and more from your CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "scripts": {

package/skills/SKILL.md

@@ -0,0 +1,381 @@
+# Efecto — Create Visual Poster Designs
+
+Efecto is a real-time visual effects application that renders posters with ASCII art, dither, halftone, glitch, and artistic effects. This skill teaches the design workflow, typography rules, font pairings, effect combos, and layout patterns for creating professional-looking posters using the Efecto MCP server tools.
+
+**Prerequisite**: The `efecto` MCP server must be configured. Tools are prefixed with `mcp__efecto__` (e.g., `mcp__efecto__create_poster`).
+
+---
+
+## Design Workflow
+
+Follow these 7 steps in order for every poster:
+
+### Step 1: Create the Poster
+Pick the aspect ratio for the use case:
+- `9:16` — Instagram Stories, TikTok, mobile wallpaper (default)
+- `16:9` — YouTube thumbnails, presentations, desktop wallpaper
+- `1:1` — Instagram posts, profile pictures, album art
+- `4:3` / `3:4` — Print, editorial, magazine covers
+- `full` — Full viewport
+
+### Step 2: Set the Background
+Choose one: solid color, gradient, image, or video.
+- **Solid**: Simple dark (`#0a0a0a`) or light (`#f5f5f0`) backgrounds
+- **Gradient**: Linear (set `gradientAngle`) or radial (set `gradientCenterX/Y`). Use `gradientStops` for multi-color gradients
+- **Image**: Use `search_images` first to find stock photos, then pass the URL
+- **Video**: Use `list_sample_videos` or `search_gifs` for animated backgrounds. Video backgrounds give effects (especially ASCII and dither) much richer source material than solid colors or gradients
+
+### Step 3: Add Text with Typography Hierarchy
+Always use `add_group` for multi-text layouts (headline + subheadline, title + date, etc.). Groups handle positioning via flexbox — never set child x/y positions inside a group.
+
+### Step 4: Add Visual Elements
+Shapes (rectangle, ellipse, polygon, star, line), images, or videos as decorative elements.
+
+### Step 5: Apply the Main Effect
+One effect per poster. Choose based on mood (see Effect Selection Guide below).
+
+### Step 6: Add Post-Processing (WebGPU effects only)
+Stack enhancements like bloom, grain, vignette, scanlines. **Critical**: post-processes do NOT work with dither effects — use dither's built-in `paletteId`/`bloomEnabled` params instead.
+
+### Step 7: Preview and Share
+- `render_image` — Render to see the result visually. Always render to check your work.
+- `generate_url` — Get a shareable URL
+
+### Quick Start — Minimal 4-Call Poster
+
+```
+1. create_poster          → aspectRatio: "9:16"
+2. set_background         → type: "gradient", gradientStyle: "linear", gradientStartColor: "#0a0a0a", gradientEndColor: "#1a1a3e", gradientAngle: 160
+3. add_group              → children: [{type: "text", content: "HELLO", fontSize: 120, fontWeight: "900", color: "#ffffff"}, {type: "text", content: "WORLD", fontSize: 32, fontWeight: "400", color: "#888888"}], y: 50
+4. apply_effect           → effectId: "ascii-standard", cellSize: 8, color: true
+```
+
+---
+
+## Typography System
+
+### Size Guidelines
+| Role | Size (px) | Weight | Use case |
+|------|-----------|--------|----------|
+| Hero headline | 96–140 | 700–900 | Single word or short phrase |
+| Headline | 64–96 | 700–900 | Main title, 2-4 words |
+| Subheadline | 28–48 | 400–600 | Supporting text |
+| Body | 16–24 | 300–400 | Descriptions, paragraphs |
+| Label / Caption | 12–16 | 500–700 | Dates, categories, credits |
+
+### Auto-Fit Behavior
+The MCP server automatically shrinks font size when the longest word in the content exceeds the frame width. This prevents mid-word text wrapping. You can trust that large font sizes will fit — the system adjusts down as needed.
+
+### Line Height
+- **Tight headlines**: `0.9` to `1.0` — for large display text where lines should stack closely
+- **Normal text**: `1.2` (default) — balanced readability
+- **Body text**: `1.3` to `1.5` — comfortable reading for longer text
+
+### Letter Spacing
+- **Large headlines (80px+)**: `-1` to `-3` — tighten for visual density
+- **Normal text**: `0` (default)
+- **Uppercase labels**: `2` to `6` — spread for elegance (pair with `textTransform: "uppercase"`)
+
+### Text in Groups
+Always use `add_group` for multi-text layouts. The group handles all positioning:
+- `layoutMode: "column"` stacks text vertically (most common)
+- `layoutMode: "row"` places text side-by-side
+- `gap: 2` (2% of canvas) for tight spacing, `4` for medium, `6` for generous
+- Children inherit alignment from the group — don't set child x/y
+
+---
+
+## Font Pairing Guide
+
+Use `fontFamily` values exactly as shown. All fonts below are available in Efecto.
+
+### 1. Modern / Clean — Space Grotesk + DM Sans
+```
+Headline:  fontFamily: "Space Grotesk"    fontSize: 96   fontWeight: "700"
+Body:      fontFamily: "DM Sans"           fontSize: 24   fontWeight: "400"
+```
+Geometric, techy, contemporary. Great for SaaS, tech events, product launches.
+
+### 2. Editorial / Luxury — Playfair Display + DM Sans
+```
+Headline:  fontFamily: "Playfair Display"  fontSize: 80   fontWeight: "900"
+Body:      fontFamily: "DM Sans"           fontSize: 20   fontWeight: "300"
+```
+Elegant contrast between serif display and clean sans. Magazines, fashion, luxury brands.
+
+### 3. Retro / Gaming — Bungee + Space Mono
+```
+Headline:  fontFamily: "Bungee"            fontSize: 72   fontWeight: "400"
+Body:      fontFamily: "Space Mono"        fontSize: 18   fontWeight: "400"
+```
+Blocky, arcade-inspired. Retro gaming, pixel art, 8-bit aesthetics. Pair with dither + gameboy palette.
+
+### 4. Bold / Event — Bebas Neue + Inter
+```
+Headline:  fontFamily: "Bebas Neue"        fontSize: 120  fontWeight: "400"
+Body:      fontFamily: "Inter"             fontSize: 20   fontWeight: "400"
+```
+Tall condensed headlines with maximum impact. Events, concerts, sports, announcements.
+
+### 5. Handwritten / Creative — Permanent Marker + Work Sans
+```
+Headline:  fontFamily: "Permanent Marker"  fontSize: 80   fontWeight: "400"
+Body:      fontFamily: "Work Sans"         fontSize: 20   fontWeight: "400"
+```
+Informal, energetic, personal. Art shows, music, street culture.
+
+### 6. Ultra Bold / Impact — Anton + Outfit
+```
+Headline:  fontFamily: "Anton"             fontSize: 110  fontWeight: "400"
+Body:      fontFamily: "Outfit"            fontSize: 22   fontWeight: "300"
+```
+Massive condensed headlines that command attention. Sales, promos, bold statements.
+
+### 7. Monospace / Hacker — JetBrains Mono + IBM Plex Mono
+```
+Headline:  fontFamily: "JetBrains Mono"    fontSize: 56   fontWeight: "700"
+Body:      fontFamily: "IBM Plex Mono"     fontSize: 16   fontWeight: "400"
+```
+Technical, code-inspired. Developer events, hacker culture, terminal aesthetics. Pair with ASCII effects.
+
+---
+
+## Color & Background Strategy
+
+### Dark Backgrounds (most common for effects)
+- Pure dark: `#0a0a0a` or `#000000` — maximum contrast for effects
+- Warm dark: `#1a0f0a` — subtle warmth
+- Cool dark: `#0a0a1a` — cinematic depth
+- Use light text (`#ffffff`, `#f0f0f0`) on dark backgrounds
+
+### Light Backgrounds
+- Off-white: `#f5f5f0` or `#fafafa` — softer than pure white
+- Warm cream: `#f5f0e8` — editorial, vintage
+- Use dark text (`#1a1a1a`, `#0a0a0a`) on light backgrounds
+
+### Gradient Tips
+- **Linear**: `gradientAngle: 160` for top-left to bottom-right diagonal (most versatile)
+- **Radial**: `gradientCenterX: 0.5, gradientCenterY: 0.3` for a vignette from upper-center
+- **Multi-stop**: Use `gradientStops` for rich color transitions (3-5 stops)
+
+### Image Backgrounds
+Use `search_images` with filters for best results:
+- Match `orientation` to aspect ratio: "vertical" for 9:16, "horizontal" for 16:9, "square" for 1:1
+- Use `luminance: "dark"` for dramatic designs with light text overlay
+- Use `type: "photo"` for photographs, `"illustration"` for artwork
+
+---
+
+## Effect Selection Guide
+
+Choose effects based on the desired mood:
+
+| Mood | Effect | Key Settings |
+|------|--------|-------------|
+| **Retro / Vintage** | `dither-atkinson` | `paletteId: "gameboy"`, `pixelation: 4` |
+| **Cyberpunk / Neon** | `glitch-digital` | `intensity: 0.6`, `speed: 1.2` |
+| **Technical / Hacker** | `ascii-standard` | `cellSize: 8`, `color: true` |
+| **Terminal / Matrix** | `ascii-matrix` | `cellSize: 6`, `color: true` |
+| **Print / Editorial** | `halftone-mono` | `dotSize: 0.3` |
+| **Painterly** | `art-kuwahara` | (defaults work well) |
+| **Sketch / Hand-drawn** | `art-crosshatch` | (defaults work well) |
+| **Engraving / Currency** | `art-engraving` | (defaults work well) |
+| **Stipple / Pointillist** | `art-stipple` | (defaults work well) |
+| **VHS / Lo-fi** | `glitch-vhs` | `intensity: 0.5`, `speed: 0.8` |
+| **Editorial / Risograph** | `dither-floyd-steinberg` | `paletteId: "ink"`, `pixelation: 3` |
+| **Warm Retro** | `dither-floyd-steinberg` | `paletteId: "sunset-blvd"`, `pixelation: 3` |
+| **Synthwave** | `dither-atkinson` | `paletteId: "synthwave"`, `bloomEnabled: true`, `bloomIntensity: 1.5` |
+| **Clean / Minimal** | `none` | Use post-processes only |
+| **Line Art** | `art-lineart` | (defaults work well) |
+
+### The Two Effect Pipelines (Critical!)
+
+**Dither effects (WebGL)** — 9 dither-* effects + color-separation:
+- Have BUILT-IN palette and bloom controls
+- Set `paletteId`, `colors`, `bloomEnabled`, `bloomIntensity`, `bloomRadius` directly in `apply_effect`
+- `add_postprocess` does NOT work with dither effects
+
+**All other effects (WebGPU)** — ASCII, Glitch, Halftone, Art, Special:
+- Use `add_postprocess` for palette, bloom, and all other enhancements
+- Support unlimited stackable post-processes
+
+---
+
+## Post-Process Combos
+
+Tested combinations that work well together. Only use with WebGPU effects (not dither).
+
+| Combo Name | Post-Processes | Key Params |
+|-----------|----------------|------------|
+| **CRT Monitor** | scanlines + curvature + vignette + chromatic-aberration | `count: 400`, `curvature: 0.3`, `radius: 0.8`, `strength: 0.02` |
+| **Cyberpunk Glow** | bloom + chromatic-aberration + scanlines | `intensity: 1.5, radius: 0.4, threshold: 0.2` / `strength: 0.03` / `count: 300` |
+| **Film Grain** | grain + vignette + brightness-contrast | `size: 1.5, speed: 0.8` / `radius: 0.7` / `contrast: 1.1` |
+| **Vaporwave** | palette + bloom + chromatic-aberration | `paletteId: "vaporwave"` / `intensity: 1.0` / `strength: 0.02` |
+| **Terminal** | color-tint + scanlines + curvature | `palette: "green"` / `count: 500` / `curvature: 0.2` |
+| **Noir** | brightness-contrast + grain + vignette | `contrast: 1.3, saturation: 0` / `size: 2.0` / `radius: 0.6` |
+| **Dream / Soft** | bloom + wave + grain | `intensity: 2.0, radius: 0.6` / `amplitude: 0.05, frequency: 3` / `size: 1.0` |
+| **Print Texture** | grain + dot-screen | `size: 1.5, speed: 0` / (defaults) |
+| **Glitch Overlay** | rgb-glitch + jitter + noise | (defaults for all) |
+| **Amber Terminal** | color-tint + scanlines + bloom | `palette: "amber"` / `count: 400` / `intensity: 0.8` |
+
+---
+
+## Layout Patterns
+
+### Page Layout — justifyContent Controls Vertical Position
+Use `set_page_layout` to control where content sits on the canvas:
+- `justifyContent: "center"` — vertically centered (default)
+- `justifyContent: "end"` — pushes content to the bottom third (most popular for photo/video backgrounds — lets the image breathe above)
+- `justifyContent: "start"` — anchors content to the top
+- `justifyContent: "space-between"` — spreads content evenly (great for header + body + footer)
+
+### Centered Title Block (most common)
+```
+add_group:
+  x: 50, y: 50, width: 80
+  layoutMode: "column", alignItems: "center", justifyContent: "center", gap: 3
+  children: [headline, subheadline]
+```
+
+### Bottom-Anchored Content (best for photo/video backgrounds)
+```
+set_page_layout: justifyContent: "end"
+
+add_group:
+  x: 50, y: 50, width: 80
+  layoutMode: "column", alignItems: "center", gap: 2
+  children: [title, subtitle, date]
+```
+Note: With `justifyContent: "end"`, the group automatically flows to the bottom — no need to set `y: 82` manually.
+
+### Left-Aligned Editorial
+```
+add_group:
+  x: 50, y: 75, width: 80
+  layoutMode: "column", alignItems: "start", gap: 2
+  children: [headline (textAlign: "left"), body (textAlign: "left")]
+```
+
+### Header + Body + Footer
+```
+set_page_layout:
+  layoutMode: "column", justifyContent: "space-between", alignItems: "center", padding: 8
+
+Then add_layer for header, main content group, and footer — they flow automatically.
+```
+
+### Two-Column Row
+```
+add_group:
+  layoutMode: "row", gap: 4, alignItems: "center", justifyContent: "center"
+  children: [left text, right text]
+```
+
+---
+
+## Shapes & Decorative Elements
+
+### Line Separator
+```
+add_layer: type: "line", startX: 20, startY: 50, endX: 80, endY: 50
+  strokeColor: "#ffffff", strokeWidth: 0.003, strokeOpacity: 0.5
+```
+
+### Decorative Circle
+```
+add_layer: type: "ellipse", width: 30, height: 30, x: 50, y: 50
+  strokeColor: "#ffffff", strokeWidth: 0.005, fillOpacity: 0
+```
+
+### Background Rectangle (for text contrast)
+```
+add_layer: type: "rectangle", width: 80, height: 20, x: 50, y: 80
+  fillColor: "#000000", fillOpacity: 0.6, cornerRadius: 0.02
+```
+
+---
+
+## Text Animations
+
+Add character-level animations to text layers for dynamic posters. Set `animationType` on any text layer.
+
+| Animation | Best For | Key Params |
+|-----------|----------|------------|
+| `wave` | Fluid, ocean-like motion | `animationFrequency: 3`, `animationAxis: "vertical"` |
+| `typewriter` | Reveals, intros | `animationSpeed: 2`, `animationCursor: true` |
+| `glitch` | Cyberpunk, hacker | `animationColorSplit: true`, `animationSliceChance: 0.3` |
+| `neon` | Signs, nightlife | `animationGlowIntensity: 1.5`, `animationFlickerChance: 0.3` |
+| `bounce` | Playful, fun | `animationHeight: 60`, `animationElasticity: 0.6` |
+| `cascade` | Dramatic reveals | `animationFallHeight: 100`, `animationBounceOnLand: true` |
+| `elastic` | Snappy entrances | `animationTension: 1.5`, `animationOvershoot: 1.0` |
+| `shake` | Urgency, alerts | `animationIntensity: 20`, `animationIncludeRotation: true` |
+
+Common settings for all animations:
+- `animationSpeed: 1.0` (0.1 = very slow, 5.0 = very fast)
+- `animationStaggerDelay: 150` (ms between characters, 0 = all at once)
+- `animationStaggerMode: "sequential"` (or "random", "center-out", "edges-in")
+- `animationLoop: true`
+
+---
+
+## Image & Video Integration
+
+### Stock Images
+```
+1. search_images: query: "cyberpunk city", orientation: "vertical", luminance: "dark"
+2. Use the returned URL in set_background (type: "image") or add_layer (type: "image")
+```
+
+### Sample Videos
+```
+1. list_sample_videos: category: "portrait"
+2. Use the returned URL in set_background (type: "video") or add_layer (type: "video")
+```
+
+### Animated GIFs
+```
+1. search_gifs: query: "abstract loop"
+2. Use the mp4Url (NOT gifUrl) for better performance
+3. set_background: type: "video", videoUrl: <mp4Url>
+```
+
+For images/videos as layers, use `objectFit: "cover"` (fills frame, may crop) or `"contain"` (fits within frame, may letterbox).
+
+---
+
+## Rendering & Output
+
+### Render to Check Your Work
+Always call `render_image` after building a poster to visually verify the design. The image is returned inline so you can see it.
+
+```
+render_image: format: "png"                    # Preview only
+render_image: format: "png", savePath: "~/Downloads/poster.png"   # Save to disk
+render_image: format: "jpeg", quality: 85      # Smaller file size
+```
+
+### Generate Shareable URL
+```
+generate_url   # Returns an efecto.app URL that opens the poster in a browser
+```
+
+### Dimensions
+Output dimensions are calculated from the aspect ratio. For custom sizes:
+```
+render_image: width: 1080, height: 1920   # Instagram Story size
+render_image: width: 1920, height: 1080   # Full HD landscape
+```
+
+---
+
+## 37 Available Color Palettes (for dither effects)
+
+Use these with `apply_effect` → `paletteId`:
+
+**Classic**: noir, ink, terminal, amber-glow
+**Retro Gaming**: gameboy, commodore, nes, cga
+**Warm**: sunset-blvd, campfire, autumn-leaves, terracotta, golden-hour, rose-gold
+**Cool**: deep-sea, arctic-night, moonlight, frozen, twilight
+**Neon**: synthwave, vaporwave, cyberpunk, tokyo-night, arcade, retrowave, electric
+**Earth**: forest, moss, desert, clay, ocean-floor
+**Monochrome**: grayscale, sepia, blueprint, cyanotype, green-phosphor, amber-phosphor