codex-imagegen-mcp 0.1.2

package/skill/imagegen/references/sample-prompts.md

@@ -0,0 +1,418 @@
+# Sample prompts (copy/paste)
+
+Prompt recipes for the imagegen MCP tools (`generate_image`, `edit_image`). Adapted from the OpenAI Codex imagegen skill; the recipes below are unchanged.
+
+Use these as starting points. They are intentionally complete prompt recipes, not the default amount of augmentation to add to every user request.
+
+When adapting a user's prompt:
+- keep user-provided requirements
+- only add detail according to the specificity policy in `SKILL.md`
+- do not treat every example below as permission to invent extra story elements
+
+The labeled lines are prompt scaffolding, not a closed schema. `Asset type` and `Input images` are prompt-only scaffolding.
+
+Execution details are tool parameters, not prompt lines:
+- canvas shape → `aspect_ratio` (e.g. `16:9` for heroes, `1:1` for icons and tiles, `9:16` for mobile screens);
+- transparency → `background: "transparent"` (keep the alpha; see `SKILL.md` for the chroma-key fallback);
+- destination → `output_path` inside the workspace for project assets.
+
+The service chooses resolution and quality itself, so recipes don't include `Quality:` or pixel sizes. For exact dimensions, generate the closest aspect ratio, then resize or crop locally.
+
+For prompting principles (structure, specificity, invariants, iteration), see `references/prompting.md`.
+
+## Generate
+
+### photorealistic-natural
+```
+Use case: photorealistic-natural
+Primary request: candid photo of an elderly sailor on a small fishing boat adjusting a net
+Scene/backdrop: coastal water with soft haze
+Subject: weathered skin with wrinkles and sun texture
+Style/medium: photorealistic candid photo
+Composition/framing: medium close-up, eye-level
+Lighting/mood: soft coastal daylight, shallow depth of field, subtle film grain
+Materials/textures: real skin texture, worn fabric, salt-worn wood
+Constraints: natural color balance; no heavy retouching; no glamorization; no watermark
+Avoid: studio polish; staged look
+```
+
+### product-mockup
+```
+Use case: product-mockup
+Primary request: premium product photo of a matte black shampoo bottle with a minimal label
+Scene/backdrop: clean studio gradient from light gray to white
+Subject: single bottle centered with subtle reflection
+Style/medium: premium product photography
+Composition/framing: centered, slight three-quarter angle, generous padding
+Lighting/mood: softbox lighting, clean highlights, controlled shadows
+Materials/textures: matte plastic, crisp label printing
+Constraints: no logos or trademarks; no watermark
+```
+
+### ui-mockup
+```
+Use case: ui-mockup
+Primary request: mobile app home screen for a local farmers market with vendors and daily specials
+Asset type: mobile app screen
+Style/medium: realistic product UI, not concept art
+Composition/framing: clean vertical mobile layout with clear hierarchy
+Constraints: practical layout, clear typography, no logos or trademarks, no watermark
+```
+
+### infographic-diagram
+```
+Use case: infographic-diagram
+Primary request: detailed infographic of an automatic coffee machine flow
+Scene/backdrop: clean, light neutral background
+Subject: bean hopper -> grinder -> brew group -> boiler -> water tank -> drip tray
+Style/medium: clean vector-like infographic with clear callouts and arrows
+Composition/framing: vertical poster layout, top-to-bottom flow
+Text (verbatim): "Bean Hopper", "Grinder", "Brew Group", "Boiler", "Water Tank", "Drip Tray"
+Constraints: clear labels, strong contrast, no logos or trademarks, no watermark
+```
+
+### scientific-educational
+```
+Use case: scientific-educational
+Primary request: biology diagram titled "Cellular Respiration at a Glance" for high school students
+Scene/backdrop: clean white classroom handout background
+Subject: glucose turns into energy inside a cell; include glycolysis, Krebs cycle, and electron transport chain
+Style/medium: flat scientific diagram with consistent icons, arrows, and readable labels
+Composition/framing: landscape slide-style layout with clear hierarchy and generous whitespace
+Text (verbatim): "Cellular Respiration at a Glance", "Glucose", "Pyruvate", "ATP", "NADH", "FADH2", "CO2", "O2", "H2O"
+Constraints: scientifically plausible; avoid tiny text; no extra decoration; no watermark
+```
+
+### logo-brand
+```
+Use case: logo-brand
+Primary request: original logo for "Field & Flour", a local bakery
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: single centered logo on a plain background with generous padding
+Constraints: strong silhouette, balanced negative space; original design only; no gradients unless essential; no trademarks; no watermark
+```
+
+### illustration-story
+```
+Use case: illustration-story
+Primary request: 4-panel comic about a pet left alone at home
+Scene/backdrop: cozy living room across panels
+Subject: pet reacting to the owner leaving, then relaxing, then returning to a composed pose
+Style/medium: comic illustration with clear panels
+Composition/framing: 4 equal-sized vertical panels, readable actions per panel
+Constraints: no text; no logos or trademarks; no watermark
+```
+
+### stylized-concept
+```
+Use case: stylized-concept
+Primary request: cavernous hangar interior with tall support beams and drifting fog
+Scene/backdrop: industrial hangar interior, deep scale, light haze
+Subject: compact shuttle parked near the center
+Style/medium: cinematic concept art, industrial realism
+Composition/framing: wide-angle, low-angle
+Lighting/mood: volumetric light rays cutting through fog
+Constraints: no logos or trademarks; no watermark
+```
+
+### ads-marketing
+```
+Use case: ads-marketing
+Primary request: campaign image for a streetwear brand called Thread
+Subject: group of friends hanging out together in a stylish urban setting
+Style/medium: polished youth streetwear campaign photography
+Composition/framing: vertical ad layout with natural poses and integrated headline space
+Lighting/mood: contemporary, energetic, tasteful
+Text (verbatim): "Yours to Create."
+Constraints: render the tagline exactly once; clean legible typography; no extra text; no watermarks; no unrelated logos
+```
+
+### productivity-visual
+```
+Use case: productivity-visual
+Primary request: one pitch-deck slide titled "Market Opportunity"
+Asset type: fundraising slide image
+Style/medium: clean modern deck slide, white background, crisp sans-serif typography
+Subject: TAM/SAM/SOM concentric-circle diagram plus a small growth bar chart from 2021 to 2026
+Composition/framing: 16:9 landscape slide, clear data hierarchy, polished spacing
+Text (verbatim): "Market Opportunity", "TAM: $42B", "SAM: $8.7B", "SOM: $340M", "AGI Research, 2024", "Internal analysis"
+Constraints: readable labels, no clip art, no stock photography, no decorative clutter, no watermark
+```
+
+### historical-scene
+```
+Use case: historical-scene
+Primary request: outdoor crowd scene in Bethel, New York on August 16, 1969
+Scene/backdrop: open field with period-appropriate staging
+Subject: crowd in period-accurate clothing, authentic environment
+Style/medium: photorealistic photo
+Composition/framing: wide shot, eye-level
+Constraints: period-accurate details; no modern objects; no logos or trademarks; no watermark
+```
+
+## Asset type templates (taxonomy-aligned)
+
+### Website assets template
+```
+Use case: <photorealistic-natural|stylized-concept|product-mockup|infographic-diagram|ui-mockup>
+Asset type: <hero image / section illustration / blog header>
+Primary request: <short description>
+Scene/backdrop: <environment or abstract backdrop>
+Subject: <main subject>
+Style/medium: <photo/illustration/3D>
+Composition/framing: <wide/centered; note usable negative space only if needed>
+Lighting/mood: <soft/bright/neutral>
+Color palette: <brand colors or neutral>
+Constraints: <no text; no logos; no watermark; leave room for UI if needed>
+```
+
+### Website assets example: minimal hero background
+```
+Use case: stylized-concept
+Asset type: landing page hero background
+Primary request: minimal abstract background with a soft gradient and subtle texture
+Style/medium: matte illustration / soft-rendered abstract background
+Composition/framing: wide composition with usable negative space for page copy
+Lighting/mood: gentle studio glow
+Color palette: restrained neutral palette
+Constraints: no text; no logos; no watermark
+```
+
+### Website assets example: feature section illustration
+```
+Use case: stylized-concept
+Asset type: feature section illustration
+Primary request: simple abstract shapes suggesting connection and flow
+Scene/backdrop: subtle light-gray backdrop with faint texture
+Style/medium: flat illustration; soft shadows; restrained contrast
+Composition/framing: centered cluster; open margins for UI
+Color palette: muted neutral palette
+Constraints: no text; no logos; no watermark
+```
+
+### Website assets example: blog header image
+```
+Use case: photorealistic-natural
+Asset type: blog header image
+Primary request: overhead desk scene with notebook, pen, and coffee cup
+Scene/backdrop: warm wooden tabletop
+Style/medium: photorealistic photo
+Composition/framing: wide crop with clean room for page copy
+Lighting/mood: soft morning light
+Constraints: no text; no logos; no watermark
+```
+
+### Game assets template
+```
+Use case: stylized-concept
+Asset type: <game environment concept art / game character concept / game UI icon / tileable game texture>
+Primary request: <biome/scene/character/icon/material>
+Scene/backdrop: <location + set dressing> (if applicable)
+Subject: <main focal element(s)>
+Style/medium: <realistic/stylized>; <concept art / character render / UI icon / texture>
+Composition/framing: <wide/establishing/top-down>; <camera angle>; <focal point placement>
+Lighting/mood: <time of day>; <mood>; <volumetric/fog/etc>
+Constraints: no logos or trademarks; no watermark
+```
+
+### Game assets example: environment concept art
+```
+Use case: stylized-concept
+Asset type: game environment concept art
+Primary request: cavernous hangar interior with tall support beams and drifting fog
+Scene/backdrop: industrial hangar interior, deep scale, light haze
+Subject: compact shuttle parked near the center
+Style/medium: cinematic concept art, industrial realism
+Composition/framing: wide-angle, low-angle
+Lighting/mood: volumetric light rays cutting through fog
+Constraints: no logos or trademarks; no watermark
+```
+
+### Game assets example: character concept
+```
+Use case: stylized-concept
+Asset type: game character concept
+Primary request: desert scout character with layered travel gear
+Subject: long coat, satchel, practical travel clothing
+Style/medium: character render; stylized realism
+Composition/framing: neutral hero pose on a simple backdrop
+Constraints: no logos or trademarks; no watermark
+```
+
+### Game assets example: UI icon
+```
+Use case: stylized-concept
+Asset type: game UI icon
+Primary request: round shield icon with a subtle rune pattern
+Style/medium: painted game UI icon
+Composition/framing: centered icon; generous padding; clear silhouette
+Constraints: no text; no background scene elements; no logos or trademarks; no watermark
+```
+
+### Game assets example: tileable texture
+```
+Use case: stylized-concept
+Asset type: tileable game texture
+Primary request: worn sandstone blocks
+Style/medium: seamless tileable texture; PBR-ish look
+Scene/backdrop: neutral lighting reference only
+Constraints: seamless edges; no obvious focal elements; no text; no logos or trademarks; no watermark
+```
+
+### Wireframe template
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: <page or flow to sketch>
+Style/medium: low-fi grayscale wireframe
+Composition/framing: <landscape or portrait to match expected device>
+Subject: <sections in order; grid/columns; key labels>
+Constraints: no color; no logos; no real photos; no watermark
+```
+
+### Wireframe example: homepage (desktop)
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: SaaS homepage layout with clear hierarchy
+Style/medium: low-fi grayscale wireframe
+Subject: top nav; hero with headline and CTA; three feature cards; testimonial strip; pricing preview; footer
+Composition/framing: landscape desktop layout
+Constraints: label major blocks; no color; no logos; no real photos; no watermark
+```
+
+### Wireframe example: pricing page
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: pricing page layout with comparison table
+Style/medium: low-fi grayscale wireframe
+Subject: header; plan toggle; 3 pricing cards; comparison table; FAQ accordion; footer
+Composition/framing: desktop or tablet layout
+Constraints: label key areas; no color; no logos; no real photos; no watermark
+```
+
+### Wireframe example: mobile onboarding flow
+```
+Use case: ui-mockup
+Asset type: mobile onboarding wireframe
+Primary request: three-screen mobile onboarding flow
+Style/medium: low-fi grayscale wireframe
+Subject: screen 1 headline and CTA; screen 2 feature bullets; screen 3 form fields and CTA
+Composition/framing: portrait mobile layout
+Constraints: label screens and blocks; no color; no logos; no real photos; no watermark
+```
+
+### Logo template
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: <brand idea or symbol concept>
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; clear silhouette; generous margin
+Color palette: <1-2 colors; high contrast>
+Text (verbatim): "<exact name>" (only if needed)
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+### Logo example: abstract symbol mark
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: geometric leaf symbol suggesting sustainability and growth
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; clear silhouette
+Color palette: deep green and off-white
+Constraints: no text unless requested; no gradients; no mockups; no 3D; no watermark
+```
+
+### Logo example: monogram mark
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: interlocking monogram of the letters "AV"
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; balanced spacing
+Color palette: black on white
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+### Logo example: wordmark
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: clean wordmark for a modern studio
+Style/medium: vector wordmark; flat colors; minimal
+Text (verbatim): "Studio North"
+Composition/framing: centered text; even letter spacing
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+## Edit
+
+### text-localization
+```
+Use case: text-localization
+Input images: Image 1: original infographic
+Primary request: replace "Bean Hopper", "Grinder", "Brew Group", "Boiler", "Water Tank", and "Drip Tray" with "Tolva", "Molino", "Grupo de infusión", "Caldera", "Depósito de agua", and "Bandeja de goteo"
+Constraints: change only the text; preserve layout, typography, spacing, and hierarchy; no extra words; do not alter logos or imagery
+```
+
+### identity-preserve
+```
+Use case: identity-preserve
+Input images: Image 1: person photo; Image 2..N: clothing references
+Primary request: replace only the clothing with the provided garments
+Constraints: preserve face, body shape, pose, hair, expression, and identity; match lighting and shadows; keep the background unchanged; no accessories or text
+```
+
+### precise-object-edit
+```
+Use case: precise-object-edit
+Input images: Image 1: room photo
+Primary request: replace only the white chairs with wooden chairs
+Constraints: preserve camera angle, room lighting, floor shadows, and surrounding objects; keep all other aspects unchanged
+```
+
+### lighting-weather
+```
+Use case: lighting-weather
+Input images: Image 1: original photo
+Primary request: make it look like a winter evening with gentle snowfall
+Constraints: preserve subject identity, geometry, camera angle, and composition; change only lighting, atmosphere, and weather
+```
+
+### style-transfer
+```
+Use case: style-transfer
+Input images: Image 1: style reference
+Primary request: apply Image 1's visual style to a man riding a motorcycle on a plain white backdrop
+Constraints: preserve palette, texture, and brushwork; no extra elements
+```
+
+### compositing
+```
+Use case: compositing
+Input images: Image 1: base scene; Image 2: subject to insert
+Primary request: place the subject from Image 2 next to the person in Image 1
+Constraints: match lighting, perspective, and scale; keep the base framing unchanged; no extra elements
+```
+
+### character consistency workflow
+```
+Use case: identity-preserve
+Input images: Image 1: previous character anchor illustration
+Primary request: continue the story with the same character in a new scene and action
+Scene/backdrop: snowy forest after a winter storm
+Subject: same young forest hero gently helping a frightened squirrel out of a fallen tree
+Style/medium: same children's book watercolor illustration style as Image 1
+Constraints: do not redesign the character; preserve facial features, proportions, outfit, color palette, and personality; no text; no watermark
+```
+
+### sketch-to-render
+```
+Use case: sketch-to-render
+Input images: Image 1: drawing
+Primary request: turn the drawing into a photorealistic image
+Constraints: preserve layout, proportions, and perspective; choose realistic materials and lighting; do not add new elements or text
+```

package/skill/imagegen/references/tools.md

@@ -0,0 +1,90 @@
+# imagegen MCP tools reference
+
+The server exposes five tools. Clients add a prefix (`imagegen_generate_image` in opencode, `mcp__imagegen__generate_image` in Claude Code). All paths may be absolute, `~/…`, or relative to the workspace root (the client's MCP root, or the directory the server was started in).
+
+## generate_image
+
+Create a new image from text. Calls `POST /backend-api/codex/images/generations`.
+
+| Parameter | Default | Notes |
+|---|---|---|
+| `prompt` | required | 1-32000 characters. Use the labeled schema from `SKILL.md`. |
+| `aspect_ratio` | `auto` | `1:1`, `4:5`, `5:4`, `4:3`, `3:4`, `3:2`, `2:3`, `16:9`, `9:16`, `21:9`, `9:21`. Appended to the prompt as an explicit line; the service then picks a matching canvas. |
+| `background` | `auto` | `transparent` returns a PNG with real alpha. `opaque` asks for a filled background; it's a hint, so also describe the backdrop in the prompt, and avoid wording like "the backdrop will be removed". |
+| `n` | `1` | 1-4 variants of the same prompt, run as parallel requests. Each one counts against the quota. |
+| `output_path` | library | File (`.png`, `.jpg`, `.jpeg`) or directory. Without it, the image goes to the server's image library, outside the project. |
+| `output_format` | `png` | `jpeg` is converted locally, flattened on white, and cannot be transparent. Inferred from the `output_path` extension. |
+| `overwrite` | `false` | When false, an existing file is never replaced; `name-2.png`, `name-3.png`… is used instead. |
+| `include_preview` | `true` | Attaches a downscaled JPEG preview (longest edge 1024 px). Transparent areas are shown as a checkerboard. |
+
+The text result lists each saved file with its dimensions, size, background, and an id such as `img_ab12…`. It also includes the exact prompt sent and any warnings.
+
+## edit_image
+
+Edit images, or generate with reference images. Calls `POST /backend-api/codex/images/edits`. It takes the same parameters as `generate_image`, plus:
+
+| Parameter | Notes |
+|---|---|
+| `images` | Required, 1-5 entries: local paths, `file://` URLs, `http(s)://` URLs, or `data:image/…;base64,…`. PNG, JPEG or WebP, up to 15 MB each. |
+
+- **Indexing:** `images[0]` is Image 1, the primary edit target. Refer to the others by index in the prompt.
+- **Inputs:** the input files are never modified.
+- **Iterating:** pass a previous output path as Image 1.
+
+## remove_background
+
+Local chroma-key removal. This is a port of the Codex skill's `remove_chroma_key.py`. It makes no network call and uses no quota.
+
+| Parameter | Default | Notes |
+|---|---|---|
+| `input_path` | required | PNG or JPEG. |
+| `output_path` | `<input>-transparent.png` | Must be `.png`. Never overwrites unless `overwrite: true`. |
+| `key_color` | auto | Hex color such as `#00ff00`. When omitted, it is the median color of the image border. |
+| `soft_matte` | `true` | Smooth alpha ramp between `transparent_threshold` (12) and `opaque_threshold` (96), using per-channel max distance to the key. |
+| `despill` | `true` | Removes key-color fringe from semi-transparent edge pixels. |
+| `tolerance` | `12` | Hard-key tolerance, used only when `soft_matte: false`. |
+| `edge_contract` | `0` | Erodes the matte by N pixels (0-16) to remove a thin halo. |
+| `edge_feather` | `0` | Gaussian blur radius (0-64) for softer edges. |
+
+The result reports the key color used and the fully and partially transparent percentages. It warns when nothing matched or when almost everything became transparent.
+
+## auth_status
+
+- **Reports:** whether a usable sign-in exists, which source and ChatGPT account/plan it belongs to, and when its token expires.
+- **Quota:** the usage windows (5-hour and weekly), fetched from `GET /backend-api/wham/usage`, which uses no image quota.
+- **During sign-in:** it also shows any sign-in that is in progress.
+
+## sign_in
+
+| Parameter | Default | Notes |
+|---|---|---|
+| `method` | `browser` | `browser`: the user opens a link on this machine, and the sign-in redirects to `http://localhost:1455`. `device`: the user enters a code at `https://auth.openai.com/codex/device` from any device; it must be enabled in ChatGPT → Settings → Security. |
+| `open_browser` | `true` | Tries to open the link automatically. |
+| `force` | `false` | Starts a new sign-in even if one exists, e.g. to switch accounts. |
+
+Returns immediately with the link or code, and sign-in completes in the background. Relay the link or code to the user verbatim, then call `auth_status`.
+
+## Where credentials come from
+
+The server checks these sources in order:
+1. **Its own sign-in** (`codex-imagegen-mcp login` or `sign_in`). Refreshed automatically.
+2. **The Codex CLI/app sign-in** at `~/.codex/auth.json`. Read-only; used while its token is valid.
+3. **The opencode ChatGPT sign-in** at `~/.local/share/opencode/auth.json`. Read-only.
+
+Borrowed sign-ins are never refreshed or modified, because refreshing them would sign the other app out. When a borrowed token expires, opening that app renews it, or you can sign in to this server directly.
+
+## Errors and what to do
+
+| Error | Meaning | Do |
+|---|---|---|
+| not signed in / session expired / HTTP 401 | No usable ChatGPT credentials | `sign_in` (relay the link), or ask the user to run the login command in the message, then `auth_status`. |
+| usage limit (HTTP 429) | ChatGPT image or Codex usage limit reached | Stop. Tell the user when it resets (included in the message). |
+| content policy | The prompt or output was blocked by OpenAI's safety system | Rephrase within policy, or ask the user. Don't resend the same prompt. |
+| HTTP 403 | The plan or workspace doesn't include Codex image generation (e.g. Free), or the request was blocked | Tell the user; `auth_status` shows the plan. |
+| server error / network / timeout | Transient | One retry is reasonable (the server already retries 5xx twice). |
+| invalid input | Bad path, unsupported format (GIF, SVG), too large, too many images | Fix the arguments. |
+
+## Limits
+- Up to 5 input images, each at most 15 MB; up to 4 variants per call.
+- Typical latency is 15-60 s per image. Requests are parallel, so `n: 4` takes about as long as one.
+- Service output is a PNG up to about 1672×941 / 1536×1024 / 1024×1536 (roughly 1.5-1.6 MP). Larger or exact sizes need local resizing.