@webdesignhot/design-md-mcp 0.1.1 → 0.1.3

package/README.md

@@ -1,10 +1,10 @@
 # @webdesignhot/design-md-mcp
 
-> MCP server exposing the [webdesignhot.com](https://www.webdesignhot.com/design.md/) DESIGN.md catalog (254+ real-brand design systems) to Claude Desktop, Claude Code, Cursor, Cline, and any other MCP-aware AI agent.
+> MCP server exposing the [webdesignhot.com](https://www.webdesignhot.com/design.md/) DESIGN.md catalog (285+ real-brand design systems) to Claude Code, Claude Desktop, Cursor, Codex, Cline, and any other MCP-aware AI agent.
 
 ## Why
 
-When an AI coding agent picks up a project, it usually has no idea what your visual style is. You can paste tokens into the system prompt, hand it a Figma export, or — best — point it at a single `DESIGN.md` file. This MCP server takes that one step further: agents can browse 254+ real-brand design systems (Linear, Stripe, Vercel, Anthropic, Notion, Apple, Tesla, BMW, …) and install one in your project without you ever leaving the chat.
+When an AI coding agent picks up a project, it usually has no idea what your visual style is. You can paste tokens into the system prompt, hand it a Figma export, or — best — point it at a single `DESIGN.md` file. This MCP server takes that one step further: agents can browse 285+ real-brand design systems (Linear, Stripe, Vercel, Anthropic, Notion, Apple, Tesla, BMW, …) and install one in your project without you ever leaving the chat.
 
 ## Tools
 
@@ -17,9 +17,46 @@ When an AI coding agent picks up a project, it usually has no idea what your vis
 
 ## Install
 
-### Claude Desktop / Claude Code
+### Claude Code (CLI / IDE extension)
 
-Add to your `~/Library/Application Support/Claude/claude_desktop_config.json` (or the equivalent on Windows / Linux):
+Easiest — let the `claude` CLI write the config for you. Pick a scope:
+
+```bash
+# Local (default) — only this project, only you. Written to ~/.claude.json
+# under the project key. Teammates won't see it.
+claude mcp add design-md -- npx -y @webdesignhot/design-md-mcp
+
+# Project — committed to the repo's .mcp.json so teammates get it on clone.
+claude mcp add --scope project design-md -- npx -y @webdesignhot/design-md-mcp
+
+# User — every project on your machine, written to ~/.claude.json globals.
+claude mcp add --scope user design-md -- npx -y @webdesignhot/design-md-mcp
+```
+
+Verify with `/mcp` inside Claude Code — `design-md` should be listed with 6 tools (`list_designs`, `get_design`, `search_designs`, `diff_designs`, `export_design`, `install_design`).
+
+Manual alternative for `--scope project` — drop `.mcp.json` in the repo root:
+
+```json
+{
+  "mcpServers": {
+    "design-md": {
+      "command": "npx",
+      "args": ["-y", "@webdesignhot/design-md-mcp"]
+    }
+  }
+}
+```
+
+> **Note:** Claude Code does **not** read `claude_desktop_config.json` — that's Claude Desktop's file. Mixing them up is the #1 wrong path.
+
+### Claude Desktop
+
+Different application, different config file. Edit:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
 
 ```json
 {
@@ -32,17 +69,46 @@ Add to your `~/Library/Application Support/Claude/claude_desktop_config.json` (o
 }
 ```
 
+Restart Claude Desktop after editing.
+
 ### Cursor
 
-In Settings → Features → MCP → "Add new MCP server":
+Drop a JSON file at one of two paths — same shape as Claude:
+
+- Global: `~/.cursor/mcp.json`
+- Project: `.cursor/mcp.json` (in repo root)
+
+```json
+{
+  "mcpServers": {
+    "design-md": {
+      "command": "npx",
+      "args": ["-y", "@webdesignhot/design-md-mcp"]
+    }
+  }
+}
+```
+
+Toggle the server on under **Settings → Features → Model Context Protocol** (or the marketplace at [cursor.directory](https://cursor.directory) for one-click adds on community servers).
+
+### Codex (OpenAI CLI / IDE extension)
+
+Codex uses **TOML**, not JSON. Edit:
+
+- Global: `~/.codex/config.toml`
+- Project: `.codex/config.toml` (for trusted projects only)
+
+```toml
+[mcp_servers.design-md]
+command = "npx"
+args = ["-y", "@webdesignhot/design-md-mcp"]
+```
 
-- **Name**: `design-md`
-- **Type**: `command`
-- **Command**: `npx -y @webdesignhot/design-md-mcp`
+The CLI and the IDE extension share this config — set it once, both clients see it.
 
-### Cline / Roo / etc.
+### Cline / Roo / Continue / etc.
 
-Any MCP client supporting stdio transports works. After install the binary is `design-md-mcp` (no scope) — run it directly, or invoke via `npx -y @webdesignhot/design-md-mcp`.
+Any MCP client supporting stdio transports works. After install the binary is exposed as `design-md-mcp` — run it directly, or invoke via `npx -y @webdesignhot/design-md-mcp`. Most clients accept the same `{ "command": "npx", "args": ["-y", "@webdesignhot/design-md-mcp"] }` JSON shape Claude uses.
 
 ## Use it
 

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@webdesignhot/design-md-mcp",
-  "version": "0.1.1",
-  "description": "MCP server exposing the webdesignhot.com DESIGN.md catalog (254+ real-brand design systems) to Claude Desktop, Claude Code, Cursor, Cline, and any other MCP-aware AI agent. Tools: list, get, search, diff, export.",
-  "keywords": ["mcp", "model-context-protocol", "design.md", "design-system", "ai-agents", "claude", "cursor"],
+  "version": "0.1.3",
+  "description": "MCP server exposing the webdesignhot.com DESIGN.md catalog (400+ real-brand design systems) to Claude Code, Claude Desktop, Cursor, Codex, Cline, and any other MCP-aware AI agent. Tools: list, get, search, diff, export.",
+  "keywords": ["mcp", "model-context-protocol", "design.md", "design-system", "ai-agents", "claude", "claude-code", "codex", "cursor"],
   "author": "webdesignhot",
   "license": "MIT",
   "homepage": "https://www.webdesignhot.com/design.md/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/WebDesignHot/design-md"
+    "url": "git+https://github.com/WebDesignHot/design-md.git"
   },
   "bin": {
     "design-md-mcp": "bin/design-md-mcp.mjs"
@@ -23,6 +23,9 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "prepublishOnly": "node -e \"const p=require('./package.json');const e=require('child_process').execSync;let r='0.0.0';try{r=e('npm view '+p.name+' version 2>/dev/null').toString().trim()||'0.0.0'}catch(_){};if(p.version===r){console.error('\\n\\x1b[31m✗ '+p.name+'@'+p.version+' already on npm. Bump version before publishing.\\x1b[0m\\n');process.exit(1)}console.log('→ '+p.name+': '+r+' → '+p.version)\""
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"
   }

package/src/server.mjs

@@ -64,7 +64,7 @@ const TOOLS = [
   {
     name: 'search_designs',
     description:
-      'Fuzzy-search the catalog by name, tagline, tags, or categories. Returns up to 20 matches sorted by relevance. Use when the user says "something like Linear" or "find me dark editorial designs".',
+      'Fuzzy-search the catalog by name, tagline, tags, or categories. A subsequence match on any of those fields includes an entry; matches are then ranked by relevance — exact name match first, then name prefix, then name substring, then tagline, then tag/category, with weaker subsequence-only hits last — and the top results (default 20, max 50) are returned. Ranking happens before the cap, so the most relevant matches survive it. Use when the user says "something like Linear" or "find me dark editorial designs".',
     inputSchema: {
       type: 'object',
       required: ['query'],
@@ -77,7 +77,7 @@ const TOOLS = [
   {
     name: 'diff_designs',
     description:
-      'Token-level diff between two designs. Returns added / removed / modified colors and radii. Useful for "what would change if we migrated from Linear to Stripe?" questions.',
+      'Token-level diff between two designs. Returns `colors` and `radii`, each split into added / removed / modified token maps (the colors map is scoped to the top-level color tokens; themed entries use their default theme). Useful for "what would change if we migrated from Linear to Stripe?" questions.',
     inputSchema: {
       type: 'object',
       required: ['from', 'to'],
@@ -115,8 +115,10 @@ const TOOLS = [
   },
 ]
 
-function tool(json) {
-  return { content: [{ type: 'text', text: typeof json === 'string' ? json : JSON.stringify(json, null, 2) }] }
+function tool(json, opts) {
+  const result = { content: [{ type: 'text', text: typeof json === 'string' ? json : JSON.stringify(json, null, 2) }] }
+  if (opts && opts.isError) result.isError = true
+  return result
 }
 
 function fuzzy(query, hay) {
@@ -131,16 +133,104 @@ function fuzzy(query, hay) {
   return true
 }
 
-function parseFrontmatter(md) {
+// Relevance score for a search hit. Higher = more relevant. Tiers (best→worst):
+// exact name > name prefix > name word-boundary > name substring > tagline
+// substring > tag/category match > subsequence-only. Name/tagline outweigh
+// tags so a true title hit always beats a metadata coincidence. Returns 0 when
+// nothing matches (caller has already gated on fuzzy(), so this is only the
+// ranking signal, never the inclusion filter).
+function scoreEntry(query, e) {
+  const q = String(query).toLowerCase().trim()
+  if (!q) return 0
+  const name = String(e.name ?? '').toLowerCase()
+  const tagline = String(e.tagline ?? '').toLowerCase()
+  const tags = (e.tags ?? []).map((t) => String(t).toLowerCase())
+  const cats = (e.categories ?? []).map((t) => String(t).toLowerCase())
+
+  let score = 0
+  // Name tiers (mutually escalating; take the strongest that applies).
+  if (name === q) score += 100
+  else if (name.startsWith(q)) score += 70
+  else if (new RegExp(`\\b${escapeRe(q)}`).test(name)) score += 55
+  else if (name.includes(q)) score += 45
+  // Tagline (weighted above tags, below name).
+  if (tagline.includes(q)) score += 30
+  // Tag / category exact-or-substring match.
+  if (tags.some((t) => t === q)) score += 22
+  else if (tags.some((t) => t.includes(q))) score += 15
+  if (cats.some((c) => c === q)) score += 20
+  else if (cats.some((c) => c.includes(q))) score += 13
+  // Subsequence-only fallback so fuzzy-but-no-substring hits still rank > 0
+  // and shorter (tighter) names edge out longer ones at the same tier.
+  if (score === 0) score += 1
+  if (name.length) score += Math.max(0, 6 - name.length / 12)
+  return score
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+const COLOR_RE = /^(#[0-9a-fA-F]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\))$/
+const RADIUS_RE = /^(\d+(?:\.\d+)?)(px)?$/
+
+function stripValue(raw) {
+  // Drop trailing `# comment`, surrounding quotes, and whitespace.
+  let v = raw.replace(/\s+#.*$/, '').trim()
+  const q = v.match(/^(['"])([\s\S]*)\1$/)
+  if (q) return q[2].trim()
+  return v
+}
+
+// Section-scoped frontmatter parser. Only captures pairs that are DIRECT
+// children of the top-level `colors:` and `radius:` maps — component-level
+// leaf keys (backgroundColor/textColor/…) can never leak in. Themed entries
+// nest colors as `colors:\n  <theme>:\n    <token>: <hex>`; for those we
+// flatten the FIRST (default) theme's tokens to bare token names.
+function parseTokens(md) {
   const m = md.match(/^---\n([\s\S]*?)\n---/)
-  if (!m) return {}
-  const out = {}
-  // Tiny parser — only handles flat color: hex pairs (good enough for diff)
-  for (const line of m[1].split('\n')) {
-    const km = line.match(/^\s+([a-zA-Z][\w-]*):\s*['"]?(#[0-9a-fA-F]{3,8}|rgba?\([^)]+\))['"]?/)
-    if (km) out[km[1]] = km[2]
+  if (!m) return { colors: {}, radii: {} }
+  const colors = {}
+  const radii = {}
+  let section = null       // current top-level section name
+  let firstTheme = null    // first/default theme name under a nested `colors:`
+  let curTheme = null      // theme block we're currently inside
+
+  for (const raw of m[1].split('\n')) {
+    if (!raw.trim() || /^\s*#/.test(raw)) continue // blank or full-line comment
+
+    const top = raw.match(/^([a-zA-Z][\w-]*):(.*)$/) // column-0 key → new top-level section
+    if (top) {
+      section = top[1]
+      firstTheme = null
+      curTheme = null
+      continue
+    }
+
+    const indent = raw.match(/^(\s+)([a-zA-Z][\w-]*):\s*(.*)$/)
+    if (!indent) continue
+    const depth = indent[1].length
+    const key = indent[2]
+    const val = stripValue(indent[3])
+
+    if (section === 'colors') {
+      if (depth === 2 && val === '') {
+        // Sub-map with no scalar value → a theme block (e.g. `light:`).
+        if (firstTheme == null) firstTheme = key // lock onto the first/default theme
+        curTheme = key
+        continue
+      }
+      if (firstTheme != null) {
+        // Themed: only capture tokens of the first theme (depth === 4).
+        if (curTheme === firstTheme && depth === 4 && COLOR_RE.test(val)) colors[key] = val
+      } else if (depth === 2 && COLOR_RE.test(val)) {
+        colors[key] = val // flat top-level color token
+      }
+    } else if (section === 'radius') {
+      if (depth === 2 && RADIUS_RE.test(val)) radii[key] = val
+    }
   }
-  return out
+  return { colors, radii }
 }
 
 function diffMaps(a, b) {
@@ -183,20 +273,31 @@ const HANDLERS = {
   async search_designs({ query, limit }) {
     const c = await fetchCatalog()
     const lim = Math.min(limit ?? 20, 50)
+    // Inclusion: subsequence match on the combined haystack (unchanged).
+    // Ranking: score each survivor, then STABLE-sort by score descending
+    // BEFORE slicing so an exact match can never be sliced off by the cap.
     const matches = c.entries
       .filter((e) => {
         const hay = `${e.name} ${e.tagline} ${(e.tags ?? []).join(' ')} ${(e.categories ?? []).join(' ')}`
         return fuzzy(query, hay)
       })
+      .map((e, i) => ({ e, i, score: scoreEntry(query, e) }))
+      .sort((a, b) => b.score - a.score || a.i - b.i) // stable via original index tiebreak
       .slice(0, lim)
+      .map((m) => m.e)
     return tool({ query, count: matches.length, matches: matches.map((e) => ({ slug: e.slug, name: e.name, tagline: e.tagline, tags: e.tags })) })
   },
 
   async diff_designs({ from, to }) {
     const [a, b] = await Promise.all([fetchRaw(from), fetchRaw(to)])
-    const fa = parseFrontmatter(a)
-    const fb = parseFrontmatter(b)
-    return tool({ from, to, colors: diffMaps(fa, fb) })
+    const ta = parseTokens(a)
+    const tb = parseTokens(b)
+    return tool({
+      from,
+      to,
+      colors: diffMaps(ta.colors, tb.colors),
+      radii: diffMaps(ta.radii, tb.radii),
+    })
   },
 
   async export_design({ slug, format }) {
@@ -232,7 +333,7 @@ export async function startServer() {
     try {
       return await handler(args ?? {})
     } catch (err) {
-      return tool({ error: (err && err.message) || String(err) })
+      return tool({ error: (err && err.message) || String(err) }, { isError: true })
     }
   })