Machine Design Vision Protocol

Abstract

MDVP-T/1.0 defines a canonical output format, a scoring taxonomy, and a set of API endpoints that together enable programmatic design perception. The protocol is inspired by the simplicity of plain-text machine protocols (HTTP, SMTP) and the structured observation patterns of perceptual computing research.

Every response is a plain-text envelope parseable by any language model without vision capabilities. Scores are deterministic, computed from DOM metrics — not from subjective AI judgment.

2. Protocol Output Format

Every MDVP response begins with a status line followed by named sections enclosed in [SECTION] markers.

2.1 Status Line

MDVP-T/1.0 <domain> <grade> <score>/100

Example:

MDVP-T/1.0 stripe.com A+ 91/100

2.2 Sections

Sections appear in this order:

3. Section Specifications

[DOM]

Extracted from computed CSS styles. All values are DOM-ground-truth, not inferred.

font-stack: Inter + system-ui (2 families)
type-scale: 48→32→24→18→16→14px (ratio ~1.33)
font-weights: 400, 600, 700
color-palette: 5 colors — dominant: #0a0a0a
css-tokens: 42 custom properties
border-radius: 8px, 12px
spacing-scale: 4, 8, 12, 16, 24, 32, 48px
animations: 3 | backdrop-blur: 1 | gradients: 2
cta-count: 2 | nav-items: 6 | semantic-tags: 8

[ENTROPY]

Shannon entropy H normalized to [0, 1]. Lower = more systematic.

typography:  0.21 (4 sizes, dominant: 16px)  CONSISTENT
spacing:     0.34 (8 unique values, grid-adherence: 94%)
color:       0.18 (6 colors)  MINIMAL
overall:     0.24  LOW NOISE — systematic
apca-lc:     78  ok  contrast-variance:0.12
grid-jitter: 0.08  clean  grit-score:0.91

Thresholds: < 0.25 CONSISTENT · 0.25–0.60 MODERATE · > 0.60 CHAOTIC

[CLASSIFY]

label: PREMIUM  confidence: 87%  scores: premium=87% good=11% chaotic=2%
top-signals: css-tokens→positive(0.412)  animations→positive(0.287)

Labels: premium · good · vibecoded · bad

[DIAGNOSIS]

originality:32 — no CSS custom properties, no animations
modernity:41 — no backdrop-blur, no motion

[RECOMMENDATIONS]

+ add CSS custom properties for color/spacing tokens
+ add entrance animations (opacity + translateY, 300ms ease)
+ add explicit CTA above fold

4. Scoring Taxonomy

MDVP scores 12 design dimensions, each 0–100.

5. Grade Scale

6. API Endpoints

POST /perceive — Full MDVP-T/1.0 envelope

POST /perceive HTTP/1.1
Host: api.mdvp.dev
Content-Type: application/json
X-API-Key: ds_your_key

{
  "domain": "stripe.com",
  "include_vision": true
}

Response headers include X-MDVP-Version, X-MDVP-Score, X-MDVP-Grade. Body is the full text envelope.

POST /audit — JSON score

POST /audit HTTP/1.1
Host: api.mdvp.dev
Content-Type: application/json
X-API-Key: ds_your_key

{ "url": "https://stripe.com" }

{
  "id": "stripe.com",
  "grade": "A+",
  "overall_score": 91,
  "label": "premium",
  "scores": {
    "overall": 91,
    "breakdown": [
      { "c": "spacing",     "s": 94 },
      { "c": "typography",  "s": 89 }
    ]
  }
}

MCP Server — Claude / Cursor

{
  "mcpServers": {
    "@mdvp/cli": {
      "url": "https://api.mdvp.dev/mcp",
      "headers": { "X-API-Key": "ds_your_key" }
    }
  }
}

Available tools: audit_url · compare_sites · perceive_url · top_sites · get_assets · submit_for_crawl

7. Authentication

X-API-Key: ds_your_key
# or
Authorization: Bearer ds_your_key

Keys issued at https://mdvp.dev. Free tier: $1.00 credit on signup.

x402 Pay-Per-Request

MDVP supports the x402 payment protocol for keyless access on Base (USDC).

curl -X POST https://api.mdvp.dev/audit \
  -d '{"url":"https://example.com"}'

# → 402 Payment Required
{
  "x402Version": 1,
  "accepts": [{
    "network": "base",
    "maxAmountRequired": "200000"
  }]
}

10. Conformance

A conformant MDVP-T/1.0 producer MUST:

• 1. Emit a valid status line as the first line of every perception response
• 2. Include [DOM], [ENTROPY], [CLASSIFY], [DIAGNOSIS], and [RECOMMENDATIONS] sections
• 3. Set X-MDVP-Version, X-MDVP-Score, and X-MDVP-Grade response headers
• 4. Return scores as integers in [0, 100]
• 5. Use normalized domain identifiers (no www., no trailing slash)

A conformant MDVP-T/1.0 consumer MUST:

• 1. Parse the status line to extract domain, grade, and score
• 2. Treat unknown [SECTION] markers as opaque (forward-compatible)
• 3. Not assume section ordering beyond the status line