Trimble Modus MCP Server

A comprehensive Model Context Protocol (MCP) server for the Trimble Modus Design System. This server provides AI assistants with access to component documentation, design rules, setup guides, code generation, and validation tools.

🚀 What's New in v2.0.0

• Complete rewrite with enhanced architecture
• 13 powerful tools for documentation, code generation, and validation
• MCP resource support for direct documentation access via URIs
• Auto-updating documentation from official sources
• Lean code generation - focused code with proper layouts (no bloat)
• Smart layout patterns - dashboard, form, and page templates built-in
• Code validation against Modus design guidelines
• Tailwind CSS integration guidance

📚 Features

Documentation

• 44 component docs - Complete documentation for all Modus Web Components
• 6 design rule categories - Colors, spacing, typography, icons, breakpoints, radius/stroke
• 5 setup guides - React, HTML, testing, theming, universal rules

🛠️ Tools (13 total)

| Tool | Description | |------|-------------| | Component Tools | | | search_components | Search components by name, keyword, or category | | get_component_docs | Get complete documentation for a component | | list_all_components | List all components organized by category | | find_by_attribute | Find components with a specific attribute | | Design Rules Tools | | | get_design_rules | Get design rules for a category | | search_design_rules | Search across all design rules | | list_design_categories | List all design rule categories | | Setup Guide Tools | | | get_setup_guide | Get setup instructions for a framework | | get_theme_usage | Get theme implementation guide | | get_development_rules | Get universal development best practices | | setup_project | Generate complete project setup instructions | | Code Tools | | | generate_component | Generate lean code with proper layout (see workflow below) | | validate_code | Validate code against Modus guidelines |

📁 Resources (MCP Resource URIs)

| URI Pattern | Description | |-------------|-------------| | docs://components/{name} | Component documentation (44 components) | | docs://rules/{category} | Design rules (colors, spacing, typography, icons, breakpoints, radius_stroke) | | docs://setup/{type} | Setup guides (html, react, testing, theme, universal) |

📦 Installation

Option 1: NPM (Recommended)

npm install trimble-modus-mcp

Option 2: Local Development

# Clone the repository
git clone https://github.com/trimble-oss/modus-web-components.git
cd trimble-modus-mcp

# Install dependencies
npm install

# Download latest documentation
npm run update-docs

# Build
npm run build

⚙️ Configuration

Cursor IDE

Add to your Cursor MCP settings (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "trimble-modus": {
      "command": "npx",
      "args": ["trimble-modus-mcp"]
    }
  }
}

For local development:

{
  "mcpServers": {
    "trimble-modus": {
      "command": "node",
      "args": ["/path/to/trimble-modus-mcp/dist/index.js"]
    }
  }
}

Claude Desktop

Add to Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trimble-modus": {
      "command": "npx",
      "args": ["trimble-modus-mcp"]
    }
  }
}

🎨 Tailwind CSS Integration

Tailwind CSS can be used alongside Modus components for styling surrounding elements (containers, layouts, wrappers).

⚠️ Important

| ✅ CAN Style with Tailwind | ❌ CANNOT Modify with Tailwind | |---------------------------|-------------------------------| | Container backgrounds | Button internal colors | | Card wrappers/containers | Component internal styles | | Layout (flex, grid, spacing) | Component shadow DOM styles | | Margins/padding around components | Alert internal colors | | Text outside components | Badge internal styling |

Use component props (color, variant, size) to customize Modus components, not Tailwind classes.

Example

// ✅ CORRECT: Style containers with Tailwind
<div className="flex items-center gap-4 p-6 bg-gray-50 rounded-lg">
  <modus-button variant="filled" color="primary">Save</modus-button>
</div>

// ❌ WRONG: Tailwind can't override component internals
<modus-button className="bg-red-500">Button</modus-button>

📖 Usage Examples

Search for Components

User: Find components for building a form
AI: [Uses search_components with query "form"]

Get Component Documentation

User: How do I use the Modus button component?
AI: [Uses get_component_docs with component "button"]

Generate Code

User: Create a dashboard with cards and a data table
AI: [Uses generate_component with description "dashboard with cards and data table"]

Validate Code

User: Check if my code follows Modus guidelines
AI: [Uses validate_code with the provided code]

Project Setup

User: Set up Modus in my React project with Tailwind
AI: [Uses setup_project with framework "react", tailwind true]

Get Design Rules

User: What are the Modus color tokens?
AI: [Uses get_design_rules with category "colors"]

🔄 Recommended Workflow

The generate_component tool returns lean, focused code with proper layout structure. For complete development, combine with other tools:

1. generate_component  → Get ready-to-use code with layout
2. get_component_docs  → Full docs for specific components (if needed)
3. get_design_rules    → Design tokens and colors (if needed)
4. setup_project       → Project setup instructions (first time only)
5. validate_code       → Check code against guidelines

Why Lean Output?

| Benefit | Description | |---------|-------------| | Faster responses | No redundant setup/docs in every generation | | Focused code | Ready-to-use examples with proper layout | | Flexible workflow | Get additional info only when needed | | Smaller context | Less token usage, better AI performance |

Example Workflow

User: Create a dashboard with stats and a table

AI: [Uses generate_component] 
    → Returns focused React/Web code with layout shell

User: What props does the table support?

AI: [Uses get_component_docs for "table"]
    → Returns full table documentation

User: What are the color tokens?

AI: [Uses get_design_rules for "colors"]
    → Returns color reference

📂 Available Components (44)

| Category | Components | |----------|------------| | Form Controls | autocomplete, checkbox, date, number-input, radio, select, slider, switch, text-input, textarea, time-input | | Data Display | avatar, badge, card, chip, icon, progress, rating, skeleton, table, typography | | Feedback | alert, input-feedback, input-label, loader, modal, toast, tooltip | | Navigation | breadcrumbs, menu, menu-item, navbar, pagination, side-navigation, stepper, tabs | | Layout | accordion, collapse, divider, dropdown-menu, toolbar, utility-panel | | Actions | button | | Theming | theme-switcher |

📐 Design Rule Categories

| Category | Description | |----------|-------------| | colors | Semantic colors, color tokens, usage guidelines | | spacing | Spacing scale, margin/padding tokens | | typography | Font families, sizes, weights, line heights | | icons | Modus icons usage and guidelines | | breakpoints | Responsive breakpoints | | radius_stroke | Border radius and stroke tokens |

🔧 Development

# Install dependencies
npm install

# Download latest docs
npm run update-docs

# Build
npm run build

# Run in development mode
npm run dev

# Test the server
npm run test

📁 Project Structure

trimble-modus-mcp/
├── docs/                   # Component documentation (44 files)
│   ├── index.json          # Component index
│   ├── modus-wc-accordion.md
│   ├── modus-wc-alert.md
│   └── ... (44 components)
├── rules/                  # Design rules (6 files)
│   ├── breakpoints.md
│   ├── modus_colors.md
│   ├── modus_icons.md
│   ├── radius_stroke.md
│   ├── spacing.md
│   └── typography.md
├── setup/                  # Setup guides (5 files)
│   ├── setup_html.md
│   ├── setup_react.md
│   ├── testing.md
│   ├── theme_usage.md
│   └── universal_rules.md
├── src/
│   ├── index.ts            # Entry point
│   ├── server.ts           # MCP server implementation
│   ├── types/              # TypeScript types
│   ├── resources/          # Resource loaders
│   └── tools/              # Tool implementations
├── dist/                   # Compiled output
├── package.json
├── tsconfig.json
└── download-docs.js        # Documentation downloader

📊 Comparison with Other Implementations

| Feature | @julianoczkowski/mcp-modus | design-system-mcp | This Server (v2.0) | |---------|---------------------------|-------------------|------------------------| | Component docs | ✅ 43 | ✅ 43 | ✅ 44 | | Design rules | ✅ 6 categories | ❌ | ✅ 6 categories | | Setup guides | ✅ 5 guides | ✅ Limited | ✅ 5 complete guides | | Code generation | ❌ | ✅ | ✅ Enhanced | | Code validation | ❌ | ✅ | ✅ Enhanced | | MCP Resources | ❌ | ✅ | ✅ | | Auto-update docs | ✅ | ❌ | ✅ | | Tailwind integration | ❌ | ✅ | ✅ |

📋 Documentation Sources

This server downloads documentation from:

• Trimble Modus - Official Website
• Modus Web Components - Official repository

Updating Documentation

To update to the latest documentation:

npm run update-docs
npm run build

🔗 Links

• Modus Design System
• Modus Web Components Storybook
• Modus Web Components GitHub
• Modus Icons
• Modus Icons Browser

📄 License

MIT