miromiro-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MiroMiro (Soraia Barroso)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# 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.
+
+## Setup
+
+1. Get a free API key (100 credits/month, no card) at **https://miromiro.app/app/developers**.
+2. Add the server to your agent's MCP config:
+
+**Cursor** (`~/.cursor/mcp.json`) / **Windsurf** (Settings → MCP):
+
+```json
+{
+  "mcpServers": {
+    "miromiro": {
+      "command": "npx",
+      "args": ["-y", "miromiro-mcp"],
+      "env": { "MIROMIRO_API_KEY": "mm_live_your_key" }
+    }
+  }
+}
+```
+
+**Claude Code** (run in your terminal, not inside a `claude` session):
+
+```bash
+claude mcp add miromiro -s user \
+  --env MIROMIRO_API_KEY=mm_live_your_key \
+  -- npx -y miromiro-mcp
+```
+
+## Tools
+
+| 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 |
+
+## Example
+
+> "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.
+
+> "Build a pricing section in the style of linear.app"
+
+The agent calls `extract_brand` → gets Linear's real colors and fonts → builds the section matching them.
+
+## Credits
+
+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).

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "miromiro-mcp",
+  "version": "0.1.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.",
+  "type": "module",
+  "author": "MiroMiro (https://miromiro.app)",
+  "homepage": "https://miromiro.app/api",
+  "bugs": { "url": "https://miromiro.app/api/docs/errors" },
+  "bin": {
+    "miromiro-mcp": "src/index.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "design-tokens",
+    "design-to-code",
+    "miromiro",
+    "cursor",
+    "claude-code",
+    "windsurf"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "license": "MIT"
+}

package/src/index.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * MiroMiro MCP server (playbook §3).
+ *
+ * Exposes the MiroMiro design-extraction API as MCP tools so a coding agent
+ * (Cursor / Claude Code / Windsurf) can pull the real design of any URL and
+ * build UI in that style — instead of guessing at colors and fonts.
+ *
+ * Auth: set MIROMIRO_API_KEY in the environment (get one free, no card, at
+ * https://miromiro.app/app/developers).
+ *
+ * Run:  MIROMIRO_API_KEY=mm_live_… npx miromiro-mcp
+ * Or wire it into your agent's MCP config (see README).
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from '@modelcontextprotocol/sdk/types.js'
+
+const API_BASE = process.env.MIROMIRO_API_BASE || 'https://miromiro.app/api/v1'
+const API_KEY = process.env.MIROMIRO_API_KEY
+
+// Tool → endpoint map. Each tool takes a single `url` (design_tokens also takes
+// an optional `format`). Descriptions are written for the agent, so it knows
+// WHEN to reach for each one.
+const TOOLS = [
+  {
+    name: 'extract_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.",
+    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).' }
+      },
+      required: ['url']
+    }
+  },
+  {
+    name: 'extract_brand',
+    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.",
+    inputSchema: {
+      type: 'object',
+      properties: { url: { type: 'string', description: 'The website URL, e.g. stripe.com' } },
+      required: ['url']
+    }
+  },
+  {
+    name: 'extract_design_tokens',
+    endpoint: 'extract',
+    description:
+      "Extract the full design-token system of a URL: every color, font family, font size, border radius, box shadow, line height and z-index (with usage counts). Pass format='css' for a :root {} block or format='tailwind' for a tailwind.config — paste-ready. Use when you need the complete token set, not just the brand summary.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'The website URL' },
+        format: { type: 'string', enum: ['json', 'css', 'tailwind'], description: 'Output shape (default json)' }
+      },
+      required: ['url']
+    }
+  },
+  {
+    name: 'extract_assets',
+    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.",
+    inputSchema: {
+      type: 'object',
+      properties: { url: { type: 'string', description: 'The website URL' } },
+      required: ['url']
+    }
+  },
+  {
+    name: '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.",
+    inputSchema: {
+      type: 'object',
+      properties: { url: { type: 'string', description: 'The website URL' } },
+      required: ['url']
+    }
+  },
+  {
+    name: 'extract_fonts',
+    endpoint: 'fonts',
+    description:
+      "Detect the real typography a site loads by resolving its full CSS cascade: every @font-face file with family/weight/style/format, Google Fonts links, preloads, plus a grouped per-family summary (families). Pass fields='families' for just the summary. Use to match typography.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'The website URL' },
+        fields: { type: 'string', description: "Optional comma-separated fields to return (e.g. 'families')" }
+      },
+      required: ['url']
+    }
+  },
+  {
+    name: 'extract_lottie',
+    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.",
+    inputSchema: {
+      type: 'object',
+      properties: { url: { type: 'string', description: 'The website URL' } },
+      required: ['url']
+    }
+  }
+]
+
+// 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']
+
+async function callApi(endpoint, args) {
+  const q = new URLSearchParams({ url: args.url })
+  for (const p of FORWARDED_PARAMS) {
+    if (args[p] !== undefined && args[p] !== null && args[p] !== '') {
+      q.set(p, String(args[p]))
+    }
+  }
+  const res = await fetch(`${API_BASE}/${endpoint}?${q}`, {
+    headers: { Authorization: `Bearer ${API_KEY}` }
+  })
+  const isJson = (res.headers.get('content-type') || '').includes('application/json')
+  const body = isJson ? await res.json() : await res.text()
+  if (!res.ok) {
+    const msg = isJson ? (body.statusMessage || body.message || JSON.stringify(body)) : body
+    throw new Error(`MiroMiro API ${res.status}: ${msg}`)
+  }
+  return isJson ? JSON.stringify(body, null, 2) : body
+}
+
+const server = new Server(
+  { name: 'miromiro', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }))
+}))
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  if (!API_KEY) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: 'MIROMIRO_API_KEY is not set. Get a free key at https://miromiro.app/app/developers and set it in your MCP config env.' }]
+    }
+  }
+  const tool = TOOLS.find(t => t.name === req.params.name)
+  if (!tool) {
+    return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }] }
+  }
+  const args = req.params.arguments || {}
+  if (!args.url) {
+    return { isError: true, content: [{ type: 'text', text: 'The "url" argument is required.' }] }
+  }
+  try {
+    const out = await callApi(tool.endpoint, args)
+    return { content: [{ type: 'text', text: out }] }
+  } catch (err) {
+    return { isError: true, content: [{ type: 'text', text: String(err.message || err) }] }
+  }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+console.error('miromiro-mcp running on stdio')