MCP FileEncoding

MCP-Server, der das Problem löst, dass KI-Kodierungsassistenten unter Windows beim Lesen/Schreiben von Nicht-UTF-8-Dateien wie GBK/GB18030 Zeichensalat erzeugen.

Beim Lesen wird die Kodierung automatisch erkannt und in UTF-8 an die KI zurückgegeben; beim Schreiben wird sie automatisch in die ursprüngliche Kodierung zurückkonvertiert, was für die KI völlig transparent ist.

Hintergrund

In chinesischen Windows-Umgebungen werden viele Quellcodedateien (C/C++, Lisp usw.) im GBK-Format gespeichert. KI-Kodierungsassistenten lesen diese Dateien standardmäßig mit UTF-8, was dazu führt, dass chinesische Kommentare und Zeichenfolgen als Zeichensalat dargestellt werden. Dieses MCP verarbeitet die Kodierungskonvertierung beim Lesen und Schreiben von Dateien automatisch, sodass die KI Nicht-UTF-8-Dateien korrekt verarbeiten kann.

Unterstützte Kodierungen

UTF-8 / UTF-8 BOM
GBK / GB2312
GB18030
Andere von Python codecs unterstützte Kodierungen

Installation

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

Konfiguration

Claude Code

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

Claude Desktop / Cursor / Andere MCP-Clients

Fügen Sie dies zur MCP-Konfigurationsdatei hinzu (der Pfad zur Konfigurationsdatei variiert je nach Client, siehe die entsprechende Client-Dokumentation):

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

Verwendung

Nach Abschluss der Konfiguration erhält die KI automatisch die folgenden 5 Tools.

Tool-Liste

Tool	Beschreibung
`read_file_with_encoding`	Datei lesen, Kodierung automatisch erkennen, UTF-8-Inhalt zurückgeben
`write_file_with_encoding`	Datei schreiben, automatisch in die ursprüngliche Kodierung zurückkonvertieren
`edit_file_with_encoding`	Dateiinhalt lokal ersetzen (String-Ersetzung)
`get_file_encoding`	Kodierungsdatensatz der Datei abfragen
`list_all_encodings`	Alle aufgezeichneten Kodierungen auflisten

Methode 1: PreToolUse Hook (Empfohlen)

Über den Hook-Mechanismus von Claude Code wird bei jedem Aufruf der Read/Write/Edit-Tools durch die KI automatisch der Dateityp überprüft und die Verwendung des MCP vorgeschlagen. Dies ist zuverlässiger als System-Prompts und schlägt in langen Dialogen nicht fehl.

Erstellen Sie .claude/settings.json im Projektstammverzeichnis:

{
  "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\": \"提示信息\"}}"
          }
        ]
      }
    ]
  }
}

Passen Sie die passenden Dateierweiterungen (.cpp, .h, .lsp usw.) nach Bedarf an.

Methode 2: System-Prompt

Fügen Sie den Prompt in Claude Code über den Parameter --system-prompt oder die Datei CLAUDE.md des Projekts hinzu:

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

Hinweis: System-Prompts können in langen Dialogen von der KI ignoriert werden; der PreToolUse Hook ist die zuverlässigere Wahl.

Arbeitsablauf

Beispiel: Bearbeiten einer .cpp-Datei mit GBK-Kodierung:

Die KI ruft read_file_with_encoding auf, um die Datei zu lesen → erkennt automatisch GBK → gibt UTF-8-Inhalt an die KI zurück
Nachdem die KI den Inhalt verstanden hat, ruft sie edit_file_with_encoding zur Bearbeitung auf → schreibt die Datei automatisch im GBK-Format zurück
Die Dateikodierung bleibt unverändert, was die Kompatibilität mit anderen Tools nicht beeinträchtigt

Hinweise

Kodierungsdatensätze werden im Arbeitsspeicher gespeichert und beim Neustart des MCP-Servers gelöscht
Wenn der Kodierungsdatensatz beim Schreiben einer Datei verloren gegangen ist, muss der Parameter encoding manuell angegeben werden
Die Erkennung basiert auf dem Dateiinhalt; bei sehr kurzen Texten ist sie möglicherweise nicht genau genug. Es wird empfohlen, dass der Dateiinhalt mindestens einige Dutzend chinesische Schriftzeichen umfasst

Entwicklung

Entwicklungsabhängigkeiten installieren

pip install -r requirements.txt
pip install pytest pyright

Tests ausführen

python -m pytest tests/ -v

Typüberprüfung

npx pyright src/

Das Projekt verwendet den pyright strict-Modus; alle Quellcode-Typüberprüfungen müssen fehlerfrei bestanden werden.

Projektstruktur

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  # 存储模块测试

Abhängigkeiten

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

Lizenz

MIT

mcp-fileencoding