designesy-mcp 1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- designesy_mcp-1/.gitignore +25 -0
- designesy_mcp-1/LICENSE +21 -0
- designesy_mcp-1/PKG-INFO +237 -0
- designesy_mcp-1/README.md +200 -0
- designesy_mcp-1/cdp-cwv-expr.js +146 -0
- designesy_mcp-1/cdp-viewport-check.js +172 -0
- designesy_mcp-1/cwv-expr.js +103 -0
- designesy_mcp-1/designesy_mcp_server.py +2962 -0
- designesy_mcp-1/pyproject.toml +84 -0
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
node_modules/
|
|
2
|
+
.next/
|
|
3
|
+
apps/site/node_modules/
|
|
4
|
+
apps/site/.next/
|
|
5
|
+
.env
|
|
6
|
+
.env.*
|
|
7
|
+
!.env.example
|
|
8
|
+
apps/*/.env
|
|
9
|
+
apps/*/.env.*
|
|
10
|
+
!apps/*/.env.example
|
|
11
|
+
temp_install/
|
|
12
|
+
install_tmp/
|
|
13
|
+
apps/site/cuelume.d.ts
|
|
14
|
+
apps/site/tsconfig.tsbuildinfo
|
|
15
|
+
|
|
16
|
+
.vercel
|
|
17
|
+
|
|
18
|
+
# Python (scoped — action/dist/ is tracked, so no blanket dist/)
|
|
19
|
+
__pycache__/
|
|
20
|
+
*.pyc
|
|
21
|
+
*.egg-info/
|
|
22
|
+
packages/*/dist/
|
|
23
|
+
packages/*/build/
|
|
24
|
+
.venv/
|
|
25
|
+
.env*
|
designesy_mcp-1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Le Vain Bey
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
designesy_mcp-1/PKG-INFO
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: designesy-mcp
|
|
3
|
+
Version: 1
|
|
4
|
+
Summary: Read-only stdio MCP server exposing designesy.org's design-intelligence infrastructure — 17 tools for design-system contracts, verification scoring, drift detection, AI readiness, token validation, accessibility, motion, and composite reports.
|
|
5
|
+
Project-URL: Homepage, https://www.designesy.org
|
|
6
|
+
Project-URL: Documentation, https://www.designesy.org/contracts/skill
|
|
7
|
+
Project-URL: Repository, https://github.com/LE-VAI/designesy-org
|
|
8
|
+
Project-URL: Bug Tracker, https://github.com/LE-VAI/designesy-org/issues
|
|
9
|
+
Project-URL: MCP Registry, https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.LE-VAI%2Fdesignesy-org
|
|
10
|
+
Project-URL: Agent Install, https://pypi.org/project/designesy-mcp/#quick-start-one-command
|
|
11
|
+
Project-URL: Changelog, https://github.com/LE-VAI/designesy-org/releases
|
|
12
|
+
Author-email: Le Vain Bey <hello@designesy.org>
|
|
13
|
+
License-Expression: MIT
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Keywords: accessibility,agent-tools,design-system,design-tokens,designesy,dtcg,lottie,mcp,model-context-protocol,motion,verification,wcag
|
|
16
|
+
Classifier: Development Status :: 4 - Beta
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: Intended Audience :: Information Technology
|
|
19
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
20
|
+
Classifier: Operating System :: OS Independent
|
|
21
|
+
Classifier: Programming Language :: Python :: 3
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
27
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
28
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
29
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
30
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
31
|
+
Classifier: Topic :: Text Processing :: Markup :: HTML
|
|
32
|
+
Classifier: Typing :: Typed
|
|
33
|
+
Requires-Python: >=3.10
|
|
34
|
+
Provides-Extra: dev
|
|
35
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
36
|
+
Description-Content-Type: text/markdown
|
|
37
|
+
|
|
38
|
+
# designesy-mcp
|
|
39
|
+
|
|
40
|
+
<!-- mcp-name: io.github.LE-VAI/designesy-org -->
|
|
41
|
+
|
|
42
|
+
[](https://pypi.org/project/designesy-mcp/)
|
|
43
|
+
[](https://www.python.org/downloads/)
|
|
44
|
+
[](LICENSE)
|
|
45
|
+
[](https://modelcontextprotocol.io)
|
|
46
|
+
|
|
47
|
+
**One-click install:**
|
|
48
|
+
|
|
49
|
+
[](https://vscode.dev/redirect/mcp/install?name=designesy&config=%7B%22designesy%22%3A%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22designesy-mcp%22%5D%7D%7D)
|
|
50
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=designesy&config=%7B%22designesy%22%3A%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22designesy-mcp%22%5D%7D%7D&quality=insiders)
|
|
51
|
+
[](cursor://anysphere.cursor-deeplink/mcp/install?name=designesy&config=%7B%22designesy%22%3A%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22designesy-mcp%22%5D%7D%7D)
|
|
52
|
+
[](https://vscode.dev/redirect/mcp/install?name=designesy&config=%7B%22designesy%22%3A%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.designesy.org%2Fapi%2Fmcp%22%7D%7D)
|
|
53
|
+
|
|
54
|
+
A **read-only stdio MCP server** exposing [designesy.org](https://www.designesy.org)'s design-intelligence infrastructure as native agent tools.
|
|
55
|
+
|
|
56
|
+
Zero external dependencies. Pure Python stdlib. Implements the [Model Context Protocol](https://modelcontextprotocol.io) JSON-RPC 2.0 over stdio.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Quick start (one command)
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
uvx designesy-mcp
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
> 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.
|
|
69
|
+
|
|
70
|
+
## MCP client config
|
|
71
|
+
|
|
72
|
+
### uvx (recommended — no install step)
|
|
73
|
+
|
|
74
|
+
```json
|
|
75
|
+
{
|
|
76
|
+
"mcpServers": {
|
|
77
|
+
"designesy": {
|
|
78
|
+
"command": "uvx",
|
|
79
|
+
"args": ["designesy-mcp"]
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### pip install (traditional)
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
pip install designesy-mcp
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"mcpServers": {
|
|
94
|
+
"designesy": {
|
|
95
|
+
"command": "designesy-mcp"
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### python -m (module form)
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"mcpServers": {
|
|
106
|
+
"designesy": {
|
|
107
|
+
"command": "python",
|
|
108
|
+
"args": ["-m", "designesy_mcp_server"]
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
No arguments needed. The server speaks JSON-RPC 2.0 over stdin/stdout.
|
|
115
|
+
|
|
116
|
+
## Tools (17)
|
|
117
|
+
|
|
118
|
+
The server exposes 17 tools, all fetched live from `https://www.designesy.org/`:
|
|
119
|
+
|
|
120
|
+
### Read-only discovery
|
|
121
|
+
| Tool | What it does |
|
|
122
|
+
|---|---|
|
|
123
|
+
| `designesy_catalog` | Get the 12-package catalog (versions, URLs, statuses) from `/open.json` |
|
|
124
|
+
| `designesy_contract` | Get the full design-system contract v0.4.0 (tokens, motion, acoustic, takt, cadence, typography, components, verification, open tensions) — or a filtered section |
|
|
125
|
+
| `designesy_design_review` | Get the Design Review kit (8 dimensions, agent prompt, output format, verification checklist) |
|
|
126
|
+
| `designesy_skill_md` | Get the agent-skill-format export (SKILL.md) with behavioral rules, tokens, anti-patterns |
|
|
127
|
+
| `designesy_agent_json` | Get the agent discovery document (`.well-known/agent.json`) — identity, authority, ingest protocol |
|
|
128
|
+
| `designesy_llms_txt` | Get the short agent brief (`/llms.txt`) |
|
|
129
|
+
| `designesy_llms_full_txt` | Get the full agent brief (`/llms-full.txt`) with ingest protocol, all packages, paste-ready prompt |
|
|
130
|
+
|
|
131
|
+
### Executable verification
|
|
132
|
+
| Tool | What it does |
|
|
133
|
+
|---|---|
|
|
134
|
+
| `designesy_score` | Run the 40-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). |
|
|
135
|
+
| `designesy_tokens_score` | Validate a design token file against the W3C Design Tokens Community Group (DTCG) 2025.10 format. 10 checks (t01–t10). |
|
|
136
|
+
| `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. |
|
|
137
|
+
| `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). |
|
|
138
|
+
|
|
139
|
+
### Executable engines (new in v1.10.0)
|
|
140
|
+
| Tool | What it does |
|
|
141
|
+
|---|---|
|
|
142
|
+
| `designesy_drift_score` | 12-check AI-drift radar — detects token fabrication, within-session drift, between-session amnesia, and silent breaking changes. |
|
|
143
|
+
| `designesy_readiness_score` | 10-check AI readiness probe — tests for DTCG tokens, llms.txt, agent.json, MCP endpoint, DESIGN.md, sitemap, robots, OG meta. |
|
|
144
|
+
| `designesy_guardrails` | Generate a frozen build-contract bundle: DTCG tokens, Stylelint config, AGENTS.md rules, component contract, anti-patterns, DESIGN.md. |
|
|
145
|
+
| `designesy_monitor_score` | Continuous drift governance — 10 monitor checks with history deltas, trend slope, and email alerts via Resend. |
|
|
146
|
+
| `designesy_compare` | Diff two design systems from live URLs — 8-dimension structured diff (added, removed, renamed, value-changed, scale, contrast, structure, score). |
|
|
147
|
+
| `designesy_report` | Composite synthesis — fires score + drift + readiness in parallel, computes weighted composite grade. The most shareable surface. |
|
|
148
|
+
|
|
149
|
+
## Resources (7)
|
|
150
|
+
|
|
151
|
+
The server also exposes 7 MCP resources (read-only URIs):
|
|
152
|
+
|
|
153
|
+
| URI | Content |
|
|
154
|
+
|---|---|
|
|
155
|
+
| `designesy://open` | Package catalog (JSON) |
|
|
156
|
+
| `designesy://contract` | Full design-system contract (JSON) |
|
|
157
|
+
| `designesy://kit/design-review` | Design Review kit (JSON) |
|
|
158
|
+
| `designesy://skill` | SKILL.md agent-skill export (Markdown) |
|
|
159
|
+
| `designesy://agent` | Agent discovery document (JSON) |
|
|
160
|
+
| `designesy://llms` | Short agent brief (text) |
|
|
161
|
+
| `designesy://llms-full` | Full agent brief (text) |
|
|
162
|
+
|
|
163
|
+
## The 40-check verification engine
|
|
164
|
+
|
|
165
|
+
`designesy_score` runs 40 deterministic checks across 13 weighted categories:
|
|
166
|
+
|
|
167
|
+
| Category | Weight | What it measures |
|
|
168
|
+
|---|---|---|
|
|
169
|
+
| cadence | 18 | Typography rhythm — line-height, font-synthesis, text-underline-position, skip-ink |
|
|
170
|
+
| accessibility | 15 | WCAG 2.2 primitives — reduced-motion, forced-colors, AI disclosure, focus-visible |
|
|
171
|
+
| semantic | 12 | Token architecture — `:root` custom properties, no raw hex, semantic naming |
|
|
172
|
+
| motion | 10 | Motion hygiene — duration tokens, easing tokens, reduced-motion blocks |
|
|
173
|
+
| tokens | 9 | DTCG 2025.10 conformance — `$type`, `$value`, `$description`, colorSpace |
|
|
174
|
+
| takt | 8 | Timing discipline — transition bands, animation hierarchy |
|
|
175
|
+
| poise | 7 | Composure — viewport overflow, scroll behavior, print styles |
|
|
176
|
+
| identity | 6 | Brand coherence — title, meta description, favicon, og tags |
|
|
177
|
+
| interaction | 6 | Interaction primitives — hover states, press feedback, disabled states |
|
|
178
|
+
| performance | 6 | Core Web Vitals readiness — preload, font-display, render-blocking |
|
|
179
|
+
| responsive | 3 | Responsive primitives — viewport meta, container queries |
|
|
180
|
+
| security | 5 | Security headers — CSP, X-Content-Type-Options, referrer policy |
|
|
181
|
+
| spec | 4 | Spec conformance — `lang` attr, `charset`, doctype |
|
|
182
|
+
|
|
183
|
+
No LLM. No roast. The same engine scores [designesy.org](https://www.designesy.org) itself — in public, at 95.3% A.
|
|
184
|
+
|
|
185
|
+
## Standards positioning
|
|
186
|
+
|
|
187
|
+
### DTCG 2025.10 — the spec went stable
|
|
188
|
+
|
|
189
|
+
The W3C Design Tokens Community Group published the spec's **first stable version** on Oct 28, 2025 — the [Final Community Group Report](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/), 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 (2026, up from 56% YoY).
|
|
190
|
+
|
|
191
|
+
`designesy_tokens_score` validates against this stable spec. Every team adopting DTCG 2025.10 needs a validator — designesy is it.
|
|
192
|
+
|
|
193
|
+
### Motion tokens — the spec's blind spot
|
|
194
|
+
|
|
195
|
+
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](https://www.thestackstories.com/blog/state-of-design-systems-2026-field-report) confirms this is the remaining friction point.
|
|
196
|
+
|
|
197
|
+
`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 — the only validator that 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.
|
|
198
|
+
|
|
199
|
+
### Contract vs. opinion
|
|
200
|
+
|
|
201
|
+
No competitor does contract-based deterministic scoring. Lighthouse is weighted heuristics. axe-core is rule violations. securityheaders.com is a single dimension. Designesy's 40-check contract-bound 0-100 score across 7 dimensions (tokens, motion, accessibility, cadence, takt, typography, copywriting) has no direct analog.
|
|
202
|
+
|
|
203
|
+
## Caching
|
|
204
|
+
|
|
205
|
+
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.
|
|
206
|
+
|
|
207
|
+
## Safety
|
|
208
|
+
|
|
209
|
+
**Read-only.** This server never writes anywhere. It does not execute code, mutate files, or access credentials.
|
|
210
|
+
|
|
211
|
+
## Provenance
|
|
212
|
+
|
|
213
|
+
All data is fetched live from:
|
|
214
|
+
- `https://www.designesy.org/open.json`
|
|
215
|
+
- `https://www.designesy.org/contracts/design-system.json`
|
|
216
|
+
- `https://www.designesy.org/kits/design-review.json`
|
|
217
|
+
- `https://www.designesy.org/contracts/skill`
|
|
218
|
+
- `https://www.designesy.org/.well-known/agent.json`
|
|
219
|
+
- `https://www.designesy.org/llms.txt`
|
|
220
|
+
- `https://www.designesy.org/llms-full.txt`
|
|
221
|
+
|
|
222
|
+
## License
|
|
223
|
+
|
|
224
|
+
MIT
|
|
225
|
+
|
|
226
|
+
## Links
|
|
227
|
+
|
|
228
|
+
- [Homepage](https://www.designesy.org)
|
|
229
|
+
- [Agent Install](https://pypi.org/project/designesy-mcp/#quick-start-one-command) — one-command `uvx designesy-mcp`
|
|
230
|
+
- [Repository](https://github.com/LE-VAI/designesy-org)
|
|
231
|
+
- [MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.LE-VAI%2Fdesignesy-org)
|
|
232
|
+
- [Changelog](https://github.com/LE-VAI/designesy-org/releases)
|
|
233
|
+
- [Design-system contract](https://www.designesy.org/contracts/design-system.json)
|
|
234
|
+
- [Leaderboard](https://www.designesy.org/leaderboard) — 30-site public cohort, A–F histogram, weekly re-score
|
|
235
|
+
- [Score badge](https://www.designesy.org/badge) — embeddable SVG badge for A/B-graded sites
|
|
236
|
+
- [Live score API](https://www.designesy.org/api/score?url=designesy.org) — JSON, no key, no login
|
|
237
|
+
- [Methodology](https://www.designesy.org/methodology)
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# designesy-mcp
|
|
2
|
+
|
|
3
|
+
<!-- mcp-name: io.github.LE-VAI/designesy-org -->
|
|
4
|
+
|
|
5
|
+
[](https://pypi.org/project/designesy-mcp/)
|
|
6
|
+
[](https://www.python.org/downloads/)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://modelcontextprotocol.io)
|
|
9
|
+
|
|
10
|
+
**One-click install:**
|
|
11
|
+
|
|
12
|
+
[](https://vscode.dev/redirect/mcp/install?name=designesy&config=%7B%22designesy%22%3A%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22designesy-mcp%22%5D%7D%7D)
|
|
13
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=designesy&config=%7B%22designesy%22%3A%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22designesy-mcp%22%5D%7D%7D&quality=insiders)
|
|
14
|
+
[](cursor://anysphere.cursor-deeplink/mcp/install?name=designesy&config=%7B%22designesy%22%3A%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22designesy-mcp%22%5D%7D%7D)
|
|
15
|
+
[](https://vscode.dev/redirect/mcp/install?name=designesy&config=%7B%22designesy%22%3A%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.designesy.org%2Fapi%2Fmcp%22%7D%7D)
|
|
16
|
+
|
|
17
|
+
A **read-only stdio MCP server** exposing [designesy.org](https://www.designesy.org)'s design-intelligence infrastructure as native agent tools.
|
|
18
|
+
|
|
19
|
+
Zero external dependencies. Pure Python stdlib. Implements the [Model Context Protocol](https://modelcontextprotocol.io) JSON-RPC 2.0 over stdio.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Quick start (one command)
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
uvx designesy-mcp
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
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.
|
|
30
|
+
|
|
31
|
+
> 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.
|
|
32
|
+
|
|
33
|
+
## MCP client config
|
|
34
|
+
|
|
35
|
+
### uvx (recommended — no install step)
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"mcpServers": {
|
|
40
|
+
"designesy": {
|
|
41
|
+
"command": "uvx",
|
|
42
|
+
"args": ["designesy-mcp"]
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### pip install (traditional)
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pip install designesy-mcp
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"designesy": {
|
|
58
|
+
"command": "designesy-mcp"
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### python -m (module form)
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"mcpServers": {
|
|
69
|
+
"designesy": {
|
|
70
|
+
"command": "python",
|
|
71
|
+
"args": ["-m", "designesy_mcp_server"]
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
No arguments needed. The server speaks JSON-RPC 2.0 over stdin/stdout.
|
|
78
|
+
|
|
79
|
+
## Tools (17)
|
|
80
|
+
|
|
81
|
+
The server exposes 17 tools, all fetched live from `https://www.designesy.org/`:
|
|
82
|
+
|
|
83
|
+
### Read-only discovery
|
|
84
|
+
| Tool | What it does |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `designesy_catalog` | Get the 12-package catalog (versions, URLs, statuses) from `/open.json` |
|
|
87
|
+
| `designesy_contract` | Get the full design-system contract v0.4.0 (tokens, motion, acoustic, takt, cadence, typography, components, verification, open tensions) — or a filtered section |
|
|
88
|
+
| `designesy_design_review` | Get the Design Review kit (8 dimensions, agent prompt, output format, verification checklist) |
|
|
89
|
+
| `designesy_skill_md` | Get the agent-skill-format export (SKILL.md) with behavioral rules, tokens, anti-patterns |
|
|
90
|
+
| `designesy_agent_json` | Get the agent discovery document (`.well-known/agent.json`) — identity, authority, ingest protocol |
|
|
91
|
+
| `designesy_llms_txt` | Get the short agent brief (`/llms.txt`) |
|
|
92
|
+
| `designesy_llms_full_txt` | Get the full agent brief (`/llms-full.txt`) with ingest protocol, all packages, paste-ready prompt |
|
|
93
|
+
|
|
94
|
+
### Executable verification
|
|
95
|
+
| Tool | What it does |
|
|
96
|
+
|---|---|
|
|
97
|
+
| `designesy_score` | Run the 40-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). |
|
|
98
|
+
| `designesy_tokens_score` | Validate a design token file against the W3C Design Tokens Community Group (DTCG) 2025.10 format. 10 checks (t01–t10). |
|
|
99
|
+
| `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. |
|
|
100
|
+
| `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). |
|
|
101
|
+
|
|
102
|
+
### Executable engines (new in v1.10.0)
|
|
103
|
+
| Tool | What it does |
|
|
104
|
+
|---|---|
|
|
105
|
+
| `designesy_drift_score` | 12-check AI-drift radar — detects token fabrication, within-session drift, between-session amnesia, and silent breaking changes. |
|
|
106
|
+
| `designesy_readiness_score` | 10-check AI readiness probe — tests for DTCG tokens, llms.txt, agent.json, MCP endpoint, DESIGN.md, sitemap, robots, OG meta. |
|
|
107
|
+
| `designesy_guardrails` | Generate a frozen build-contract bundle: DTCG tokens, Stylelint config, AGENTS.md rules, component contract, anti-patterns, DESIGN.md. |
|
|
108
|
+
| `designesy_monitor_score` | Continuous drift governance — 10 monitor checks with history deltas, trend slope, and email alerts via Resend. |
|
|
109
|
+
| `designesy_compare` | Diff two design systems from live URLs — 8-dimension structured diff (added, removed, renamed, value-changed, scale, contrast, structure, score). |
|
|
110
|
+
| `designesy_report` | Composite synthesis — fires score + drift + readiness in parallel, computes weighted composite grade. The most shareable surface. |
|
|
111
|
+
|
|
112
|
+
## Resources (7)
|
|
113
|
+
|
|
114
|
+
The server also exposes 7 MCP resources (read-only URIs):
|
|
115
|
+
|
|
116
|
+
| URI | Content |
|
|
117
|
+
|---|---|
|
|
118
|
+
| `designesy://open` | Package catalog (JSON) |
|
|
119
|
+
| `designesy://contract` | Full design-system contract (JSON) |
|
|
120
|
+
| `designesy://kit/design-review` | Design Review kit (JSON) |
|
|
121
|
+
| `designesy://skill` | SKILL.md agent-skill export (Markdown) |
|
|
122
|
+
| `designesy://agent` | Agent discovery document (JSON) |
|
|
123
|
+
| `designesy://llms` | Short agent brief (text) |
|
|
124
|
+
| `designesy://llms-full` | Full agent brief (text) |
|
|
125
|
+
|
|
126
|
+
## The 40-check verification engine
|
|
127
|
+
|
|
128
|
+
`designesy_score` runs 40 deterministic checks across 13 weighted categories:
|
|
129
|
+
|
|
130
|
+
| Category | Weight | What it measures |
|
|
131
|
+
|---|---|---|
|
|
132
|
+
| cadence | 18 | Typography rhythm — line-height, font-synthesis, text-underline-position, skip-ink |
|
|
133
|
+
| accessibility | 15 | WCAG 2.2 primitives — reduced-motion, forced-colors, AI disclosure, focus-visible |
|
|
134
|
+
| semantic | 12 | Token architecture — `:root` custom properties, no raw hex, semantic naming |
|
|
135
|
+
| motion | 10 | Motion hygiene — duration tokens, easing tokens, reduced-motion blocks |
|
|
136
|
+
| tokens | 9 | DTCG 2025.10 conformance — `$type`, `$value`, `$description`, colorSpace |
|
|
137
|
+
| takt | 8 | Timing discipline — transition bands, animation hierarchy |
|
|
138
|
+
| poise | 7 | Composure — viewport overflow, scroll behavior, print styles |
|
|
139
|
+
| identity | 6 | Brand coherence — title, meta description, favicon, og tags |
|
|
140
|
+
| interaction | 6 | Interaction primitives — hover states, press feedback, disabled states |
|
|
141
|
+
| performance | 6 | Core Web Vitals readiness — preload, font-display, render-blocking |
|
|
142
|
+
| responsive | 3 | Responsive primitives — viewport meta, container queries |
|
|
143
|
+
| security | 5 | Security headers — CSP, X-Content-Type-Options, referrer policy |
|
|
144
|
+
| spec | 4 | Spec conformance — `lang` attr, `charset`, doctype |
|
|
145
|
+
|
|
146
|
+
No LLM. No roast. The same engine scores [designesy.org](https://www.designesy.org) itself — in public, at 95.3% A.
|
|
147
|
+
|
|
148
|
+
## Standards positioning
|
|
149
|
+
|
|
150
|
+
### DTCG 2025.10 — the spec went stable
|
|
151
|
+
|
|
152
|
+
The W3C Design Tokens Community Group published the spec's **first stable version** on Oct 28, 2025 — the [Final Community Group Report](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/), 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 (2026, up from 56% YoY).
|
|
153
|
+
|
|
154
|
+
`designesy_tokens_score` validates against this stable spec. Every team adopting DTCG 2025.10 needs a validator — designesy is it.
|
|
155
|
+
|
|
156
|
+
### Motion tokens — the spec's blind spot
|
|
157
|
+
|
|
158
|
+
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](https://www.thestackstories.com/blog/state-of-design-systems-2026-field-report) confirms this is the remaining friction point.
|
|
159
|
+
|
|
160
|
+
`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 — the only validator that 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.
|
|
161
|
+
|
|
162
|
+
### Contract vs. opinion
|
|
163
|
+
|
|
164
|
+
No competitor does contract-based deterministic scoring. Lighthouse is weighted heuristics. axe-core is rule violations. securityheaders.com is a single dimension. Designesy's 40-check contract-bound 0-100 score across 7 dimensions (tokens, motion, accessibility, cadence, takt, typography, copywriting) has no direct analog.
|
|
165
|
+
|
|
166
|
+
## Caching
|
|
167
|
+
|
|
168
|
+
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.
|
|
169
|
+
|
|
170
|
+
## Safety
|
|
171
|
+
|
|
172
|
+
**Read-only.** This server never writes anywhere. It does not execute code, mutate files, or access credentials.
|
|
173
|
+
|
|
174
|
+
## Provenance
|
|
175
|
+
|
|
176
|
+
All data is fetched live from:
|
|
177
|
+
- `https://www.designesy.org/open.json`
|
|
178
|
+
- `https://www.designesy.org/contracts/design-system.json`
|
|
179
|
+
- `https://www.designesy.org/kits/design-review.json`
|
|
180
|
+
- `https://www.designesy.org/contracts/skill`
|
|
181
|
+
- `https://www.designesy.org/.well-known/agent.json`
|
|
182
|
+
- `https://www.designesy.org/llms.txt`
|
|
183
|
+
- `https://www.designesy.org/llms-full.txt`
|
|
184
|
+
|
|
185
|
+
## License
|
|
186
|
+
|
|
187
|
+
MIT
|
|
188
|
+
|
|
189
|
+
## Links
|
|
190
|
+
|
|
191
|
+
- [Homepage](https://www.designesy.org)
|
|
192
|
+
- [Agent Install](https://pypi.org/project/designesy-mcp/#quick-start-one-command) — one-command `uvx designesy-mcp`
|
|
193
|
+
- [Repository](https://github.com/LE-VAI/designesy-org)
|
|
194
|
+
- [MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.LE-VAI%2Fdesignesy-org)
|
|
195
|
+
- [Changelog](https://github.com/LE-VAI/designesy-org/releases)
|
|
196
|
+
- [Design-system contract](https://www.designesy.org/contracts/design-system.json)
|
|
197
|
+
- [Leaderboard](https://www.designesy.org/leaderboard) — 30-site public cohort, A–F histogram, weekly re-score
|
|
198
|
+
- [Score badge](https://www.designesy.org/badge) — embeddable SVG badge for A/B-graded sites
|
|
199
|
+
- [Live score API](https://www.designesy.org/api/score?url=designesy.org) — JSON, no key, no login
|
|
200
|
+
- [Methodology](https://www.designesy.org/methodology)
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
// CDP Core Web Vitals checker — simplified version
|
|
2
|
+
// Uses a separate expression file (cwv-expr.js) to avoid escaping issues.
|
|
3
|
+
//
|
|
4
|
+
// R2 improvements (2026-07-26):
|
|
5
|
+
// - Honest INP: reports `inp: null` + `inpPass: null` when no interaction occurred.
|
|
6
|
+
// - Settle-based wait (handled inside cwv-expr.js).
|
|
7
|
+
// - --throttle flag applies Lighthouse mobile preset.
|
|
8
|
+
//
|
|
9
|
+
// Usage: node cdp-cwv-expr.js <url> [--throttle]
|
|
10
|
+
const http = require('http');
|
|
11
|
+
// Node 21+ provides a global WebSocket (DOM API: onopen/onmessage/onerror).
|
|
12
|
+
// No need for the 'ws' npm package — this keeps the MCP package zero-dependency.
|
|
13
|
+
const fs = require('fs');
|
|
14
|
+
const path = require('path');
|
|
15
|
+
|
|
16
|
+
const CDP_HOST = '127.0.0.1';
|
|
17
|
+
const CDP_PORT = 9222;
|
|
18
|
+
|
|
19
|
+
function cdpRequest(p, method = 'PUT') {
|
|
20
|
+
return new Promise((resolve, reject) => {
|
|
21
|
+
const req = http.request({ host: CDP_HOST, port: CDP_PORT, path: p, method }, (res) => {
|
|
22
|
+
let data = '';
|
|
23
|
+
res.on('data', c => data += c);
|
|
24
|
+
res.on('end', () => { try { resolve(JSON.parse(data)); } catch (e) { resolve({}); } });
|
|
25
|
+
});
|
|
26
|
+
req.on('error', reject);
|
|
27
|
+
req.end();
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
// R2-fix: Lighthouse DevTools-method preset values (NOT raw simulated values).
|
|
32
|
+
// requestLatencyMs = 150 * 3.75 = 562.5ms
|
|
33
|
+
// downloadThroughput = 1.44 Mbps, uploadThroughput = 675 Kbps, cpu = 4x
|
|
34
|
+
// See cdp-cwv-check.js for full note. Matches Lighthouse DevTools-method only.
|
|
35
|
+
async function applyThrottling(send) {
|
|
36
|
+
try { await send('Network.enable'); } catch (e) {}
|
|
37
|
+
await send('Network.emulateNetworkConditions', {
|
|
38
|
+
offline: false, latency: 562.5, downloadThroughput: 1440000, uploadThroughput: 675000,
|
|
39
|
+
});
|
|
40
|
+
await send('Emulation.setCPUThrottlingRate', { rate: 4 });
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
async function clearCacheForColdRun(send, origin) {
|
|
44
|
+
try {
|
|
45
|
+
await send('Storage.clearDataForOrigin', {
|
|
46
|
+
origin: origin || '*',
|
|
47
|
+
storageTypes: 'cache_storage,websql,indexeddb,local_storage,service_workers',
|
|
48
|
+
});
|
|
49
|
+
} catch (e) {}
|
|
50
|
+
try { await send('Network.clearBrowserCache'); } catch (e) {}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
async function checkCWV(url, throttle) {
|
|
54
|
+
console.log(`Opening ${url}${throttle ? ' [throttled]' : ''}...`);
|
|
55
|
+
const tab = await cdpRequest(`/json/new?${encodeURIComponent(url)}`);
|
|
56
|
+
if (!tab.webSocketDebuggerUrl) throw new Error('Could not create tab');
|
|
57
|
+
console.log(`Tab: ${tab.id}`);
|
|
58
|
+
|
|
59
|
+
const ws = new WebSocket(tab.webSocketDebuggerUrl);
|
|
60
|
+
let msgId = 0;
|
|
61
|
+
const pending = {};
|
|
62
|
+
|
|
63
|
+
function send(method, params = {}) {
|
|
64
|
+
return new Promise((resolve, reject) => {
|
|
65
|
+
const id = ++msgId;
|
|
66
|
+
pending[id] = { resolve, reject };
|
|
67
|
+
ws.send(JSON.stringify({ id, method, params }));
|
|
68
|
+
setTimeout(() => { if (pending[id]) { pending[id].reject(new Error(method + ' timeout')); delete pending[id]; } }, 25000);
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
return new Promise((resolve, reject) => {
|
|
73
|
+
const overallTimeout = setTimeout(() => { ws.close(); cdpRequest(`/json/close/${tab.id}`); reject(new Error('timeout')); }, 40000);
|
|
74
|
+
|
|
75
|
+
ws.onmessage = (event) => {
|
|
76
|
+
const msg = JSON.parse(event.data);
|
|
77
|
+
if (pending[msg.id]) { pending[msg.id].resolve(msg); delete pending[msg.id]; }
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
ws.onopen = async () => {
|
|
81
|
+
try {
|
|
82
|
+
await send('Performance.enable');
|
|
83
|
+
await send('Runtime.enable');
|
|
84
|
+
if (throttle) {
|
|
85
|
+
await clearCacheForColdRun(send, new URL(url).origin);
|
|
86
|
+
await applyThrottling(send);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// Short pre-roll for first paint; cwv-expr.js handles settle/maxWait
|
|
90
|
+
await new Promise(r => setTimeout(r, 600));
|
|
91
|
+
console.log('Measuring CWV (settle-based)...');
|
|
92
|
+
|
|
93
|
+
const exprPath = path.join(__dirname, 'cwv-expr.js');
|
|
94
|
+
const expr = fs.readFileSync(exprPath, 'utf8');
|
|
95
|
+
|
|
96
|
+
const result = await send('Runtime.evaluate', {
|
|
97
|
+
expression: expr,
|
|
98
|
+
returnByValue: true,
|
|
99
|
+
awaitPromise: true,
|
|
100
|
+
userGesture: true,
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
clearTimeout(overallTimeout);
|
|
104
|
+
ws.close();
|
|
105
|
+
|
|
106
|
+
let d = { lcp: null, inp: -1, cls: 0, inpMeasured: false, lcpMeasured: false, settled: 'unknown' };
|
|
107
|
+
if (result.result && result.result.result && result.result.result.value) {
|
|
108
|
+
d = JSON.parse(result.result.result.value);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
// R2: honest INP — -1 sentinel (web-vitals interop) when no interaction
|
|
112
|
+
const lcpPass = d.lcpMeasured ? (d.lcp > 0 && d.lcp < 2500) : null;
|
|
113
|
+
const inpPass = d.inpMeasured ? (d.inp < 200) : null;
|
|
114
|
+
const clsPass = d.cls < 0.1;
|
|
115
|
+
const plausible = d.lcpMeasured ? (d.lcp > 0 && d.lcp < 25000 && d.cls < 1) : (d.cls < 1);
|
|
116
|
+
|
|
117
|
+
console.log(` LCP: ${d.lcpMeasured ? d.lcp + 'ms' : 'n/a'} ${lcpPass === true ? 'PASS' : lcpPass === false ? 'FAIL' : 'N/A'} (threshold 2500ms)`);
|
|
118
|
+
console.log(` INP: ${d.inpMeasured ? d.inp + 'ms' : '-1 (no interaction)'} ${inpPass === true ? 'PASS' : inpPass === false ? 'FAIL' : 'N/A'} (threshold 200ms)`);
|
|
119
|
+
console.log(` CLS: ${d.cls} ${clsPass ? 'PASS' : 'FAIL'} (threshold 0.1)`);
|
|
120
|
+
console.log(` plausible: ${plausible} | settled: ${d.settled} | throttled: ${throttle}`);
|
|
121
|
+
|
|
122
|
+
await cdpRequest(`/json/close/${tab.id}`);
|
|
123
|
+
resolve({
|
|
124
|
+
url, lcp: d.lcp, inp: d.inp, cls: d.cls,
|
|
125
|
+
inpMeasured: d.inpMeasured, lcpMeasured: d.lcpMeasured, settled: d.settled,
|
|
126
|
+
lcpPass, inpPass, clsPass, plausible,
|
|
127
|
+
throttled: throttle,
|
|
128
|
+
thresholds: { lcp: 2500, inp: 200, cls: 0.1 },
|
|
129
|
+
});
|
|
130
|
+
} catch (err) {
|
|
131
|
+
clearTimeout(overallTimeout);
|
|
132
|
+
ws.close();
|
|
133
|
+
await cdpRequest(`/json/close/${tab.id}`);
|
|
134
|
+
reject(err);
|
|
135
|
+
}
|
|
136
|
+
};
|
|
137
|
+
|
|
138
|
+
ws.onerror = (e) => { clearTimeout(overallTimeout); cdpRequest(`/json/close/${tab.id}`); reject(e); };
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
const args = process.argv.slice(2);
|
|
143
|
+
const throttle = args.includes('--throttle');
|
|
144
|
+
const url = args.find(a => !a.startsWith('--'));
|
|
145
|
+
if (!url) { console.error('Usage: node cdp-cwv-expr.js <url> [--throttle]'); process.exit(1); }
|
|
146
|
+
checkCWV(url, throttle).then(r => { console.log('\n' + JSON.stringify(r, null, 2)); process.exit(0); }).catch(e => { console.error('Error:', e.message); process.exit(1); });
|