japan-ux-mcp: Instructions file for Codex

AGENTS.md — japan-ux-mcp

Guide for AI coding agents (Claude Code, Cursor, Codex, Copilot…) working in this repo.

What this project is

Japan Design — an MCP server that enforces Japanese UI (typography, colour, layout) and UX (forms, keigo, trust, seasonal) conventions on real CSS/markup, so AI generates culturally correct Japanese interfaces instead of Western defaults.

• npm: japan-ux-mcp · registry name: io.github.mrslbt/japan-ux
• Local stdio server, read-only, deterministic, bundled data only — no API keys, no network.
• Flagship tool: review_jp_ui — the front-end correctness enforcer (scores any UI against the Japanese standard with JLReq/JIS citations + fixes).

Quick commands

npm install        # deps
npm run build      # tsc → dist/   (must pass before commit)
npm test           # build + node --test test/*.test.mjs   (must pass before commit)
npm run smoke      # build + a live MCP round-trip (lists tools, calls review_jp_ui)
npm run dev        # tsc --watch

Pre-commit: npm run build && npm test. Both must pass. 18 tests today.

Architecture (the whole mental model)

src/
├── index.ts            # McpServer — registers every tool/prompt/resource + server instructions
├── meta.ts             # READONLY annotation + withTitles() param-title helper
├── tools/
│   ├── review-jp-ui.ts # FLAGSHIP — composes typography + colour + font-payload checks
│   ├── check-jp-typography.ts, audit-japan-ux.ts, transform-for-japan.ts, … (one file per tool)
└── data/               # bundled, offline rule data (typography-rules, visual-rules, keigo, seasonal, …)
test/                   # integration + regression (.test.mjs) and smoke.mjs

11 tools · 10 prompts · 9 resources. The SDK is @modelcontextprotocol/sdk (1.29+), zod 4.

How to add or change a tool

Every tool is registered in index.ts with annotations + parameter titles. Use this exact shape — do not drop withTitles or READONLY:

import { READONLY, withTitles } from "./meta.js";

server.tool(
  "your_tool_name",                                   // snake_case, verb-first
  "Verb-first description, ≤2 sentences, names the next tool to call.",
  withTitles({
    some_field: z.string().describe("English description with a concrete example."),
  }),
  READONLY,                                           // every tool is read-only + deterministic
  async (params) => {
    const result = yourToolFn({ ...params });
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }
);