@movable/ui-mcp

An MCP (Model Context Protocol) server that exposes @movable/ui component information to AI assistants.

Quick Start

Run the MCP server directly without installation:

npx @movable/ui-mcp

Overview

This server allows AI coding assistants like Claude Code, Cursor, and others to discover and understand the components available in @movable/ui without manually searching through source files.

Available Tools

| Tool | Description | |------|-------------| | list_components | Lists all exported components from @movable/ui | | get_component | Gets detailed info for a specific component (props, JSDoc) | | get_theme | Gets theme configuration (palette, typography, component overrides) | | get_design_tokens | Gets design tokens by category with resolved hex values | | get_component_example | Gets code examples from Storybook stories | | search_components | Searches components by keyword or category | | get_eslint_rules | Gets available ESLint rules from @movable/ui/eslint-plugin |

Configuration

Claude Code

claude mcp add movable-ui -- npx -y @movable/ui-mcp

Then restart Claude Code and run /mcp to verify the server is connected.

Migrating from Local Installation

If you previously configured the MCP server to run from a local clone:

# Remove the old local configuration
claude mcp remove movable-ui

# Add the new npx-based configuration
claude mcp add movable-ui -- npx -y @movable/ui-mcp

Old configuration (no longer needed):

{
  "movable-ui": {
    "command": "node",
    "args": ["/path/to/ui/mcp-server/dist/index.js"]
  }
}

New configuration (recommended):

{
  "movable-ui": {
    "command": "npx",
    "args": ["-y", "@movable/ui-mcp@latest"]
  }
}

Benefits of the npx approach:

• No need to clone the repository
• Always uses the latest published version
• Works on any machine without setup

Auto-approve MCP Tools

By default, Claude Code will ask for permission each time an MCP tool is used. To auto-approve all movable-ui tools, add to your ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__movable-ui__*"
    ]
  }
}

VS Code / Cursor

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "movable-ui": {
      "command": "npx",
      "args": ["-y", "@movable/ui-mcp"]
    }
  }
}

Local Development

If you're developing the MCP server itself:

# Clone the repo
git clone [email protected]:movableink/ui.git
cd ui/mcp-server

# Install dependencies
npm install

# Extract data and build
npm run build

# Run locally
npm start

Development Scripts

| Script | Description | |--------|-------------| | npm run extract-data | Extract component/token data from source files | | npm run build | Extract data and compile TypeScript | | npm run dev | Watch mode for TypeScript compilation | | npm start | Run the compiled server |

How It Works

The MCP server operates in two modes:

1. npx mode (bundled data): When installed via npx, the server uses pre-extracted JSON data files bundled with the package. This allows it to run anywhere without access to the source repo.

2. Local development mode: When running from a cloned repo, the server can read directly from source files for the most up-to-date information.

Data Extraction

The extract-data script parses the UI source files and generates:

• data/components.json - Component metadata and props
• data/tokens.json - Design tokens with resolved hex values
• data/theme.json - Theme configuration
• data/stories.json - Storybook story metadata
• data/categories.json - Component categories
• data/eslint-rules.json - ESLint rule metadata

Testing

Test the server manually using JSON-RPC over stdin:

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | npx @movable/ui-mcp

# List tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx @movable/ui-mcp

# Call a tool
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_design_tokens","arguments":{"category":"blue"}}}' | npx @movable/ui-mcp

Publishing

The package is published to npm as @movable/ui-mcp via GitHub Actions.

Automatic Publishing

The MCP server is automatically published when changes are pushed to main in:

• mcp-server/src/**/*.ts - MCP server source
• mcp-server/scripts/**/*.ts - Data extraction scripts
• src/components/**/* - UI components (affects extracted data)
• src/theme/**/*.ts - Theme definitions (affects extracted data)
• stories/**/*.stories.tsx - Storybook stories (affects extracted data)
• eslint-plugin-ui/src/rules/**/*.ts - ESLint rules (affects extracted data)

Manual Publishing

To manually trigger a release:

1. Go to Actions > Release MCP Server to NPM
2. Click "Run workflow"
3. Select release type (release or prerelease)
4. Optionally override the version increment

Note: Do not publish manually via npm publish. Always use the GitHub Action to ensure consistent releases.

Related

• GitHub Issue #501 - npx support implementation
• GitHub Issue #500 - Design tokens hex value resolution