Unicode Remover

A small CLI and MCP server that finds literal Unicode escape sequences in a file and either decodes them to the actual character or strips them entirely. Built to fix files where text like the literal six characters ' survived a JSON pipeline and ended up on disk instead of the apostrophe it was meant to represent.

Features

• Recognizes three escape forms: \uXXXX, \UXXXXXXXX, and \u{1-6 hex}
• Two modes: decode (replace with the actual character) or delete (strip the sequence)
• Combines surrogate pairs into the supplementary codepoint (e.g. 😀 becomes the grinning face emoji)
• Leaves lone surrogates and out-of-range codepoints untouched rather than silently substituting U+FFFD
• Optional .bak backup before modifying
• --dry-run to report what would change without writing
• Works as a CLI or as an MCP stdio server

Installation

go install github.com/hegner123/unicode-remover@latest

Or build from source:

git clone https://github.com/hegner123/unicode-remover
cd unicode-remover
just install

The install recipe builds, ad-hoc codesigns the binary, and copies it to /usr/local/bin/.

Usage

CLI

unicode-remover --cli --file /path/to/file.txt

Flags:

Flag	Default	Purpose
--file	(required)	Absolute path to the file to process
--mode	decode	decode to replace, delete to strip
--backup	true	Write a .bak before modifying
--no-backup	false	Skip the backup
--dry-run	false	Report what would change without writing

Example:

$ unicode-remover --cli --file demo.txt
{"file":"demo.txt","mode":"decode","replacements":2,"bytes_in":16,"bytes_out":6,"backup":"demo.txt.bak","status":"modified"}

MCP server

Register with Claude Code:

claude mcp add --transport stdio unicode-remover -- unicode-remover

Tool name: unicode_remove. Parameters:

Name	Type	Default	Required
file	string	—	yes
mode	string	decode	no
backup	bool	true	no
dry_run	bool	false	no

The MCP path matters because it bypasses any tool layer that would JSON-decode \uXXXX before it reaches the file. The tool only sees a path; the bytes on disk are read and rewritten in place.

License

MIT