uxui-principles
# UX/UI Principles MCP server
Source of [`@uxuiprinciples/mcp-server`](https://www.npmjs.com/package/@uxuiprinciples/mcp-server): 195 research-backed UX/UI principles with their citations, 12 UX smells with fix recipes and 12 user-flow checklists, in English and Spanish, for Claude Code, Claude Desktop, Cursor, VS Code, Windsurf or any MCP client.
Install, tools, pro mode and troubleshooting: [packages/mcp-server/README.md](packages/mcp-server/README.md) or [uxuiprinciples.com/en/docs/mcp](https://uxuiprinciples.com/en/docs/mcp).
```bash
claude mcp add uxui-principles -- npx -y @uxuiprinciples/mcp-server
```
## About this repository
This is a read-only mirror. The code is developed in a private monorepo and pushed here by a workflow on every release tag, so pull requests cannot be merged; issues are welcome and get answered. The dataset in `packages/principles-data/src/generated/dataset.ts` is the same public catalogue (metadata, summaries, citations) that ships in the npm package; the full guides and the AI prompts stay in the [Principles Library](https://uxuiprinciples.com/en/developers).
## Run from source
```bash
npm install
npm run build
node packages/mcp-server/dist/index.js
```
`npm run smoke-test` packs the server, installs it in a temp project and drives both modes over stdio. The `Dockerfile` builds the same server for registry checks.
MIT, UX/UI Principles.
TDQS
Scored across 13 tools
Most tools target clearly distinct resources: principles (get/list/search), smells (get/list/detect), flows (get/list), and checklists/audit. The main overlap is between detect_smell, suggest_fix, and audit_interface, since suggest_fix internally detects a smell and audit_interface is described as a superset; descriptions do disambiguate them but an agent may still hesitate on which to call. get_flow_principles vs get_principle is also mildly confusable by name despite different purposes.
All 13 tools follow a consistent verb_noun snake_case pattern (get_, list_, search_, detect_, suggest_, generate_, audit_) with singular/plural nouns used logically for single-item vs collection operations. No mixing of conventions or casing styles.
13 tools is well within the 3-15 sweet spot and each maps to a distinct capability across principles, smells, flows, and auditing. Nothing appears redundant or padding the surface.
The surface covers the core lifecycle: browse/search/fetch principles, get prompts, browse/detect smells and get fixes, list/get flows, generate checklists, and audit an interface. Minor gaps exist — no way to enumerate the prompt library directly and no tool to list principle parts/tags as a standalone operation — but these are workable via list_principles and search_principles.