MCP FileEncoding

MCP-сервер, решающий проблему отображения «кракозябр» при чтении и записи файлов в кодировках GBK/GB18030 и других, отличных от UTF-8, в среде Windows для ИИ-ассистентов.

При чтении автоматически определяет кодировку и преобразует её в UTF-8 для передачи ИИ, а при записи автоматически преобразует обратно в исходную кодировку, что делает процесс полностью прозрачным для ИИ.

Предыстория

В китайской локали Windows многие проекты (C/C++, Lisp и т.д.) используют кодировку GBK для сохранения исходных файлов. ИИ-ассистенты по умолчанию читают эти файлы в UTF-8, что приводит к превращению китайских комментариев и строк в нечитаемые символы. Данный MCP автоматически обрабатывает преобразование кодировок при чтении и записи файлов, позволяя ИИ корректно работать с файлами не в формате UTF-8.

Поддерживаемые кодировки

UTF-8 / UTF-8 BOM
GBK / GB2312
GB18030
Другие кодировки, поддерживаемые codecs в Python

Установка

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"]
    }
  }
}

Использование

После завершения настройки ИИ автоматически получит следующие 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, при каждом вызове ИИ инструментов 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 等文件不需要使用。其他文件一般不需要使用，只有遇到读取文本乱码后才尝试使用。"

Примечание: Системные промпты могут игнорироваться ИИ в длинных диалогах, поэтому PreToolUse Hook является более надежным выбором.

Рабочий процесс

На примере редактирования .cpp файла в кодировке GBK:

ИИ вызывает read_file_with_encoding для чтения файла → автоматически определяется GBK → содержимое в UTF-8 возвращается ИИ
ИИ понимает содержимое и вызывает 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, все проверки типов исходного кода должны проходить без ошибок.

Структура проекта

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