Design System MCP

An independent Harvey case study and a reusable blueprint for brand-governed AI

Independent project — not affiliated with Harvey. This is an unofficial educational case study created from publicly observable brand materials. It is not sponsored, endorsed, reviewed, or maintained by Harvey AI, Inc. “Harvey” and associated marks belong to their respective owners. See NOTICE.md before reusing brand assets or guidance.

This repository demonstrates how to turn a design system into two synchronized interfaces:

1. a visual atlas that people can browse; and
2. a Model Context Protocol (MCP) server that agents can query before designing UI, images, motion, or video.

The Harvey package is a worked example. The reusable idea is the contract: structured tokens, rules, recipes, media rights, evaluation gates, capability modules, prompts, tools, and audits that all resolve from one versioned brand package.

Try the example

• Visual design-system atlas: harvey-design-system.vercel.app
• Public Streamable HTTP MCP: harvey-design-system.vercel.app/mcp

Add the remote endpoint to any compatible AI agent:

{
  "mcpServers": {
    "harvey-design-system": {
      "url": "https://harvey-design-system.vercel.app/mcp"
    }
  }
}

Then try requests such as:

Use the Harvey design-system MCP to create a responsive product-page blueprint.
Compile an on-brand image prompt for a legal team working late in New York.
Plan a ten-second partnership announcement and audit it before rendering.
Explain which rules made the output pass or fail.

The MCP is a read-only brand-intelligence layer. It does not need a Harvey credential, collect API keys, submit paid generation jobs, or claim that concept work is approved for publication.

What is inside

harvey-design-system-mcp/
├── src/                          # React visual atlas
├── api/mcp.mjs                  # Vercel Streamable HTTP handler
├── mcp/
│   ├── server.mjs               # tools, resources, and prompts
│   ├── brand-loader.mjs         # package loading and rights checks
│   ├── production-planner.mjs   # UI, image, motion, and video planning
│   ├── audit.mjs                # deterministic brand preflight
│   ├── brand-system-spec/
│   │   └── v1/schemas/          # reusable JSON schemas
│   └── brand-package/
│       └── harvey/              # worked brand-package example
├── scripts/
│   └── validate-brand-package.mjs
├── tests/                        # MCP, HTTP, and hosting checks
├── worker/                       # alternate Sites-compatible runtime
└── videos/                       # inspectable motion example source

The frontend is presentation-only. The MCP provides machine-readable governance. Your AI agent of choice remains responsible for calling image/video providers, composing output, inspecting the result, and preserving provenance.

The portable brand-package contract

Each brand lives in one directory:

<brand-id>/
├── brand.json
├── tokens.json
├── rules.json
├── recipes.json
├── media.json
├── evaluation.json
├── DESIGN.md
├── media/
│   ├── official/
│   └── marketing-reference/
└── modules/
    ├── interactive.json
    ├── static.json
    ├── imagery.json
    ├── commerce.json
    ├── marketing.json
    ├── motion.json
    ├── generative-image.json
    ├── generative-video.json
    ├── spatial.json
    └── sequential.json

File	Responsibility
brand.json	Identity, package version, audiences, traits, provenance, and module registry
tokens.json	Semantic color, type, spacing, size, shape, border, and layout primitives
rules.json	Required, preferred, permitted, prohibited, and reference-only behavior
recipes.json	Repeatable compositions that connect inputs, tokens, and rule IDs
media.json	Asset/source catalog with provenance, checksums, rights, and allowed uses
evaluation.json	Hard rejection gates, weighted quality dimensions, and approval policy
DESIGN.md	Human-readable interpretation of the same package
modules/*.json	Capability-specific extensions without duplicating the core system

Stable IDs matter more than prose. An audit can cite rule.motion.partnership.identity-reveal, a recipe can point back to it, and a later package version can supersede it without silently changing what an old production meant.

Build a design MCP for your own brand

1. Establish authority and rights first

Use source priority deliberately:

1. official brand manuals and licensed asset portals;
2. design files and production components owned by the brand;
3. current public product and marketing surfaces;
4. inferred patterns, labeled as inferred rather than official.

Record source URL, retrieval date, confidence, lifecycle, permitted uses, and whether an asset may be uploaded to a model. Do not bundle proprietary fonts, customer data, private design files, or reference imagery without redistribution rights.

2. Fork the repository and replace the example package

git clone https://github.com/thenpceo/harvey-design-system-mcp.git
cd harvey-design-system-mcp
npm install

cp -R mcp/brand-package/harvey mcp/brand-package/example-brand

Replace every Harvey-specific value, rule, recipe, source, and asset. A practical final cleanup is:

rg -n -i "harvey" . \
  --glob '!node_modules/**' \
  --glob '!dist/**' \
  --glob '!.git/**'

Do not merely recolor the example. Rebuild the package from evidence for the new brand.

3. Encode tokens, then behavior

Start with semantic tokens (color.surface.primary, not just #ffffff). Add rules with:

• a stable ID;
• authority level;
• lifecycle and confidence;
• capabilities the rule applies to;
• a testable statement; and
• source IDs that justify it.

Add recipes only after the primitives and rules exist. A recipe should describe how to compose a known output, not smuggle in undocumented design decisions.

4. Separate core truth from provider adapters

Keep volatile provider syntax outside the canonical package. The package should say what the brand requires; adapters translate that into GPT Image, fal, Kling, HyperFrames, CSS, or another renderer.

This boundary lets the brand survive tool changes:

brand package → MCP plan/audit → provider adapter → generation/composition → inspected output

5. Expose resources, tools, and prompts

A useful design MCP normally needs all three:

• Resources for identity, tokens, rules, recipes, assets, and the human guide.
• Tools that compile prompts, create UI/motion/video plans, retrieve authorized files, and audit outputs.
• Prompts that teach an agent the recommended workflow for common production intents.

Return rule IDs and package versions in outputs. That makes a generated artifact explainable and reproducible.

6. Add deterministic gates

At minimum, block:

• unsupported claims or metrics;
• missing source records;
• unlicensed logo/font/media use;
• reference-only assets used as production assets;
• likeness or customer-story ambiguity;
• paid generation without a disclosed model and cost; and
• delivery without inspection evidence.

An MCP should not say “on brand” merely because a prompt contains adjectives. It should be able to explain which constraints were applied and which evidence was checked.

7. Validate the package

npm run validate:brand
npm test
npm run build

The included validator checks package completeness, stable references, token references, schemas, asset checksums, evaluation weights, module declarations, and tool-independent core guidance.

8. Deploy Streamable HTTP

The Vercel handler at api/mcp.mjs is stateless and credential-free. After replacing the package and server naming, deploy with your preferred Vercel workflow. Your endpoint will be:

https://<your-project>.vercel.app/mcp

Keep provider credentials in the user's agent secret store. Never put them in the browser frontend, Git repository, brand package, production plan, or MCP response.

Local development

Requirements: Node.js 20+ and npm.

npm install
npm run dev

Run the MCP over local stdio:

npm run mcp:start

Example local client configuration:

{
  "mcpServers": {
    "harvey-design-system": {
      "command": "node",
      "args": ["/absolute/path/to/harvey-design-system-mcp/mcp/server.mjs"]
    }
  }
}

Verification

npm run validate:brand   # package contract and references
npm run test:mcp         # tool/resource/prompt inventory and behavior
npm run test:http-mcp    # Streamable HTTP handshake
npm run test:sites       # alternate hosting worker
npm run build            # production frontend + server artifacts

The current example exposes 14 tools, 10 resources, and 8 prompts. Treat those counts as a versioned test fixture, not as a universal target for every brand.

Generative media and motion

The repository contains original synthetic demo imagery and footage plus an inspectable HyperFrames-style partnership composition. Brand-critical text, claims, UI, and logos remain deterministic overlays rather than being baked into generative footage.

The example MCP may recommend optional companions for production:

• fal.ai MCP for model discovery and generation;
• HyperFrames for deterministic motion composition and rendering.

Those services are independent, may incur cost, and are not called by the public website or this brand-intelligence endpoint.

Important limitations

• This repository is not an official Harvey design system.
• Public interfaces and brand details can change after the recorded research date.
• Inferred guidance must yield to any current official manual.
• The included Harvey-specific package is an educational example, not permission to publish as Harvey.
• Official marks remain subject to Harvey's current press and trademark terms.
• Proprietary Harvey font files are not bundled. The demo documents fallbacks and references public web resources, but production use requires appropriate authorization.
• Partnership names and claims in motion examples are fictional concept material unless separately sourced and approved.

License and attribution

Original code is available under the MIT License. That license does not grant rights to Harvey trademarks, third-party brand assets, fonts, public-site content, model outputs with separate terms, or any material identified as reference-only. See NOTICE.md and the rights record in media.json.

If you build your own design MCP from this project, keep the provenance and rights layer. It is part of the architecture, not paperwork to remove at the end.