Refero MCP

Search styles.refero.design in plain English and drop a DESIGN.md into any project.

Quick Navigation

| Link | Section | What it does | Time | |---|---|---|---| | What this is | Overview | The catalog, the gap, the wrap | ~1 min | | Quick install | Setup | One line into Claude Code | ~1 min | | Usage | Talk to it | Plain-English prompts | ~2 min | | Tools | Reference | The six tools, one line each | ~1 min | | Configuration | Setup | Env vars + JSON config | ~1 min | | How it works | Reference | Cache, embeddings, DESIGN.md generation | ~1 min | | Troubleshooting | Reference | The likely first three problems | ~1 min | | License + Author | Meta | MIT | — |

What this is

Refero Styles is a beta catalog of about 200 curated sites where someone has done the painful work of pulling out the colors, typography, spacing, and per-style do/don't guidance. Each entry ships with a designSystem block that's basically a DESIGN.md waiting to happen.

This MCP wraps that catalog so Claude Code can search it in natural language and drop a generated DESIGN.md straight into whatever project you're scaffolding. No browser-tab JSON copy-paste, no hand-rolled token tables.

It's for anyone using Claude Code to spin up a new app, deck, or client project who wants the design language locked down before the first component renders.

↑ back to top

Quick install

One line:

claude mcp add refero -- npx -y fidgetcoding-refero-mcp

Restart Claude Code and start describing the look you want.

If you want vibe search (semantic ranking against each style's poetic northStar summary), pass an OpenAI key:

claude mcp add refero --env OPENAI_API_KEY=sk-... -- npx -y fidgetcoding-refero-mcp

Without it, search falls back to keyword scoring. Works fine, just less magical.

For claude_desktop_config.json users:

{
  "mcpServers": {
    "refero": {
      "command": "npx",
      "args": ["-y", "fidgetcoding-refero-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "REFERO_MCP_VAULT_DIR": "/absolute/path/to/your/vault"
      }
    }
  }
}

↑ back to top

Usage

[!IMPORTANT] You talk. Claude dispatches. No commands, no syntax, no JSON.

Every tool here is wired to plain-English prompts. You don't memorize tool names or build payloads — Claude picks the tool and fills in the parameters.

A few prompts that route cleanly:

"Find me a dark editorial style with a serif and a warm accent."

"Pull the full breakdown for Linear."

"What's similar to Vercel in the Refero catalog?"

"Render Cursor's DESIGN.md — don't save it yet, just show me."

"Save Cursor's DESIGN.md into my PARZVL project."

"Show me only dark-mode brutalist styles, top five."

"Refresh the Refero catalog before we start the design pass."

More worked recipes in docs/USAGE.md.

↑ back to top

Tools

| Tool | What it does | |---|---| | refero_search | Natural-language vibe search across the catalog. Embeddings if OPENAI_API_KEY is set, BM25-lite fallback if not. | | refero_get | Fetch the full design system for one style. Accepts a uuid, hostname (e.g. cursor.com), or site name (e.g. "Cursor"). | | refero_similar | Refero's own "similar styles" ranking for a given style. Free recommendations from the upstream. | | refero_list | Browse the local catalog mirror with optional theme/tag filters. Stably ordered. | | refero_design_md | Render a style as an agent-friendly DESIGN.md (frontmatter, north star, color table, dos/donts). Optionally writes to disk. | | refero_refresh | Force a full re-fetch of the catalog and overwrite the local mirror. Skips the 24h TTL. |

↑ back to top

Configuration

Everything is optional. Defaults are picked so the MCP just runs.

| Variable | Required | Default | What it does | |---|---|---|---| | OPENAI_API_KEY | No | unset | Enables vibe search via text-embedding-3-small. Without it, search falls back to keyword scoring. | | REFERO_API_BASE | No | https://styles.refero.design | Override if Refero ever moves the API or you're pointing at a fixture. | | REFERO_CACHE_DIR | No | ~/.refero-cache | Where the local catalog mirror, embeddings, and detail cache live. | | REFERO_CACHE_TTL_MS | No | 86400000 (24h) | How long a cached page is considered fresh. | | REFERO_MCP_VAULT_DIR | No (required for project writes) | unset | Absolute path to the vault root that refero_design_md writes into. If unset, the tool returns the markdown but doesn't write to disk. |

A copy-paste .env.example ships in the repo root.

There's no default for REFERO_MCP_VAULT_DIR. The previous draft hardcoded my laptop path, which worked great for exactly one machine on Earth. The reviewer caught it. Now if you don't set it, the tool just refuses to write — rude, but better than dropping files into a folder that doesn't exist on your computer.

↑ back to top

How it works

There is no public Refero API doc as of writing — the shape was mapped empirically against the live site. The full breakdown is in docs/api-surface.md so future-me doesn't re-discover it.

• Local catalog mirror. Refero exposes ?page=N pagination but silently ignores ?search=, ?q=, and ?colorScheme=. So this MCP walks the pages once, mirrors them locally under REFERO_CACHE_DIR, and runs all filtering and ranking client-side.
• Vibe search via northStar. Every Refero style ships with a one-line poetic summary called northStar. With OPENAI_API_KEY set, the MCP embeds those summaries with text-embedding-3-small and ranks by cosine similarity to your query. Without a key, it falls back to keyword scoring on northStar + tags + site name.
• DESIGN.md generated locally. Refero does not expose a /design.md endpoint. The MCP synthesizes one from style.fullResult.designSystem (dos, donts, tags, theme, role-tagged colors). Output is compatible with the /stitch-design-taste and /design-taste-frontend skills.

↑ back to top

Troubleshooting

"No styles found" / catalog feels empty. First-run hits a cold cache. Ask Claude to "refresh the Refero catalog" once — it walks the ~10 pages with a polite 250ms gap and writes them to REFERO_CACHE_DIR. After that, search is instant.

Search results feel keyword-y rather than semantic. You probably don't have OPENAI_API_KEY set. Add it to your MCP config and restart, or lean harder on the catalog's vocabulary (industries plus tags like editorial, brutalist, glass).

refero_design_md returns markdown but won't write to disk. REFERO_MCP_VAULT_DIR is unset. Set it to your vault root (absolute path) and the tool will write to <vault>/05-Projects/<NAME>/DESIGN.md. Without it, you get the markdown back in conversation and can paste it wherever.

↑ back to top

License

MIT — see LICENSE for details.

Author

Built by Nate Davidovich / Lorecraft LLC.

• GitHub: lorecraft-io
• npm: lorecraft
• Sister projects: morgen-mcp, motion-mcp

⤴ back to top

Security: gitleaks scan

This repo ships with a .gitleaks.toml config and a scripts/security-scan.sh helper that scans the working tree for secrets (GitHub tokens, API keys, JWTs, private keys, Anthropic keys, etc.).

bash scripts/security-scan.sh

A .husky/pre-commit hook also runs gitleaks protect --staged on every commit and warn-no-ops if gitleaks isn't installed locally.

If you don't have it yet:

• macOS: brew install gitleaks
• Linux: https://github.com/gitleaks/gitleaks/releases