designesy-mcp

One-click install:

Design quality gate for AI-generated UI: score any URL on 45 deterministic checks, A–F grade. This package is the stdio MCP server that exposes designesy.org's tools to agents. Every tool is read-only except designesy_monitor_score, which can send a drift-alert email (see Safety).

Zero external dependencies. Pure Python stdlib. Implements the Model Context Protocol JSON-RPC 2.0 over stdio.

Quick start (one command)

uvx designesy-mcp

That's it. uvx fetches the package from PyPI, creates an ephemeral environment, and launches the stdio MCP server. No virtualenv, no pip install, no git clone. The server is ready to speak JSON-RPC 2.0 on stdin/stdout immediately.

Don't have uv? Install it once: curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows). Or use pipx run designesy-mcp as an equivalent one-liner.

MCP client config

uvx (recommended — no install step)

{
  "mcpServers": {
    "designesy": {
      "command": "uvx",
      "args": ["designesy-mcp"]
    }
  }
}

pip install (traditional)

pip install designesy-mcp

{
  "mcpServers": {
    "designesy": {
      "command": "designesy-mcp"
    }
  }
}

python -m (module form)

{
  "mcpServers": {
    "designesy": {
      "command": "python",
      "args": ["-m", "designesy_mcp_server"]
    }
  }
}

No arguments needed. The server speaks JSON-RPC 2.0 over stdin/stdout.

Tools (17)

The server exposes 17 tools, all fetched live from https://www.designesy.org/:

Read-only discovery

Executable verification

Executable engines (new in v1.10.0)

Resources (7)

The server also exposes 7 MCP resources (read-only URIs):

The 45-check verification engine

designesy_score runs 45 deterministic checks across 14 weighted categories:

No LLM. No roast. The same engine scores designesy.org itself, in public: its current score is on the leaderboard.

Standards positioning

DTCG 2025.10 — the spec went stable

The W3C Design Tokens Community Group published the spec's first stable version on Oct 28, 2025 — the Final Community Group Report, classified as a Candidate Recommendation and considered stable. 24+ organizations back it (Adobe, Google, Meta, Figma, Amazon, Microsoft, Shopify, Sketch, Framer). 84% of teams now use design tokens (zeroheight Design Systems Report 2025, up from 56% in 2024).

designesy_tokens_score validates against this stable spec. Every team adopting DTCG 2025.10 needs a validator — designesy is it.

Motion tokens — the spec's blind spot

The DTCG 2025.10 spec leaves motion tokens as a second-class citizen — there is no standard for motion token structure, reduced-motion markers, or animation accessibility. The 2026 State of Design Systems field report confirms this is the remaining friction point.

designesy_motion_score fills this gap. It validates Lottie files against the Lottie spec v1.0.1 AND the Designesy §16 Ten Non-Negotiable Motion Standards, so one call checks both structural well-formedness and accessibility (reduced-motion markers, no deprecated versions). It is the verification layer for the spec's known blind spot.

Contract vs. opinion

Lighthouse weights audits into category scores. axe-core reports rule violations. securityheaders.com grades one dimension. Designesy scores a page 0-100 against a published contract: 45 checks across 14 weighted categories, each rule and weight public.

Caching

All responses are cached with a 5-minute TTL. The server only fetches public, machine-readable exports from designesy.org via HTTPS. It does not read local files, credentials, or source roots.

Safety

Read-only, with one exception. designesy_monitor_score can send email: when you pass an email address and a drift alert fires, designesy.org sends an HTML drift-alert email to that address through Resend, if the server has a Resend key configured. A repeated call can send another email. The other 16 tools only read. The server writes no local files and reads no credentials.

Every tool declares a title and the MCP annotation hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), matching the hosted endpoint at https://www.designesy.org/api/mcp. designesy_monitor_score is the one tool marked readOnlyHint: false.

Provenance

All data is fetched live from:

• https://www.designesy.org/open.json
• https://www.designesy.org/contracts/design-system.json
• https://www.designesy.org/kits/design-review.json
• https://www.designesy.org/contracts/skill
• https://www.designesy.org/.well-known/agent.json
• https://www.designesy.org/llms.txt
• https://www.designesy.org/llms-full.txt

License

MIT

Links

• Homepage
• Agent Install — one-command uvx designesy-mcp
• Repository
• MCP Registry entry
• Changelog
• Design-system contract
• Leaderboard — 30-site public cohort, A–F histogram, weekly re-score
• Score badge — live SVG badge with a site's cached grade, score and scoring date
• Live score API — JSON, no key, no login
• Methodology