design-md-mcp

MCP server that exposes DESIGN.md design system knowledge from awesome-design-md and awesome-design-md-jp collections.

Features

• Indexes 350+ DESIGN.md files at startup
• Tools for listing, reading, section extraction, and full-text search
• Resources at design-md://{catalog}/{id} URIs
• Supports global (English) and jp (Japanese) catalogs
• Zero external dependencies at runtime beyond Node.js

Installation

From source (recommended)

git clone <your-repo-url> design-md-analyzer
cd design-md-analyzer/mcp-server
npm install
npm run build

npm (after publishing)

npm install -g design-md-mcp

The npm package does not bundle design data. Set DESIGN_MD_ROOT to a clone of the full repository.

Configuration

| Variable | Description | Default | |----------|-------------|---------| | DESIGN_MD_ROOT | Root directory containing awesome-design-md-main/ and awesome-design-md-jp-main/ | Auto-detected from cwd or package location |

MCP host setup

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "design-md": {
      "command": "node",
      "args": ["/absolute/path/to/design-md-analyzer/mcp-server/dist/index.js"],
      "env": {
        "DESIGN_MD_ROOT": "/absolute/path/to/design-md-analyzer"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "design-md": {
      "command": "node",
      "args": ["/absolute/path/to/design-md-analyzer/mcp-server/dist/index.js"],
      "env": {
        "DESIGN_MD_ROOT": "/absolute/path/to/design-md-analyzer"
      }
    }
  }
}

VS Code (Copilot)

.vscode/mcp.json in your project:

{
  "servers": {
    "design-md": {
      "type": "stdio",
      "command": "node",
      "args": ["../design-md-analyzer/mcp-server/dist/index.js"],
      "env": {
        "DESIGN_MD_ROOT": "../design-md-analyzer"
      }
    }
  }
}

Tools

list_design_systems

Browse available design systems.

| Parameter | Type | Description | |-----------|------|-------------| | catalog | "global" | "jp" | Filter by catalog | | query | string | Keyword search (id, title, description) | | language | "en" | "ja" | Filter by language | | limit | number | Max results (default 50, max 200) | | offset | number | Pagination offset |

Example prompt: "List Japanese design systems related to fintech"

get_design_system

Retrieve a full DESIGN.md document.

| Parameter | Type | Description | |-----------|------|-------------| | catalog | "global" | "jp" | Required | | id | string | Site id (directory name), e.g. vercel, smarthr | | includeContent | boolean | Include full markdown (default true) |

get_design_section

Retrieve a specific section to save context tokens.

| Parameter | Type | Description | |-----------|------|-------------| | catalog | "global" | "jp" | Required | | id | string | Site id | | section | string | Section keyword, e.g. color, typography, layout |

search_design_content

Full-text search across all DESIGN.md files.

| Parameter | Type | Description | |-----------|------|-------------| | query | string | Search terms (min 2 chars) | | catalog | "global" | "jp" | Optional filter | | limit | number | Max results (default 20) |

Resources

URI scheme: design-md://{catalog}/{id}

| URI | Content | |-----|---------| | design-md://global/vercel | Vercel-inspired design system | | design-md://global/stripe | Stripe-inspired design system | | design-md://jp/smarthr | SmartHR design system (Japanese) | | design-md://jp/mercari | Mercari design system (Japanese) |

Troubleshooting

Works in design-md-analyzer but errors in other repositories

Cursor may sandbox MCP servers to the current workspace. When you open another project, the server cannot read DESIGN.md files outside that workspace and fails to start.

Fix: disable sandbox for this read-only server in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "design-md": {
      "command": "node",
      "args": ["/absolute/path/to/design-md-analyzer/mcp-server/dist/index.js"],
      "env": {
        "DESIGN_MD_ROOT": "/absolute/path/to/design-md-analyzer"
      },
      "sandboxEnabled": false
    }
  }
}

See examples/cursor-mcp.json for a full template.

After editing, restart the MCP server in Cursor Settings → MCP.

Development

npm run dev      # Run with tsx (stdio)
npm run build    # Compile to dist/
npm run typecheck

Architecture

src/
├── index.ts      # MCP server entry, tool/resource registration
├── catalog.ts    # Filesystem scan, index building
├── sections.ts   # Section parsing and extraction
├── search.ts     # List and full-text search
└── types.ts      # Shared types

On startup, the server scans:

• {DESIGN_MD_ROOT}/awesome-design-md-main/design-md/*/DESIGN.md
• {DESIGN_MD_ROOT}/awesome-design-md-jp-main/design-md/*/DESIGN.md

License

MIT

日本語

概要

design-md-mcp は、awesome-design-md コレクションの DESIGN.md を MCP 経由で AI エージェントに提供するサーバーです。

推奨ワークフロー

1. list_design_systems でブランドを検索（catalog: "jp" で日本語サイトに絞り込み）
2. get_design_section で必要なセクション（色・タイポグラフィなど）だけ取得
3. 全文が必要な場合のみ get_design_system を使用

カタログ

| カタログ | 内容 | |---------|------| | global | 英語圏の開発者向けサービス（Vercel, Stripe など） | | jp | 日本の Web サービス（和文タイポグラフィ仕様付き） |

他リポジトリでエラーになる場合

design-md-analyzer では緑、他プロジェクトでは赤になる場合、Cursor の MCP サンドボックスがワークスペース外のファイル読み取りをブロックしています。~/.cursor/mcp.json に "sandboxEnabled": false を追加し、MCP サーバーを再起動してください（上記 Troubleshooting 参照）。