@webdesignhot/design-md-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webdesignhot
+
+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,63 @@
+# @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.
+
+## 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.
+
+## Tools
+
+- **`list_designs`** — list every design (with `featured_only` / `category` / `tag` filters)
+- **`get_design`** — full DESIGN.md/v1.5 source for a slug
+- **`search_designs`** — fuzzy search by name, tagline, tags, categories
+- **`diff_designs`** — token-level diff between any two designs
+- **`export_design`** — render tokens to tailwind / css / dtcg / figma
+- **`install_design`** — get the npx command + raw markdown to install one
+
+## Install
+
+### Claude Desktop / Claude Code
+
+Add to your `~/Library/Application Support/Claude/claude_desktop_config.json` (or the equivalent on Windows / Linux):
+
+```json
+{
+  "mcpServers": {
+    "design-md": {
+      "command": "npx",
+      "args": ["-y", "@webdesignhot/design-md-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+In Settings → Features → MCP → "Add new MCP server":
+
+- **Name**: `design-md`
+- **Type**: `command`
+- **Command**: `npx -y @webdesignhot/design-md-mcp`
+
+### Cline / Roo / 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`.
+
+## Use it
+
+Once connected, ask your agent things like:
+
+> *"List the top 10 dark editorial design systems."*
+>
+> *"Install Stripe's DESIGN.md into this project."*
+>
+> *"Diff Linear and Vercel — what changes if I switch?"*
+>
+> *"Export Anthropic's tokens as Tailwind config."*
+
+The agent calls the right tool, the response flows back, and you stay in the IDE.
+
+## License
+
+MIT — © 2026 webdesignhot

package/bin/design-md-mcp.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startServer } from '../src/server.mjs'
+
+startServer().catch((err) => {
+  process.stderr.write('design-md-mcp fatal: ' + (err?.message ?? err) + '\n')
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@webdesignhot/design-md-mcp",
+  "version": "0.1.0",
+  "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"],
+  "author": "webdesignhot",
+  "license": "MIT",
+  "homepage": "https://www.webdesignhot.com/design.md/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WebDesignHot/design-md"
+  },
+  "bin": {
+    "design-md-mcp": "bin/design-md-mcp.mjs"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/src/server.mjs

@@ -0,0 +1,242 @@
+/**
+ * design-md MCP server — exposes the webdesignhot.com DESIGN.md catalog
+ * as MCP tools so any MCP-aware agent (Claude Desktop, Claude Code,
+ * Cursor, Cline, Roo, etc.) can list/search/get/diff/export design
+ * systems without leaving the IDE.
+ *
+ * Stdio transport. Talks to the same prerendered endpoints the CLI uses.
+ */
+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 BASE = process.env.DESIGN_MD_BASE || 'https://www.webdesignhot.com'
+
+let _catalog = null
+async function fetchCatalog() {
+  if (_catalog) return _catalog
+  const res = await fetch(`${BASE}/api/design-md/index.json`)
+  if (!res.ok) throw new Error(`Catalog fetch failed: ${res.status}`)
+  _catalog = await res.json()
+  return _catalog
+}
+async function fetchRaw(slug) {
+  const res = await fetch(`${BASE}/api/design-md/${slug}.md`)
+  if (res.status === 404) throw new Error(`No design "${slug}". Use list_designs.`)
+  if (!res.ok) throw new Error(`Raw fetch failed: ${res.status}`)
+  return res.text()
+}
+async function fetchExport(slug, format) {
+  const res = await fetch(`${BASE}/api/design-md/${slug}/export/${format}`)
+  if (!res.ok) throw new Error(`Export ${format} failed: ${res.status}`)
+  return res.text()
+}
+
+const TOOLS = [
+  {
+    name: 'list_designs',
+    description:
+      'List every design in the webdesignhot.com catalog. Returns slug, name, tagline, categories, tags, and a 3-color preview swatch per entry. Use this to discover what is available before calling get_design.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        featured_only: { type: 'boolean', description: 'Filter to featured (curated) designs only.' },
+        category: { type: 'string', description: 'Filter by single category (e.g. "dev-tools", "fintech", "ai", "media").' },
+        tag: { type: 'string', description: 'Filter by single tag (e.g. "dark", "editorial", "minimal").' },
+      },
+    },
+  },
+  {
+    name: 'get_design',
+    description:
+      'Fetch the full DESIGN.md/v1.5 source for a specific design (YAML frontmatter + markdown body). The response is the exact file an agent should read as its style source of truth. Use the agent-prompt header from the file to anchor every component decision.',
+    inputSchema: {
+      type: 'object',
+      required: ['slug'],
+      properties: {
+        slug: { type: 'string', description: 'The design slug, e.g. "linear", "stripe", "vercel". See list_designs.' },
+      },
+    },
+  },
+  {
+    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".',
+    inputSchema: {
+      type: 'object',
+      required: ['query'],
+      properties: {
+        query: { type: 'string', description: 'Free-text query.' },
+        limit: { type: 'number', description: 'Max results, default 20.' },
+      },
+    },
+  },
+  {
+    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.',
+    inputSchema: {
+      type: 'object',
+      required: ['from', 'to'],
+      properties: {
+        from: { type: 'string', description: 'From slug.' },
+        to: { type: 'string', description: 'To slug.' },
+      },
+    },
+  },
+  {
+    name: 'export_design',
+    description:
+      'Convert a design\'s tokens to a target format. Returns ready-to-paste output for tailwind, css, dtcg, or figma.',
+    inputSchema: {
+      type: 'object',
+      required: ['slug', 'format'],
+      properties: {
+        slug: { type: 'string' },
+        format: { type: 'string', enum: ['tailwind', 'css', 'dtcg', 'figma'] },
+      },
+    },
+  },
+  {
+    name: 'install_design',
+    description:
+      'Get the npx command and the raw .md content to install a design as DESIGN.md in the user\'s project. Returns both the recommended CLI invocation and the full markdown for the agent to write directly if it has filesystem access.',
+    inputSchema: {
+      type: 'object',
+      required: ['slug'],
+      properties: {
+        slug: { type: 'string' },
+        out: { type: 'string', description: 'Output path, default DESIGN.md.' },
+      },
+    },
+  },
+]
+
+function tool(json) {
+  return { content: [{ type: 'text', text: typeof json === 'string' ? json : JSON.stringify(json, null, 2) }] }
+}
+
+function fuzzy(query, hay) {
+  const n = query.toLowerCase()
+  const h = String(hay).toLowerCase()
+  let i = 0
+  for (const c of n) {
+    const f = h.indexOf(c, i)
+    if (f === -1) return false
+    i = f + 1
+  }
+  return true
+}
+
+function parseFrontmatter(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]
+  }
+  return out
+}
+
+function diffMaps(a, b) {
+  const result = { added: {}, removed: {}, modified: {} }
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+  for (const k of keys) {
+    if (a[k] == null && b[k] != null) result.added[k] = b[k]
+    else if (a[k] != null && b[k] == null) result.removed[k] = a[k]
+    else if (a[k] !== b[k]) result.modified[k] = { from: a[k], to: b[k] }
+  }
+  return result
+}
+
+const HANDLERS = {
+  async list_designs({ featured_only, category, tag }) {
+    const c = await fetchCatalog()
+    let entries = c.entries
+    if (featured_only) entries = entries.filter((e) => e.featured)
+    if (category) entries = entries.filter((e) => (e.categories ?? []).includes(category))
+    if (tag) entries = entries.filter((e) => (e.tags ?? []).includes(tag))
+    return tool({
+      count: entries.length,
+      entries: entries.map((e) => ({
+        slug: e.slug,
+        name: e.name,
+        tagline: e.tagline,
+        categories: e.categories,
+        tags: e.tags,
+        featured: e.featured,
+        preview_swatch: e.preview_swatch,
+      })),
+    })
+  },
+
+  async get_design({ slug }) {
+    const md = await fetchRaw(slug)
+    return tool(md)
+  },
+
+  async search_designs({ query, limit }) {
+    const c = await fetchCatalog()
+    const lim = Math.min(limit ?? 20, 50)
+    const matches = c.entries
+      .filter((e) => {
+        const hay = `${e.name} ${e.tagline} ${(e.tags ?? []).join(' ')} ${(e.categories ?? []).join(' ')}`
+        return fuzzy(query, hay)
+      })
+      .slice(0, lim)
+    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) })
+  },
+
+  async export_design({ slug, format }) {
+    const text = await fetchExport(slug, format)
+    return tool(text)
+  },
+
+  async install_design({ slug, out }) {
+    const md = await fetchRaw(slug)
+    return tool({
+      command: `npx design-md add ${slug}${out ? ` --out ${out}` : ''}`,
+      out: out || 'DESIGN.md',
+      bytes: md.length,
+      markdown: md,
+      hint:
+        'If you have filesystem access, write `markdown` to `out`. Otherwise instruct the user to run `command`. Then read DESIGN.md as the visual source of truth — every color, type scale, radius, motion, accessibility token must come from it.',
+    })
+  },
+}
+
+export async function startServer() {
+  const server = new Server(
+    { name: 'design-md', version: '0.1.0' },
+    { capabilities: { tools: {} } },
+  )
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params
+    const handler = HANDLERS[name]
+    if (!handler) throw new Error(`Unknown tool: ${name}`)
+    try {
+      return await handler(args ?? {})
+    } catch (err) {
+      return tool({ error: (err && err.message) || String(err) })
+    }
+  })
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  // Stays alive on stdio
+}