@vadenai/mcp-server

An MCP Server that provides your Vaden design system to MCP-compatible coding agents such as Claude Code, Cursor, and Windsurf.

Overview

Coding Agent ←→ MCP Server (stdio) ←→ Vaden API ←→ Design System

Using the Model Context Protocol (MCP), this server provides coding agents with design tokens, CSS variables, component specs, wireframes (screen layouts and navigation flows), and concepts (brand personality and design philosophy) from your Vaden project. Agents can generate code that adheres to your design system instead of hardcoding values.

Problem

Coding agents don't know about your project-specific design system. They tend to generate hardcoded values like bg-blue-500 or implementations that deviate from your design system.

This MCP Server solves this by providing design context that agents can reference during implementation.

| Problem | Without MCP | With MCP | | ------------------- | ------------------------------------------------ | ------------------------------------------------------------------ | | Token deviation | Hardcoded colors and magic numbers | Generates using CSS variables + usage guide | | Component misuse | Implements from generic shadcn/ui docs only | References project-specific variants, Do/Don'ts, a11y requirements | | Inconsistent output | Different implementations per developer/prompt | Same spec = convergent design decisions | | Lost design intent | "Why this design?" is lost during implementation | Token usage guide carries intent alongside values |

Tools

| Tool | Description | Arguments | | ---------------------- | ------------------------------------------------------------------------------------------------ | --------------------------- | | get_design_tokens | Returns design tokens (colors, fonts, spacing, radius, etc.) | none | | get_theme_css | Returns CSS variables (:root, .dark, @theme) | none | | get_component_list | Returns a list of available components | none | | get_component_spec | Returns the spec for a component (props, variants, CVA classes, resolved colors) | component: component name | | search_components | Searches components by keyword (Japanese supported) | query: search query | | get_wireframes | Returns wireframe screen list and navigation flows | none | | get_wireframe_detail | Returns screen details (components, states, behaviors) | screen_id: screen ID | | get_concept | Returns concept info (brand personality, mood, visual style, target users, design principles) | none | | get_design_rationale | Returns design philosophy, decision rationale, UX principles, color strategy, typography choices | none |

Example Output

get_design_tokens — Usage guide + raw JSON

# Design Token Usage Guide

## Colors
- `primary`: Brand color. Use for primary buttons, links, and key interactive elements.
- `secondary`: Supporting color. Use for secondary actions.
...

## Raw Design Tokens (JSON)
{ "colors": { "light": { ... }, "dark": { ... } }, "fontFamily": { ... }, ... }

get_theme_css — Drop-in CSS for theme.css

:root {
  --color-primary-9: #4f46e5;
  --radius: 0.5rem;
  --spacing: 0.25rem;
  ...
}
.dark { ... }
@theme { --color-background: var(--background); ... }

get_component_spec — Human-readable guide + registry spec (JSON)

# Button — Component Usage Guide

> Displays a button or a component that looks like a button.

**Category**: form

## Structure
Single element component (cva-based) with variants.

## Variants
- `variant`: default | destructive | outline | secondary | ghost | link
- `size`: default | sm | lg | icon

## Dependencies
- `@radix-ui/react-slot`

## Accessibility
- Use <button> for actions, <a> for navigation (use asChild with Link)
- Always provide accessible label: visible text or aria-label for icon buttons
- Disabled buttons must use disabled attribute, not aria-disabled

## States
Supported: hover, focus-visible, active, disabled

## Do NOT
- Do not use color props — use variant instead
- Do not hardcode border-radius — it comes from design tokens
- Do not nest interactive elements inside a button
- Do not use ghost/link variant for primary actions

## Important Rules
- Always use design token CSS variables — never hardcode colors or spacing.
- Follow the variant system — do not create ad-hoc style overrides.

---

## Style Config (botanical-organic)

**Type**: single

**Base Styles**:
`inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-full text-sm font-medium ...`

**variant**:
- default: `bg-primary text-primary-foreground shadow-sm hover:bg-primary/90 hover:shadow`
- destructive: `bg-destructive text-destructive-foreground hover:bg-destructive/90`
- outline: `border border-primary/50 bg-transparent text-primary hover:bg-primary/5`
- secondary: `bg-secondary text-secondary-foreground hover:bg-secondary/80`
- ghost: `text-primary hover:bg-accent`
- link: `text-primary underline-offset-4 hover:underline`

**Resolved Colors** (preferred appearance):
- primary: bg=#7C3AED, fg=#FFFFFF
- secondary: bg=#F472B6, fg=#1E293B
- destructive: #EF4444

---

## Registry Spec (JSON)
```json
{
  "name": "button",
  "title": "Button",
  "description": "Displays a button or a component that looks like a button.",
  "categories": ["form"],
  "registryDependencies": [],
  "dependencies": ["@radix-ui/react-slot"],
  "files": [{ "path": "ui/button.tsx", "type": "registry:ui" }],
  "cssVars": { "light": {}, "dark": {} }
}

Components with registered metadata return both a guide and registry JSON. Components without metadata return registry JSON only. When the project has a generated design system, a Style Config section with CVA class definitions and resolved color values is included between the guide and registry spec.

get_component_list — Array of component summaries

{
  "components": [
    {
      "name": "button",
      "title": "Button",
      "description": "...",
      "categories": ["form"]
    },
    {
      "name": "card",
      "title": "Card",
      "description": "...",
      "categories": ["layout"]
    }
  ]
}

search_components — Keyword search (Japanese-to-English mapping supported)

## Search Results for "ボタン"

| Component | Title | Categories | Score |
|-----------|-------|------------|-------|
| `button` | Button | form | 100 |
| `button-group` | Button Group | form | 80 |
...

Use `get_component_spec` with a component name for full details.

get_wireframes — Screen list + navigation flow + raw JSON

# Wireframe Overview

Total screens: 22

## Screen Map
| ID | Name | Purpose | Group | Journey Stage | Components |
...

## Screen Groups
### auth
- `login` — **Login**: User login
...

## Navigation Flow
Login --[submit] "Login successful"--> Dashboard
...

## Raw Wireframe (JSON)
{ "screens": [...], "transitions": [...], "metadata": { ... } }

get_wireframe_detail — Screen details (component layout, UI states, behaviors)

# Screen: Dashboard

**ID**: `dashboard`
**Purpose**: Display project overview on the dashboard
**Group**: authenticated

## Components
| ID | Type | Label | DataKey | Position (x,y) | Size (w×h) |
...

## UI States
### Initial State
- **Condition**: Data not yet loaded
- **Display**: Loading indicator

## Behaviors
| Action | Result | On Error |
...

## Related Screens
- `settings` — **Settings**: Settings page

## Raw Screen (JSON)
{ "id": "dashboard", "components": [...], ... }

get_concept — Brand personality, visual style, target audience, design principles

# Concept: GreenHarvest

## Brand Identity
- **Project**: GreenHarvest
- **Service**: Organic food e-commerce
- **Domain**: Food & E-commerce
- **Brand Personality**: Natural, warm, and trustworthy

## Visual Direction
- **Aesthetic**: Natural & Organic
- **Mood**: Warmth & Trust
- **Era**: Modern
- **Inspiration**: A farm at dawn

## Target Audience
- **Demographics**: Ages 30-50, health-conscious urban residents
- **Psychographics**: High concern for food safety
- **Pain Points**: Difficulty finding trustworthy organic food
- **Aspirations**: Providing safe meals for their family

## Design Principles
- Visuals that evoke natural materials
- Simple and intuitive navigation
...

## Raw Concept (JSON)
{ "projectName": "GreenHarvest", "brandPersonality": "...", ... }

get_design_rationale — Design philosophy, color strategy, typography rationale, UX principles

# Design Rationale

## Philosophy
A design that emphasizes harmony with nature and gives users a sense of security.

## Interface Approach
Minimal and intuitive. Clean layouts that maximize product appeal.

## Color Strategy
- **Base**: Earth tones (warm beige and brown)
- **Accent**: Fresh green (#4CAF50)
- **Accent Meaning**: Symbolizes nature, freshness, and organic quality

## Typography
- **Choice**: Noto Sans JP
- **Rationale**: High readability without compromising the natural aesthetic

## UX Principles
- Highlight product origin and producer information
- Complete purchase flow in 3 steps or fewer
...

## Raw Design Analysis (JSON)
{ "philosophy": "...", "colorStrategyBase": "...", ... }

Setup

Prerequisites

| Requirement | Description | | --------------- | --------------------------------------------- | | Node.js | 18.18 or later | | Vaden Dashboard | A project created (design system is optional) | | Registry Token | Issued from Dashboard > Settings > Tokens |

1. Install

npm install -g @vadenai/mcp-server

2. Issue a Token

Go to your Vaden Dashboard > Settings > Tokens. Set a label and expiration, then copy the token shown after creation. Store tokens securely and never commit them to version control.

3. Configure MCP

Claude Code (.claude/mcp.json)

Set the token as an environment variable (recommended for security):

export VADEN_TOKEN="your-token-here"

Then configure MCP:

{
  "mcpServers": {
    "vaden": {
      "command": "vaden-mcp-server",
      "args": ["--project-id", "your-project-id"]
    }
  }
}

The server reads VADEN_TOKEN from the environment automatically. You can also pass it via --token, but environment variables are preferred to avoid leaking secrets in config files.

Cursor (Settings > MCP Servers)

Add the same command and args to Cursor's MCP settings.

Environment Variables

All options can be set via environment variables:

export VADEN_PROJECT_ID="your-project-id"
export VADEN_TOKEN="your-token-here"
export VADEN_API_URL="https://app.vaden.ai"  # default if omitted

CLI Options

vaden-mcp-server [options]

| Option | Environment Variable | Required | Description | | ------------------- | -------------------- | ------------ | ---------------------------------------------- | | --project-id <id> | VADEN_PROJECT_ID | Yes (either) | Vaden project ID | | --token <jwt> | VADEN_TOKEN | Yes (either) | Registry Token (JWT) | | --api-url <url> | VADEN_API_URL | No | API endpoint (default: https://app.vaden.ai) |

Note: "Yes (either)" means the value must be provided via the CLI argument or the environment variable — either one satisfies the requirement.

Security

• Never commit tokens to Git — If you hardcode tokens in .claude/mcp.json or similar config files, add them to .gitignore
• Prefer environment variables — VADEN_TOKEN is the safest way to configure your token
• Principle of least privilege — Use read + design-system scope when read-write + project is not needed
• Rotate tokens regularly — Issue new tokens from the Dashboard (Settings > Tokens) and revoke old ones
• If a token leaks — Revoke it immediately from the Dashboard

License

MIT