Easel

A local, human-in-the-loop MCP server that bridges an AI agent to Higgsfield's web image generator. The agent asks for an image; a human generates it by hand in the Higgsfield web UI and pastes the result back through a small dashboard; the agent picks it up by polling. Nothing is generated automatically — this is a manual bridge so you can use your Higgsfield web subscription and features.

  AI agent ──request_image_generation──▶ [ bridge daemon ] ──live──▶ 🧑 dashboard (localhost)
     │                                         │                         │  copy prompt
     │  (does other work, then polls)          │  SQLite queue           │  generate in Higgsfield
     ◀──────get_image_result (long-poll)───────┤                         │  paste result back
                       image ◀─────────────────┴─────────────────────────┘  Mark complete

How it works (the agent's contract)

1. The agent calls request_image_generation with a prompt + context. It returns a job_id immediately — it never blocks, and never returns an image.

2. The agent goes off and does other work, then polls get_image_result(job_id) every 5–10s. That call long-polls (holds up to ~25s waiting for a change), so loose polling is cheap and a "call once" agent still tends to catch the result.

3. You (the human) see the request appear live on the dashboard, copy the prompt, open Higgsfield, generate the image, and paste / drag / upload it back, then Mark complete. You can also Reject with a reason (the agent sees it and can rephrase) or Dismiss (cancel).

4. The next poll returns the image as an absolute file path and, for images under ~1 MB, an inline MCP image content block the agent can see directly.

This process is written into every tool's description, so the calling agent knows to stay non-blocking and poll.

Related MCP server: ComfyUI MCP

Requirements

• Node.js ≥ 22 (uses the built-in node:sqlite; 24+ recommended). It will refuse to start on older Node with a clear message.

• macOS gets a native desktop notification on each new request; every platform also logs a clickable dashboard URL to the daemon's terminal.

Install & build

cd ~/easel
npm install
npm run build

Run the daemon

Start it once and leave it running (it must outlive individual agent sessions so the queue and dashboard survive):

npm start
# Dashboard:   http://127.0.0.1:7391/
# MCP (http):  http://127.0.0.1:7391/mcp

Open the dashboard in a browser and keep the tab around (click Enable alerts for desktop notifications). If you forget to start the daemon, the agent's tool calls fail with a plain connection error — start it and retry.

Register it with your MCP client

Add to your client's MCP config (e.g. .mcp.json for Claude Code):

{
  "mcpServers": {
    "easel": { "type": "http", "url": "http://127.0.0.1:7391/mcp" }
  }
}

MCP tools

Configuration (env vars)

Design notes

• One process, one port serves the MCP endpoint (/mcp, stateful Streamable HTTP), the dashboard (/), its API (/api/*), a live SSE stream (/events), and stored images (/files/*, path-traversal-guarded). Bound to 127.0.0.1 with a Host-header check.

• State lives only in SQLite, keyed by job id (not MCP session) — multiple agent sessions share one queue. On restart, any in_progress job is reset to queued (no human is mid-work after a crash).

• Images: returned by absolute path always; inline base64 / MCP image blocks only under a ~1 MB cap so a huge PNG can't blow up the agent's context. The dashboard normalizes pasted/dropped images (canvas resize to ≤2048px) before upload.

Security

This is a single-user local tool. It binds to 127.0.0.1 and checks the Host header; there is no authentication, so don't expose the port to a network. It guards against path traversal, secret exfiltration via reference images (only real image files are accepted), SSRF via reference URLs (public http(s) only), and osascript injection. See SECURITY.md for the full threat model and how to report issues.

Dev

• npm run dev — rebuild on change and restart the daemon.

• npm run typecheck — tsc --noEmit (strict).

• npm start — run the built daemon.

The scripts/ folder has two helpers (start the daemon first; both honor EASEL_PORT):

• node scripts/smoke.mjs — end-to-end MCP round-trip + security-guard test.

• node scripts/seed.mjs — populate the dashboard with a few sample jobs to eyeball the UI.

See CONTRIBUTING.md to contribute.

License

MIT © pradeexsu