zhtw-mcp-linguistic-linter

# zhtw-mcp-linguistic-linter > Skill by [ara.so](https://ara.so) — MCP Skills collection. A linguistic linter for Traditional Chinese (zh-TW) that enforces Taiwan Ministry of Education (MoE) standards on vocabulary, punctuation, and character shapes. It runs as an MCP server inside AI coding assistants and catches Mainland Chinese (zh-CN) regional drift before it reaches the user. ## What It Does **zhtw-mcp** enforces three official Taiwan standards: 1. **Punctuation**: Taiwan-style `「」` corner brackets instead of `""` curly quotes, full-width punctuation (`，` `。` `：`) 2. **Character shapes**: MoE standard forms (裏→裡, 着→著) 3. **Vocabulary**: Cross-strait normalization (軟件→軟體, 內存→記憶體, 默認→預設) The tool includes 1100+ vocabulary rules and 15 casing rules. For ambiguous terms, it uses the AI assistant itself to help decide context. ### Key Use Cases - Lint Traditional Chinese documentation - Auto-fix cross-strait terminology drift - Enforce Taiwan MoE standards in CI/CD - Review AI-generated Chinese text for regional correctness - Quality gates for zh-TW content ## Installation ### Pre-built Binaries **macOS / Linux:** ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/sysprog21/zhtw-mcp/releases/latest/download/zhtw-mcp-installer.sh | sh ``` **Windows (PowerShell):** ```powershell powershell -ExecutionPolicy Bypass -c "irm https://github.com/sysprog21/zhtw-mcp/releases/latest/download/zhtw-mcp-installer.ps1 | iex" ``` ### Building from Source Requires Rust 1.91+: ```bash git clone https://github.com/sysprog21/zhtw-mcp.git cd zhtw-mcp make # Binary at target/release/zhtw-mcp ``` ### Quick Install with Make ```bash make install # build, install to ~/.local/bin, register with detected MCP clients make uninstall # remove binary and MCP registrations make status # check installation state ``` ### MCP Client Registration **Claude Code:** ```bash claude mcp add zhtw-mcp -- /path/to/zhtw-mcp ``` **Codex CLI:** ```bash codex mcp add zhtw -- /path/to/zhtw-mcp ``` **OpenCode:** ```bash opencode mcp add zhtw-mcp /path/to/zhtw-mcp ``` **Generic (`.mcp.json` in project root):** ```json { "mcpServers": { "zhtw-mcp": { "command": "/home/user/.local/bin/zhtw-mcp", "args": [] } } } ``` ## CLI Usage ### Basic Commands ```bash # Lint a file zhtw-mcp lint README.md # Auto-fix in place zhtw-mcp lint file.md --fix # Preview fixes without modifying zhtw-mcp lint file.md --fix --dry-run # Show telemetry summary zhtw-mcp lint file.md --telemetry # Clear judgment cache zhtw-mcp cache clear ``` ### Advanced CLI Options ```bash # Use strict MoE profile zhtw-mcp lint doc.md --profile strict # Relaxed mode for UI strings zhtw-mcp lint ui.md --relaxed # Detect AI writing artifacts zhtw-mcp lint article.md --detect-ai # Specify content type zhtw-mcp lint notes.txt --content-type markdown # Set max errors for quality gate zhtw-mcp lint doc.md --max-errors 5 # Convert Simplified to Traditional (S2T) zhtw-mcp s2t input.md -o output.md ``` ### Configuration File Create `.zhtw.toml` in your project root: ```toml # Profile: "base" or "strict" profile = "base" # Flags relaxed = false detect_ai = false # Fix mode: "lexical_safe" or "none" fix_mode = "lexical_safe" # Max errors for quality gate (0 = unlimited) max_errors = 0 # Content type: "auto", "plain", "markdown" content_type = "auto" ``` ## MCP Tool API When running as an MCP server, the AI assistant calls the `zhtw` tool with JSON parameters. ### Tool: `zhtw` **Parameters:** ```typescript { text: string; // Required: text to lint profile?: "base" | "strict"; // Default: "base" relaxed?: boolean; // Default: false detect_ai?: boolean; // Default: false fix_mode?: "lexical_safe" | "none"; // Default: "none" max_errors?: number; // Default: 0 (unlimited) content_type?: "auto" | "plain" | "markdown"; // Default: "auto" include_telemetry?: boolean; // Default: false } ``` **Response:** ```typescript { accepted: boolean; // Quality gate verdict issues: Array<{ line: number; column: number; message: string; suggestion?: string; rule_type: string; }>; corrected_text?: string; // Only if fix_mode != "none" telemetry?: { input_tokens: number; output_tokens?: number; cache_creation_tokens?: number; cache_read_tokens?: number; // ... }; } ``` ## Common Patterns ### 1. Basic Linting **User says:** "Check this paragraph for mainland terms" **Assistant calls:** ```json { "name": "zhtw", "arguments": { "text": "這個軟件的默認設置存儲在內存中。" } } ``` **Response:** ```json { "accepted": false, "issues": [ { "line": 1, "column": 3, "message": "Mainland term: '軟件' → '軟體'", "suggestion": "軟體", "rule_type": "vocabulary" }, { "line": 1, "column": 6, "message": "Mainland term: '默認' → '預設'", "suggestion": "預設", "rule_type": "vocabulary" }, { "line": 1, "column": 12, "message": "Mainland term: '內存' → '記憶體'", "suggestion": "記憶體", "rule_type": "vocabulary" } ] } ``` ### 2. Auto-fix Text **User says:** "Fix the zh-TW issues in this document" **Assistant calls:** ```json { "name": "zhtw", "arguments": { "text": "這是一個測試文件,包含錯誤的標點.", "fix_mode": "lexical_safe" } } ``` **Response:** ```json { "accepted": true, "issues": [], "corrected_text": "這是一個測試文件，包含錯誤的標點。" } ``` ### 3. Strict MoE Enforcement **User says:** "Check this with strict MoE rules" **Assistant calls:** ```json { "name": "zhtw", "arguments": { "text": "這裏有一些内容需要檢查。", "profile": "strict" } } ``` **Response includes character variant issues:** ```json { "accepted": false, "issues": [ { "line": 1, "column": 2, "message": "Non-standard character variant: '裏' → '裡'", "suggestion": "裡", "rule_type": "variant" }, { "line": 1, "column": 7, "message": "Simplified character: '内' → '內'", "suggestion": "內", "rule_type": "variant" } ] } ``` ### 4. UI String Linting (Relaxed Mode) **User says:** "Lint this UI string, skip grammar" **Assistant calls:** ```json { "name": "zhtw", "arguments": { "text": "設定範圍: 1-100", "relaxed": true } } ``` Relaxed mode: - Disables colon/dunhao enforcement - Uses en-dash for ranges - Skips grammar checks ### 5. AI Writing Review **User says:** "Review this for AI writing artifacts" **Assistant calls:** ```json { "name": "zhtw", "arguments": { "text": "首先，我們需要注意的是，在這個過程中，重要的是要確保系統的安全性。", "detect_ai": true } } ``` Detects: - Filler phrases (首先, 在這個過程中) - Semantic safety words (需要注意的是, 重要的是) - Excessive copula/passive voice - Density-based patterns ### 6. Markdown-Aware Linting **User says:** "Lint this markdown, skip code blocks" **Assistant calls:** ```json { "name": "zhtw", "arguments": { "text": "這是說明文件.\n\n```rust\nlet code = \"不檢查\";\n```\n\n更多內容,這裏。", "content_type": "markdown" } } ``` Excludes from scanning: - Fenced code blocks - Inline code spans - HTML blocks - YAML frontmatter ### 7. Quality Gate with Error Threshold **User says:** "Reject if more than 3 zh-TW errors" **Assistant calls:** ```json { "name": "zhtw", "arguments": { "text": "文檔內容...", "max_errors": 3 } } ``` **Response:** ```json { "accepted": false, "issues": [ // 4+ issues listed ] } ``` ### 8. Telemetry for Cost Tracking **User says:** "Lint this and include telemetry" **Assistant calls:** ```json { "name": "zhtw", "arguments": { "text": "長文檔內容...", "include_telemetry": true } } ``` **Response includes:** ```json { "accepted": true, "issues": [], "telemetry": { "input_tokens": 1250, "output_tokens": 0, "cache_creation_tokens": 0, "cache_read_tokens": 0, "total_cost_usd": 0.000375 } } ``` ## MCP Resources The server exposes two read-only resources for AI assistants: ### `zh-tw://style-guide/moe` Taiwan Ministry of Education style guide covering: - Punctuation rules - Character shape standards - Vocabulary preferences ### `zh-tw://dictionary/ambiguous` Cross-strait term disambiguation dictionary with context examples. **Access in prompt:** ``` Please consult zh-tw://style-guide/moe before making suggestions. ``` ## Rule Types The linter reports issues with these `rule_type` values: | Type | Description | Example | |------|-------------|---------| | `vocabulary` | Cross-strait vocabulary | 軟件→軟體 | | `punctuation` | Punctuation marks | `.`→`。` | | `spacing` | CJK-Latin/digit spacing | `zh tw`→`zh-TW` | | `variant` | Character variants (strict) | 裏→裡 | | `casing` | Proper noun casing | `github`→`GitHub` | | `grammar` | Grammar issues | 台→臺 (in 臺灣) | | `political` | Politically colored terms | 祖國, 內地 | | `filler` | AI filler phrases (detect_ai) | 首先, 總的來說 |