miromiro-mcp 0.2.0 → 0.2.1

package/README.md

@@ -1,11 +1,30 @@
 # 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.
+
+## 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 +52,46 @@ 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_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.
 
-## Example
+### 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
+
+The REST API and this local npm server always return everything untrimmed.
+
+## 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. It does not execute JavaScript, so a fully client-rendered app may return little for images and Lottie (tokens, fonts, brand, and code come from CSS and are unaffected).
+- 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.2.1",
   "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

@@ -57,7 +57,7 @@ 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' } },
@@ -157,7 +157,7 @@ async function callApi(endpoint, args) {
 }
 
 const server = new Server(
-  { name: 'miromiro', version: '0.2.0' },
+  { name: 'miromiro', version: '0.2.1' },
   { capabilities: { tools: {} } }
 )