Metadata-Version: 2.4
Name: designesy-mcp
Version: 1.8.1
Summary: Read-only stdio MCP server exposing designesy.org's design-intelligence infrastructure — 11 tools for design-system contracts, verification scoring, token validation, accessibility, and motion.
Project-URL: Homepage, https://www.designesy.org
Project-URL: Documentation, https://www.designesy.org/contracts/skill
Project-URL: Repository, https://github.com/LE-VAI/designesy-org
Project-URL: Bug Tracker, https://github.com/LE-VAI/designesy-org/issues
Project-URL: MCP Registry, https://registry.modelcontextprotocol.io/io.github.LE-VAI/designesy-org
Project-URL: Agent Install, https://pypi.org/project/designesy-mcp/#quick-start-one-command
Project-URL: Changelog, https://github.com/LE-VAI/designesy-org/releases
Author-email: Le Vain Bey <hello@designesy.org>
License-Expression: MIT
License-File: LICENSE
Keywords: accessibility,agent-tools,design-system,design-tokens,designesy,dtcg,lottie,mcp,model-context-protocol,motion,verification,wcag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# designesy-mcp

<!-- mcp-name: io.github.LE-VAI/designesy-org -->

[![PyPI version](https://img.shields.io/pypi/v/designesy-mcp.svg)](https://pypi.org/project/designesy-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-2025.06.18-purple.svg)](https://modelcontextprotocol.io)

A **read-only stdio MCP server** exposing [designesy.org](https://www.designesy.org)'s design-intelligence infrastructure as native agent tools.

Zero external dependencies. Pure Python stdlib. Implements the [Model Context Protocol](https://modelcontextprotocol.io) JSON-RPC 2.0 over stdio.

---

## Quick start (one command)

```bash
uvx designesy-mcp
```

That's it. [`uvx`](https://docs.astral.sh/uv/) 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)

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

### pip install (traditional)

```bash
pip install designesy-mcp
```

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

### python -m (module form)

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

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

## Tools (11)

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

### Read-only discovery
| Tool | What it does |
|---|---|
| `designesy_catalog` | Get the 12-package catalog (versions, URLs, statuses) from `/open.json` |
| `designesy_contract` | Get the full design-system contract v0.3.0 (tokens, motion, acoustic, takt, cadence, typography, components, verification, open tensions) — or a filtered section |
| `designesy_design_review` | Get the Design Review kit (8 dimensions, agent prompt, output format, verification checklist) |
| `designesy_skill_md` | Get the agent-skill-format export (SKILL.md) with behavioral rules, tokens, anti-patterns |
| `designesy_agent_json` | Get the agent discovery document (`.well-known/agent.json`) — identity, authority, ingest protocol |
| `designesy_llms_txt` | Get the short agent brief (`/llms.txt`) |
| `designesy_llms_full_txt` | Get the full agent brief (`/llms-full.txt`) with ingest protocol, all packages, paste-ready prompt |

### Executable verification
| Tool | What it does |
|---|---|
| `designesy_score` | Run the 36-check contract verification against a live URL. Fetches HTML + CSS, parses `:root` custom properties, returns PASS/FAIL/WARN/SKIP per check with an overall score, letter grade, and per-category breakdown. Supports 4 emission formats: `designesy` (default), `canonical` (review-findings.json schema), `review` (jakubkrehel markdown), `google` (@google/design.md JSON). |
| `designesy_tokens_score` | Validate a design token file against the W3C Design Tokens Community Group (DTCG) 2025.10 format. 10 checks (t01–t10). |
| `designesy_a11y_score` | Get the WCAG 2.2 AA accessibility verification framework (11 checks, a01–a11) + a Playwright/axe-core script template for local execution. |
| `designesy_motion_score` | Validate a Lottie animation file against Lottie spec v1.0.1 + the Designesy 10 Non-Negotiable Motion Standards. 10 checks (m01–m10). |

## Resources (7)

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

| URI | Content |
|---|---|
| `designesy://open` | Package catalog (JSON) |
| `designesy://contract` | Full design-system contract (JSON) |
| `designesy://kit/design-review` | Design Review kit (JSON) |
| `designesy://skill` | SKILL.md agent-skill export (Markdown) |
| `designesy://agent` | Agent discovery document (JSON) |
| `designesy://llms` | Short agent brief (text) |
| `designesy://llms-full` | Full agent brief (text) |

## The 36-check verification engine

`designesy_score` runs 36 deterministic checks across 13 weighted categories:

| Category | Weight | What it measures |
|---|---|---|
| cadence | 18 | Typography rhythm — line-height, font-synthesis, text-underline-position, skip-ink |
| accessibility | 15 | WCAG 2.2 primitives — reduced-motion, forced-colors, AI disclosure, focus-visible |
| semantic | 12 | Token architecture — `:root` custom properties, no raw hex, semantic naming |
| motion | 10 | Motion hygiene — duration tokens, easing tokens, reduced-motion blocks |
| tokens | 9 | DTCG 2025.10 conformance — `$type`, `$value`, `$description`, colorSpace |
| takt | 8 | Timing discipline — transition bands, animation hierarchy |
| poise | 7 | Composure — viewport overflow, scroll behavior, print styles |
| identity | 6 | Brand coherence — title, meta description, favicon, og tags |
| interaction | 6 | Interaction primitives — hover states, press feedback, disabled states |
| performance | 6 | Core Web Vitals readiness — preload, font-display, render-blocking |
| responsive | 3 | Responsive primitives — viewport meta, container queries |
| security | 5 | Security headers — CSP, X-Content-Type-Options, referrer policy |
| spec | 4 | Spec conformance — `lang` attr, `charset`, doctype |

No LLM. No roast. The same engine scores [designesy.org](https://www.designesy.org) itself — in public, at 99.1% A.

## 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.** This server never writes anywhere. It does not execute code, mutate files, or access credentials.

## 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](https://www.designesy.org)
- [Agent Install](https://pypi.org/project/designesy-mcp/#quick-start-one-command) — one-command `uvx designesy-mcp`
- [Repository](https://github.com/LE-VAI/designesy-org)
- [MCP Registry entry](https://registry.modelcontextprotocol.io/io.github.LE-VAI/designesy-org)
- [Changelog](https://github.com/LE-VAI/designesy-org/releases)
- [Design-system contract](https://www.designesy.org/contracts/design-system.json)
- [Leaderboard](https://www.designesy.org/leaderboard)
- [Methodology](https://www.designesy.org/methodology)