Which integrations are available for this server?

Allows GitHub Copilot to manage design system resources such as tokens, components, patterns, and validation through MCP.

How do I use MPDS-MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MPDS-MCP validate color contrast #333333 on #FFFFFF" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MPDS-MCP

by nouhouari

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

MPDS-MCP

Multi-Project Design System MCP Server — an HTTP server that exposes design tokens, component specs, and validation utilities via a JSON REST API and an MCP JSON-RPC endpoint. Multiple design-system projects can coexist, each with parent-child inheritance for token resolution.

Architecture

modules/
  mcp-server/   # Express HTTP server (this binary, port MCP_PORT)
  registry/     # Project CRUD (SQLite-backed)
  tokens/       # Token storage, overrides, semantic resolution
  components/   # Component spec storage and overrides
  patterns/     # Pattern library: patterns, variants, composition rules, layout guidelines
  validate/     # Color-pair + snippet validation
  preview/      # HTML showcase generator (generate_showcase MCP tool)
  db/           # Shared SQLite connection + migrations

Related MCP server: ds-mcp

Inheritance model

Every project carries a nullable parentId (registry):

A project with parentId = null is a base design system.
A project with a parentId is a child that inherits from its base and may override individual tokens, component-spec fields, and patterns.
Inheritance is two levels deep only — creating a child of a child is rejected with MAX_INHERITANCE_DEPTH (no grandchildren).
A base cannot be deleted while it still has children (BASE_HAS_CHILDREN), and a project cannot be deleted while it still owns tokens (PROJECT_HAS_TOKENS).

graph TD
    Base["<b>Base design system</b><br/>parentId = null"]
    ChildA["<b>Child: Brand A</b><br/>parentId = Base"]
    ChildB["<b>Child: Brand B</b><br/>parentId = Base"]
    GC(["Grandchild<br/>❌ MAX_INHERITANCE_DEPTH"])

    Base --> ChildA
    Base --> ChildB
    ChildA -. rejected .-> GC

    classDef base fill:#1f4e5f,stroke:#0d2b36,color:#fff;
    classDef child fill:#2d6a4f,stroke:#1b4332,color:#fff;
    classDef bad fill:#7f1d1d,stroke:#450a0a,color:#fff,stroke-dasharray: 4 3;
    class Base base;
    class ChildA,ChildB child;
    class GC bad;

How values resolve

resolveTokens (and the equivalent component/pattern resolvers) merge the base layer with the child's own layer. For a base project every value is tagged source: "base"; for a child the base values are inherited and any keys the child defines win, tagged source: "override":

flowchart LR
    subgraph BASE["Base project (parent)"]
        BA["color.primary = #1f4e5f"]
        BB["color.surface = #ffffff"]
        BC["radius.md = 8px"]
    end

    subgraph CHILD["Child project (own layer)"]
        OA["color.primary = #2d6a4f"]
    end

    BASE -->|"inherited (source: base)"| R
    CHILD -->|"overrides (source: override)"| R

    subgraph R["resolveTokens(child) → resolved set"]
        RA["color.primary = #2d6a4f  (override)"]
        RB["color.surface = #ffffff  (base)"]
        RC["radius.md = 8px  (base)"]
    end

Resolution order is: start from the parent's values, then apply the child's own values by key — so a child key of the same name replaces the inherited one while every un-overridden base key flows through unchanged.

Running locally

Prerequisites

Node.js 20+ and npm
A writable directory for the SQLite DB (or use :memory: for a transient session)

Start (development)

npm ci
MCP_SECRET=dev DB_PATH=/tmp/mpds-dev.db MCP_PORT=3100 \
  npm --prefix modules/mcp-server run dev

Health check:

curl http://localhost:3100/health
# → {"status":"ok"}

Start (production build)

npm ci
npm --prefix modules/mcp-server run build
MCP_SECRET=<secret> DB_PATH=/home/mpds/data/mpds.db MPDS_ENV=production \
  npm --prefix modules/mcp-server start

Environment variables

Variable	Required	Default	Description
`MCP_SECRET`	Yes (production)	`""` (no auth)	Bearer token — every `/api/*` request must carry it
`DB_PATH`	Yes	—	SQLite file path or `:memory:` (transient)
`MCP_PORT`	No	random port	TCP port the server listens on
`MPDS_ENV`	No	—	Set to `production` to enforce `MCP_SECRET` check
`HOME`	No (set by OS/Docker)	—	Used for allowed DB path prefix validation

API endpoints

All endpoints (except /health) require Authorization: Bearer <MCP_SECRET>.

Error envelope: { "error": { "code": "...", "message": "..." } }

Health

GET /health

Projects

GET    /api/projects
POST   /api/projects           body: { id, name, parentId? }
GET    /api/projects/:id
DELETE /api/projects/:id

Tokens

GET    /api/projects/:projectId/tokens
PUT    /api/projects/:projectId/tokens/:key     body: { value, description? }
DELETE /api/projects/:projectId/tokens/:key/override

Components

GET    /api/projects/:projectId/components
GET    /api/projects/:projectId/components/:componentId
PUT    /api/projects/:projectId/components/:componentId/override
DELETE /api/projects/:projectId/components/:componentId/override

Validation

POST   /api/validate/color-pair     body: { foreground, background }

Patterns

GET    /api/projects/:projectId/patterns
POST   /api/projects/:projectId/patterns                       body: { id, name, category, description?, tags?, guidanceUrl? }
GET    /api/projects/:projectId/patterns/:patternId
PATCH  /api/projects/:projectId/patterns/:patternId            body: { name?, description?, tags?, guidanceUrl? }
DELETE /api/projects/:projectId/patterns/:patternId

Pattern variants

GET    /api/projects/:projectId/patterns/:patternId/variants
POST   /api/projects/:projectId/patterns/:patternId/variants   body: { name, appliesAt, description? }
GET    /api/projects/:projectId/patterns/:patternId/variants/:variantId
PATCH  /api/projects/:projectId/patterns/:patternId/variants/:variantId
DELETE /api/projects/:projectId/patterns/:patternId/variants/:variantId

Composition rules

GET    /api/projects/:projectId/composition-rules
POST   /api/projects/:projectId/composition-rules              body: { patternAId, patternBId, relation, guidance? }
DELETE /api/projects/:projectId/composition-rules/:ruleId

relation enum: NESTING_ALLOWED | NESTING_FORBIDDEN | OVERRIDE_CAUTION | SIBLING_ONLY | EXCLUSIVE

Layout guidelines

GET    /api/projects/:projectId/layout-guidelines
POST   /api/projects/:projectId/layout-guidelines              body: { type, name, description?, data }
GET    /api/projects/:projectId/layout-guidelines/:guidelineId
PATCH  /api/projects/:projectId/layout-guidelines/:guidelineId
DELETE /api/projects/:projectId/layout-guidelines/:guidelineId

See contracts/P1/ and contracts/P2/ for the full frozen OpenAPI specs.

MCP configuration

The server exposes a JSON-RPC 2.0 endpoint at POST /mcp (requires the same Authorization: Bearer <MCP_SECRET> header as the REST API). Configure it in your MCP client as an HTTP server.

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)

{
  "mcpServers": {
    "mpds": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3100/mcp"],
      "env": {
        "MCP_REMOTE_HEADER_AUTHORIZATION": "Bearer <MCP_SECRET>"
      }
    }
  }
}

Claude Code (`.claude/settings.json` in your project)

{
  "mcpServers": {
    "mpds": {
      "type": "http",
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_SECRET>"
      }
    }
  }
}

GitHub Copilot (`.vscode/mcp.json` in your workspace)

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mpds_secret",
      "description": "MPDS MCP bearer token",
      "password": true
    }
  ],
  "servers": {
    "mpds": {
      "type": "http",
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mpds_secret}"
      }
    }
  }
}

The input block causes VS Code to prompt for the secret once per session and store it in the system keychain. To skip the prompt, replace ${input:mpds_secret} with the token literal (not recommended for shared workspaces).

OpenCode (`opencode.json` in your project root, or `~/.config/opencode/opencode.json` globally)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mpds": {
      "type": "remote",
      "url": "http://localhost:3100/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <MCP_SECRET>"
      }
    }
  }
}

To avoid hard-coding the secret, reference an environment variable using OpenCode's {env:VAR} interpolation:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mpds": {
      "type": "remote",
      "url": "http://localhost:3100/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MCP_SECRET}"
      }
    }
  }
}

Available MCP methods

Read & validate

Method	Description	Required params
`list_projects`	List all design-system projects	—
`get_tokens`	Resolve tokens for a project (with inheritance)	`projectId`, `category?`
`get_design_system`	Full token map + component specs	`projectId`
`get_component_spec`	Single component spec	`projectId`, `componentId`
`validate_color_pair`	WCAG contrast ratio	`fg`, `bg`, `context` (`normal`\|`large`\|`ui`)
`validate_token_pair`	Contrast check using token keys	`projectId`, `fgKey`, `bgKey`, `context`
`validate_snippet`	Lint HTML/JSX for a11y issues	`content`, `contentType?` (`html`\|`jsx`)
`create_guideline`	Create a design guideline	`id`, `title`, `body?`, `tags?`
`search_guidelines`	Full-text search guidelines	`query`
`propose_token_override`	Propose a token value change for review	`projectId`, `tokenKey`, `proposedValue`, `rationale?`, `agentId?`
`list_proposals`	List pending token proposals	`projectId`

Write — projects & tokens

Method	Description	Required params
`create_project`	Create a project	`id`, `name`, `parentId?`
`update_project`	Rename a project	`projectId`, `name`
`delete_project`	Delete a project	`projectId`
`list_tokens`	List all tokens for a project	`projectId`, `category?`
`get_token`	Get a single token	`projectId`, `key`
`create_token`	Create a token	`projectId`, `key`, `category`, `value`, `isSemantic?`, `semanticRef?`
`update_token`	Update a token value (OCC)	`projectId`, `key`, `version`, `value?`, `semanticRef?`
`set_token`	Set/override a token value	`projectId`, `key`, `value`, `version`
`delete_token`	Delete a token (OCC)	`projectId`, `key`, `version`
`delete_token_override`	Remove a child project override	`projectId`, `key`

Write — components

Method	Description	Required params
`create_component`	Create a component spec	`projectId`, `id`, `name`, `description?`, `props?`, `variants?`, `states?`, …
`update_component`	Update a component spec (OCC)	`projectId`, `componentId`, `version`, `name?`, `description?`, …
`delete_component`	Delete a component spec	`projectId`, `componentId`

Write — pattern library

Method	Description	Required params
`create_pattern`	Create a pattern	`projectId`, `id`, `name`, `category`, `description?`, `tags?`
`update_pattern`	Update a pattern	`projectId`, `patternId`, `name?`, `description?`, `tags?`
`delete_pattern`	Delete a pattern	`projectId`, `patternId`
`create_variant`	Add a variant to a pattern	`projectId`, `patternId`, `name`, `appliesAt`, `description?`
`update_variant`	Update a variant	`projectId`, `patternId`, `variantId`, `name?`, `appliesAt?`
`delete_variant`	Delete a variant	`projectId`, `patternId`, `variantId`
`create_composition_rule`	Define a pattern relationship	`projectId`, `patternAId`, `patternBId`, `relation`, `guidance?`
`delete_composition_rule`	Remove a composition rule	`projectId`, `ruleId`
`create_layout_guideline`	Create a layout guideline	`projectId`, `type`, `name`, `description?`, `data`
`update_layout_guideline`	Update a layout guideline	`projectId`, `guidelineId`, `name?`, `description?`, `data?`
`delete_layout_guideline`	Delete a layout guideline	`projectId`, `guidelineId`

Showcase

Method	Description	Required params
`generate_showcase`	Generate a self-contained HTML design system preview (color palette, component gallery, pattern library)	`projectId`, `title?`

# Save and open the showcase locally
curl -s http://localhost:3100/mcp \
  -H "Authorization: Bearer <MCP_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"generate_showcase","params":{"projectId":"my-ds"}}' \
  | jq -r '.result.html' > /tmp/showcase.html && open /tmp/showcase.html

All requests follow JSON-RPC 2.0:

curl -s http://localhost:3100/mcp \
  -H "Authorization: Bearer <MCP_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"list_projects","params":{}}' | jq

Running tests

Tests use an in-memory SQLite database and require no external services:

DB_PATH=:memory: MCP_SECRET=test npm test

Docker

docker build -t mpds-mcp .
docker run -p 3100:3100 \
  -e MCP_SECRET=<secret> \
  -e DB_PATH=/home/mpds/data/mpds.db \
  -v $(pwd)/data:/home/mpds/data \
  mpds-mcp

See INSTALL.md for full setup and docker-compose instructions.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Product Management Mcp D
io.github.varvararatta
MCP server for Product Management
Product Management Project Management
2
James's MCP Server A
io.github.JGPAS
MCP server with quote and live cryptocurrency price tools, local and cloud-deployed transports.
Cryptocurrency Finance
21
neverinfamous-memory-journal-mcp
ai.smithery
A MCP server built for developers enabling Git based project management with project and personal…
Version Control Developer Tools Project Management
320
MANDATE Credential Broker B
io.github.projetnanocorp
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Security
111

Related MCP Servers

ds-pilot
Design Tools Developer Tools
lyse-labs
A
license
Not graded
quality
C
maintenance
MCP server that exposes your design system components and tokens to AI agents, preventing duplicate component creation and hardcoded token values.
Updated 4 months ago (2026-05-13 14:09 UTC)
5 npm
9
MIT
ds-mcp
Developer Tools Design Tools
aestheticfunction
A
license
Not graded
quality
A
maintenance
A read-only MCP server that provides AI coding agents with a queryable contract for design system tokens, components, patterns, and anti-patterns.
Updated a month ago (2026-08-12 17:25 UTC)
6 npm
1
Apache 2.0
@dsk/mcp
Design Tools Documentation Access
rabindranath1311
A
license
Not graded
quality
B
maintenance
An MCP server that gives AI assistants structured access to a design system's tokens, components, guidelines, and patterns, enabling them to read, lint, and author design system data.
Updated 2 months ago (2026-07-15 22:48 UTC)
1
MIT
systembridge-mcp
Design Tools Developer Tools
teyepe
A
license
A
quality
C
maintenance
MCP server that gives LLMs deep knowledge of design systems and tokens, enabling intelligent design evolution, token analysis, and designer-to-developer handoffs.
Updated 6 days ago (2026-09-09 22:51 UTC)
37
5 npm
2
MIT

MPDS-MCP

Architecture

Inheritance model

How values resolve

Running locally

Prerequisites

Start (development)

Start (production build)

Environment variables

API endpoints

Health

Projects

Tokens

Components

Validation

Patterns

Pattern variants

Composition rules

Layout guidelines

MCP configuration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

Claude Code (.claude/settings.json in your project)

GitHub Copilot (.vscode/mcp.json in your workspace)

OpenCode (opencode.json in your project root, or ~/.config/opencode/opencode.json globally)

Available MCP methods

Read & validate

Write — projects & tokens

Write — components

Write — pattern library

Showcase

Running tests

Docker

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

ds-pilot

ds-mcp

@dsk/mcp

systembridge-mcp

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)

Claude Code (`.claude/settings.json` in your project)

GitHub Copilot (`.vscode/mcp.json` in your workspace)

OpenCode (`opencode.json` in your project root, or `~/.config/opencode/opencode.json` globally)