MCP FileEncoding

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

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

Предыстория

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

Related MCP server: filesystem-mcp

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

• 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 инструментов.

Список инструментов

Способ 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:

1. ИИ вызывает read_file_with_encoding для чтения файла → автоматически определяется GBK → содержимое в UTF-8 возвращается ИИ

2. ИИ понимает содержимое и вызывает edit_file_with_encoding для внесения правок → автоматически записывается обратно в файл в кодировке GBK

3. Кодировка файла остается неизменной, что не нарушает совместимость с другими инструментами

Примечания

• Записи о кодировках хранятся в оперативной памяти и очищаются после перезапуска 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