Magnetly

Creates a new magnet draft in the authenticated Magnetly account from a MagnetConfigV2 JSON. Returns the publicId and a direct link to the visual builder. REQUIRED workflow before calling this tool: 1. get-brand-assets (if a website URL was provided) 2. expose-config (to get the schema and examples) 3. validate-config (must return valid: true) Skipping these steps will likely result in an invalid config being saved.

Returns the complete blueprint for building a valid MagnetConfigV2: full JSON Schema, component catalog (all 27 component types with their fields), canonical defaults, and curated examples. Call this BEFORE building or customising any magnet config. Required reading before calling create-magnet with a custom config — without it you risk schema errors.

Extracts visual brand assets (colors, logos, backdrop images, brand name) from a website URL using OpenBrand. Call this FIRST whenever the user provides a website URL and wants a magnet built for their brand. The returned colors, logos and brand name must be used in the magnet globalStyle and components to match the brand identity. If status is "unavailable", proceed without branding and note it to the user.

Fetches a single magnet by publicId. Returns its name, status (draft / published / modifications), total step count, and full active config (draftConfiguration if present, otherwise configuration). Call this BEFORE update-magnet-step to inspect the current config and understand the exact step structure. Status meanings: DRAFT = never published; PUBLISHED = live with no pending changes; CHANGES = live but has unpublished draft changes.

Returns performance analytics for a magnet: total impressions, leads captured, conversion rate, and a daily breakdown. Use this to report how a magnet is performing or to decide whether to update it. Periods: today, this_week (last 7 days), this_month (default), this_year.

Lists all magnets in the authenticated Magnetly account with their publicId, name, publication status, and creation date. Use this to check what magnets already exist before creating a new one, or to find the publicId needed for publish-magnet or get-magnet.

Publishes a draft magnet, making it publicly live and embeddable. Takes the publicId returned by create-magnet or list-magnets. This action is immediate and irreversible without going back to draft manually in the builder.

Replaces a single step of an existing magnet draft without touching the rest of the config. Fetches the current draft, swaps the step at stepIndex, validates the full resulting config, then saves. Use this instead of create-magnet when the user only wants to change one step (copy, components, layout). REQUIRED WORKFLOW before calling this tool: 1. list-magnets — find the publicId if not already known. 2. get-magnet — read the full current config and inspect the steps array. 3. Identify the correct stepIndex. CRITICAL: stepIndex is zero-based. When the user says "step N", the index is N-1 (e.g. "step 3" → stepIndex 2, "step 1" → stepIndex 0). Always verify against the actual steps array returned by get-magnet. 4. expose-config — check the step schema if you are unsure of the structure. IMPORTANT CONSTRAINT — last step (output/redirection): the final step of a magnet is protected. Only hex color values (#rrggbb) are merged into it; all other properties (component structure, labels, types, ids) are preserved as-is. To change colors on the last step, pass a step object with only the color fields you want to update — non-color fields are ignored. Will throw a detailed validation error if the updated config is invalid.

Validates a MagnetConfigV2 JSON against the canonical Zod schema. Returns { valid: true, normalizedConfig } on success, or { valid: false, errors } with exact JSON paths on failure. Call this AFTER building a config and BEFORE calling create-magnet. If valid is false, fix every reported error and call validate-config again. Do not call create-magnet until valid is true.