Skip to main content
Glama
whyjp

Encoding MCP Server

by whyjp
OverviewInspectSchemaRelated ServersScoreDiscussions
Python
Local

Encoding MCP Server v2.0.1

PyPI version Python 3.10+ License: MIT Downloads

왜 필요한가

문제: AI Agent(Claude, GPT 등)가 파일을 생성할 때 UTF-8 without BOM으로 작성합니다. 이는 Agent의 write 도구가 BOM을 처리하지 않기 때문입니다.

영향: Windows MSVC 컴파일러는 BOM 없이는 한글 주석/문자열을 잘못 해석합니다. 빌드 실패나 깨진 문자가 발생합니다.

해결: 이 MCP 서버는 Agent가 파일을 쓰기 전에 올바른 인코딩(UTF-8 with BOM)으로 빈 파일을 먼저 생성합니다. Agent의 구조적 한계를 우회하는 방식입니다.

Related MCP server: MCP Server

새로운 기능

파일명/경로 분리 인터페이스

  • Agent가 자연스럽게 현재 작업 디렉터리를 인식

  • 파일명과 디렉터리 경로를 명확히 분리

  • 경로 관련 사용성 문제 완전 해결

인코딩 감지

  • charset-normalizer: 최신 고성능 라이브러리

  • chardet: 전통적이지만 안정적

  • fallback: 라이브러리 없을 때 개선된 휴리스틱

  • 95%+ 정확도 달성

Agent와의 협업

  • MCP: 정확한 인코딩으로 빈 파일 생성

  • Agent: write 도구로 내용 채움

  • 결과: UTF-8 BOM 보존

빠른 시작

설치

PyPI에서 설치 (권장)

pip install encoding-mcp

개발자 모드 설치

git clone https://github.com/whyjp/encoding_mcp.git cd encoding_mcp pip install -e .[dev,test]

설치 확인

# 패키지 정보 확인 pip show encoding-mcp # 버전 확인 python -c "import encoding_mcp; print(encoding_mcp.__version__)" # MCP 서버 실행 테스트 python -m encoding_mcp

Cursor 연결

Cursor 설정 → Extensions → MCP → 설정 파일에 추가:

{ "mcpServers": { "encoding-mcp": { "command": "python", "args": ["-m", "encoding_mcp"], "env": { "DEBUG": "false" } } } }

Cursor 재시작 후 사용 가능.

테스트

npx @modelcontextprotocol/inspector python -m encoding_mcp

주요 도구

create_empty_file

지정된 인코딩으로 빈 파일을 생성합니다. Agent가 내용을 채울 수 있도록 빈 파일만 생성합니다.

매개변수:

  • file_name: 생성할 파일명 (예: hello.cpp, test.h)

  • directory_path: 파일을 생성할 디렉터리의 절대 경로

  • encoding: 파일 인코딩 (utf-8-bom, utf-8, cp949, euc-kr, ascii)

detect_file_encoding

파일의 인코딩을 정확하게 감지합니다.

매개변수:

  • file_name: 확인할 파일명 (예: hello.cpp, test.h)

  • directory_path: 파일이 있는 디렉터리의 절대 경로

  • max_bytes: 분석할 최대 바이트 수 (기본값: 8192)

convert_file_encoding

파일을 지정된 인코딩으로 변환합니다. 자동 백업 지원.

매개변수:

  • file_name: 변환할 파일명 (예: hello.cpp, test.h)

  • directory_path: 파일이 있는 디렉터리의 절대 경로

  • target_encoding: 목표 인코딩 (utf-8-bom, utf-8, cp949, euc-kr, ascii)

  • backup: 원본 파일 백업 여부 (기본값: false)

get_system_info

Encoding MCP 시스템 정보를 확인합니다. 사용 가능한 라이브러리와 지원 인코딩을 보여줍니다.

사용 예시

기본 워크플로우

1. 빈 UTF-8 BOM 파일 생성

# MCP 호출 mcp_encoding_create_empty_file( file_name="hello.cpp", directory_path="D:/my_project/src", encoding="utf-8-bom" )

2. Agent가 내용 채우기

# Agent write 도구 사용 write( file_path="D:/my_project/src/hello.cpp", contents="#include <iostream>\n\nint main() {\n std::cout << \"Hello, World!\" << std::endl;\n return 0;\n}" )

3. 인코딩 검증

# 인코딩 감지 mcp_encoding_detect_file_encoding( file_name="hello.cpp", directory_path="D:/my_project/src" )

4. 필요시 인코딩 변환

# 안전한 변환 (자동 백업) mcp_encoding_convert_file_encoding( file_name="hello.cpp", directory_path="D:/my_project/src", target_encoding="utf-8", backup=true )

다양한 인코딩

# UTF-8 BOM (Windows C++ 최적화) create_empty_file(file_name="main.cpp", directory_path="D:/project", encoding="utf-8-bom") # UTF-8 (범용) create_empty_file(file_name="script.py", directory_path="D:/project", encoding="utf-8") # CP949 (Windows 한글) create_empty_file(file_name="korean.txt", directory_path="D:/project", encoding="cp949") # ASCII (호환성) create_empty_file(file_name="config.txt", directory_path="D:/project", encoding="ascii")

지원 인코딩

인코딩

설명

Windows 호환

용도

utf-8-bom

UTF-8 with BOM

🪟 ✅

C++, PowerShell

utf-8

UTF-8 without BOM

🐧 ✅

범용적 사용

cp949

Windows 한글

🪟 ✅

레거시 한글

euc-kr

Unix/Linux 한글

🐧 ✅

Unix 환경

ascii

7비트 ASCII

🌍 ✅

호환성 최고

인코딩 감지

감지 방법 우선순위

  1. BOM 감지 (100% 정확도)

  2. charset-normalizer (현대적, 고성능)

  3. chardet (전통적, 안정적)

  4. fallback (개선된 휴리스틱)

감지 정확도

  • BOM 있는 파일: 100%

  • UTF-8: 94%+

  • CP949/EUC-KR: 82%+

  • ASCII: 98%+

Windows 빌드 문제 해결

❌ 문제 상황

  • C++ 파일: UTF-8 without BOM → 한글 주석 깨짐

  • PowerShell 스크립트: UTF-8 without BOM → 한글 출력 깨짐

  • 배치 파일: 인코딩 문제 → 스크립트 실행 실패

✅ 해결 결과

  • 모든 파일이 UTF-8 with BOM으로 생성

  • Windows 환경에서 안정적 작동

  • 한글 포함 소스코드 지원

고급 설정

개발자 모드

{ "mcpServers": { "encoding-mcp-dev": { "command": "python", "args": ["-m", "encoding_mcp"], "env": { "DEBUG": "true", "LOG_LEVEL": "DEBUG" } } } }

특정 Python 버전

{ "mcpServers": { "encoding-mcp": { "command": "python3.11", "args": ["-m", "encoding_mcp"], "env": { "DEBUG": "false" } } } }

가상환경

{ "mcpServers": { "encoding-mcp": { "command": "/path/to/venv/bin/python", "args": ["-m", "encoding_mcp"], "env": { "DEBUG": "false" } } } }

직접 실행 (개발용)

{ "mcpServers": { "encoding-mcp-dev": { "command": "python", "args": ["/path/to/encoding_mcp/encoding_mcp/server.py"], "env": { "DEBUG": "true" } } } }

아키텍처

모듈 구조

encoding_mcp/ ├── server.py # 메인 MCP 서버 ├── encoding_detector.py # 인코딩 감지 ├── file_operations.py # 파일 생성/변환 로직 ├── __main__.py # 모듈 실행 엔트리 포인트 └── __init__.py # 패키지 초기화

워크플로우

1. MCP: 정확한 인코딩으로 빈 파일 생성 2. Agent: write 도구로 내용 채움 3. 결과: UTF-8 BOM 보존

Agent 협업 패턴

# 1단계: MCP로 빈 파일 생성 mcp_encoding_create_empty_file( file_name="hello.cpp", directory_path=os.getcwd(), # Agent가 자동 인식 encoding="utf-8-bom" ) # 2단계: Agent가 내용 채움 write( file_path="hello.cpp", contents="C++ 소스 코드..." ) # 결과: UTF-8 BOM 보존된 파일

기술 세부사항

시스템 요구사항

  • Python 3.10+ (MCP 모듈의 pattern matching 기능 사용)

  • Windows, macOS, Linux 지원

의존성

  • mcp>=1.0.0: Model Context Protocol

  • charset-normalizer>=3.0.0: 현대적 인코딩 감지

  • chardet>=5.0.0: 전통적 인코딩 감지

고급 기능

  • BOM 감지: 바이트 시퀀스 분석

  • 백업 시스템: 원본 파일 자동 보존

  • 오류 복구: 실패 시 백업에서 복원

라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

기여

버그 리포트, 기능 요청, 풀 리퀘스트를 환영합니다.

GitHub: https://github.com/whyjp/encoding_mcp

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/whyjp/encoding_mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server