MCP FileEncoding

Servidor MCP que resuelve el problema de caracteres ilegibles cuando los asistentes de codificación de IA leen o escriben archivos que no son UTF-8 (como GBK/GB18030) en Windows.

Detecta automáticamente la codificación al leer y la convierte a UTF-8 para la IA, y al escribir, la convierte de nuevo a la codificación original, siendo totalmente transparente para la IA.

Antecedentes

En el entorno chino de Windows, muchos proyectos (C/C++, Lisp, etc.) guardan sus archivos fuente utilizando la codificación GBK. Los asistentes de codificación de IA leen estos archivos por defecto en UTF-8, lo que provoca que los comentarios y cadenas de texto en chino se conviertan en caracteres ilegibles. Este MCP gestiona automáticamente la conversión de codificación al leer y escribir archivos, permitiendo que la IA procese correctamente archivos que no son UTF-8.

Codificaciones soportadas

• UTF-8 / UTF-8 BOM

• GBK / GB2312

• GB18030

• Otras codificaciones soportadas por codecs de Python

Instalación

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

Configuración

Claude Code

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

Claude Desktop / Cursor / Otros clientes MCP

Añadir a la configuración de MCP (la ruta del archivo de configuración varía según el cliente, consulte la documentación correspondiente):

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

Modo de uso

Una vez configurado, la IA obtendrá automáticamente las siguientes 5 herramientas.

Lista de herramientas

Opción 1: PreToolUse Hook (Recomendado)

A través del mecanismo Hook de Claude Code, se comprueba automáticamente el tipo de archivo cada vez que la IA llama a las herramientas Read/Write/Edit y se sugiere el uso de MCP. Es más fiable que las instrucciones del sistema y no falla en conversaciones largas.

Cree un archivo .claude/settings.json en la raíz del proyecto:

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

Modifique las extensiones de archivo según sea necesario (.cpp, .h, .lsp, etc.).

Opción 2: Instrucciones del sistema

Añada las instrucciones en Claude Code mediante el parámetro --system-prompt o en el archivo CLAUDE.md del proyecto:

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

Nota: Las instrucciones del sistema pueden ser ignoradas por la IA en conversaciones largas; el PreToolUse Hook es una opción más fiable.

Flujo de trabajo

Tomando como ejemplo la edición de un archivo .cpp codificado en GBK:

1. La IA llama a read_file_with_encoding para leer el archivo → detecta automáticamente que es GBK → devuelve el contenido en UTF-8 a la IA

2. Tras comprender el contenido, la IA llama a edit_file_with_encoding para modificarlo → se escribe automáticamente de vuelta al archivo en GBK

3. La codificación del archivo se mantiene sin cambios, sin romper la compatibilidad con otras herramientas

Notas importantes

• El registro de codificación se almacena en memoria y se borra al reiniciar el servidor MCP

• Si el registro de codificación se pierde al escribir un archivo, deberá especificar manualmente el parámetro encoding

• La detección se basa en el contenido del archivo; si el texto es muy corto, la precisión puede ser menor. Se recomienda que el contenido del archivo tenga al menos varias decenas de caracteres chinos

Desarrollo

Instalar dependencias de desarrollo

pip install -r requirements.txt
pip install pytest pyright

Ejecutar pruebas

python -m pytest tests/ -v

Comprobación de tipos

npx pyright src/

El proyecto utiliza el modo estricto de pyright; toda la comprobación de tipos del código fuente debe pasar sin errores.

Estructura del proyecto

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

Dependencias

• Python >= 3.10

• mcp >= 1.0.0

• charset-normalizer >= 3.0.0

Licencia

MIT