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 Settings の MCP でサーバーを有効にします。

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

VS Code

ワークスペース内の .vscode/mcp.json に追加し、MCP パネルからサーバーを起動するか、Copilot エージェントモードに起動させます。

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

npx の代わりに uxui-mcp バイナリをクライアントに指定します。新しいバージョンを取得するには、インストールを再実行してください。

プロモード（Principles Library キー）

Principles Library（年額59ドル）には REST API キーが含まれています。キーを UXUI_API_KEY 環境変数としてサーバーに渡すと、4つのツールの動作が変わります。

ツール	無料モード	プロモード
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	スラッグで原則を1つ取得します。概要、引用（著者、タイトル、年、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文字）を監査します。重大度、改善策、ビジネスへの影響を含む指摘事項、スコア、インターフェースの種類、強み、優先度の高い修正項目3つを提示します。UXUI_API_KEY が必要です
check_requirements	データとして提供された画面（フロー、コンポーネント、consequential および automated フラグ付きのアクション、実装済みの状態）を、8つの必須状態ルールに照らして確認します。ルールは、重大な結果を伴うアクションの前の確認、エラー、空、読み込み状態、取り消しまたは編集、AI 出力のソース、AI エラー後の復旧、自動化の前の同意です。各ルールについて、原則とその引用とともに pass、fail、not_applicable のいずれかを返し、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" を受け付けます。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 はビルドをパッケージ化し、一時プロジェクトにインストールして、stdio 経由で両方のモードを実行します（Pro モードでは API のローカルな模擬実装を使用）。この README と同じディレクトリにある server.json は MCP Registry マニフェストです。npm リリース後に mcp-publisher publish で公開してください。

ライセンス

MIT © UX/UI Principles

リンク

• uxuiprinciples.com - 原則ライブラリの全体版
• サイトの MCP ドキュメント
• REST API - 同じデータを HTTPS 経由で利用できます
• MCP ドキュメント - MCP について学ぶ