Wizard Spells MCP Server & Prototyping Harness

The official Model Context Protocol (MCP) server and prototyping harness for Instrument Wizard Spells.

Enables non-technical and semi-technical creative users (designers, strategists, creative technologists) using Cursor or Google Antigravity (VS Code Plugin / IDE) to rapidly prototype interactive experiences and deploy them to Wizard Spells with zero terminal friction.

⚡ 30-Second Quickstart

Step 1: Connect Cursor & Antigravity

From the Wizard Spells Web UI, generate an API Key, or run:

npx @ricky.instrument/spells-mcp setup --token sp_live_YOUR_TOKEN_HERE

This single command:

• Verifies your token against the Spells API.
• Configures Cursor (~/.cursor/mcp.json).
• Configures Antigravity (~/.gemini/config/mcp_config.json).
• Automatically configures the spells MCP server running over stdio.

Step 2: Start Prototyping

Open any folder in Cursor or VS Code (with Antigravity).

In your AI chat (Composer / Chat), prompt:

"Scaffold a new Three.js interactive prototype for Nike"

The AI invokes spells.scaffold_prototype to create:

• Starter code (index.html, style.css, main.js)
• spell.config.json and spell.config.schema.json
• .cursorrules (instructing Cursor to keep paths relative and never publish without user approval)
• GEMINI.md (instructing Antigravity with matching guidelines)

Step 3: Review Configuration & Metadata

You can customize spell.config.json at any time before publishing:

• Give your prototype a custom title and slug.
• Assign it to an active Spells platform project (e.g. nike, google, internal).
• Configure permissions (default: Instrument & Google accounts only, or public).

Prompt your AI to check your prototype:

"Validate this prototype"

The AI invokes spells.validate_prototype and reports your metadata, Spells project validity, and file health.

Step 4: Publish When You're Ready

🚨 Publication Policy: The AI will NEVER publish your prototype autonomously. It will only deploy when you explicitly command it to do so.

🛑 Failure & Retry Limit: If a deployment fails twice, the AI will immediately stop trying, report the error details to you, and suggest you ask for help from team members (e.g. in the Spells Slack channel).

When you're ready to share your prototype, prompt:

"Deploy this prototype to Spells"

The AI invokes spells.deploy_prototype, streams files directly to Google Cloud Storage via signed URLs, and returns your live preview link: https://wizard.instrument.com/spells/your-prototype-slug

⚙️ Prototype Configuration (spell.config.json)

Every prototype uses spell.config.json at the root as its single source of truth for deployment metadata.

{
  "$schema": "./spell.config.schema.json",
  "title": "Interactive 3D Sneaker Showcase",
  "slug": "interactive-3d-sneaker-showcase",
  "project": "nike",
  "description": "Interactive Three.js sneaker configurator with colorway customization.",
  "permissions": {
    "users": [
      "*@instrument.com",
      "*@google.com"
    ]
  },
  "entry": "index.html",
  "rewrite_asset_urls": true
}

Properties Reference

| Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | title | string | Yes | Human-readable title displayed on Spells overview cards and browser tabs. | | slug | string | Yes | Unique URL identifier under /spells/<slug>/. Lowercase alphanumeric and single hyphens only. | | project | string | Yes | Active Spells project key. Must be a project listed by Spells (run spells.list_projects). | | permissions | object | Yes | Access control settings. Defaults to ["*@instrument.com", "*@google.com"]. Use [] for public access. | | description | string | No | Creative summary or notes for reviewers. | | anchor_slug | string | No | Slug of the anchor spell if this prototype is a child version. | | slug_appendage | string | No | Version suffix (e.g. v2) if this prototype is a child version. | | entry | string | No | Main HTML entry point (defaults to "index.html"). | | rewrite_asset_urls | boolean | No | Automatically rewrites root-relative asset URLs (e.g. /style.css -> ./style.css) (default: true). |

Note on Tags: Tags are not currently supported by the Spells platform. Mandatory Creation Fields: Initial publishing requires title, slug, project, permissions, and at least one file (index.html). Slug & Appendage Prompting: AI assistants are instructed to NEVER auto-generate slugs or appendages without explicit user confirmation. Pre-flight checks will verify availability on Spells and warn if a slug is already taken.

🛠️ MCP Tools Reference

| Tool | Description | Key Parameters | | :--- | :--- | :--- | | deploy_prototype | Publishes or updates a prototype directory on Spells. Only called upon explicit user request. | path, title, slug, project_key, permissions, action ("add" | "update"), update, rewrite_asset_urls | | create_version | Adds an iteration (e.g. v2, dark-mode) under an anchor spell and records lineage in spell.config.json. Only called upon explicit user request. | anchor_slug, slug_appendage, path, title, copy_files | | list_projects | Lists active client projects on the Spells platform. | active_only (default true) | | get_spell_status | Checks deployment/build health of a spell. | slug | | scaffold_prototype | Initializes a folder with starter code, spell.config.json, and agent rules. | template (creative-canvas, threejs-3d, vite-tailwind), title, slug, project, permissions | | validate_prototype | Validates entry points, asset paths, size, and verifies spell.config.json against Spells platform projects. | path, title, slug, project_key, permissions |

🧪 Development & Testing

cd tools/mcp-server
npm install
npm run build
npm test