zhtw-mcp

A linguistic linter for Traditional Chinese (zh-TW) that enforces Taiwan Ministry of Education (MoE) standards on vocabulary, punctuation, and character shapes. It plugs into AI coding assistants through the Model Context Protocol (MCP) and catches Mainland Chinese (zh-CN) regional drift before it reaches the user.

The tool enforces three official Taiwan standards:

• Revised Handbook of Punctuation (《重訂標點符號手冊》修訂版) -- punctuation marks
• Standard Form of National Characters (《國字標準字體》) -- character shapes
• Cross-strait vocabulary normalization, grounded in OpenCC's TWPhrases/TWVariants datasets -- word choices

Over 1100 vocabulary rules and 15 casing rules are compiled into the binary. For ambiguous terms, the server asks the AI assistant it runs inside for help deciding -- no extra API keys required.

Why this exists

Modern Chinese is an inadequately standardized language

In the late Qing dynasty, scholars had to express Western concepts in a writing system with no native vocabulary for them. Whether coining new words or importing translations via Japanese (和製漢語), they assembled a literary system under enormous time pressure. Many translated terms were inconsistent, ambiguous, or contradictory. The Chinese-speaking world has lived with these deficiencies for over a century.

Simplified Chinese made it worse

The PRC simplification effort reduced not just stroke counts but vocabulary precision. Terms that should vary by domain got flattened into single catch-all translations. Many PRC translations were coined hastily: if a term worked in one context, it spread uncritically to others.

AI models amplify the problem

AI language models learn from web text where Simplified Chinese vastly outweighs Traditional Chinese (roughly 2.6:1 in CC-100). Major datasets like CulturaX do not even track Traditional Chinese separately. A FAccT 2025 study confirmed that most models favor zh-CN terminology when asked to write zh-TW. The output looks plausible but is not how people in Taiwan actually write.

This goes beyond character conversion. The same word often means different things across the strait:

What this project does

Automatically check and correct zh-TW text produced by AI, catching cross-strait terminology leaks:

• Half-width punctuation (, . :) that should be full-width (， 。 ：)
• Mainland-style "" curly quotes replaced with Taiwan-style 「」 corner brackets
• Missing or extra CJK-Latin/digit spacing when the project's spacing policy requires it
• Mainland vocabulary -- 軟件→軟體, 內存→記憶體, 默認→預設, etc.
• Non-standard character variants -- 裏→裡, 着→著 per MoE standard forms in the strict profile; form preferences are advisory
• Politically colored terms -- 祖國, 內地
• Casing -- JavaScript, GitHub, macOS

These standards are enforced through two profiles on the strictness axis, plus orthogonal capability flags:

For unsupported authority attributions, select document_genre in MCP or --document-genre casual|technical|financial in the CLI. The check runs only with AI detection on (--detect-ai / detect_ai), and never suggests an edit in any genre: deleting an attribution changes what the sentence claims, so the genre selects the advice rather than a rewrite. Casual prose is told to name the source or drop the appeal; technical and financial prose are told the claim needs a citation.

Profiles control how strict the zh-TW norm enforcement is. Flags are orthogonal -- detect_ai works with either profile, relaxed can combine with strict if you want variant normalization but lenient punctuation.

spacing=require is the default because source text also appears outside CSS-capable renderers. Projects that control their HTML can select strip and use text-autospace, a Baseline newly-available property since November 2025. UTR #59 is a draft for layout-time autospacing, not a requirement to remove source-text spaces. Either way the policy governs the U+0020 space, and only where CJK meets an ASCII letter or an ASCII digit.

See docs/rules.md for the full rule reference.

Naming convention: cn and tw

This project follows BCP 47. The region subtag comes from ISO 3166-1 alpha-2, where "region" can denote a sovereign state, territory, or economic area -- not necessarily a "country."

• zh-CN: Chinese as written in the CN region (Simplified)
• zh-TW: Chinese as written in the TW region (Traditional)

Throughout the codebase, cn and tw denote regional writing conventions, not a political statement.

Getting started

Pre-built binaries

Every successful push to main refreshes the rolling latest release, which is what GitHub reports as the latest release. No version tag is involved. Each archive holds the binary, LICENSE, and README.md, and SHA256SUMS ships next to them.

On any other platform, use Nix below or build from source.

The browser extension is packaged onto the same release as zhtw-mcp-extension.zip. Unpack it and load it through chrome://extensions with developer mode on.

macOS / Linux

base=https://github.com/sysprog21/zhtw-mcp/releases/download/latest
case "$(uname -sm)" in
  "Darwin arm64")  asset=zhtw-mcp-aarch64-apple-darwin.tar.gz ;;
  "Linux x86_64")  asset=zhtw-mcp-x86_64-unknown-linux-gnu.tar.gz ;;
  "Linux aarch64") asset=zhtw-mcp-aarch64-unknown-linux-gnu.tar.gz ;;
  *) asset=""; echo "no pre-built binary for $(uname -sm)" >&2 ;;
esac
[ -n "$asset" ] &&
  curl -fsSLO "$base/$asset" -O "$base/SHA256SUMS" &&
  shasum -a 256 --ignore-missing -c SHA256SUMS &&
  tar -xzf "$asset" zhtw-mcp

On Linux without shasum, use sha256sum --ignore-missing -c SHA256SUMS instead.

Windows (PowerShell)

$base = "https://github.com/sysprog21/zhtw-mcp/releases/download/latest"
$asset = "zhtw-mcp-x86_64-pc-windows-msvc.tar.gz"
irm "$base/$asset" -OutFile $asset
irm "$base/SHA256SUMS" -OutFile SHA256SUMS
$want = ((Select-String -Path SHA256SUMS -SimpleMatch $asset).Line -split '\s+')[0]
if ((Get-FileHash -Algorithm SHA256 $asset).Hash -ine $want) { throw "checksum mismatch" }
tar -xzf $asset zhtw-mcp.exe

Both snippets leave the binary in the current directory; move it somewhere on your PATH to run it by name.

Nix

On any system with Nix and flakes enabled:

# builds and drops into a temporary shell with `zhtw-mcp` on `$PATH`
nix shell "github:sysprog21/zhtw-mcp"

# builds and runs zhtw-mcp (you can use this command to register with an MCP
# client as shown in the Installing section)
nix run "github:sysprog21/zhtw-mcp"

Note: The first run compiles the project from source, which can take several minutes. Subsequent runs reuse the Nix store cache and start instantly. To speed up the initial build, run nix build --cores 0 "github:sysprog21/zhtw-mcp" first. And --cores 0 tells Nix to use all available CPU cores.

Building from source

Requires stable Rust 1.91+.

make

The binary is at target/release/zhtw-mcp.

Python 3 is a build requirement, not just a test requirement: the OpenCC conversion tables are generated rather than committed.

Working on the code

make check           # the gate CI runs: tests, clippy, formatting, hooks
make indent          # run the formatters; the gate checks their result
make hooks           # install the git hooks; uninstall-hooks removes them
make corpus          # precision, recall and false-positive metrics

scripts/indent.sh holds the formatter chain: comment reflow with commentflow, then cargo fmt, black, shfmt, and the assets/ruleset.json normalization that scripts/check-ruleset.py owns. make indent runs