@vadenai/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ROUTE06, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,356 @@
+# @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
+
+```text
+Coding Agent ←→ MCP Server (stdio) ←→ Vaden API ←→ Design System
+```
+
+Using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), 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, etc.)                                         | `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
+
+```text
+# 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`
+
+```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)
+
+````text
+# 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.
+
+---
+
+## 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.
+
+**`get_component_list`** — Array of component summaries
+
+```json
+{
+  "components": [
+    {
+      "name": "button",
+      "title": "Button",
+      "description": "...",
+      "categories": ["form"]
+    },
+    {
+      "name": "card",
+      "title": "Card",
+      "description": "...",
+      "categories": ["layout"]
+    }
+  ]
+}
+```
+
+**`search_components`** — Keyword search (Japanese-to-English mapping supported)
+
+```text
+## 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
+
+```text
+# 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)
+
+```text
+# 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
+
+```text
+# 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
+
+```text
+# 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
+
+```bash
+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):
+
+```bash
+export VADEN_TOKEN="your-token-here"
+```
+
+Then configure MCP:
+
+```json
+{
+  "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:
+
+```bash
+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
+
+```bash
+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](./LICENSE)

package/dist/api-client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Vaden レジストリ API クライアント
+ *
+ * Bearer トークン認証で Vaden API にアクセスする。
+ * packages/vaden-sdk/src/api-client.ts を参考にした独立実装。
+ */
+export declare class VadenMcpApiClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly timeoutMs;
+    constructor(baseUrl: string, token: string);
+    private headers;
+    private buildUrl;
+    get<T>(path: string): Promise<T>;
+}

package/dist/api-client.js

@@ -0,0 +1,52 @@
+/**
+ * Vaden レジストリ API クライアント
+ *
+ * Bearer トークン認証で Vaden API にアクセスする。
+ * packages/vaden-sdk/src/api-client.ts を参考にした独立実装。
+ */
+export class VadenMcpApiClient {
+    baseUrl;
+    token;
+    timeoutMs = 30_000;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    headers() {
+        return {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.token}`,
+        };
+    }
+    buildUrl(path) {
+        const base = this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`;
+        const cleanPath = path.startsWith("/") ? path.slice(1) : path;
+        return new URL(cleanPath, base).toString();
+    }
+    async get(path) {
+        const url = this.buildUrl(path);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                headers: this.headers(),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                throw new Error(`API error (${response.status}): ${body}`);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new Error(`Request timeout after ${this.timeoutMs}ms: ${url}`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}

package/dist/guides/component-metadata.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 全コンポーネントの構造メタデータ
+ *
+ * ComponentStyleConfig から抽出した静的情報。
+ * MCP Server 側でコンポーネントガイドを生成するためのデータソース。
+ *
+ * - type: "single" (cva ベース) / "multipart" (slots ベース)
+ * - variants: バリアントキーとそのオプション
+ * - slots: multipart の構成パーツ
+ * - dependencies: Radix UI 等の実行時依存
+ * - a11y: アクセシビリティ上の注意事項
+ * - states: 対応する UI ステート
+ * - doNot: よくある誤用・禁止事項
+ */
+interface ComponentMetadata {
+    type: "single" | "multipart";
+    variants?: Record<string, string[]>;
+    slots?: string[];
+    dependencies?: string[];
+    a11y?: string[];
+    states?: string[];
+    doNot?: string[];
+}
+export declare const componentMetadata: Record<string, ComponentMetadata>;
+export {};