Magic Patterns

Creates a new Magic Patterns design. This is the starting point for both prompt-based and code-first workflows.

BEHAVIOR:

• With prompt: Creates a design and kicks off AI generation (long-running, especially when design-system setup is involved). Do not wait synchronously; poll get_design_status to track progress.
• Without prompt: Creates a blank design with scaffold files (App.tsx, index.tsx, index.css, tailwind.config.js) — returns immediately.
• With templateId: Forks an existing design first, then optionally applies the prompt to the fork. The templateId is an editor ID — you can get it from a design URL (the ID in magicpatterns.com/c/<id>) or via get_editor_id_from_url.

You can optionally specify a design system. If the user mentions one, call list_design_systems first.

NEXT STEPS:

• With prompt: Call get_design_status(editorId) to poll until generation completes. This often takes a while, so the caller should keep polling instead of assuming the design is ready immediately.
• Without prompt: Call get_design_status(editorId) to get the active artifact, then create_new_artifact to start editing.

Creates a new, blank design system owned by you and returns its ID + editor URL. Seeds an empty initial version so you can immediately write files into it.

NEXT STEPS:

• write_design_system_files(designSystemId, files) to add components, styling, and rules
• publish_design_system(designSystemId) to publish a version

Note: this creates a BLANK design system. Forking from an existing design system is not supported here.

Creates a Magic Patterns inspiration document and returns a shareable magicpatterns.com/inspiration/<id> link that renders the concepts side by side.

Preferred flow: create a PLACEHOLDER here by declaring each concept's { name, description } WITHOUT html, then fill each one in with a separate inspiration_add_variant call (passing the html directly). This lets you publish the link immediately and stream each concept in without ever holding all the HTML at once. The page shows a loading tile per declared concept until its html arrives.

You may also pass html inline for any/all concepts to publish them fully in one call (the document is only marked ready once every concept has html).

INPUT:

• title: short label for what the concepts explore (e.g. "Projects list empty state").
• files: 1-8 concepts, each { name, description, html? }. Omit html to declare a placeholder concept to fill later via inspiration_add_variant.
• repositoryUrl: optional GitHub repo the concepts came from (kept for context).
• baseline: optional { html, focus, sharedCopy, baselineStyle } — the baseline the variants diverge from (html is the faithful recreation of the current UI).

RESPONSE: { id, url, variants: [{ id, name }] }. Pass each variant id (with the inspiration id) to inspiration_add_variant to fill it in. Return the url to the user; it may require login.

Creates a new artifact by cloning an existing artifact. The new artifact becomes the active artifact for the design. This gives you a safe "branch" to write code to before publishing.

BEFORE CALLING: Always call get_design_status or get_artifact first to get the CURRENT active artifact ID. The user may have changed the active artifact in the UI since you last checked.

WHEN TO USE: Call this BEFORE making file changes (write_artifact_files) so the user can revert to the previous artifact if needed.

The new artifact is set as active and a version entry is added to the design timeline with the provided name.

NEXT STEPS:

• Call read_artifact_files(artifactId, fileNames) to understand existing code.
• Call write_artifact_files(artifactId, files) to make changes.
• Call publish_artifact(artifactId, editorId) when done.

Creates a new Magic Patterns slide deck and kicks off AI generation. A slide deck is a 16:9, full-bleed, one-slide-at-a-time React presentation where each slide maps to a screen in the canvas.

BEHAVIOR:

• A prompt is REQUIRED — the deck is generated from it (unlike create_design, there is no blank-deck path).
• Generation is long-running (especially with design-system setup). Do not wait synchronously; poll get_design_status to track progress.

You can optionally specify a design system. If the user mentions one, call list_design_systems first.

NEXT STEPS:

• Call get_design_status(editorId) to poll until generation completes. This often takes a while, so keep polling instead of assuming the deck is ready immediately.

Gets the active artifact for a design, including its ID and list of files.

Use this to discover the current artifact before reading files or creating a new artifact branch. Because the editor is collaborative, always call this (or get_design_status) to get the LATEST active artifact — do not rely on a previously cached artifact ID.

NEXT STEPS:

• Call read_artifact_files(artifactId, fileNames) to read code.
• Call create_new_artifact(artifactId, name) to create a working copy before making changes.

Gets the current status of a design: whether AI generation is active, the active artifact ID, and available files.

ALWAYS call this before starting new work on an existing design. The user or other agents may have changed the active artifact, sent prompts, or made edits in the UI since you last checked. This is your source of truth for the current state.

Also use this to poll for completion after create_design (with prompt) or send_prompt.

RESPONSE:

• isGenerating: true if AI is still working
• activeArtifactId: the current active artifact ID (use for create_new_artifact, read_artifact_files, etc.)
• availableFiles: list of file names in the active artifact

NEXT STEPS:

• If isGenerating=true: Wait at least 60 seconds before polling again. Generation can take up to 10 minutes.
• If isGenerating=false: Use activeArtifactId with create_new_artifact (for code-first edits) or read_artifact_files (to inspect generated code).

Resolves a design system's active artifact and lists its files. ALWAYS call this first — design systems are collaborative, so the active artifact id can change between calls; never reuse a cached artifactId.

Returns:

• artifactId: the current active artifact (pass as baseArtifactId to write_design_system_files to detect drift)
• files: the persisted files (e.g. components/<Name>/*, index.css, tailwind.config.js, rules/*)
• hasUnpublishedChanges: whether the active artifact differs from the latest published version
• guide: pointer to the design_system_authoring_guide prompt — load it before writing files

NEXT STEPS:

• read_design_system_files(designSystemId, fileNames) to read file contents
• write_design_system_files(designSystemId, files) to create or update files
• publish_design_system(designSystemId) to publish a new version

Resolves a Magic Patterns URL to an editor ID. Use this when the user shares a Magic Patterns link and you need the editorId for subsequent operations like send_prompt or get_design_status.

NEXT STEPS: Use the returned editorId with send_prompt, get_design_status, get_artifact, or other editor-scoped tools.

Loads a Magic Patterns inspiration document by its id. An inspiration document is a set of design "concepts" (variants) — each a self-contained HTML sketch of a UI direction.

Use this when the user asks to implement/build a specific concept from a Magic Patterns inspiration (e.g. "Implement Concept B from Magic Patterns inspiration <id>"). Pass the inspiration id as inspirationId.

RESPONSE:

• title, userPrompt: the original request the concepts explore
• viewport: the canvas the concepts were authored against (absent = 1280x800 desktop). Any concept you regenerate must be authored at these exact dimensions.
• status: 'generating' while concepts are still being produced, else 'ready'/'error'.
• variants: the concepts, in order. Concept A = variants[0], Concept B = variants[1], etc. Each has { id, name, description, implementationPrompt, html, status }. A variant is only usable once its status is 'ready'; a non-ready one has empty/partial html and must NOT be recreated (retry after generation finishes).

NEXT STEPS: Pick the referenced concept (by letter/name), confirm its status is 'ready', then recreate its html as a React + TypeScript component in the user's project, keeping the styling 1:1 (same layout, colors, spacing, typography; copy SVGs verbatim).

Fills in one concept of an existing Magic Patterns inspiration document with its self-contained HTML.

Use this after create_inspiration_document to stream concepts in one at a time: pass the html directly here instead of holding it all for a single create call. The concept renders live on the shared page as soon as its html arrives, and the document flips to "ready" once every concept is filled.

INPUT:

• inspirationId: the inspiration document id returned by create_inspiration_document.
• variantId: the concept id returned by create_inspiration_document (targets that specific placeholder). If omitted, the first still-empty concept is filled.
• name / description: optional; updates the concept's label/direction.
• html: the full, self-contained HTML document (non-empty).

RESPONSE: { ok, variantId, url }.

Resets every concept of an existing Magic Patterns inspiration document back to an empty placeholder — dropping each concept's html and its pre-created "Iterate" room.

Use this to REPLACE all concepts: clear the document, then invent a fresh set of directions and stream each one's html back in with inspiration_add_variant (targeting the returned concept ids). The document shows loading tiles again until the new concepts arrive.

INPUT:

• inspirationId: the inspiration document id returned by create_inspiration_document.

RESPONSE: { ok, url, variants: [{ id, name }] }. Each concept keeps its id and name; pass them to inspiration_add_variant (with a new name/description/html) to fill the fresh concepts in.

Revises a single already-filled concept of a Magic Patterns inspiration document in place, replacing its html (and optionally its name/description).

Use this to UPDATE a subset of concepts (e.g. "focus more on the messaging", "update Concept C") without touching the others: read the current concepts with get_inspiration_document, regenerate the targeted concept FROM ITS PREVIOUS html, then push the revised html here. The concept's "Iterate in Magic Patterns" room is refreshed so it builds from the new html.

INPUT:

• inspirationId: the inspiration document id.
• variantId: the concept id to revise (from get_inspiration_document). Required — this targets an existing filled concept, unlike inspiration_add_variant which fills empty placeholders.
• name / description: optional; updates the concept's label/direction.
• html: the full, self-contained HTML document (non-empty).

RESPONSE: { ok, variantId, url }.

Lists the design systems available to the authenticated user. Returns both built-in (reserved) design systems and any custom design systems the user has created or has access to.

Use this when the user mentions a specific design system (e.g. "use Shadcn", "with my company design system") so you can resolve the correct ID to pass to create_design.

Each result includes:

• id: The unique design system ID to pass to create_design
• name: The human-readable name
• isReserved: Whether it is a built-in preset (e.g. Base, Shadcn, MUI)
• isActive: Whether this is the user's currently active design system

Lists the artifact version history for a design. Returns the most recent 20 versions with their artifact IDs, version labels, and titles. Use the skip parameter to paginate backwards.

Because the editor is collaborative, new versions may have been created by the user or AI since you last checked. Use this alongside get_design_status to understand the full picture.

Each version corresponds to a snapshot of the design's code at a point in time. Use the artifactId from a version entry to read_artifact_files for that version, or create_new_artifact to branch from it.

Compiles an artifact's source files and sets it as the active artifact for the design. This is the final step in the code-first workflow (Workflow B).

This tool: 1. Compiles all source files in an existing artifact version (bundling for preview). 2. Sets that artifact as the design's active artifact (so it appears in the editor and preview). 3. Does NOT create a version entry. Call create_new_artifact first and publish the artifactId it returns. 4. Records your description on the version, above the file changes already logged from write_artifact_files.

ALWAYS pass a description. The people who open this design did not watch you work, and the version is otherwise an unexplained code change.

NEXT STEPS: The design preview will update. Share the editor URL with the user.

Publishes the design system's active artifact as a new immutable version. STRICT: refuses if the active artifact has validation errors — run write_design_system_files and clear all validationErrors first.

Returns the new version (major.minor) and whether it is backwards-compatible with the previously published version (a breaking change — e.g. a removed component or prop — bumps the major version).

Reads the contents of one or more files from an artifact.

IMPORTANT: Always read files BEFORE making changes with write_artifact_files so you understand the current state.

This code is meant as a starting point or inspiration. It is NOT production-ready. You should adapt this code to match the user's project style, frameworks, libraries, and conventions.

Reads the contents of one or more files from a design system's active artifact.

Design system file structure:

• components/<Name>/index.tsx — component source (named exports only)
• components/<Name>/<Name>.previews.tsx — preview definitions; default-export a ComponentPreviewModule with componentName, importPath, and previews
• components/<Name>/Context.md — AI/usage documentation
• index.css — design system styles / Tailwind imports
• tailwind.config.js — Tailwind configuration
• rules/<slug>.md — design rules

Call get_design_system first to discover available file names. Always read before editing.

Reads the recent chat item history for a design. Returns the last 10 chat items (user prompts, AI responses, artifact versions, edits). Use the skip parameter to paginate backwards through older items.

Because the editor is collaborative, the user may have sent prompts or made changes in the UI between your tool calls. Use this to catch up on what happened and understand the current context before acting.

Note: Code contents are omitted from the response to keep it concise. Use read_artifact_files to read full file contents.

Sends a natural language prompt to the Magic Patterns AI for an existing design. The AI will interpret the prompt and generate/update code. Returns immediately with a requestId.

BEFORE CALLING: Call get_design_status(editorId) to make sure the design is not already generating (isGenerating=false) and to understand the current state. The user may have sent prompts or made changes in the UI.

Use this for prompt-based updates to existing designs (Workflow A with existing design).

⚠️ IMPORTANT: This kicks off a LONG-RUNNING generation that typically takes 2–10 minutes. Do NOT poll more often than every 60 seconds. Call get_design_status(editorId) once every 60 seconds until isGenerating=false. Do NOT treat slow generation as an error — it is expected.

Creates or overwrites one or more files in an artifact. If a file exists, it will be replaced. If it doesn't exist, it will be created.

IMPORTANT: This only saves source files — it does NOT compile or publish. Call publish_artifact after you have finished all file changes.

Each file you write is logged onto the version in the design's chat, with a diff the user can open — so the design records what you changed, not just the end result.

NEXT STEPS:

• Call write_artifact_files again for additional files.
• When done with all changes, call publish_artifact(artifactId, editorId) to compile and activate.

Creates or overwrites files in a design system. Incoming files are validated, merged onto the existing artifact (existing files are preserved), compiled, and activated immediately.

COMPONENT FORMAT (required):

• Use a PascalCase folder and write the complete trio for every code component:

components/<Name>/index.tsx components/<Name>/<Name>.previews.tsx components/<Name>/Context.md

• Export the component from index.tsx as a named export. Default exports reject the entire write; fix the file and retry.
• Default-export the previews object from <Name>.previews.tsx. It must include componentName, importPath, and previews; every preview needs a render function returning JSX.
• Do not write flat component files such as components/Button.tsx or components/Button/Button.tsx.

IMPORTANT:

• Call get_design_system first and pass its artifactId as baseArtifactId. A 409 means someone else changed the design system — re-read and retry.
• Magic Patterns does not post-process MCP writes. Non-canonical paths, syntax errors, source-format violations, and shell/auto-generated files reject the entire write so you can fix them and retry.
• validationErrors for incomplete component trios remain non-blocking — fix them before publish_design_system, which is strict.

Load the design_system_authoring_guide prompt for the full file contract.