japan-ux-mcp

# japan-ux-mcp

[![npm version](https://img.shields.io/npm/v/japan-ux-mcp.svg)](https://www.npmjs.com/package/japan-ux-mcp)
[![npm downloads](https://img.shields.io/npm/dm/japan-ux-mcp.svg)](https://www.npmjs.com/package/japan-ux-mcp)
[![MCP Badge](https://lobehub.com/badge/mcp-full/mrslbt-japan-ux-mcp?theme=light)](https://lobehub.com/mcp/mrslbt-japan-ux-mcp)
[![japan-ux-mcp MCP server](https://glama.ai/mcp/servers/mrslbt/japan-ux-mcp/badges/card.svg)](https://glama.ai/mcp/servers/mrslbt/japan-ux-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Japan Design — UI + UX correctness for AI coding agents.** A front-end *enforcer*: point it at real CSS/markup and it scores your UI against the Japanese standard — typography (kinsoku, line-height, fonts), colour symbolism, font performance — with **W3C JLReq / JIS X 4051 citations** and fixes. Plus the full UX layer: forms (姓名/furigana), keigo, trust signals, legal, and seasonal design.

Lead tool: **`review_jp_ui`** — the front-end correctness enforcer (run it on any UI, including Western-built, before shipping to Japan).

Eleven tools, ten prompts, nine resources. Runs locally, no API keys. Findings are labelled **spec** (JLReq/JIS) vs **convention** (documented JP web practice) so authority is never overstated.

## Install

```bash
claude mcp add japan-ux -- npx -y japan-ux-mcp
```

### JSON config

The server config is the same across clients; only the file path differs.

<details>
<summary>Claude Code — <code>~/.claude/.mcp.json</code></summary>

```json
{
  "mcpServers": {
    "japan-ux": { "command": "npx", "args": ["-y", "japan-ux-mcp"] }
  }
}
```

</details>

<details>
<summary>Cursor — <code>~/.cursor/mcp.json</code></summary>

```json
{
  "mcpServers": {
    "japan-ux": { "command": "npx", "args": ["-y", "japan-ux-mcp"] }
  }
}
```

</details>

<details>
<summary>Windsurf — <code>~/.codeium/windsurf/mcp_config.json</code></summary>

```json
{
  "mcpServers": {
    "japan-ux": { "command": "npx", "args": ["-y", "japan-ux-mcp"] }
  }
}
```

</details>

<details>
<summary>VS Code (GitHub Copilot) — <code>.vscode/mcp.json</code></summary>

```json
{
  "servers": {
    "japan-ux": { "type": "stdio", "command": "npx", "args": ["-y", "japan-ux-mcp"] }
  }
}
```

</details>

<details>
<summary>Cline (VS Code extension)</summary>

Open Cline's MCP settings panel and add:

```json
{
  "mcpServers": {
    "japan-ux": { "command": "npx", "args": ["-y", "japan-ux-mcp"] }
  }
}
```

</details>

<details>
<summary>Claude Desktop — <code>claude_desktop_config.json</code></summary>

```json
{
  "mcpServers": {
    "japan-ux": { "command": "npx", "args": ["-y", "japan-ux-mcp"] }
  }
}
```

Config path:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

</details>

<details>
<summary>Zed — <code>~/.config/zed/settings.json</code></summary>

```json
{
  "context_servers": {
    "japan-ux": { "command": { "path": "npx", "args": ["-y", "japan-ux-mcp"] } }
  }
}
```

</details>

### From source

```bash
git clone https://github.com/mrslbt/japan-ux-mcp.git
cd japan-ux-mcp
npm install && npm run build
```

Point the client config at the built entry:

```json
{ "command": "node", "args": ["/absolute/path/to/japan-ux-mcp/dist/index.js"] }
```

## Tools

| Tool | Description |
|---|---|
| `review_jp_ui` | **Flagship enforcer** — scores CSS/markup against the Japanese UI standard (typography, colour, font payload) with JLReq/JIS citations and fixes. |
| `generate_jp_form` | Outputs Japanese form markup: 姓/名 order, furigana, 〒 postal auto-fill, 3-field phone, 年月日 dates. |
| `validate_jp_form` | Scores a form against JP conventions (0-100) with issues, severity, and code fixes. |
| `generate_jp_placeholder` | Returns test data: names in kanji/katakana/romaji, real postal codes, formatted phone numbers, era dates. |
| `suggest_keigo_level` | Converts English UI text to Japanese at the appropriate politeness level for a given business context. |
| `score_japan_readiness` | Rates a page across five categories: forms, copy, trust signals, typography, cultural fit. |
| `transform_for_japan` | Rewrites Western markup into Japan-ready markup with a before/after score and per-change explanations. |
| `check_jp_typography` | Audits CSS for Japanese typography: font stacks, line-height, kinsoku shori, sizing, palt. |
| `get_seasonal_context` | Returns the current season, active events, 24 microseasons (二十四節気), and launch blackout windows. |
| `audit_japan_ux` | Seven-category audit (layout, typography, visual, navigation, trust, content, mobile) with a letter grade. |
| `design_direction_for_japan` | Produces a Japan-specific design brief from brand type, audience, and industry. |

## Prompts

| Prompt | Description |
|---|---|
| `japan_form` | Walks through building a Japanese form. |
| `japan_audit` | Audits pasted markup for JP UX issues. |
| `japan_transform` | Transforms Western markup with before/after scoring. |
| `japan_testdata` | Generates Japanese test data for prototypes. |
| `japan_keigo` | Returns UI text at the appropriate politeness level. |
| `japan_score` | Scores a page description for Japan-readiness. |
| `japan_typography` | Checks CSS for Japanese typography issues. |
| `japan_seasonal` | Returns seasonal design context for a specific month. |
| `japan_full_audit` | Runs a full seven-category Japanese UX audit. |
| `japan_design_direction` | Generates a Japan-specific visual direction. |

## Resources

| Resource | Content |
|---|---|
| `keigo-guide` | Four politeness levels across eight business contexts, 30+ UI copy patterns. |
| `form-checklist` | Japanese form conventions for pre-ship review. |
| `phone-formats` | Mobile, landline, toll-free, IP phone patterns with field-split rules. |
| `era-calendar` | 令和 through 明治 with date ranges and conversion formulas. |
| `typography-guide` | Font stacks, type scale, line-height, kinsoku shori, CSS suggestions. |
| `seasonal-calendar` | 24 events, 24 microseasons, seasonal palettes, launch blackout dates. |
| `trust-checklist` | Trust signals, legal pages, and social proof by site type. |
| `color-guide` | Japanese color meanings, the red-name taboo, visual design rules. |
| `layout-guide` | Grid, spacing, density, responsive breakpoints, structural patterns. |

## Example prompts

```
Build a registration form for a Japanese B2B SaaS product. Include name,
email, phone, company, and address. Use TSX with Tailwind.
```

```
Audit this form for Japanese conventions:
<form>
  <input name="firstName" placeholder="First Name" />
  <input name="lastName" placeholder="Last Name" />
  <input name="email" />
  <input name="phone" />
  <button>Submit</button>
</form>
```

```
Transform this form for the Japanese market (fintech context):
<form>
  <label>First Name <input name="firstName" /></label>
  <label>Last Name <input name="lastName" /></label>
  <label>Phone <input name="phone" /></label>
  <label>Address <input name="address" /></label>
  <button type="submit">Submit</button>
</form>
```

```
I need Japanese UI copy for a banking app:
- Error: "Invalid email address"
- Button: "Submit application"
- Empty state: "No transactions yet"
- Confirmation: "Are you sure you want to delete?"
```

```
Check this CSS for Japanese typography issues:
body { font-family: Arial; font-size: 14px; line-height: 1.4; font-style: italic; }
```

```
Run a Japanese UX audit on this B2B SaaS landing page. Hero with English
tagline, feature grid, pricing table, no phone number in header, no
company info page, single-column layout.
```

## Bundled data

All data ships with the package. No external APIs, no keys, no network calls.

| Data | Count | Details |
|---|---|---|
| Prefectures | 47 | Code, name, kana, romaji, region |
| Names | 100 | 50 surnames + 50 given names in kanji/kana/romaji |
| Addresses | 12 | Real postal codes across major cities |
| Phone formats | 6 | Mobile, landline, toll-free, IP, Navi Dial |
| Eras | 5 | 令和 through 明治 with start/end dates |
| Keigo patterns | 30 | UI strings at 4 politeness levels across 9 element types |
| Width rules | 6 | Full-width/half-width validation per field type |
| Layout rules | 28 | Grid, spacing, density, responsive, structural patterns |
| Typography rules | 24 | Font stacks, sizing, line-height, wrapping, rendering |
| Font stacks | 7 | System, web, serif, mixed modern/elegant/rounded/corporate |
| Visual rules | 21 | Color meanings, imagery, icons, shadows, corners |
| Navigation rules | 16 | Header, footer, menu, search, breadcrumb, pagination |
| Trust signals | 20 | Company info, social proof, certifications, contact |
| Legal requirements | 10 | 特定商取引法, APPI, 景品表示法, 薬機法, and more |
| Seasonal events | 25 | Full year with design impact and business notes |
| Microseasons | 24 | 二十四節気 with approximate dates |
| Color meanings | 9 | Japanese-specific color associations with hex values |
| Platform patterns | 30+ | LINE, QR codes, mobile payments, IME handling, social sharing |
| Accessibility rules | 20+ | JIS X 8341-3, aging population, screen readers, furigana |
| Content patterns | 15+ | Density, copy, product pages, localization rules |

## Conventions covered

### Forms and input

| Convention | Practice |
|---|---|
| Name order | Family name (姓) first, given name (名) second |
| Furigana | Katakana reading fields (セイ/メイ) below each name input |
| Phone | Three separate fields. Pattern: XXX-XXXX-XXXX |
| Address | 〒 postal code auto-fills prefecture + city. Large-to-small order |
| Dates | Separate 年/月/日 inputs with optional era display (令和6年 = 2024) |
| Character width | Auto-convert full-width digits and symbols to half-width on input |
| Confirmation | 確認画面 review screen before final submission |

### Typography

| Convention | Practice |
|---|---|
| No italics | Japanese has no italic form. Use bold, color, or size for emphasis |
| Line-height 1.8+ | Kanji density re