Codepage Bridge MCP

中文说明 / README_CN

Encoding-transparent file tools for Claude Code and other MCP clients.

Codepage Bridge exposes Read, Grep, Edit, and Write over MCP while transparently converting project files between their on-disk legacy encoding and Unicode text for the LLM. The model sees normal Unicode text; files are written back in the encoding selected by the nearest .encoding-rules.

It is designed for legacy codebases that still use GBK/GB2312/GB18030, Big5, Shift-JIS, EUC-KR, Windows codepages, UTF-16, and other non-UTF-8 encodings.

Recommended install

This is now the single recommended installation path for end users.

Windows

# Remove an older install with the same name first, if one exists.
claude mcp remove codepage-bridge -s user

# Register the npm package once, at user scope. `cmd` is required on Windows.
claude mcp add --scope user codepage-bridge -- cmd /d /s /c "npx -y codepage-bridge-mcp"
claude mcp get codepage-bridge

macOS / Linux

# Remove an older install with the same name first, if one exists.
claude mcp remove codepage-bridge -s user

# Register the npm package once, at user scope.
claude mcp add --scope user codepage-bridge -- npx -y codepage-bridge-mcp
claude mcp get codepage-bridge

What this requires locally:

• claude
• node

What it does not require:

• git clone
• npm install
• npm run build
• downloading a GitHub Release package first

Avoid duplicate MCP registrations

Register codepage-bridge in only one scope. Claude Code treats the same server name with different commands as a configuration conflict—for example, an older user-scoped local build and this repository's project-scoped .mcp.json npm command.

Run claude mcp list to diagnose duplicates. Keep the endpoint you want, then remove the other registration:

# Keep the npm command from the user-scoped installation.
claude mcp remove codepage-bridge -s project

# Or keep a project-local configuration and remove a previous user installation.
claude mcp remove codepage-bridge -s user

After removing a registration, run claude mcp get codepage-bridge again. It must report one endpoint with status Connected.

Large text files

Read and Grep allow individual text files up to 32 MiB by default. To use a different limit, set CODEPAGE_BRIDGE_MAX_TEXT_FILE_MIB to a positive integer before starting Claude Code:

setx CODEPAGE_BRIDGE_MAX_TEXT_FILE_MIB 64

Restart Claude Code after changing the variable. Larger files require proportionally more Node.js memory while decoding, splitting lines, and matching regular expressions.

Why

Claude Code built-in file tools assume UTF-8 for normal text reads. In legacy projects this can lead to:

• unreadable C/C++ comments and string literals;
• searches that silently miss text;
• edits that corrupt the original codepage;
• accidental UTF-8 rewrites of GBK or other legacy files.

Codepage Bridge keeps encoding conversion below the model boundary:

legacy bytes on disk -> decode by .encoding-rules -> Unicode for the LLM
Unicode from the LLM -> strict encode by .encoding-rules -> legacy bytes on disk

If new text cannot be represented in the target encoding, the write fails instead of silently replacing characters with ?.

Required Claude Code configuration

Installing the MCP is not sufficient by itself.

Claude Code may still choose its built-in:

• Read
• Grep
• Edit
• Write
• NotebookEdit

Those tools bypass .encoding-rules.

Step 1 — merge settings.fragment.json

Merge this into your existing ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__codepage-bridge__Read",
      "mcp__codepage-bridge__Grep",
      "mcp__codepage-bridge__Edit",
      "mcp__codepage-bridge__Write"
    ],
    "deny": [
      "Read",
      "Grep",
      "Edit",
      "Write",
      "NotebookEdit"
    ]
  }
}

Template file:

• examples/claude-config/settings.fragment.json

Do not replace your whole settings file unless it is empty. Merge these arrays into your existing configuration.

Step 2 — add a CLAUDE.md policy

Add this to the project CLAUDE.md, or to ~/.claude/CLAUDE.md for a global policy:

## File encoding policy

Use Codepage Bridge for all project file content operations:

- Read with `mcp__codepage-bridge__Read`.
- Search with `mcp__codepage-bridge__Grep`.
- Edit with `mcp__codepage-bridge__Edit`.
- Create or completely rewrite with `mcp__codepage-bridge__Write`.

Do not use built-in Read, Grep, Edit, Write, NotebookEdit, shell commands,
PowerShell commands, or scripts as substitutes for project file content access.
Glob may only be used to discover paths.

Do not manually transcode files or normalize line endings. `.encoding-rules`
is the source of truth.

Template file:

• examples/minimal-project/CLAUDE.md

Step 3 — add .encoding-rules

.encoding-rules is optional. When it is absent, Codepage Bridge treats the target file's directory as the allowed root and reads/writes using strict UTF-8. Add a rules file whenever the project contains legacy-encoded files or needs a shared project root.

Example:

# Last matching rule wins
*.c gbk
*.cpp gbk
*.h gbk
legacy/**/*.txt windows-1251
assets/**/*.csv shift_jis
**/*.json utf8

# Cancel earlier matches and return to strict UTF-8
!SourceCode/generated/**

Template file:

• examples/minimal-project/.encoding-rules

Rules:

• Empty lines and lines beginning with # are ignored.
• *, **, and ? use glob semantics.
• Patterns without /, such as *.cpp, match basenames at every directory depth.
• Patterns containing / are relative to the .encoding-rules directory.
• The last matching rule wins.
• !pattern cancels previous matches and selects strict UTF-8.
• Files with no matching rule use strict UTF-8.
• The nearest .encoding-rules is used; its directory is the allowed project root.

Verify the setup

1. Check the MCP is connected

claude mcp get codepage-bridge

Expected:

• name: codepage-bridge
• status: Connected

2. Start a fresh Claude Code session in a legacy project

3. Ask Claude to read or search a legacy-encoded file

Examples:

Read SourceCode/Main.cpp and show the first 10 lines.

Search SourceCode for the string 错误码.

4. Confirm the model uses Codepage Bridge tools

In a verbose / print-mode session, the tool call should be one of:

• mcp__codepage-bridge__Read
• mcp__codepage-bridge__Grep
• mcp__codepage-bridge__Edit
• mcp__codepage-bridge__Write

It should not call built-in Read, Grep, Edit, or Write.

Features

• Encoding-aware Read, Grep, Edit, and Write tools.
• Project-level .encoding-rules with gitignore-like glob behavior.
• The nearest .encoding-rules defines both the project root and active rules.
• Last matching rule wins; !pattern resets matching files to strict UTF-8.
• Basename patterns such as *.cpp match at every directory depth.
• Strict UTF-8 fallback for files not matched by a rule.
• GBK/GB2312/GB18030, Big5, Shift-JIS, EUC-KR, Windows codepages, UTF-8, and UTF-16 support.
• BOM and dominant line-ending preservation for edits.
• Read-before-write protection and stale-write detection using byte hashes.
• Atomic temporary-file writes and per-path write locks.
• Symlink and project-root boundary checks.
• Image, PDF, and Jupyter Notebook reading.
• Grep output modes, context lines, glob/type filters, regex flags, and pagination.
• Large-file partial edit authorization: the model only needs to read the target lines it wants to edit, not the entire file.

Development

npm install
npm run check
npm test
npm run build
npm start

License

MIT. See LICENSE.