miromiro-mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,11 +1,44 @@
 # miromiro-mcp
 
-MCP server for the [MiroMiro](https://miromiro.app/api) design-extraction API. Give your coding agent (Cursor, Claude Code, Windsurf) the real design of any website — code, tokens, assets, SVGs, fonts, and Lottie — so it builds UI in that style instead of guessing.
+[![npm version](https://img.shields.io/npm/v/miromiro-mcp)](https://www.npmjs.com/package/miromiro-mcp)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-## Setup
+MCP server for the [MiroMiro](https://miromiro.app/api) design-extraction API. Give your AI agent the real design of any live website - brand colors, fonts, design tokens, SVGs, images, Lottie animations, and paste-ready component code - so it builds from actual values instead of guessing from a screenshot.
 
-1. Get a free API key (100 credits/month, no card) at **https://miromiro.app/api/dashboard**.
-2. Add the server to your agent's MCP config:
+Works with Claude (web, desktop, Claude Code), ChatGPT, Cursor, Windsurf, Codex, and any MCP client.
+
+## Claude Code plugin
+
+Install as a plugin to get the tools plus three skills that teach Claude when to reach for
+each one (`clone-section`, `match-brand`, `extract-assets`):
+
+```bash
+claude plugin marketplace add anthropics/claude-plugins-community
+claude plugin install miromiro@claude-community
+```
+
+The plugin uses the remote server, so there is nothing to install and no key to paste - on
+first use it opens a one-click MiroMiro sign-in that links a free account (100 credits/month,
+no card).
+
+## Quick start: remote server (nothing to install)
+
+A hosted server lives at:
+
+```
+https://miromiro.app/mcp
+```
+
+Paste that URL into any client that accepts a remote MCP server. On first use it opens a one-click MiroMiro sign-in that links a free account (100 credits/month, no card).
+
+- **Claude (web or desktop):** Settings → Connectors → Add custom connector → paste the URL. Or use the [one-click install](https://miromiro.app/api/mcp).
+- **ChatGPT:** Settings → Security and login → enable Developer mode, then add the URL as a connector (authentication: OAuth).
+- **Cursor (remote):** add `{ "mcpServers": { "miromiro": { "url": "https://miromiro.app/mcp" } } }` to `~/.cursor/mcp.json`.
+- **Raw API key instead of OAuth:** append `?access_key=mm_live_...` to the URL, or send it as an `Authorization: Bearer` header.
+
+## Local server (npm)
+
+Prefer a local stdio process with the key in an env var? Get a free key at [miromiro.app/api/dashboard](https://miromiro.app/api/dashboard), then:
 
 **Cursor** (`~/.cursor/mcp.json`) / **Windsurf** (Settings → MCP):
 
@@ -33,24 +66,50 @@ claude mcp add miromiro -s user \
 
 | Tool | What it returns | Credits |
 |---|---|---|
-| `extract_code` | A section of a live page as a paste-ready component (Tailwind, HTML+CSS, JSX or Vue) + the tokens it uses — start here to rebuild real UI | 25 |
-| `extract_brand` | Named color roles (primary/accent/background/text), palette, fonts, logo | 15 |
-| `extract_design_tokens` | Full token system; `format: css` or `tailwind` for paste-ready output | 10 |
-| `extract_fonts` | Font files & families the site loads | 5 |
-| `extract_lottie` | Lottie animations declared in the page | 3 |
-| `extract_svgs` | Inline SVG code + SVG files | 1 |
-| `extract_assets` | Every image URL on a page | 1 |
+| `extract_code` | A section of a live page as a paste-ready component (Tailwind, HTML+CSS, JSX or Vue) plus the tokens it uses - start here to rebuild real UI | 25 |
+| `extract_brand` | Named color roles (primary/accent/background/text), palette, fonts split by role, logo, social profiles, and a 0-1 confidence score | 15 |
+| `extract_design_tokens` | Full token system with usage counts; `format: css` or `tailwind` for paste-ready output | 10 |
+| `extract_fonts` | Every font file and family the site loads, with weights, formats, and file URLs | 5 |
+| `extract_videos` | Video files, `og:video`, and player embeds (YouTube, Vimeo, Wistia, Loom), tagged by source | 1 |
+| `extract_audio` | Audio files, `og:audio`, and podcast enclosures, tagged by source | 1 |
+| `extract_lottie` | Lottie animation JSON files declared in the page | 3 |
+| `extract_svgs` | Inline SVG code (sanitized, paste-ready) plus external SVG file URLs | 1 |
+| `extract_assets` | Every image URL on a page, tagged by source, with alt text | 1 |
+
+All tools are read-only and retry-safe. Identical calls within 24 hours are served from cache for free, and failed calls are never billed.
+
+### Controlling output size (remote server)
+
+Remote results are trimmed by default so a big page cannot flood the chat context, and every trimmed response says exactly what was dropped. Two optional arguments loosen it per call:
+
+- `limit` (up to 200) - raise the item cap: "give me 80 SVGs, not 20"
+- `full_output: true` - complete long strings, like entire inline SVG markup
 
-## Example
+The REST API and this local npm server always return everything untrimmed, so `limit` and
+`full_output` apply to the remote server only. Every tool on both servers accepts
+`render: true`.
+
+## Examples
 
 > "Rebuild stripe.com's pricing section in React"
 
-The agent calls `extract_code` with the URL → gets the section's real markup, colors, fonts and spacing → adapts actual values instead of guessing from a screenshot.
+The agent calls `extract_code` with the URL, gets the section's real markup, colors, fonts, and spacing, and adapts actual values instead of guessing.
+
+> "Build a dashboard in the style of linear.app"
+
+The agent calls `extract_brand` and `extract_design_tokens`, gets Linear's real colors, fonts, and spacing scale, and builds to match.
+
+> "What fonts does apple.com use?"
+
+The agent calls `extract_fonts` and returns every family with its font file URLs and weights.
+
+## Notes
 
-> "Build a pricing section in the style of linear.app"
+- The API reads static HTML and resolves the full CSS cascade by default, so a fully client-rendered app may return little for images, video, audio and Lottie (tokens, fonts, brand, and code come from CSS and are unaffected). Pass `render: true` on any remote-server tool to run the page in a real browser first so its JavaScript executes (+5 credits).
+- Respect the sites you extract from: check their terms before reusing assets commercially.
 
-The agent calls `extract_brand` → gets Linear's real colors and fonts → builds the section matching them.
+## Links
 
-## Credits
+[API docs](https://miromiro.app/api/docs) · [Playground (no account)](https://miromiro.app/api/demo) · [Pricing](https://miromiro.app/api/pricing) · [Changelog](https://miromiro.app/api/changelog) · [Connect page](https://miromiro.app/api/mcp)
 
-Weighted per endpoint (see table above). Cached and failed calls are free. Full reference: [docs](https://miromiro.app/api/docs) · [pricing](https://miromiro.app/api/pricing).
+MIT © [MiroMiro](https://miromiro.app)

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "miromiro-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for the MiroMiro design-extraction API — give your coding agent the real code, design tokens, assets, SVGs, fonts, and Lottie of any website.",
+  "mcpName": "app.miromiro/miromiro",
   "type": "module",
   "author": "MiroMiro (https://miromiro.app)",
   "homepage": "https://miromiro.app/api",
-  "bugs": { "url": "https://miromiro.app/api/docs/errors" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SoraiaBarroso/miromiro-mcp.git"
+  },
+  "bugs": { "url": "https://github.com/SoraiaBarroso/miromiro-mcp/issues" },
   "bin": {
     "miromiro-mcp": "src/index.mjs"
   },
@@ -15,8 +20,11 @@
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "mcp-server",
     "design-tokens",
     "design-to-code",
+    "brand-colors",
+    "web-scraping",
     "miromiro",
     "cursor",
     "claude-code",

package/src/index.mjs

@@ -34,20 +34,29 @@ const TOOL_ANNOTATIONS = {
   openWorldHint: true
 }
 
+// Shared input arg: every tool accepts render=true to execute the page's
+// JavaScript in a real (rented) browser before extraction - the fix for
+// client-rendered React/Next/SPA sites that return little statically.
+const RENDER_ARG = {
+  type: 'boolean',
+  description: 'Run the page in a real browser first so its JavaScript executes - use for client-rendered (React/Next/SPA) sites, or when a normal call came back thin. Slower, and adds 5 credits to the call.'
+}
+
 const TOOLS = [
   {
     name: 'extract_code',
     title: 'Extract section as code',
     endpoint: 'code',
     description:
-      "Turn a section of a LIVE website into clean, paste-ready component code. Give it a URL and (optionally) a CSS selector; it resolves the page's real CSS cascade and returns a self-contained component in Tailwind, plain HTML+CSS, React (JSX) or Vue — plus the design tokens that section actually uses. The response also includes `sections`: every extractable section on the page with a human-readable label and a ready selector — when the user wants a specific part (pricing, footer, testimonials), find it there and call again with that selector. USE THIS whenever the user asks to rebuild, clone, port, or copy a section of a real website: it returns the actual code with true colors, fonts, spacing and copy, so you adapt real values instead of guessing from a screenshot. Note: it reads static HTML/CSS and does not execute JavaScript, so a fully client-rendered app may return little.",
+      "Turn a section of a LIVE website into clean, paste-ready component code. Give it a URL and (optionally) a CSS selector; it resolves the page's real CSS cascade and returns a self-contained component in Tailwind, plain HTML+CSS, React (JSX) or Vue — plus the design tokens that section actually uses. The response also includes `sections`: every extractable section on the page with a human-readable label and a ready selector — when the user wants a specific part (pricing, footer, testimonials), find it there and call again with that selector. USE THIS whenever the user asks to rebuild, clone, port, or copy a section of a real website: it returns the actual code with true colors, fonts, spacing and copy, so you adapt real values instead of guessing from a screenshot. Note: it reads static HTML/CSS by default - for a fully client-rendered app that returns little, call again with render=true to execute the page's JavaScript in a real browser first (+5 credits).",
     inputSchema: {
       type: 'object',
       properties: {
         url: { type: 'string', description: 'The website URL, e.g. stripe.com' },
         selector: { type: 'string', description: 'CSS selector for the section to extract, e.g. "#hero" or ".pricing-card". Omit to auto-detect the hero.' },
         framework: { type: 'string', enum: ['tailwind', 'html', 'jsx', 'vue'], description: 'The code to generate (default tailwind).' },
-        name: { type: 'string', description: 'Component name for the jsx/vue targets (default ExtractedSection).' }
+        name: { type: 'string', description: 'Component name for the jsx/vue targets (default ExtractedSection).' },
+        render: RENDER_ARG
       },
       required: ['url']
     }
@@ -57,10 +66,10 @@ const TOOLS = [
     title: 'Extract brand identity',
     endpoint: 'brand',
     description:
-      "Get a website's curated brand identity: named color roles (primary, accent, background, text), the brand palette, primary fonts, logo, and social image. Use this when you only need a site's STYLE (colors/fonts) rather than its code — to build new UI 'in the style of' a reference site. If you need the actual markup of a section, use extract_code instead.",
+      "Get a website's curated brand identity: color roles (primary, accent, background, text) read from the site's own CSS variables and logo — each as hex plus a human-readable name like 'Royal Blue' — dark/light theme detection, the brand palette, fonts split by role (primary/mono), logo, social image, the brand's social profiles (X, GitHub, LinkedIn, …), and a 0-1 confidence score for how much the site declared vs how much was inferred. Use this when you only need a site's STYLE (colors/fonts) rather than its code — to build new UI 'in the style of' a reference site. If you need the actual markup of a section, use extract_code instead.",
     inputSchema: {
       type: 'object',
-      properties: { url: { type: 'string', description: 'The website URL, e.g. stripe.com' } },
+      properties: { url: { type: 'string', description: 'The website URL, e.g. stripe.com' }, render: RENDER_ARG },
       required: ['url']
     }
   },
@@ -74,7 +83,8 @@ const TOOLS = [
       type: 'object',
       properties: {
         url: { type: 'string', description: 'The website URL' },
-        format: { type: 'string', enum: ['json', 'css', 'tailwind'], description: 'Output shape (default json)' }
+        format: { type: 'string', enum: ['json', 'css', 'tailwind'], description: 'Output shape (default json)' },
+        render: RENDER_ARG
       },
       required: ['url']
     }
@@ -84,10 +94,10 @@ const TOOLS = [
     title: 'Extract images',
     endpoint: 'images',
     description:
-      "List every image on a page (img, srcset, picture, CSS background, favicon, og:image) as resolved URLs tagged by source. Use to recover imagery from a site or pull reference assets.",
+      "List every image on a page (img, srcset, picture, CSS background, favicon, og:image) as resolved URLs tagged by source. Use to recover imagery from a site or pull reference assets. Best-effort from static HTML: if images are mounted by JavaScript, call again with render=true (+5 credits).",
     inputSchema: {
       type: 'object',
-      properties: { url: { type: 'string', description: 'The website URL' } },
+      properties: { url: { type: 'string', description: 'The website URL' }, render: RENDER_ARG },
       required: ['url']
     }
   },
@@ -96,10 +106,10 @@ const TOOLS = [
     title: 'Extract SVGs',
     endpoint: 'svg',
     description:
-      "Extract inline SVGs (as paste-ready code) and SVG file references from a page. Use to grab icons and vector logos.",
+      "Extract inline SVGs (as paste-ready code) and SVG file references from a page. Use to grab icons and vector logos. Best-effort from static HTML: if icons are mounted by JavaScript, call again with render=true (+5 credits).",
     inputSchema: {
       type: 'object',
-      properties: { url: { type: 'string', description: 'The website URL' } },
+      properties: { url: { type: 'string', description: 'The website URL' }, render: RENDER_ARG },
       required: ['url']
     }
   },
@@ -113,7 +123,8 @@ const TOOLS = [
       type: 'object',
       properties: {
         url: { type: 'string', description: 'The website URL' },
-        fields: { type: 'string', description: "Optional comma-separated fields to return (e.g. 'families')" }
+        fields: { type: 'string', description: "Optional comma-separated fields to return (e.g. 'families')" },
+        render: RENDER_ARG
       },
       required: ['url']
     }
@@ -123,10 +134,34 @@ const TOOLS = [
     title: 'Extract Lottie animations',
     endpoint: 'lottie',
     description:
-      "Find Lottie/animation JSON files declared on a page. Best-effort from static HTML (runtime-injected animations need the MiroMiro browser extension). Use to recover animations.",
+      "Find Lottie/animation JSON files declared on a page. Best-effort from static HTML - most Lotties are runtime-injected, so pass render=true to execute the page JS first and catch those too (+5 credits). Use to recover animations.",
+    inputSchema: {
+      type: 'object',
+      properties: { url: { type: 'string', description: 'The website URL' }, render: RENDER_ARG },
+      required: ['url']
+    }
+  },
+  {
+    name: 'extract_videos',
+    title: 'Extract videos',
+    endpoint: 'videos',
+    description:
+      'List every video a page declares: <video>/<source> files, og:video, player embeds (YouTube, Vimeo, Wistia, Loom) and direct video-file links - each tagged by source, with a poster image when declared. Note `source: "embed"` is a player page, not a downloadable file. Best-effort from static HTML: most sites mount their player with JavaScript, so if the result is thin or empty, call again with render=true to execute the page JS first (+5 credits).',
+    inputSchema: {
+      type: 'object',
+      properties: { url: { type: 'string', description: 'The website URL' }, render: RENDER_ARG },
+      required: ['url']
+    }
+  },
+  {
+    name: 'extract_audio',
+    title: 'Extract audio',
+    endpoint: 'audio',
+    description:
+      'List every audio file a page declares: <audio>/<source> files, og:audio, and direct audio-file links such as podcast enclosures and download buttons - each tagged by source. Best-effort from static HTML: if a JavaScript player mounts the audio at runtime, call again with render=true (+5 credits).',
     inputSchema: {
       type: 'object',
-      properties: { url: { type: 'string', description: 'The website URL' } },
+      properties: { url: { type: 'string', description: 'The website URL' }, render: RENDER_ARG },
       required: ['url']
     }
   }
@@ -134,7 +169,7 @@ const TOOLS = [
 
 // Query params a tool may forward to the API, beyond `url`. Anything else in the
 // tool arguments is ignored, so a hallucinated param can't reach the endpoint.
-const FORWARDED_PARAMS = ['format', 'selector', 'framework', 'name', 'fields']
+const FORWARDED_PARAMS = ['format', 'selector', 'framework', 'name', 'fields', 'render']
 
 async function callApi(endpoint, args) {
   const q = new URLSearchParams({ url: args.url })
@@ -157,7 +192,7 @@ async function callApi(endpoint, args) {
 }
 
 const server = new Server(
-  { name: 'miromiro', version: '0.2.0' },
+  { name: 'miromiro', version: '0.3.0' },
   { capabilities: { tools: {} } }
 )