ds MCP

Design System UX MCP Server

A Model Context Protocol (MCP) server for Design System UX components and utilities. This server provides resources and tools for working with design system components, enabling AI assistants and other MCP clients to interact with design system functionality.

Features

• 🚀 MCP Server - Full Model Context Protocol implementation
• 📦 Resource Management - Dynamic resource templates for extensible functionality
• 🔌 HTTP Transport - Express-based HTTP server for MCP communication
• 🎨 Design System Integration - Ready for Next.js design system component integration
• 🎨 Figma Integration - Tools to interact with Figma files via REST API
• 📝 TypeScript - Fully typed with TypeScript
• ⚙️ Configurable - Environment-based configuration support

Installation

# Clone the repository
git clone https://github.com/kettilvo/ds-mcp.git
cd ds-mcp

# Install dependencies
npm install

Usage

Development Mode

Start the server in development mode with hot reload:

npm run start:dev

Production Mode

Build and start the production server:

# Build the project
npm run build

npm run extract-dscomponents

*Run data ingestion:**

npm run ingest
# Start the server
npm start

MCP Inspector

Use the MCP inspector to test and debug the server:

npm run start:mcp

The server will be available at http://localhost:3000/mcp by default.

Project Structure

ds-mcp/
├── src/
│   ├── index.ts          # Entry point
│   └── server.ts         # MCP server implementation
├── config/               # Configuration files
│   ├── common-config-properties
│   ├── local-common-config-properties
│   ├── prod-common-config-properties
│   └── qa-common-config-properties
├── dist/                 # Build output (generated)
├── package.json
├── tsconfig.json
└── tsconfig.build.json

Available Resources

Addition Resource

A simple addition tool that adds two numbers.

URI Pattern: add://{a}/{b}

Example:

add://5/3

Response:

{
  "result": 8
}

Greeting Resource

A dynamic greeting generator.

URI Pattern: greeting://{name}

Example:

greeting://World

Response:

Hello, World!

Available Tools

Figma Tools

The server includes four Figma tools for interacting with Figma files:

1. figma_get_file - Retrieve a complete Figma file by file ID
2. figma_get_file_info - Get parsed information about a Figma file
3. figma_get_nodes - Retrieve specific nodes from a Figma file
4. figma_get_images - Get image URLs for exporting design assets

Setup:

1. Get a Figma Personal Access Token from Figma Account Settings
2. Set the FIGMA_ACCESS_TOKEN environment variable:

   export FIGMA_ACCESS_TOKEN="your-token-here"

For detailed documentation, see FIGMA_INTEGRATION.md.

Scripts

Configuration

The server can be configured using environment variables:

• PORT - Server port (default: 3000)

Configuration files are available in the config/ directory for different environments:

• local-common-config-properties - Local development
• qa-common-config-properties - QA environment
• prod-common-config-properties - Production environment

API Endpoint

The MCP server exposes a single HTTP endpoint:

POST /mcp

Handles MCP protocol requests.

Request Body:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "add://5/3"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "contents": [
      {
        "uri": "add://5/3",
        "text": "{\"result\":8}"
      }
    ]
  }
}

Development

Adding New Resources

To add a new resource, use the server.registerResource() method in src/server.ts:

server.registerResource(
  'resource-name',
  new ResourceTemplate('resource://{param}', { list: undefined }),
  {
    title: 'Resource Title',
    description: 'Resource description'
  },
  async (uri, { param }) => ({
    contents: [
      {
        uri: uri.href,
        text: `Resource content for ${param}`
      }
    ]
  })
);

Type Checking

Run TypeScript type checking:

npm run check

Code Formatting

Format code using Prettier:

npm run format

Dependencies

Core Dependencies

• @modelcontextprotocol/sdk - MCP SDK for server implementation
• express - Web framework for HTTP transport
• zod - Schema validation

Development Dependencies

• typescript - TypeScript compiler
• ts-node-dev - Development server with hot reload
• prettier - Code formatter
• eslint - Linter

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Kettil Oeunpuu

• Email: kettil.wko@gmail.com
• GitHub: @kettilvo

Related Projects

This MCP server is designed to work with design system components. For the Next.js design system components, see the related Next.js project.

Support

For issues and questions, please open an issue on .