mcp-server

Check AgentBrush authentication status, plan details, and token balance. Returns: authentication state, plan name, token balance, monthly allocation, cycle reset date, and quota state. Requires authentication (credentials must exist from a prior agentbrush_login). If not authenticated, returns a suggestion to run agentbrush_login. Call this before agentbrush_generate if you need to confirm the user has enough tokens for a generation. The response includes a human-readable summary you can relay directly to the user, including how many generations they can afford. Handles gracefully: missing credentials (suggests login), API unreachable (suggests retry), expired/revoked keys (suggests re-login).

Open a browser-based mask editor for spatial precision edits on an existing image, then block until the user accepts a result. Use this instead of agentbrush_generate when the change requires repositioning, area-specific modifications, removing or adding elements in a specific region, or any edit that text prompts alone cannot express. How it works: 1. The tool opens a browser tab where the user draws a mask over the area to modify. 2. The user describes the change and submits the edit. 3. The tool blocks while the user edits (up to 30 minutes). 4. Returns the edited image path, token cost, and remaining balance when the user accepts a result. If you want to hand the editor URL to the user and continue working while they draw, call agentbrush_edit_mask_open instead and then agentbrush_edit_mask_result to retrieve the image. Requires authentication — run agentbrush_login first if not authenticated. image_path must be an absolute path to an existing image file within the project. instruction describes what should change in the masked area (max 500 characters). quality_hint: low=1 token, medium=5 tokens (default), high=20 tokens at 1024×1024.

Open a mask editor session and return the editor URL immediately, without blocking. Prefer agentbrush_edit_mask for most cases — it blocks and returns the edited image automatically when the user accepts. Use this non-blocking variant only if you must keep working while the user draws. IMPORTANT: the edited image is NOT delivered to you until you call agentbrush_edit_mask_result with the returned session_id. Call it right after handing over the URL so the result is retrieved as soon as the user finishes (it keeps polling until they Accept and Finish). The tool best-effort opens the system default browser to the editor URL and also returns the URL as text so the agent can relay it. Requires authentication — run agentbrush_login first if not authenticated. image_path must be an absolute path to an existing image file within the project. instruction describes what should change in the masked area (max 500 characters). quality_hint: low=1 token, medium=5 tokens (default), high=20 tokens at 1024×1024.

Block until the mask editor session reaches "completed" (the user accepted a result), then download and save the edited image. Pair with agentbrush_edit_mask_open. Blocks for up to 30 minutes (matching the signed editor URL lifetime); returns immediately when the user accepts. session_id is the UUID returned by agentbrush_edit_mask_open. image_path is optional. Pass the same path you handed to _open so the result is saved alongside it; otherwise the saved file lands in the current working directory.

Generate an image from a text description. Use when the user or project needs a new image asset. Presets: - realistic: Realistic (single model) - flat_illustration: Flat Illustration (single model) - pixel_art: Pixel Art (single model) - isometric: Isometric (single model) - logo: Logo (single model) - custom: Custom (single model) Quality levels (quality_hint): low=1 token, medium=5 tokens (default), high=20 tokens — at 1024×1024. Multiplied by a resolution factor for other sizes (portrait 0.8×, landscape 0.95×). Size: 1024x1024 (square), 1024x1536 (portrait), 1536x1024 (landscape), or a { width, height } custom object. Format: png (lossless, transparency), jpeg (smaller), webp (modern, transparency). Background: opaque or auto. For transparent backgrounds, generate with opaque and call agentbrush_remove_background on the result. style_context: optional { style_descriptor?, color_hints?, mood_tags? }. Auto-filled from .agentbrush/identity.json when omitted; explicit values override the file. reference_image_paths: optional absolute paths to reference images (max 10). When supplied, the backend routes the generation to OpenAI /v1/images/edits with the references attached as image[] parts — the model uses them as the appearance/style authority and composes the new image per the subject prompt. Paths must resolve inside .agentbrush/references/; obtain them via agentbrush_list_references or register a generated image as a reference via agentbrush_save_as_reference. Character iteration workflow: generate a character once with agentbrush_generate, optionally polish it via agentbrush_edit_mask, save it with agentbrush_save_as_reference, then every subsequent agentbrush_generate call can pass the reference path to keep the character consistent across new scenes/poses. output_dir: directory to save the image (default: ./public/images/). Relative to project root. Returns: saved file path, generation metadata, token cost, remaining balance, and an inline image preview.

Initialize AgentBrush in a project. Creates .agentbrush/ directory with: - identity.json: brand identity stub (style descriptor, color palette, mood tags) - references/: folder for reference images Non-destructive: skips files that already exist. Call this once per project before using brand identity features. This scaffolds project files only; it does not authenticate. Use the agentbrush_login tool (or run `agentbrush-mcp init` in a terminal) to connect an account.

List all available AgentBrush image generation presets. Returns preset IDs, display names, pipeline types, word budgets, and features. No authentication required. Call this before agentbrush_generate if unsure which preset to use. Each preset has a unique visual style. The "realistic" preset uses the gpt-image-2 single-shot path (formerly a two-model pipeline). All other presets are single-model. Token cost is determined by quality_hint (low=1 / medium=5 / high=20 tokens at 1024×1024, multiplied by a resolution factor), not by preset. The response includes enough detail for you to recommend a preset to the user without further prompting.

Browse reference images available in the project brand identity folder (.agentbrush/references/). Returns a list of image files with their filenames, tags, descriptions, and absolute paths, merged from identity.json.references[] manifest entries and any additional image files found on disk. Call this before agentbrush_generate when the user mentions a style, brand, or visual reference, so you can pick the most relevant images to include in the generation request. Optional tags parameter filters by tag (OR semantics, case-insensitive): { tags: ["hero", "logo"] } returns entries tagged with either "hero" or "logo". Omit the parameter to see every reference. Returns metadata only — no image bytes. No authentication required.

Authenticate this CLI with your AgentBrush account using device authorization. Opens a browser window where you approve the connection. After approval, API credentials are saved locally and persist across sessions. Only needs to be called once. Call this if agentbrush_check_status reports unauthenticated, or if agentbrush_generate fails with an authentication error. If already authenticated with a valid key, returns the current plan and token balance without starting a new auth flow. The tool blocks while waiting for browser approval (up to 15 minutes). No input parameters required.

Auto-populate the project brand identity table from 1-3 inspiration URLs. Two modes: plan and apply. Plan mode (call without extractions): Returns a structured plan listing the URLs and the exact screenshot paths to save. The MCP does NOT crawl URLs itself — your browser/screenshot tools (Playwright, Chrome devtools, vision API, etc.) execute the plan. Apply mode (call with extractions): After your tools have taken screenshots and analysed them for dominant colors, visual style, and mood, call this tool again with the same urls plus an extractions array. The tool merges your findings into .agentbrush/identity.json without overwriting existing data. Save screenshots EXACTLY at the paths returned by plan mode — the apply step validates each path resolves inside .agentbrush/references/ and rejects symlinks or escapes. Workflow: 1) Call this tool with { urls: [...] } to get the plan. 2) Use your own browser/screenshot tools to capture and analyse each URL. 3) Call this tool again with { urls: [...], extractions: [...] } to merge. For URLs that fail to crawl, include them in extractions with { failed: true, failure_reason: "..." }. Partial results are accepted — successful URLs are merged and failed URLs are reported. Maximum 3 URLs per call. Only http:// and https:// are accepted. Color palette caps at 8 entries; mood tags cap at 10. Existing brand identity content is preserved (merge semantics, not overwrite).

Strip the background from a PNG/JPG/WebP and return a transparent PNG. Runs locally — no token charge. Typical use: generate an image with background: 'opaque', then call agentbrush_remove_background on the saved file. image_path must be an absolute path to an existing PNG/JPG/WebP file. output_dir is optional — defaults to the same directory as the source image. Returns the absolute path of the new PNG with a transparent background.

Promote a previously-generated or mask-edited image into the project brand identity folder (.agentbrush/references/) and register it in identity.json so the agent can reuse it as a style/character reference on future agentbrush_generate calls. Typical workflow: generate a character with agentbrush_generate → optionally polish it via agentbrush_edit_mask → call agentbrush_save_as_reference with the saved file path → now every agentbrush_generate call can pass that reference path via reference_image_paths to keep the character consistent across new scenes. image_path must be an absolute path to a PNG/JPG/WebP file. Optional `name` becomes the stored filename (slugified). Optional `tags` and `description` surface in agentbrush_list_references output so the agent can filter later. Returns the manifest-relative path and the absolute path — both work as inputs to reference_image_paths.