Red Sift Design System — MCP Server

A Model Context Protocol (MCP) server that gives AI assistants deep knowledge of the Red Sift Design System. It provides tools for component search, prop documentation, code generation, design token lookup, and composition pattern guidance.

Looking for a generic HTTP retrieval API instead? See the sibling @redsift/ds-rag-server — same data, but exposed as a POST /retrieve HTTP endpoint with semantic + BM25 search. Built for chatbots, docs search boxes, and custom agentic pipelines (LangGraph, Vercel AI SDK). Use MCP for IDE coding agents; use RAG for everything else. Comparison.

Install from public npm

The published package is available on the public npm registry. No .npmrc configuration or authentication is required:

npx @redsift/ds-mcp-server

Or add it to an AI client's MCP configuration (e.g. VS Code, Claude Desktop) as a stdio server invoking npx @redsift/ds-mcp-server.

Internal alternative: GitHub Packages

The same versions are also published to GitHub Packages for internal consumers. To install from there, configure an .npmrc with the @redsift scope mapped to https://npm.pkg.github.com and authenticate with a GitHub Personal Access Token that has read:packages:

@redsift:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PAT}

Local development

# From the design-system repo root:
yarn mcp:build    # Build the server
yarn mcp:start    # Run (production)
yarn mcp:dev      # Run (development, no build needed)

The server uses stdio transport — it communicates over stdin/stdout and is designed to be launched by an AI client (VS Code, Claude Desktop, etc.), not run as a standalone HTTP server.

Architecture

scripts/extract-component-docs.ts
    ↓  yarn extract:docs
docs/components.json, components-index.json, patterns.json, patterns-catalog.md
    ↓  loaded at startup
DataStore, TokenStore, PatternStore
    ↓  queried by
Tools (10) + Resources (7) + Prompts (7)
    ↓  exposed via
MCP stdio transport → AI client

Data Flow

1. yarn extract:docs parses the component source files and generates machine-readable documentation in docs/.
2. At startup, the MCP server loads docs/components.json, docs/components-index.json, docs/patterns.json, and docs/patterns-catalog.md into in-memory stores.
3. AI clients call tools, read resources, and use prompts — all backed by the stores.

Important: If you add or change components, run yarn extract:docs to regenerate the data the MCP server sees.

Tools

| Tool | Description | Key Parameters | | ----------------------------- | ----------------------------------------------------- | -------------------------------------------------------- | | search_components | Search components by name, description, or keyword | query, package?, limit? | | get_component_props | Get full prop documentation grouped by category | name, package? | | get_component_usage | Get import statement and minimal JSX example | name, package? | | list_packages | List all packages with component counts | — | | generate_component_scaffold | Generate all 6 boilerplate files for a new component | name, package?, element?, description?, props? | | search_design_tokens | Search design tokens by name, value, or CSS variable | query, category?, limit? | | get_design_tokens | Get all tokens for a category | category | | get_css_variables | Find CSS custom properties by component or token type | pattern, limit? | | update_changelog | Generate a formatted CHANGELOG.md entry | type, package, description | | search_patterns | Search composition patterns for common UI scenarios | query, limit? |

Resources

| URI | Description | | --------------------------------------------- | --------------------------------------------------------------------------- | | design-system://llms.txt | Lightweight overview of all components for initial orientation | | design-system://llms-full.txt | Complete documentation for all 170+ components | | design-system://conventions | Component structure conventions, naming rules, coding patterns | | design-system://usage-rules | Mandatory lookup rules for consuming projects (prevents prop hallucination) | | design-system://components/{package}/{name} | Full JSON documentation for a specific component | | design-system://patterns-catalog | Markdown catalog of all composition patterns | | design-system://patterns/{slug} | Full pattern spec: anatomy, state hooks, data contracts, demo code |

Prompts

| Prompt | Description | Key Arguments | | ------------------ | --------------------------------------------------- | -------------------------------------------------------------------- | | create-component | Step-by-step guide to scaffold a new component | name, package?, element?, description? | | add-prop | Guide to add a prop across all component files | component, propName, propType, required?, defaultValue? | | build-form | Generate a form composition from field definitions | fields, submitLabel?, layout? | | pr-description | Generate a PR description from the repo template | title, changes, issueNumber?, packages? | | implement-ui | Build a UI from a description using proven patterns | description, target? | | create-pattern | Create a new pattern page for the website | name, description, components, relatedPatterns?, variants? | | add-demo | Create a demo file for the documentation website | patternSlug, variant, description |

Using in Other Projects

The MCP server runs locally from this repo and is available to any AI tool on your machine. It does not need to be installed in the consuming project.

VS Code (Copilot Chat) — Recommended

Add to the consuming project's .vscode/mcp.json:

{
  "servers": {
    "design-system": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/design-system/apps/mcp-server/dist/index.js"]
    }
  }
}

Tip: Run yarn mcp:build in this repo first. For a build-free setup, use tsx:

{
  "servers": {
    "design-system": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/design-system/apps/mcp-server/src/index.ts"]
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "design-system": {
      "command": "node",
      "args": ["/absolute/path/to/design-system/apps/mcp-server/dist/index.js"]
    }
  }
}

Any MCP-compatible Client

The server uses stdio transport. Point any MCP client at:

node /absolute/path/to/design-system/apps/mcp-server/dist/index.js

Forcing Correct Usage (Preventing Hallucination)

LLMs often guess component props based on other design systems (MUI, Chakra, etc.). To force them to look up the actual API, copy one of the instruction files from consumer-instructions/ into your project:

| File | Target | Where to place it | | --------------------------------------- | --------------- | --------------------------------------- | | redsift-design-system.instructions.md | VS Code Copilot | .github/instructions/ in your project | | CLAUDE.md | Claude Code | Project root | | .cursorrules | Cursor | Project root |

These files contain mandatory rules that tell the AI to call get_component_props before using any @redsift/* component.

Development

Source Files

| File | Purpose | | ---------------------- | --------------------------------------------------------- | | src/index.ts | Server entry point, store initialization, stdio transport | | src/tools.ts | All MCP tool registrations | | src/resources.ts | All MCP resource registrations | | src/prompts.ts | All MCP prompt registrations | | src/data-store.ts | Component data loading, search, and lookup | | src/token-store.ts | Design token loading and search | | src/pattern-store.ts | Pattern loading, search, and demo code extraction | | src/scaffold.ts | Component boilerplate generation | | src/types.ts | Shared TypeScript interfaces |

Adding a New Tool

1. Open src/tools.ts
2. Add a server.tool(...) call inside registerTools()
3. Follow the existing pattern: name, schema with z.object(...), description, handler
4. Rebuild: yarn mcp:build

Adding a New Resource

1. Open src/resources.ts
2. Add a server.resource(...) call inside registerResources()
3. For static resources, use a direct URI. For templates, use new ResourceTemplate(...)
4. Rebuild: yarn mcp:build

Adding a New Prompt

1. Open src/prompts.ts
2. Add a server.registerPrompt(...) call inside registerPrompts()
3. Define argsSchema with Zod and return { messages: [...] }
4. Rebuild: yarn mcp:build

Updating Data

When components are added, removed, or modified:

yarn extract:docs   # Regenerate docs/components.json, etc.
yarn mcp:build      # Rebuild the server

Testing

Use the MCP Inspector to test tools and resources interactively:

npx @modelcontextprotocol/inspector node apps/mcp-server/dist/index.js

Or verify in VS Code by opening Copilot Chat and asking:

• "Search for button components in the design system" → should call search_components
• "What props does DataGrid accept?" → should call get_component_props

Releasing

The MCP server is published to two registries. Both publishes are required to keep them in sync.

1. GitHub Packages (CI). Trigger .github/workflows/publish-mcp.yml via the Actions UI.

2. Public npm (manual). From a clean checkout of the merged release branch:

   npm whoami --registry=https://registry.npmjs.org   # confirm logged in
   cd apps/mcp-server
   npm pack --dry-run                                  # inspect tarball file list
   npm publish                                         # real publish

   prepublishOnly runs bundle-data and build automatically, so dist/ and data/ are guaranteed fresh. The files allowlist in package.json ensures only dist/, data/, and consumer-instructions/ are shipped.

After both publishes, verify with:

npm view @redsift/ds-mcp-server --registry=https://registry.npmjs.org
npm view @redsift/ds-mcp-server --registry=https://npm.pkg.github.com