MCP FileEncoding

Windows環境でAIコーディングアシスタントがGBK/GB18030などの非UTF-8ファイルを読み書きする際の文字化け問題を解決するMCPサーバーです。

読み込み時にエンコーディングを自動検出しUTF-8に変換してAIに返し、書き込み時に元のエンコーディングに自動変換するため、AI側からは完全に透過的に動作します。

背景

Windowsの中国語環境では、多くのプロジェクト（C/C++、Lispなど）のソースファイルがGBKエンコーディングで保存されています。AIコーディングアシスタントはデフォルトでこれらのファイルをUTF-8として読み込むため、中国語のコメントや文字列が文字化けしてしまいます。本MCPはファイル読み書き時にエンコーディング変換を自動処理し、AIが非UTF-8ファイルを正しく扱えるようにします。

サポートされているエンコーディング

UTF-8 / UTF-8 BOM
GBK / GB2312
GB18030
その他 Python codecs がサポートするエンコーディング

インストール

git clone https://github.com/jidzhang/mcp-fileencoding.git
cd mcp-fileencoding
pip install -r requirements.txt

設定

Claude Code

claude mcp add fileencoding -- python /path/to/mcp-fileencoding/src/server.py

Claude Desktop / Cursor / その他のMCPクライアント

MCP設定ファイルに追加します（設定ファイルのパスはクライアントによって異なります。各クライアントのドキュメントを参照してください）：

{
  "mcpServers": {
    "fileencoding": {
      "command": "python",
      "args": ["/path/to/mcp-fileencoding/src/server.py"]
    }
  }
}

使用方法

設定完了後、AIは自動的に以下の5つのツールを利用できるようになります。

ツール一覧

ツール	説明
`read_file_with_encoding`	ファイルを読み込み、エンコーディングを自動検出してUTF-8の内容を返す
`write_file_with_encoding`	ファイルを書き込み、元のエンコーディングに自動変換する
`edit_file_with_encoding`	ファイル内容を部分的に置換する（文字列置換）
`get_file_encoding`	ファイルのエンコーディング記録を照会する
`list_all_encodings`	記録されたすべてのエンコーディングを一覧表示する

方法1：PreToolUse Hook（推奨）

Claude CodeのHook機能を使用し、AIがRead/Write/Editツールを呼び出すたびに自動的にファイルタイプをチェックしてMCPの使用を促します。システムプロンプトよりも信頼性が高く、長時間の対話でも無効になりません。

プロジェクトのルートディレクトリに .claude/settings.json を作成します：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Write|Edit",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查 $ARGUMENTS 中的文件路径，如果文件扩展名是 .cpp、.h 或 .lsp，则：\n- 对于 Read 操作：使用 mcp__fileencoding__read_file_with_encoding 代替 Read 工具\n- 对于 Write/Edit 操作：使用 mcp__fileencoding__write_file_with_encoding 代替 Write/Edit 工具\n\n返回 JSON: {\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"additionalContext\": \"提示信息\"}}"
          }
        ]
      }
    ]
  }
}

必要に応じて、対象とするファイル拡張子（.cpp、.h、.lsp など）を変更してください。

方法2：システムプロンプト

Claude Codeの --system-prompt 引数、またはプロジェクトの CLAUDE.md ファイルにプロンプトを追加します：

claude --system-prompt "在读取和修改 .cpp/.h/.lsp/.txt 等文本文件时，使用 fileencoding MCP。.py/.js/.html 等文件不需要使用。其他文件一般不需要使用，只有遇到读取文本乱码后才尝试使用。"

注意：システムプロンプトは長時間の対話でAIに無視される可能性があるため、PreToolUse Hookの方がより信頼性の高い選択肢です。

ワークフロー

GBKエンコーディングの .cpp ファイルを編集する場合の例：

AIが read_file_with_encoding を呼び出してファイルを読み込む → 自動的にGBKと検出 → UTF-8の内容をAIに返す
AIが内容を理解した後、 edit_file_with_encoding を呼び出して修正 → 自動的にGBKでファイルに書き戻す
ファイルのエンコーディングは維持され、他のツールの互換性を損なうことはありません

注意事項

エンコーディングの記録はメモリ上に保存され、MCPサーバーの再起動時にクリアされます
ファイル書き込み時にエンコーディング記録が失われている場合は、手動で encoding 引数を指定する必要があります
検出はファイル内容に基づいて行われるため、短いテキストでは精度が不十分な場合があります。数十文字以上の漢字を含むファイルでの使用を推奨します

開発

開発依存関係のインストール

pip install -r requirements.txt
pip install pytest pyright

テストの実行

python -m pytest tests/ -v

型チェック

npx pyright src/

プロジェクトはpyrightのstrictモードを使用しており、すべてのソースコードの型チェックでエラーがゼロである必要があります。

プロジェクト構造

src/
├── server.py          # MCP 服务器入口，工具定义和请求处理
├── detector.py        # 编码检测（charset-normalizer + GBK 回退）
├── converter.py       # 编码转换（字节 ↔ UTF-8）
└── encoding_store.py  # 内存编码记录存储
tests/
├── test_server.py     # 服务器 handler 测试
├── test_detector.py   # 编码检测测试
├── test_converter.py  # 编码转换测试
└── test_encoding_store.py  # 存储模块测试

依存関係

Python >= 3.10
mcp >= 1.0.0
charset-normalizer >= 3.0.0

ライセンス

MIT

mcp-fileencoding