# @dreamlayer/mcp

Image generation and editing tools for MCP-compatible AI clients, backed by the
[DreamLayer Agent API](https://docs.dreamlayer.io/agent-api).

This working tree includes the **unpublished 0.5.0-beta.0 video candidate**.
The published version in the installation section below remains image/sprite-only.
For local review use Node >=22.12, `pnpm install --frozen-lockfile`, `pnpm build`,
and configure the MCP client to run `node /absolute/path/to/dist/index.js` with an
authorized video-enabled API endpoint. This does not publish or deploy anything.

## Video candidate tools

`dreamlayer_video_quote` performs no paid generation. `dreamlayer_video_execute`
admits only a ready owned quote under an explicit user-authorized credit ceiling.
Never invent that authorization. Save the idempotency key before execution.

```json
{"tool":"dreamlayer_video_quote","arguments":{"operation":"text_to_video","prompt":"A silent forest video","options":{"resolution":"720p","generate_audio":false,"aspect_ratio":"16:9"}}}
```

For an image, first use `dreamlayer_upload_image` with an absolute local path,
then use the returned owned asset ID:

```json
{"tool":"dreamlayer_video_quote","arguments":{"operation":"image_to_video","prompt":"Restrained product showcase on a clean white background","input_asset_id":"OWNED_ASSET_UUID","context":{"use_case":"product_showcase","requested_background":"clean_white"},"options":{"model":"auto","duration_seconds":15,"generate_audio":false}}}
{"tool":"dreamlayer_video_execute","arguments":{"quote_id":"READY_QUOTE_UUID","max_credits":40,"idempotency_key":"SAVED_UNIQUE_KEY"}}
{"tool":"dreamlayer_execution","arguments":{"execution_id":"EXECUTION_UUID"}}
{"tool":"dreamlayer_events","arguments":{"execution_id":"EXECUTION_UUID"}}
{"tool":"dreamlayer_download","arguments":{"execution_id":"EXECUTION_UUID","path":"/absolute/new/result.mp4"}}
```

The execute result includes `video_job`, not an inline/base64 video. Status and
events are read-only and never start work. Progress is actual execution stages,
not an invented percentage. A bounded wait or lost response does not cancel a
job; recover its identity with the same quote/key. Already consumed quotes remain
recoverable after expiry. Retry downloads without generating again.

Default: 10s when absent from both prompt and options, native 720p, no audio unless requested; text aspect 16:9. Explicit durations and issued quotes are unchanged. One image
uses native/source-driven aspect. Explicit incompatible settings and extra images
are rejected before charging.

Policy `video-v3-scoped-intent-10s-20261010` applies only to new quotes.
Explicit compatible model first; automatic 4s or 21–30s selects Seedance.
Complex action, demanding audio, continuity, white/unknown product backgrounds
and uncertain classification prefer Seedance. Clearly simple non-white product,
one-speaker talking-head, retro or controlled cinematic-lighting scenes prefer
FLUX. Complexity beats style; these are preferences, not quality guarantees.
FLUX accepts 5–20s; Seedance 4–30s. Source pixels are not analyzed.
Spoken dialogue enables unspecified audio; captions/labels do not. Speech instructions
are not discarded by a preceding "no music" clause. Non-white is not also white;
a speaker alone does not establish simple action. Shot timestamps
are not duration/aspect settings. Overlong timelines fail before spending rather
than being compressed; dialogue is never truncated. Live-test defaults remain 5s.
Existing quotes retain their model, prompt, settings and price.

No automatic cross-provider retry, fidelity scoring, UI change, extension,
upscaling, keyframes or multiple-reference support is included. Downloads use
owned 30-day storage, bounded streaming, SHA-256 verification and no overwrite.
`pricing_pending`/disabled access must be reported honestly, not bypassed.

Use it for raster logo concepts, product imagery, marketing visuals, print artwork
concepts and game assets. Inspect output quality and task-specific requirements.
See the [installable agent workflows](https://github.com/TheDesignFounder/dreamlayer-agent-plugin)
for task guidance and Godot/Unity import examples.

The full workflow below uses the published sprite-capable beta. Stable `latest`
remains `0.3.0`; use the explicit version shown here.

## Install

Add it to your client. Claude Code:

```bash
claude mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/mcp@0.4.0-beta.5
```

Codex:

```bash
codex mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/mcp@0.4.0-beta.5
```

Cursor, or any other stdio MCP client:

```json
{
  "mcpServers": {
    "dreamlayer": {
      "command": "npx",
      "args": ["-y", "@dreamlayer/mcp@0.4.0-beta.5"],
      "env": { "DREAMLAYER_API_KEY": "dlr_live_your_key" }
    }
  }
}
```

The key must be in the **server's own** environment. MCP clients spawn this as a
subprocess, so a key exported in your shell does not reach it. That is the most common
setup failure, and the server exits with an explanation rather than starting up broken.

Get a key at [platform.dreamlayer.io](https://platform.dreamlayer.io). A new account
starts at zero credits. Ordinary image operations cost one credit each; sprite
bundles use the frame-count quote described below.

## Tools

| Tool | What it does |
|---|---|
| `dreamlayer_capabilities` | Read the contract and the operations this key may run. Spends nothing. |
| `dreamlayer_balance` | Read this API key's promotional, purchased, and total available credits. Spends nothing. |
| `dreamlayer_upload_image` | Upload PNG, JPEG, WebP, or camera RAW (up to 200 MB) and get an `input_asset_id`. |
| `dreamlayer_generate` | Generate or edit. Returns the event stream. |
| `dreamlayer_execution` | Read canonical state for one execution. |
| `dreamlayer_events` | Resume a stream after a drop, from a last event id. |
| `dreamlayer_download` | Save a completed execution to a new local path without generating again. |

## Operations

Omit `operation` and DreamLayer reads the prompt, which may come back asking a
clarifying question. Name it and that inference is skipped entirely.

| `operation` | Needs an image | Result |
|---|---|---|
| `text_to_image` | No | A new image from the prompt |
| `image_to_image` | Yes | The reference, edited as described |
| `background_remove` | Yes | The subject on transparency |
| `upscale` | Yes | Twice the width and height |

`upscale` doubles each side and finished images are capped at 4096 per side, so the
longest side of your input must be 2048 or less. A larger one is refused before it
costs a credit.

## Behaviour worth knowing

**A question is not a failure.** An ambiguous prompt returns a `question` event ending
in `needs_input`. Answer it by calling `dreamlayer_generate` again with `respond` and
the `conversation_id`.

**Retries are safe if you reuse the key.** An `idempotency_key` is generated for you.
Pass the same one back to retry after an uncertain response and the original result
replays rather than paying twice.

**Long runs are truncated, not lost.** A stream over 256 events returns what it has,
marks `truncated`, and gives you the `execution_id` and last event id to resume from.

**Errors are stable and provider-neutral.** Error tool results include `code`, `reason`,
`message`, `retryable`, and `request_id`, matching REST and the CLI. A model should branch
on `reason` and `retryable`, never message text. The response excludes prompts, local
filenames, asset URLs, provider details, credentials, and raw upstream responses.

## Requirements

Node.js 22.12 or later.

## License

MIT. See LICENSE and NOTICE.

## Sprite-sheet beta

Sprite requests accept exactly one of `options.animation_prompt` (1–4000 characters) or an `options.action` preset (`walk`, `run`, `idle`). Custom prompts can describe characters, creatures, objects, effects or 360° turntables. `animation_mode` is `loop` or `once`; presets default to loop, custom prompts to once. For a turntable, request a stationary camera and rotating subject. Broad requests do not guarantee correct motion, unseen details or successful effect transparency.

Request integer `frame_count` 7–100 (default 12) and `frame_size` 32, 64, 128, 256, 512, 720 or 1080 (default 512). These are square export canvases; a larger export does not guarantee additional detail. Aspect ratio and shared alignment are preserved with transparent padding. A bundle contains transparent PNG frames, sheet, atlas, preview and import instructions, including each frame's playback duration. Send `background: "keep"` in `options` when transparency is not needed: the frames ship with the generated background in place, plain rather than cut out, and cost the flat plain rate. A frame that cannot be cut out is retried at nearby moments of the same clip, and a single stubborn frame ships with its background rather than failing the sheet; `atlas.json` lists any such frame in `kept_background_frames`. Choose a repeating loop or a one-time action with a beginning and ending. If the requested number of distinct frames cannot be delivered, the job fails and held credits are returned. Translucent effects can lose detail or fail; small exports are not automatically pixel art.

Pricing is unchanged across sizes: frames 1–14 cost $0.14 each; additional frames $0.07 each. With `background: "keep"` every frame is a flat $0.07 with no tier, roughly half a transparent sheet (12 frames: 5.0 credits instead of 9.9). One credit is $0.17. Round the complete order upward once to a tenth of a credit. Check `sprite_pricing` in capabilities and approve the quote with `max_credits`. Credits are held during processing, settled after complete delivery and restored on failure/timeout. There is no customer cancellation. Keep the execution ID to resume status. Custom requests need the matching broad-animation server release; older servers reject them. New live generation quality, 100-frame duration and actual cost remain unverified.

Call `dreamlayer_upload_image`, then `dreamlayer_generate` with `operation: "sprite_sheet"`, the uploaded `input_asset_id`, `options: {action: "walk", frame_count: 12}`, and `max_credits` set to your approved limit.

Each tool call waits for a bounded interval. If the result remains active, pass its `execution_id` and `last_event_id` to `dreamlayer_events`. When completed, use `dreamlayer_download` with `execution_id` and an absolute `path` ending in `.zip`. Existing files are never overwritten.

For affordability, compare the complete rounded quote in **credits** with `available`. One tenth of a credit is $0.017. Promotional and purchased amounts are displayed rounded down separately, so their displayed sum can be 0.1 credit below `available`; stored fractions are preserved. Compare against the combined total, not that sum. The order charge rounds only once, never per frame or per tier.

## Tool discovery and recovery

Read `tools/list` for descriptions, input schemas, and operation availability. Read-only
calls are marked with `readOnlyHint`; upload, generation, and local download are not.
These annotations describe effects, not permission grants. Generation starts paid work.

Every tool returns `structuredContent` plus the same JSON serialized in a text block for
older clients. Failures set `isError: true`. Generation results and errors include the
idempotency key, including when the server generated it for you. Choose and save your own
key before calling when you need recovery even after the MCP process itself is lost.

After interruption, call `dreamlayer_execution` with the saved execution ID, then
`dreamlayer_events` with the last processed event ID. Retrieve completed work with
`dreamlayer_download`. Never start a replacement generation merely because the stream
closed. Keep the same uploaded asset ID and identical arguments when replaying a key.

[MCP setup](https://docs.dreamlayer.io/mcp/index) ·
[API overview](https://docs.dreamlayer.io/agent-api) ·
[Execution recovery](https://docs.dreamlayer.io/agent-api/jobs-and-events)

Abrupt stream failures trigger a canonical status read. If state is still uncertain,
the error is `temporarily_unavailable` with recovery guidance and the known execution
ID, cursor and retry key. `local_output_failed` means a completed output could not be
written: fix the path and retry `dreamlayer_download`, not `dreamlayer_generate`.
Client-side input validation uses `invalid_request`; other unclassified client failures
use `client_error` and are not evidence that generation failed.

## Sprite backgrounds in beta.5

`options.background` selects what the frames look like. `remove`, the default, cuts every frame out for transparent frames. `keep` leaves the generated background in place: the frames are plain rather than cut out, and every frame costs the flat `sprite_pricing.plain_frame_cents` with no tier, about half the transparent price. Twelve frames quote 5 credits kept against 9.9 transparent.

beta.4 and earlier reject this field: their `options` schema set `additionalProperties: false`, so a request naming a background never reached the service. Pin beta.5 or later to use it.

A spelled-out `background: "remove"` is normalised away before the request is sent, because it is exactly what an absent field already means and the service fingerprints the options it receives; sending it would otherwise split one job into two idempotency identities.

## Parameter descriptions in beta.4

Every input parameter in `tools/list` now states what it accepts, including the nested sprite `options` fields: `prompt`, `conversation_id`, `max_credits` (image operations require exactly 1; sprite jobs at or above the quoted price), `aspect_ratio`, `execution_id` and `last_event_id`. Tool names, arguments and results are unchanged from beta.3.

## Error handling updates in beta.3

Malformed event payloads return `response_contract_error` with `retryable: false`, preserving the execution ID, last event ID and idempotency key when known. Check client compatibility or contact support; do not submit replacement work. Interrupted network streams still reconcile canonical state.