@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:

``bash
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

$3

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

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

$3

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

`bash


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):
`json
{
"movable-ui": {
"command": "node",
"args": ["/path/to/ui/mcp-server/dist/index.js"]
}
}
`

New configuration (recommended):
`json
{
"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:

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

$3

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

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

Local Development

If you're developing the MCP server itself:

`bash


Clone the repo

git clone git@github.com:movableink/ui.git
cd ui/mcp-server

Install dependencies

npm install

Extract data and build

npm run build

Run locally

npm start
`

$3

| 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 |

$3

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.

$3

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:

`bash


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.

$3

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)

$3

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