uxui-principles

@uxuiprinciples/mcp-server

UX/UI Principles 的 MCP 服务：提供 195 条有研究依据的原则及其引文、12 种 UX 反模式及修复方案，以及 12 份用户流程检查清单，支持在 Claude Code、Claude Desktop、Cursor、VS Code、Windsurf 或任何 MCP 客户端中使用英语和西班牙语。

默认免费且离线运行：数据集随软件包一起发布，服务不会发起网络请求。添加 Principles Library API 密钥即可启用 专业模式，通过 uxuiprinciples.com API 获取完整指南正文、AI 提示词和界面审查功能。

什么是 MCP？

Model Context Protocol（MCP） 是一种开放协议，可让 AI 助手调用外部工具。此服务通过 stdio 使用 MCP，并注册 13 个工具。

安装

需要 Node.js 18 或更高版本。首次运行时，npx -y 会获取最新版本。

Claude Code

claude mcp add uxui-principles -- npx -y @uxuiprinciples/mcp-server

添加 --scope user，即可在每个项目中使用。运行 claude mcp list 确认。

Claude Desktop

将配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），然后重启 Claude Desktop：

{
  "mcpServers": {
    "uxui-principles": {
      "command": "npx",
      "args": ["-y", "@uxuiprinciples/mcp-server"]
    }
  }
}

Cursor

将配置添加到项目中的 .cursor/mcp.json（或添加到 ~/.cursor/mcp.json，以便在每个项目中使用），然后在 Cursor 设置的 MCP 中启用此服务：

{
  "mcpServers": {
    "uxui-principles": {
      "command": "npx",
      "args": ["-y", "@uxuiprinciples/mcp-server"]
    }
  }
}

VS Code

将配置添加到工作区中的 .vscode/mcp.json，然后从 MCP 面板启动此服务，或让 Copilot Agent 模式启动它：

{
  "servers": {
    "uxui-principles": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@uxuiprinciples/mcp-server"]
    }
  }
}

Windsurf

将配置添加到 ~/.codeium/windsurf/mcp_config.json，然后在 Cascade 中刷新 MCP 列表：

{
  "mcpServers": {
    "uxui-principles": {
      "command": "npx",
      "args": ["-y", "@uxuiprinciples/mcp-server"]
    }
  }
}

全局安装

npm install -g @uxuiprinciples/mcp-server
uxui-mcp

让客户端指向 uxui-mcp 二进制文件，而不是 npx。重新运行安装命令以获取新版本。

专业模式（Principles Library 密钥）

Principles Library（每年 59 美元）提供 REST API 密钥。将密钥作为 UXUI_API_KEY 环境变量传递给服务，即可改变以下四个工具的行为：

工具	免费模式	专业模式
get_principle	元数据、摘要、引文、链接	除上述内容外，还在 content 中提供完整指南正文
get_principle_prompts	指向指南的链接	此原则的 AI 提示词
audit_interface	提示需要密钥并拒绝执行	映射到原则和反模式的问题、评分及优先修复项
check_requirements	提示需要密钥并拒绝执行	按每条必需状态规则给出通过或失败结果，并附上对应原则及引文

其他所有功能仍可离线运行。如果 API 无法访问，get_principle 和 get_principle_prompts 会退回免费模式的答复，并在 proError 中报告失败；audit_interface 和 check_requirements 则会返回错误代码。

{
  "mcpServers": {
    "uxui-principles": {
      "command": "npx",
      "args": ["-y", "@uxuiprinciples/mcp-server"],
      "env": { "UXUI_API_KEY": "uxui_live_..." }
    }
  }
}

对于 Claude Code：claude mcp add uxui-principles -e UXUI_API_KEY=uxui_live_... -- npx -y @uxuiprinciples/mcp-server。密钥仅读取自环境，绝不会写入日志。可在 uxuiprinciples.com/account 获取或轮换密钥。服务在 stderr 输出的启动行会显示 pro mode 或 free mode，传递给客户端的 instructions 也会说明这一点。

可用工具

原则

工具	描述
get_principle	按 slug 获取一条原则：摘要、引文（作者、标题、年份、url）及完整指南链接。专业模式：完整指南正文
search_principles	按查询词、部分、难度或标签搜索
list_principles	列出所有原则，或按部分筛选
get_principle_prompts	获取某条原则的 AI 提示词。专业模式：提示词文本；免费模式：指南链接

反模式

工具	描述
get_smell	获取一种反模式及其症状和修复方案
list_smells	列出所有反模式，可按类别筛选
detect_smell	根据英语或西班牙语撰写的 UI 描述检测反模式
suggest_fix	获取 UX 问题的修复建议

流程（用户旅程）

工具	描述
get_flow	获取包含前置／后置检查清单的流程
list_flows	列出所有可用流程
generate_checklist	为流程阶段生成检查清单
get_flow_principles	获取流程的关键原则

Pro

工具	描述
audit_interface	审核描述的屏幕（20 至 5,000 个字符）：提供带严重性、修复建议和业务影响的发现、评分、界面类型、优势以及三项优先修复措施。需要 UXUI_API_KEY
check_requirements	根据八项必需状态规则，检查以数据形式提供的屏幕（流程、组件、带有 consequential 和 automated 标记的操作、已实现状态）：重要操作前的确认、错误、空状态和加载状态、撤销或编辑、AI 输出的来源、AI 错误后的恢复、自动化前的同意。每条规则均提供通过、失败或不适用的结果，以及原则及其引文，并附带 Markdown 摘要。需要 UXUI_API_KEY

使用示例

You: What principle should I follow for form design?

Claude: Let me search for form-related principles...
[Calls search_principles with query="form"]

Based on the UX/UI Principles database, here are the key principles for form design:
1. Progressive Disclosure (D.1.1.01) - Show only essential fields initially
2. Inline Validation - Validate as users type
3. Smart Defaults - Pre-fill common choices
...

You: My login form has a 60% abandonment rate. Help me fix it.

Claude: Let me detect potential UX issues...
[Calls detect_smell with description="login form high abandonment"]

I detected "Form Graveyard" smell with high confidence. Let me get the fix recipe...
[Calls get_smell with id="form-graveyard"]

Here's my analysis and recommendations:
1. Reduce fields to email + password only
2. Add social login options
3. Use inline validation
...

Let me also get the flow checklist for the form...
[Calls generate_checklist with flow_id="forms" phase="postflight"]

使用密钥：

You: Audit this checkout: three steps, no order summary until the last one, the Pay button is disabled with no explanation until every field validates.

Claude: [Calls audit_interface with the description]
Score 58, fair. Two warnings: Visibility of System Status (order summary hidden) and Silent Errors (disabled button without feedback). Priority fix: ...

构建屏幕后：

You: Build the settings page: profile form, an AI summary of recent activity, and a danger zone with "Delete account". Then check it.

Claude: [Builds the page, then calls check_requirements with flow "settings", the components, the actions (Delete account flagged consequential) and the states it implemented]
3 of 6 applicable rules fail: undo-or-edit (User Control and Freedom, Nielsen 1994), show-sources (AI Source Citations, Liu et al. 2023), ai-error-recovery (Efficient AI Correction, Amershi et al. 2019). Adding an undo toast, a sources line under the summary and a regenerate control...

双语支持

所有工具都接受 locale: "en" | "es"。无论 locale 为何，detect_smell 和 suggest_fix 都能理解以任一语言撰写的描述：

search_principles({ query: "navegación", locale: "es" })
detect_smell({ description: "el formulario es demasiado largo", locale: "es" })

包含的数据

• 195 条原则，分为 6 个部分；get_principle 可返回 500 多条参考文献（指南完整引用了 2,400 多条学术引文）
• 12 种 UX 气味及其修复方案
• 12 条用户流程及其检查清单
• 双语（英语 + 西班牙语）

本地开发

git clone https://github.com/joselhurtado/uxuiprinciples-web.git
cd uxuiprinciples-web
npm install
npm run build --workspace=@uxuiprinciples/principles-data
npm run build --workspace=@uxuiprinciples/mcp-server
node packages/mcp-server/dist/index.js

npm run smoke-test --workspace=@uxuiprinciples/mcp-server 会打包构建产物，在临时项目中安装，并通过标准输入／输出测试两种模式（Pro 模式使用本地模拟 API）。此 README 旁的 server.json 是 MCP Registry 清单；npm 发布后，使用 mcp-publisher publish 进行发布。

许可证

MIT © UX/UI Principles

链接

• uxuiprinciples.com - 完整原则库
• 网站上的 MCP 文档
• REST API - 通过 HTTPS 提供相同的数据
• MCP 文档 - 了解 MCP