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:

English	zh-CN	zh-TW	Why it matters
concurrency	並發	並行	In zh-CN, 並行 means "parallel" -- a different concept entirely
parallel	並行	平行	zh-CN 並行 = "parallel"; in Taiwan, 並行 = "concurrent"
process (OS)	進程	行程	進程 in Taiwan means "progress," not an OS process
file / document	文件 / 文檔	檔案 / 文件	文件 in China = "file"; in Taiwan = "document"
render	渲染	算繪	渲染 in Taiwan = "exaggerate" (a painting technique)
traverse	遍歷	走訪	遍歷 in Taiwan is reserved for Ergodic theory (遍歷理論)

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:

Profile	Purpose
base	Cross-strait vocabulary, punctuation, casing, grammar, politically colored terms
strict	Full MoE enforcement: character variants (裏→裡), grammar (臺/台), all punctuation

Flag	Purpose
relaxed	Relaxed for software UI: disables colon/dunhao enforcement and grammar checks; uses en-dash for ranges
detect_ai	AI writing review: filler phrase detection, semantic safety words, copula/passive voice checks, density-based pattern detection
spacing	CJK boundary policy, --spacing require|strip: require stores spaces (default); strip leaves the gap to a controlled HTML renderer. The one flag here that takes a value, and a different thing from --off spacing, which turns the whole family off

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.

Platform	Asset
Linux x86_64 (glibc 2.39 or newer)	zhtw-mcp-x86_64-unknown-linux-gnu.tar.gz
Linux arm64 (glibc 2.39 or newer)	zhtw-mcp-aarch64-unknown-linux-gnu.tar.gz
macOS arm64	zhtw-mcp-aarch64-apple-darwin.tar.gz
Windows x86_64	zhtw-mcp-x86_64-pc-windows-msvc.tar.gz

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 it with --write and the gate runs it with --check, against a copy of the tree so a check never rewrites what it is judging. The chain runs to a fixed point, since reindenting a block can invalidate the wrap of a comment inside it.

No formatter here is passed a style flag. shfmt takes its settings from .editorconfig and commentflow takes its column limit from .clang-format, which exists only for that number: comments wrap at 80 while rustfmt allows code 100.

Every lane reports that it skipped rather than failing when its tool is missing, which is why a green local run is weaker evidence than a green CI run. CI installs commentflow, shfmt and shellcheck on the Linux leg and sets ZHTW_REQUIRE_TOOLS=1 there, which turns a skip into a failure.

Any cargo build installs the git hooks, through build.rs, and make hooks does it on its own. A configured core.hooksPath is left untouched, since it may be shared by unrelated repositories. The pre-commit hook runs rustfmt, black, shellcheck, shfmt, commentflow and the ruleset checks over a checkout of the index, so an unstaged edit neither fails a commit nor rides along in one. The commit-msg hook holds the subject to 50 columns and the body to 72, imperative and free of em dashes, counting a CJK character as the two columns a terminal spends on it. The pre-push hook replays those rules over commits a rebase or an amend rewrote, and CI runs the same script over a pull request's own commits, so the rules bind a contributor who never installed the hooks as well.

scripts/check-comments.sh holds source comments to the two prose rules no formatter knows about: no em dash, and no backtick outside a /// or //! doc comment, where backticks are rustdoc markup rather than prose. It runs in the gate and in the pre-commit hook.

scripts/test-git-hooks.sh drives all four hooks against a scratch repository and runs in the gate, so a hook that stops rejecting fails there rather than on somebody's next commit.

Installing

The quickest way to build, install to $XDG_BIN_HOME (or ~/.local/bin), stop older server processes, and register with detected MCP clients (Claude Code and/or Codex):

make install      # build release, install binary, register detected MCP clients
make uninstall    # remove binary and detected MCP registrations
make status       # check binary freshness, process, and registration state

For manual setup or other MCP clients:

# Claude Code
claude mcp add zhtw-mcp -- /path/to/zhtw-mcp

# Codex CLI
codex mcp add zhtw -- /path/to/zhtw-mcp

# OpenCode
opencode mcp add zhtw-mcp /path/to/zhtw-mcp

Other MCP clients may use .mcp.json in your project root:

{
  "mcpServers": {
    "zhtw-mcp": {
      "command": "/path/to/zhtw-mcp",
      "args": []
    }
  }
}

Replace /path/to/zhtw-mcp with the actual binary path (e.g., target/release/zhtw-mcp).

CLI quick start

zhtw-mcp lint README.md                 # lint a file
zhtw-mcp lint file.md --fix             # auto-fix in place
zhtw-mcp lint file.md --fix --dry-run   # preview fixes
zhtw-mcp lint file.md --telemetry       # print stderr summary counters
zhtw-mcp cache clear                    # clear persistent judgment cache

See docs/cli.md for the full CLI reference and docs/mcp.md for MCP tool/resource/prompt details.

Common prompts

When running as an MCP server, you interact through natural language. The assistant translates your intent into zhtw tool calls:

Intent	Say	Maps to	What happens
Lint text	"Check this paragraph for mainland terms"	zhtw({ "text": "..." })	Returns issues with line/column, suggestions, and rule type
Auto-fix	"Fix the zh-TW issues in this document"	zhtw({ "text": "...", "fix_mode": "lexical_safe" })	Deterministic fixes applied; corrected text returned
Quality gate	"Reject if more than 3 zh-TW errors"	zhtw({ "text": "...", "max_errors": 3 })	accepted: true/false verdict based on error count
Strict MoE	"Check this with strict MoE rules"	zhtw({ "text": "...", "profile": "strict" })	Adds character variant (裏→裡) and full punctuation enforcement
UI strings	"Lint this UI string, skip grammar"	zhtw({ "text": "...", "relaxed": true })	Disables colon/dunhao/grammar enforcement; uses en-dash for ranges
AI writing review	"Review this for AI writing artifacts"	zhtw({ "text": "...", "detect_ai": true })	Flags filler phrases, semantic safety words, copula/passive overuse
Markdown-aware	"Lint this markdown, skip code blocks"	zhtw({ "text": "...", "content_type": "markdown" })	Fenced code, inline code, and HTML blocks excluded from scanning
Cost telemetry	"Lint this and include telemetry"	zhtw({ "text": "...", "include_telemetry": true })	Returns estimated token/caching metrics for the call

Each zhtw call is stateless -- parameters like profile are per-call, not session state. Omitting profile defaults to base.

The server also exposes two read-only resources for assistants to consult: zh-tw://style-guide/moe (MoE standards) and zh-tw://dictionary/ambiguous (cross-strait term disambiguation). See docs/mcp.md for the full prompt catalog.

Further reading

• docs/cli.md -- full CLI reference, config files, CI/CD integration, S2T conversion
• docs/mcp.md -- MCP tool parameters, resources, prompts, sampling, usage examples
• docs/internals.md -- processing pipeline, script detection, design decisions, testing
• docs/rules.md -- rule type reference, extending the ruleset, runtime overrides

License

zhtw-mcp is available under a permissive MIT-style license. Use of this source code is governed by a MIT license that can be found in the LICENSE file.