editor-mcp

편집자 MCP

FastMCP 기반으로 구축된 Python 기반 텍스트 편집기 서버로, 강력한 파일 작업 도구를 제공합니다. 이 서버는 표준화된 API를 통해 텍스트 파일을 읽고, 편집하고, 관리할 수 있도록 지원하며, 고유한 다단계 접근 방식을 통해 LLM 및 AI 어시스턴트의 코드 편집 정확도와 안정성을 크게 향상시킵니다.

특징

• 파일 선택 : 절대 경로를 사용하여 작업할 파일 설정
• 읽기 작업 :
  • skim 사용하여 줄 번호가 있는 전체 파일 읽기
  • read 사용하여 접두사가 붙은 줄 번호로 특정 줄 범위를 읽습니다.
  • find_line 사용하여 파일 내에서 특정 텍스트 찾기
  • find_function 사용하여 Python 및 JavaScript/JSX 파일에서 함수 정의를 찾아 추출합니다.
• 편집 작업 :
  • diff 미리보기를 통한 2단계 편집 프로세스
  • ID 검증을 통해 텍스트 선택 및 덮어쓰기
  • 선택 → 덮어쓰기 → 확인/취소 패턴으로 편집 워크플로우를 깔끔하게 정리합니다.
  • Python(.py) 및 JavaScript/React(.js, .jsx) 파일에 대한 구문 검사
  • 콘텐츠로 새 파일을 만듭니다
• 파일 관리 :
  • 적절한 초기화로 새 파일을 만듭니다.
  • 파일 시스템에서 파일 삭제
  • listdir 로 디렉토리 내용 나열
• 테스트 지원 :
  • run_tests 로 Python 테스트 실행
  • 적절한 모듈 확인을 위한 Python 경로 설정
• 안전 기능 :
  • 충돌 방지를 위한 콘텐츠 ID 확인
  • 리소스 고갈을 방지하기 위한 줄 수 제한
  • 코드 무결성을 유지하기 위한 구문 검사
  • 민감한 파일에 대한 액세스를 제한하는 보호된 경로

보안 위험

editor-mcp에는 특정 보안 고려 사항과 함께 제공되는 강력한 기능이 포함되어 있습니다.

• 탈옥 위험 : editor-mcp는 유해한 명령어가 내장된 파일을 읽을 때 잠재적으로 탈옥될 수 있습니다. 편집 중인 파일의 악성 콘텐츠에는 AI 비서를 조작하는 명령어가 포함되어 있을 수 있습니다.
• 임의 코드 실행 : 테스트 실행이 활성화된 경우 조작된 테스트 파일이나 악성 Python 코드를 통해 임의 코드가 실행될 위험이 있습니다.
• 데이터 노출 : 적절한 경로 보호가 구성되지 않은 경우 파일 시스템 작업에 액세스하면 잠재적으로 중요한 정보가 노출될 수 있습니다.

이러한 위험을 완화하려면:

1. PROTECTED_PATHS 환경 변수를 사용하여 중요한 파일과 디렉토리에 대한 액세스를 제한합니다.
2. 절대적으로 필요하지 않는 한, 프로덕션 환경에서 테스트 실행 기능을 비활성화합니다.
3. 특히 신뢰할 수 없는 출처에서 온 파일이라면 열기 전에 주의 깊게 검토하세요.
4. 권한이 제한된 샌드박스 환경에서 편집기를 실행하는 것을 고려하세요.

LLM의 주요 장점

이 텍스트 편집기의 독특한 디자인은 일반적으로 LLM 코드 편집에 영향을 미치는 중요한 문제를 해결합니다.

• 컨텍스트 손실 방지 - 기존 방식에서는 LLM이 몇 번의 수정 후 코드베이스에 대한 전반적인 정보를 잃는 경우가 많았습니다. 이 구현 방식은 다단계 프로세스를 통해 컨텍스트를 유지합니다.
• 리소스 소모가 많은 재작성 방지 - LLM은 일반적으로 혼동 시 전체 파일을 교체하는 방식으로 작동하는데, 이는 비용이 많이 들고 느리며 비효율적입니다. 이 편집기는 선택적 편집을 지원합니다.
• 시각적 피드백 제공 - diff 미리보기 시스템을 통해 LLM은 변경 사항을 커밋하기 전에 실제로 변경 사항을 보고 확인할 수 있으므로 오류가 크게 줄어듭니다.
• 구문 검사 강화 - Python 및 JavaScript/React에 대한 자동 검증을 통해 깨진 코드가 커밋되지 않도록 보장합니다.
• 편집 추론 개선 - 다단계 접근 방식은 LLM이 단계 사이에서 추론할 시간을 제공하여 무질서한 토큰 생성을 줄입니다.

자원 관리

편집기는 시스템 안정성을 보장하고 리소스 고갈을 방지하기 위해 여러 가지 보호 장치를 구현합니다.

• 최대 편집 줄 수 : 기본적으로 편집기는 단일 편집 작업에 대해 50줄 제한을 적용합니다.

설치

이 MCP는 Claude Desktop을 사용하여 개발 및 테스트되었습니다. 모든 플랫폼에서 Claude Desktop을 다운로드할 수 있습니다. Linux용 Claude Desktop의 경우, 공식 파일 기반의 비공식 설치 스크립트를 사용할 수 있습니다. 권장 저장소는 https://github.com/emsi/claude-desktop/tree/main 입니다.

Claude Desktop을 설치한 후 아래 지침에 따라 해당 MCP를 설치하세요.

UVX를 사용한 간편한 설치(권장)

Editor MCP를 설치하는 가장 쉬운 방법은 제공된 설치 스크립트를 사용하는 것입니다.

지엑스피1

이 스크립트는 다음을 수행합니다.

1. UVX가 설치되어 있는지 확인하고 필요하면 설치하세요.
2. 개발 모드에서 Editor MCP 설치
3. PATH에서 editor-mcp 명령을 사용할 수 있도록 설정하세요.

수동 설치

UVX 사용

기존 pip 사용

요구 사항 사용(레거시)

잠금 파일에서 설치:

잠긴 요구 사항 파일 생성:

용법

서버 시작

설치 후 다음 방법 중 하나를 사용하여 Editor MCP 서버를 시작할 수 있습니다.

MCP 구성

MCP 구성 파일에 Editor MCP를 추가할 수 있습니다.

환경 변수 구성

Editor MCP는 동작을 사용자 정의하기 위해 여러 환경 변수를 지원합니다.

• MAX_SELECT_LINES : "100" - 단일 작업에서 편집할 수 있는 최대 줄 수(기본값은 50)
• ENABLE_JS_SYNTAX_CHECK : "0" - JavaScript 및 JSX 구문 검사를 활성화/비활성화합니다(기본값은 "1" - 활성화됨)
• FAIL_ON_PYTHON_SYNTAX_ERROR : "1" - 활성화하면 Python 구문 오류가 발생하면 자동으로 덮어쓰기 작업이 취소됩니다(기본값은 활성화됨).
• FAIL_ON_JS_SYNTAX_ERROR : "0" - 활성화 시 JavaScript/JSX 구문 오류 발생 시 자동으로 덮어쓰기 작업이 취소됩니다(기본값은 비활성화됨).
• PROTECTED_PATHS : 액세스할 수 없는 파일 패턴 또는 경로의 쉼표로 구분된 목록, 와일드카드 지원(예: " .env, .env ,/etc/passwd")

소스에서 빌드할 때의 샘플 MCP 구성

사용 가능한 도구

Editor MCP는 파일 조작, 편집 및 테스트를 위한 13가지 강력한 도구를 제공합니다.

1. set_file

현재 작업할 파일을 설정합니다.

매개변수 :

• filepath (str): 파일의 절대 경로

반품 :

• 파일 경로가 포함된 확인 메시지

2. skim

현재 파일에서 전체 텍스트를 읽습니다. 각 줄에는 줄 번호가 접두사로 붙습니다.

반품 :

• 줄 번호, 줄의 총 수, 최대 편집 줄 설정이 포함된 줄 사전

출력 예 :

3. read

현재 파일의 시작 줄부터 끝 줄까지 텍스트를 읽습니다.

매개변수 :

• start (int): 시작 줄 번호(1부터 시작하는 인덱싱)
• end (int): 줄 끝 번호(1부터 시작하는 인덱싱)

반품 :

• 줄 번호를 키로 하는 줄과 시작 및 끝 줄 정보를 포함하는 사전

출력 예 :

4. select

이후 덮어쓰기 작업을 위해 현재 파일에서 줄 범위를 선택합니다.

매개변수 :

• start (int): 시작 줄 번호(1부터 시작)
• end (int): 줄 끝 번호(1부터 시작)

반품 :

• 선택된 라인, 라인 범위, 검증을 위한 ID를 포함하는 사전

메모 :

• 이 도구는 max_select_lines에 대한 선택을 검증합니다.
• 선택 세부 정보는 덮어쓰기 도구에서 사용하기 위해 저장됩니다.
• 덮어쓰기 도구를 호출하기 전에 이것을 사용해야 합니다.

5. overwrite

현재 파일의 특정 줄을 새 텍스트로 덮어쓸 준비를 합니다.

매개변수 :

• new_lines (목록): 선택한 범위를 덮어쓸 새 줄 목록

반품 :

• 제안된 변경 사항을 보여주는 Diff 미리보기

메모 :

• 이는 2단계 프로세스의 첫 번째 단계입니다.
  1. 첫 번째 호출 overwrite()를 사용하여 diff 미리보기를 생성합니다.
  2. 그런 다음 Confirm()을 호출하여 보류 중인 변경 사항을 적용하거나 cancel()을 호출하여 보류 중인 변경 사항을 취소합니다.
• 이 도구를 사용하면 이전에 선택한 줄을 새 콘텐츠로 바꿀 수 있습니다.
• 새로운 줄의 수는 원래 선택과 다를 수 있습니다.
• Python 파일(.py 확장자)의 경우 작성 전에 구문 검사가 수행됩니다.
• JavaScript/React 파일(.js, .jsx 확장자)의 경우 구문 검사는 선택 사항이며 ENABLE_JS_SYNTAX_CHECK 환경 변수를 통해 비활성화할 수 있습니다.

6. confirm

덮어쓰기 작업에서 보류 중인 변경 사항을 적용합니다.

반품 :

• 상태 및 메시지가 포함된 작업 결과

메모 :

• 이는 편집 프로세스의 두 번째 단계에서 가능한 두 가지 작업 중 하나입니다.
• 변경 사항이 성공적으로 적용되면 선택이 제거됩니다.

7. cancel

덮어쓰기 작업에서 보류 중인 변경 사항을 취소합니다.

반품 :

• 상태 및 메시지가 포함된 작업 결과

메모 :

• 이것은 편집 프로세스의 두 번째 단계에서 가능한 두 가지 작업 중 하나입니다.
• 변경 사항이 취소되어도 선택 사항은 그대로 유지됩니다.

8. delete_file

현재 설정된 파일을 삭제합니다.

반품 :

• 상태 및 메시지가 포함된 작업 결과

9. new_file

새로운 파일을 만듭니다.

매개변수 :

• absolute_file_path (str): 새 파일의 경로

반품 :

• 해당되는 경우 콘텐츠의 상태 및 ID가 포함된 작업 결과

메모 :

• 현재 파일이 존재하고 비어 있지 않으면 이 도구는 실패합니다.

10. find_line

현재 파일에서 제공된 텍스트와 일치하는 줄을 찾습니다.

매개변수 :

• search_text (str): 파일에서 검색할 텍스트

반품 :

• 줄 번호와 전체 일치 항목이 포함된 일치하는 줄을 포함하는 사전

출력 예 :

메모 :

• 파일 경로가 설정되지 않으면 오류가 반환됩니다.
• 각 줄 내에서 정확한 텍스트 일치 항목을 검색합니다.
• ID는 후속 편집 작업에 사용될 수 있습니다.

11. find_function

현재 Python 또는 JavaScript/JSX 파일에서 함수나 메서드 정의를 찾습니다.

매개변수 :

• function_name (str): 찾을 함수 또는 메서드의 이름

반품 :

• 줄 번호, 시작 줄, 종료 줄을 포함하는 함수 줄을 포함하는 사전

출력 예 :

메모 :

• Python 파일의 경우 이 도구는 Python의 AST 및 tokenize 모듈을 사용하여 데코레이터 및 docstring을 포함한 함수 경계를 정확하게 식별합니다.
• JavaScript/JSX 파일의 경우 이 도구는 여러 가지 접근 방식을 조합하여 사용합니다.
  • 기본 방법: 사용 가능한 경우 Babel AST 구문 분석(Node.js 및 Babel 패키지 필요)
  • 대체 방법: Babel을 사용할 수 없는 경우 함수 선언에 대한 정규식 패턴 일치
• 표준 함수, 비동기 함수, 화살표 함수, React 후크를 포함한 다양한 JavaScript 함수 유형을 지원합니다.
• 파일 경로가 설정되지 않았거나 함수를 찾을 수 없는 경우 오류를 반환합니다.

12. listdir

디렉토리의 내용을 나열합니다.

매개변수 :

• dirpath (str): 나열할 디렉토리의 경로

반품 :

• 파일 이름 목록과 쿼리된 경로가 포함된 사전

13. run_tests 및 set_python_path

pytest로 Python 테스트를 실행하고 Python 환경을 구성하기 위한 도구입니다.

• JavaScript 구문 검사를 비활성화하려면 "0", "false" 또는 "no"로 설정합니다.
• Babel 및 관련 종속성이 설치되지 않은 경우 유용합니다.
• FAIL_ON_PYTHON_SYNTAX_ERROR : Python 구문 오류가 발생하면 자동으로 덮어쓰기 작업이 취소되는지 여부를 제어합니다(기본값: 1)
  • 활성화된 경우 Python 파일의 구문 오류로 인해 덮어쓰기 작업이 자동으로 취소됩니다.
  • 선은 선택된 상태로 유지되므로 오류를 수정하고 다시 시도할 수 있습니다.
• FAIL_ON_JS_SYNTAX_ERROR : JavaScript/JSX 구문 오류가 자동으로 덮어쓰기 작업을 취소할지 여부를 제어합니다(기본값: 0)
  • 활성화된 경우 JavaScript/JSX 파일의 구문 오류로 인해 덮어쓰기 작업이 자동으로 취소됩니다.
  • 선은 선택된 상태로 유지되므로 오류를 수정하고 다시 시도할 수 있습니다.
• DUCKDB_USAGE_STATS : DuckDB 데이터베이스에서 사용 통계를 수집할지 여부를 제어합니다(기본값: 0)
  • 도구 사용 통계 수집을 활성화하려면 "1", "true" 또는 "yes"로 설정하세요.
  • 활성화하면 타임스탬프와 인수를 포함한 각 도구 호출에 대한 정보가 기록됩니다.
• STATS_DB_PATH : 통계를 위한 DuckDB 데이터베이스가 저장될 경로(기본값: "text_editor_stats.duckdb")
  • DUCKDB_USAGE_STATS 활성화된 경우에만 사용됩니다.
• PROTECTED_PATHS : 액세스가 거부될 파일 패턴 또는 절대 경로의 쉼표로 구분된 목록
  • 예: *.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/credentials.txt
  • 와일드카드를 모든 위치에 사용할 수 있는 정확한 파일 경로와 유연한 글로브 패턴을 모두 지원합니다.
    • *.env - .env , dev.env , prod.env 와 같이 .env로 끝나는 파일과 일치합니다.
    • .env* - .env , .env.local , .env.production 과 같이 .env로 시작하는 파일과 일치합니다.
    • *secret* - 이름에 'secret'이 포함된 모든 파일과 일치합니다.
  • 중요한 구성 파일 및 자격 증명이 실수로 노출되는 것을 방지합니다.
  • 선은 선택된 상태로 유지되므로 오류를 수정하고 다시 시도할 수 있습니다.

개발

필수 조건

editor-mcp에는 다음이 필요합니다.

• 파이썬 3.7 이상
• FastMCP 패키지
• 검정색(Python 코드 형식 검사용)
• Babel(해당 파일로 작업하는 경우 JavaScript/JSX 구문 검사를 위해)

개발 종속성 설치:

JavaScript/JSX 구문 검증을 위해서는 Node.js와 Babel이 필요합니다. 텍스트 편집기는 다음 파일 형식을 편집할 때 npx babel 사용하여 JS/JSX 구문을 검사합니다.

편집자에게는 다음이 필요합니다.

• @babel/core 및 @babel/cli - 구문 검사를 위한 핵심 Babel 패키지
• @babel/preset-env - 표준 JavaScript(.js) 파일용
• @babel/preset-react - React JSX(.jsx) 파일용

테스트 실행

테스트 구조

테스트 모음에는 다음이 포함됩니다.

1. set_file 도구
   • 유효한 파일 설정
   • 존재하지 않는 파일 설정
2. 읽기 도구
   • 파일 상태 검증
   • 전체 파일 읽기
   • 특정 라인 범위 읽기
   • 빈 파일과 같은 예외 상황
   • 잘못된 범위 처리
3. 선택 도구
   • 라인 범위 검증
   • max_select_lines에 대한 선택 검증
   • 후속 작업을 위한 선택 저장소
4. 덮어쓰기 도구
   • ID를 사용하여 선택된 콘텐츠 검증
   • 콘텐츠 교체 검증
   • Python 및 JavaScript/React 파일에 대한 구문 검사
   • 변경 사항에 대한 diff 미리보기 생성
5. 확인 및 취소 도구
   • 보류 중인 변경 사항 적용 또는 취소
   • 2단계 인증 프로세스
6. delete_file 도구
   • 파일 삭제 검증
7. new_file 도구
   • 파일 생성 검증
   • 기존 파일 처리
8. find_line 도구
   • 파일에서 텍스트 일치 항목 찾기
   • 특정 검색어 처리
   • 존재하지 않는 파일에 대한 오류 처리
   • 일치하는 항목이 없는 경우 처리
   • 기존 파일 처리

작동 원리

다단계 편집 접근 방식

LLM이 편집할 줄을 검색하여 바꾸는 것만으로 끝나는 기존 코드 편집 방식(여러 번 편집한 후 혼란이 발생하는 경우가 많음)과 달리 이 편집기는 편집 정확도를 획기적으로 개선하는 구조화된 다단계 워크플로를 구현합니다.

1. set_file - 먼저 LLM은 편집하려는 파일을 설정합니다.
2. skim - LLM은 전체 파일을 읽어 전체적인 개요를 파악합니다.
3. 읽기 - LLM은 더 나은 맥락을 위해 숫자 옆에 줄이 표시된 작업과 관련된 특정 섹션을 조사합니다.
4. 선택 - 편집할 준비가 되면 LLM은 특정 줄을 선택합니다(구성 가능한 개수로 제한됨, 기본값 50)
5. 덮어쓰기 - LLM은 대체 콘텐츠를 제안하여 정확히 무엇이 변경될지 보여주는 git diff 스타일 미리보기를 생성합니다.
6. 확인/취소 - LLM은 미리보기를 검토한 후 변경 사항을 적용하거나 취소할 수 있습니다.

이러한 체계적인 워크플로는 LLM이 각 편집 내용을 신중하게 판단하도록 하고, 실수로 전체 파일을 덮어쓰는 것과 같은 일반적인 오류를 방지합니다. LLM은 변경 내용을 커밋하기 전에 미리 확인하여 편집 내용이 정확한지 확인할 수 있습니다.

신원 확인 시스템

서버는 FastMCP를 사용하여 명확하게 정의된 API를 통해 텍스트 편집 기능을 제공합니다. ID 검증 시스템은 읽기 작업과 수정 작업 사이에 콘텐츠가 변경되지 않았는지 확인하여 데이터 무결성을 보장합니다.

ID 메커니즘은 SHA-256을 사용하여 파일 내용 또는 선택된 줄 범위의 고유 식별자를 생성합니다. 줄별 작업의 경우, ID에는 줄 범위를 나타내는 접두사(예: "L10-15-[해시]")가 포함됩니다. 이를 통해 편집 내용이 예상된 내용에 적용되도록 할 수 있습니다.

구현 세부 사항

주요 TextEditorServer 클래스:

1. "text-editor"라는 FastMCP 인스턴스로 초기화합니다.
2. 환경 변수에서 구성 가능한 max_select_lines 제한(기본값: 50)을 설정합니다.
3. 현재 파일 경로를 상태로 유지합니다.
4. FastMCP를 통해 13개의 주요 도구를 등록합니다.
   • set_file : 현재 파일 경로를 검증하고 설정합니다.
   • skim : 파일의 전체 내용을 읽고 줄 번호 사전을 줄 텍스트로 반환합니다.
   • read : 지정된 줄 범위에서 줄을 읽고 줄 내용의 구조화된 사전을 반환합니다.
   • select : 이후 덮어쓰기 작업을 위한 줄을 선택합니다.
   • overwrite : 새 줄 목록을 가져와서 콘텐츠 변경에 대한 diff 미리보기를 준비합니다.
   • confirm : 덮어쓰기 작업에서 보류 중인 변경 사항을 적용합니다.
   • cancel : 덮어쓰기 작업에서 보류 중인 변경 사항을 취소합니다.
   • delete_file : 현재 파일을 삭제합니다
   • new_file : 새 파일을 만듭니다
   • find_line : 특정 텍스트가 포함된 줄을 찾습니다.
   • find_function : Python 및 JavaScript/JSX 파일에서 함수 또는 메서드 정의를 찾습니다.
   • listdir : 디렉토리의 내용을 나열합니다
   • run_tests 및 set_python_path : Python 테스트 실행 도구

서버는 기본적으로 FastMCP의 stdio 전송을 사용하여 실행되므로 다양한 클라이언트와 쉽게 통합할 수 있습니다.

최상의 결과를 위한 시스템 프롬프트

AI 어시스턴트를 이용해 최적의 결과를 얻으려면 AI가 관리 가능하고 안전한 편집을 수행하도록 안내하는 시스템 프롬프트( system_prompt.md 참조)를 사용하는 것이 좋습니다.

이 시스템 프롬프트는 AI 도우미에게 다음과 같은 도움을 줍니다.

1. 증분적 변경 사항 만들기 - 편집 내용을 더 작은 부분으로 나누기
2. 코드 무결성 유지 - 코드 기능을 유지하는 변경 사항 만들기
3. 리소스 제한 내에서 작업 - 시스템에 과부하를 일으킬 수 있는 작업 방지
4. 검증 워크플로우를 따르세요 - 편집 후 오류에 대한 최종 확인 수행

AI 도우미를 사용할 때 이 시스템 프롬프트를 통합하면 더욱 안정적인 편집 동작을 얻을 수 있고 자동 코드 편집에서 흔히 저지르는 실수를 피할 수 있습니다.

사용 통계

텍스트 편집기 MCP를 활성화하면 사용 통계를 수집하여 편집 도구가 어떻게 사용되고 있는지에 대한 통찰력을 제공할 수 있습니다.

• 데이터 수집 : DUCKDB_USAGE_STATS 활성화되면 DuckDB 데이터베이스에 통계가 수집됩니다.
• 추적된 정보 : 도구 이름, 인수, 타임스탬프, 현재 파일 경로, 도구 응답 및 요청/클라이언트 ID를 기록합니다.
• 저장 위치 : 데이터는 STATS_DB_PATH 로 지정된 DuckDB 파일에 저장됩니다.
• 개인정보 보호 : 모든 것이 로컬 컴퓨터에 저장됩니다.

수집된 통계는 사용 패턴을 이해하고, 일반적인 워크플로를 파악하고, 가장 빈번한 작업에 맞게 편집기를 최적화하는 데 도움이 될 수 있습니다.

DuckDB 클라이언트를 통해 표준 SQL을 사용하여 데이터베이스를 쿼리하여 사용 패턴을 분석할 수 있습니다.

문제 해결

문제가 발생하는 경우:

1. 파일 권한 확인
2. 파일 경로가 절대 경로인지 확인하세요
3. 환경이 Python 3.7+를 사용하고 있는지 확인하세요.

영감

비슷한 프로젝트에서 영감을 얻었습니다: https://github.com/tumf/mcp-text-editor . 처음에는 포크했지만, 전반적인 아이디어만 그대로 유지하기 위해 전체 코드베이스를 처음부터 다시 쓰기로 결정했습니다.