Design System MCP Server

A Model Context Protocol (MCP) server for private design system repositories. This server enables AI assistants like C### NPM Package (Recommended)

For easier setup, you can use the published NPM package:

{
  "mcpServers": {
    "design-system": {
      "command": "npx",
      "args": ["-y", "design-system-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "token_here",
        "REPO_OWNER": "your-org",
        "REPO_NAME": "your-repo",
        "REPO_BRANCH": "main"
      }
    }
  }
}

All configuration via environment variables:

| Variable | Description | Default | |----------|-------------|---------| | GITHUB_PERSONAL_ACCESS_TOKEN | GitHub token (required) | - | | REPO_OWNER | GitHub org/username | your-org | | REPO_NAME | Repository name | your-repo | | REPO_BRANCH | Default branch | main | | COMPONENTS_PATH | Components directory | /packages/core | | STORIES_PATH | Storybook stories path | /packages/core | | DOCS_PATH | Documentation path | /packages/core | | TOKENS_PATH | Design tokens path | packages/design-tokens | | COMPONENT_EXTENSION | File extension | .ts | | STORY_SUFFIX | Story file suffix | .stories.ts |ode Copilot, Continue.dev, and Cursor to access your private design system components, documentation, and design tokens seamlessly.

🚀 Features

• Component Access: Get source code for any component in your design system
• Documentation Integration: Access component docs, Storybook stories, and examples
• Design Tokens: Fetch design tokens (colors, spacing, typography, etc.)
• Search Capabilities: Find components by name or description
• Private Repository Support: Full authentication for private GitHub repositories
• Flexible Configuration: Adapt to your specific repository structure

📦 Quick Start

1. Configure Your Repository

Update src/config.ts with your repository details:

export const CONFIG = {
  // Your repository details
  REPO_OWNER: 'your-company',           // Your GitHub org/username
  REPO_NAME: 'design-system',           // Your repository name
  REPO_BRANCH: 'main',                  // Default branch

  // Adjust paths to match your structure
  COMPONENTS_PATH: 'src/components',     // Where components live
  STORIES_PATH: 'src/stories',          // Storybook stories
  DOCS_PATH: 'docs/components',         // Component documentation
  TOKENS_PATH: 'src/tokens',            // Design tokens

  // File conventions
  NESTED_COMPONENTS: true,              // Button/Button.tsx vs Button.tsx
  COMPONENT_EXTENSION: '.tsx',          // File extension
  // ... more options
};

2. Set Up GitHub Authentication

For private repositories, you need a GitHub Personal Access Token:

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate a new token (classic)
3. Required scopes for private repos:
   • ✅ repo (Full control of private repositories)
   • ✅ read:org (if repository is in an organization)

3. Install Dependencies

npm install

4. Build and Run

# Development
npm run dev

# Production build
npm run build
npm start

# Or run directly
npx tsx src/index.ts --github-token ghp_your_token_here

📦 Publishing

Automated Release (Recommended)

Use the built-in release scripts that handle testing, versioning, and publishing:

# Patch release (1.0.0 → 1.0.1) - for bug fixes
npm run release:patch

# Minor release (1.0.0 → 1.1.0) - for new features
npm run release:minor

# Major release (1.0.0 → 2.0.0) - for breaking changes
npm run release:major

# Default patch release
npm run release

What the release script does:

1. ✅ Runs all tests
2. ✅ Builds the project
3. ✅ Bumps package.json version
4. ✅ Commits the version change
5. ✅ Creates a git tag
6. ✅ Publishes to npm
7. ✅ Pushes to git remote

Manual Publishing

If you prefer manual control:

# Test and build
npm run test
npm run build

# Manually bump version
npm run version:patch  # or version:minor, version:major

# Publish to npm
npm run publish:npm

# Or use the quick publish script (no version bump)
./publish.sh

🛠️ Available Tools

get-component

Get source code and files for a specific component.

{
  "componentName": "Button",
  "includeIndex": true,
  "includeTypes": true
}

list-components

List all available components in your design system.

{
  "includeMetadata": true
}

get-docs

Get documentation, stories, and examples for a component.

{
  "componentName": "Button",
  "includeStory": true,
  "includeExample": true
}

get-tokens

Access design tokens from your design system.

{
  "category": "colors",
  "format": "json"
}

search-components

Search for components by name.

{
  "query": "button",
  "includeContent": true,
  "maxResults": 5
}

get-repo-info

Get repository information and health status.

🔧 Editor Integration

VS Code with Continue

Add to your Continue configuration:

{
  "mcpServers": {
    "design-system": {
      "command": "npx",
      "args": ["tsx", "/path/to/your/server/src/index.ts"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

NPM Package (Recommended)

For easier setup, you can use the published NPM package:

{
  "mcpServers": {
    "design-system": {
      "command": "npx",
### Claude Desktop

Add to `~/.config/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "design-system": {
      "command": "node",
      "args": ["/path/to/your/server/dist/index.js", "--github-token", "ghp_your_token_here"]
    }
  }
}

Or using the NPM package:

{
  "mcpServers": {
    "design-system": {
      "command": "npx",
      "args": ["-y", "design-system-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "token_here",
        "REPO_OWNER": "your-org",
        "REPO_NAME": "your-repo",
        "REPO_BRANCH": "main"
      }
    }
  }
}

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "design-system": {
      "command": "node",
      "args": ["/path/to/your/server/dist/index.js", "--github-token", "ghp_your_token_here"]
    }
  }
}

Or using the NPM package:

{
  "mcpServers": {
    "design-system": {
      "command": "npx",
      "args": ["-y", "design-system-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "token_here"
      }
    }
  }
}

Cursor

Create .cursorrules in your project:

{
  "mcpServers": {
    "design-system": {
      "command": "npx",
      "args": ["tsx", "/path/to/server/src/index.ts"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Or using the NPM package:

{
  "mcpServers": {
    "design-system": {
      "command": "npx",
      "args": ["-y", "design-system-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "token_here",
        "REPO_OWNER": "your-org",
        "REPO_NAME": "your-repo",
        "REPO_BRANCH": "main"
      }
    }
  }
}

  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "token_here"
  }
}

} }

## 📁 Supported Repository Structures

The server is flexible and supports various component organization patterns:

### Nested Components (default)

src/components/ ├── Button/ │ ├── Button.tsx │ ├── Button.stories.tsx │ └── index.ts ├── Card/ │ ├── Card.tsx │ └── index.ts

### Flat Components

src/components/ ├── Button.tsx ├── Card.tsx ├── Modal.tsx

### Mixed Structure
Configure paths independently:
- Components: `packages/ui/src/components`
- Stories: `apps/storybook/stories`
- Docs: `docs/components`
- Tokens: `packages/tokens/src`

## 🔍 Customization

### Adding New Tools

1. Create a new tool in `src/tools/your-tool.ts`
2. Add it to `src/tools/index.ts`
3. Rebuild and test

### Custom File Extensions

Update `CONFIG.COMPONENT_EXTENSION` to support `.vue`, `.svelte`, etc.

### Different Token Formats

The server supports JSON, CSS, and SCSS token formats automatically.

## 🚨 Troubleshooting

### Authentication Issues
- Ensure your token has `repo` scope for private repositories
- Check that the token hasn't expired
- Verify the repository name and owner are correct

### Component Not Found
- Check the `COMPONENTS_PATH` in config.ts
- Verify the component naming convention matches `NESTED_COMPONENTS` setting
- Use `get-repo-info` tool to validate repository access

### Rate Limiting
- Private repositories have higher rate limits (5000/hour with token)
- The server includes intelligent caching to minimize API calls

## 📊 Monitoring

The server includes built-in monitoring:
- Request logging
- Cache hit/miss statistics
- Rate limit tracking
- Error reporting

Set `LOG_LEVEL=debug` for detailed logging.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details.

---

**Need help?** Open an issue or check the [troubleshooting guide](#-troubleshooting).