# Design System MCP Server

An MCP (Model Context Protocol) server that exposes an airline-grade design system as a queryable knowledge base — enabling AI-assisted component discovery, use-case-driven scaffolding, and spec-driven prototype generation.

This project will encode deep domain knowledge — fare display, ancillary retailing, and booking flows — into an AI workflow that lets Claude reason about component selection the way an experienced engineer would.

---

## What This Is

Most design system tooling answers the question *"what does this component do?"*

This MCP server answers *"what component should I use for this problem?"*

Claude Desktop (or Claude Code) can invoke these tools mid-conversation to make informed, design-system-aware decisions when scaffolding prototypes — without digging through Storybook or asking a teammate.

---

## Architecture

```
Claude Desktop / Claude Code  ←— orchestration layer
        ↓
Design System MCP Server      ←— this repo (tool layer)
        ↓
components.json               ←— structured component knowledge base
```

The MCP server runs locally via stdio. Claude decides when to call a tool based on context — the developer never has to invoke tools manually.

---

## Tools

### `get_component`
Returns full component spec by exact name — variants, props, accessibility guidance, usage notes, and related components.

```
Input:  { name: "FareCard" }
Output: variants, props, a11y guidance, usage, related components
```

### `find_component_for_use_case`
Semantic search — describe what you need in plain English and get the most relevant components ranked by relevance.

```
Input:  { description: "show ancillary upsell offers after fare selection" }
Output: AncillaryOfferCard, AncillaryOfferGroup, AncillaryCartSummary
```

### `list_components_by_category`
Browse the component library by category. Returns name, category, and description for each match.

```
Input:  { category: "Booking forms" }
Output: PassengerForm, BookingFormStepper, PriceBreakdown
```

---

## Component Coverage

The knowledge base covers three core categories of the airline passenger journey:

**Fare display & selection**
- `FareCard` — single fare option with price, cabin class, and conditions
- `FareGrid` — responsive fare family comparison grid

**Ancillary offers**
- `AncillaryOfferCard` — individual ancillary product (bag, seat, upgrade, insurance)
- `AncillaryOfferGroup` — grouped ancillary offers with expand/collapse
- `AncillaryCartSummary` — persistent selected ancillaries and running total

**Booking forms**
- `PassengerForm` — passenger details capture (adult, child, infant variants)
- `BookingFormStepper` — multi-step booking flow navigation
- `PriceBreakdown` — itemised fare, tax, fee, and ancillary cost summary

---

## Setup

**Prerequisites:** Node.js v18+, Claude Desktop

```bash
git clone https://github.com/yourusername/design-system-mcp
cd design-system-mcp
npm install
npm run build
```

Add to your `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "design-system-mcp": {
      "command": "/path/to/node",
      "args": ["/path/to/design-system-mcp/build/index.js"]
    }
  }
}
```

Restart Claude Desktop. The server will appear under Settings → Developer.

---

## Example Usage

**In Claude Desktop or Claude Code:**

> *"I need to build a fare selection screen for an NDC booking flow. What components should I use?"*

Claude will call `find_component_for_use_case`, get back `FareGrid` and `FareCard`, then call `get_component` on each to retrieve their full specs — and use that context to scaffold a React prototype using the correct components, props, and accessibility patterns.

---

## Roadmap

This server is Phase 2 of a larger pipeline:

- **Phase 3a** — Spec-to-Figma generator: take a service blueprint and generate an editable Figma layout (spec-first path)
- **Phase 3b** — Figma MCP tool: read a Figma frame and map its components to this design system (design-first path)
- **Phase 4** — Full pipeline: service blueprint → structured spec → Figma → MCP tools → React prototype, orchestrated by Claude Code

---

## Background

This project grew out of 6 years building and governing Spark — Sabre's enterprise design system across airline and hospitality products. The goal is to encode that domain expertise into an AI workflow that lets prototypes scale in complexity without losing design system fidelity.

The broader thesis: AI-assisted engineering is about encoding deep domain knowledge into workflows that make the right decisions automatically.

---

## Tech Stack

- TypeScript
- `@modelcontextprotocol/sdk`
- `zod`
- Node.js v20