MCP server for @movable/ui component library - run via npx
npm install @movable/ui-mcpAn MCP (Model Context Protocol) server that exposes @movable/ui component information to AI assistants.
Run the MCP server directly without installation:
``bash`
npx @movable/ui-mcp
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.
| 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 |
`bash`
claude mcp add movable-ui -- npx -y @movable/ui-mcp
Then restart Claude Code and run /mcp to verify the server is connected.
If you previously configured the MCP server to run from a local clone:
`bashRemove the old local configuration
claude mcp remove movable-ui
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-serverInstall dependencies
npm installExtract data and build
npm run buildRun 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 metadataTesting
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-mcpList tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx @movable/ui-mcpCall 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.- GitHub Issue #501 - npx support implementation
- GitHub Issue #500 - Design tokens hex value resolution