MCP FileEncoding

AI 코딩 어시스턴트가 Windows 환경에서 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

License

MIT

mcp-fileencoding