MCP 텍스트 편집기 서버

표준화된 API를 통해 줄 단위 텍스트 파일 편집 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 효율적인 부분 파일 접근을 통해 토큰 사용량을 최소화하는 LLM 도구에 최적화되어 있습니다.

Claude.app 사용자를 위한 빠른 시작

Claude.app과 함께 이 편집기를 사용하려면 프롬프트에 다음 구성을 추가하세요.

지엑스피1

{
  "mcpServers": {
    "text-editor": {
      "command": "uvx",
      "args": [
        "mcp-text-editor"
      ]
    }
  }
}

또는 docker를 사용하여:

{
  "mcpServers": {
    "text-editor": {
      "command": "docker",
      "args": [
          "run",
          "-i",
          "--rm",
          "--mount",
          "type=bind,src=/some/path/src,dst=/some/path/dst",
          "mcp/text-editor"
      ]
    }
  }
}

개요

MCP 텍스트 편집기 서버는 클라이언트-서버 아키텍처에서 안전하고 효율적인 라인 기반 텍스트 파일 작업을 지원하도록 설계되었습니다. 모델 컨텍스트 프로토콜(Model Context Protocol)을 구현하여 강력한 충돌 감지 및 해결 기능을 통해 안정적인 파일 편집을 보장합니다. 라인 기반 접근 방식은 협업 편집 도구, 자동 텍스트 처리 시스템 또는 여러 프로세스가 텍스트 파일을 안전하게 수정해야 하는 시나리오와 같이 동기화된 파일 액세스가 필요한 애플리케이션에 이상적입니다. 부분 파일 액세스 기능은 파일의 필요한 부분만 로드하여 토큰 소모를 줄이는 데 도움이 되므로 LLM 기반 도구에 특히 유용합니다.

주요 이점

라인 기반 편집 작업
라인 범위 사양을 사용한 토큰 효율적인 부분 파일 액세스
LLM 도구 통합을 위해 최적화됨
해시 기반 검증을 통한 안전한 동시 편집
원자적 다중 파일 작업
사용자 정의 오류 유형을 통한 강력한 오류 처리
포괄적인 인코딩 지원(utf-8, shift_jis, latin1 등)

특징

줄 중심 텍스트 파일 편집 및 읽기
LLM 애플리케이션에서 토큰 사용을 최소화하기 위한 스마트 부분 파일 액세스
줄 범위 지정을 사용하여 텍스트 파일 내용 가져오기
단일 작업으로 여러 파일에서 여러 범위를 읽습니다.
줄 번호 이동을 올바르게 처리하는 줄 기반 패치 애플리케이션
충돌 감지를 통해 텍스트 파일 내용 편집
유연한 문자 인코딩 지원(utf-8, shift_jis, latin1 등)
여러 파일 작업 지원
해시 기반 검증을 통한 동시 편집의 적절한 처리
대용량 파일의 메모리 효율적 처리

요구 사항

Python 3.11 이상
POSIX 호환 운영 체제(Linux, macOS 등) 또는 Windows
텍스트 파일 작업을 위한 충분한 디스크 공간
읽기/쓰기 작업에 대한 파일 시스템 권한

Python 3.11+ 설치

pyenv install 3.11.6
pyenv local 3.11.6

uv(권장) 또는 pip 설치

curl -LsSf https://astral.sh/uv/install.sh | sh

가상 환경을 생성하고 종속성을 설치합니다.

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

요구 사항

파이썬 3.13+
POSIX 호환 운영 체제(Linux, macOS 등) 또는 Windows
읽기/쓰기 작업에 대한 파일 시스템 권한

설치

uvx를 통해 실행

uvx mcp-text-editor

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Text Editor Server를 자동으로 설치하려면:

npx -y @smithery/cli install mcp-text-editor --client claude

수동 설치

Python 3.13+ 설치

pyenv install 3.13.0
pyenv local 3.13.0

도커 설치

docker build --network=host -t mcp/text-editor .

uv(권장) 또는 pip를 설치하세요

curl -LsSf https://astral.sh/uv/install.sh | sh

가상 환경을 생성하고 종속성을 설치합니다.

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

용법

서버를 시작합니다:

python -m mcp_text_editor

docker로 서버를 시작합니다.

docker run -i --rm --mount "type=bind,src=/some/path/src,dst=/some/path/dst" mcp/text-editor

검사관과 함께:

npx @modelcontextprotocol/inspector docker run -i --rm --mount "type=bind,src=/some/path/src,dst=/some/path/dst" mcp/text-editor

MCP 도구

서버는 텍스트 파일 조작을 위한 여러 도구를 제공합니다.

텍스트 파일 내용 가져오기

줄 범위 지정을 통해 하나 이상의 텍스트 파일의 내용을 가져옵니다.

단일 범위 요청:

{
  "file_path": "path/to/file.txt",
  "line_start": 1,
  "line_end": 10,
  "encoding": "utf-8"  // Optional, defaults to utf-8
}

여러 범위 요청:

{
  "files": [
    {
      "file_path": "file1.txt",
      "ranges": [
        {"start": 1, "end": 10},
        {"start": 20, "end": 30}
      ],
      "encoding": "shift_jis"  // Optional, defaults to utf-8
    },
    {
      "file_path": "file2.txt",
      "ranges": [
        {"start": 5, "end": 15}
      ]
    }
  ]
}

매개변수:

file_path : 텍스트 파일의 경로
line_start / start : 시작할 줄 번호(1부터 시작)
line_end / end : 종료할 줄 번호 (포함, 파일 끝의 경우 null)
encoding : 파일 인코딩(기본값: "utf-8"). 텍스트 파일의 인코딩을 지정합니다(예: "shift_jis", "latin1").

단일 범위 응답:

{
  "contents": "File contents",
  "line_start": 1,
  "line_end": 10,
  "hash": "sha256-hash-of-contents",
  "file_lines": 50,
  "file_size": 1024
}

다중 범위 응답:

{
  "file1.txt": [
    {
      "content": "Lines 1-10 content",
      "start": 1,
      "end": 10,
      "hash": "sha256-hash-1",
      "total_lines": 50,
      "content_size": 512
    },
    {
      "content": "Lines 20-30 content",
      "start": 20,
      "end": 30,
      "hash": "sha256-hash-2",
      "total_lines": 50,
      "content_size": 512
    }
  ],
  "file2.txt": [
    {
      "content": "Lines 5-15 content",
      "start": 5,
      "end": 15,
      "hash": "sha256-hash-3",
      "total_lines": 30,
      "content_size": 256
    }
  ]
}

패치_텍스트_파일_내용

강력한 오류 처리 및 충돌 감지 기능을 통해 텍스트 파일에 패치를 적용합니다. 단일 작업으로 여러 파일을 편집할 수 있습니다.

요청 형식:

{
  "files": [
    {
      "file_path": "file1.txt",
      "hash": "sha256-hash-from-get-contents",
      "encoding": "utf-8",  // Optional, defaults to utf-8
      "patches": [
        {
          "start": 5,
          "end": 8,
          "range_hash": "sha256-hash-of-content-being-replaced",
          "contents": "New content for lines 5-8\n"
        },
        {
          "start": 15,
          "end": null,  // null means end of file
          "range_hash": "sha256-hash-of-content-being-replaced",
          "contents": "Content to append\n"
        }
      ]
    }
  ]
}

중요 참고 사항:

편집하기 전에 항상 get_text_file_contents를 사용하여 현재 해시와 range_hash를 가져옵니다.
패치는 줄 번호 이동을 올바르게 처리하기 위해 아래에서 위로 적용됩니다.
패치는 동일한 파일 내에서 겹치면 안 됩니다.
줄 번호는 1부터 시작합니다.
end: null 파일 끝에 내용을 추가하는 데 사용할 수 있습니다.
파일 인코딩은 get_text_file_contents에서 사용된 인코딩과 일치해야 합니다.

성공 응답:

{
  "file1.txt": {
    "result": "ok",
    "hash": "sha256-hash-of-new-contents"
  }
}

힌트가 포함된 오류 응답:

{
  "file1.txt": {
    "result": "error",
    "reason": "Content hash mismatch",
    "suggestion": "get",  // Suggests using get_text_file_contents
    "hint": "Please run get_text_file_contents first to get current content and hashes"
  }
}

"result": "error",
"reason": "Content hash mismatch - file was modified",
"hash": "current-hash",
"content": "Current file content"

} }

### Common Usage Pattern

1. Get current content and hash:

```python
contents = await get_text_file_contents({
    "files": [
        {
            "file_path": "file.txt",
            "ranges": [{"start": 1, "end": null}]  # Read entire file
        }
    ]
})

파일 내용 편집:

result = await edit_text_file_contents({
    "files": [
        {
            "path": "file.txt",
            "hash": contents["file.txt"][0]["hash"],
            "encoding": "utf-8",  # Optional, defaults to "utf-8"
            "patches": [
                {
                    "line_start": 5,
                    "line_end": 8,
                    "contents": "New content\n"
                }
            ]
        }
    ]
})

갈등을 처리하세요:

if result["file.txt"]["result"] == "error":
    if "hash mismatch" in result["file.txt"]["reason"]:
        # File was modified by another process
        # Get new content and retry
        pass

오류 처리

서버는 다양한 오류 사례를 처리합니다.

파일을 찾을 수 없습니다
권한 오류
해시 불일치(동시 편집 감지)
잘못된 패치 범위
겹치는 패치
인코딩 오류(파일을 지정된 인코딩으로 디코딩할 수 없는 경우)
줄 번호가 범위를 벗어났습니다.

보안 고려 사항

파일 경로 검증: 서버는 디렉토리 트래버설 공격을 방지하기 위해 모든 파일 경로를 검증합니다.
액세스 제어: 권한이 있는 디렉토리에 대한 액세스를 제한하려면 적절한 파일 시스템 권한을 설정해야 합니다.
해시 검증: 모든 파일 수정 사항은 경쟁 조건을 방지하기 위해 SHA-256 해시를 사용하여 검증됩니다.
입력 정리: 모든 사용자 입력은 적절하게 정리되고 검증됩니다.
오류 처리: 오류 메시지에 민감한 정보가 노출되지 않습니다.

문제 해결

일반적인 문제

허가 거부됨
- 파일 및 디렉토리 권한 확인
- 서버 프로세스에 필요한 읽기/쓰기 액세스 권한이 있는지 확인하세요.
해시 불일치 및 범위 해시 오류
- 파일이 다른 프로세스에 의해 수정되었습니다.
- 교체되는 콘텐츠가 변경되었습니다.
- get_text_file_contents를 실행하여 최신 해시를 얻으세요.
인코딩 문제
- 파일 인코딩이 지정된 인코딩과 일치하는지 확인하세요.
- 새 파일에는 utf-8을 사용하세요
- 파일에서 BOM 마커 확인
연결 문제
- 서버가 실행 중이고 접근 가능한지 확인하세요.
- 네트워크 구성 및 방화벽 설정을 확인하세요
성능 문제
- 대용량 파일의 경우 더 작은 줄 범위를 사용하는 것을 고려하세요.
- 시스템 리소스(메모리, 디스크 공간) 모니터링
- 파일 유형에 적합한 인코딩을 사용하세요

개발

설정

저장소를 복제합니다
Python 가상 환경 생성 및 활성화
개발 종속성 설치: uv pip install -e ".[dev]"
테스트 실행: make all

코드 품질 도구

린팅용 러프
코드 서식을 위한 검정색
수입 정렬을 위한 isort
유형 검사를 위한 mypy
테스트 커버리지를 위한 pytest-cov

테스트

테스트는 tests 디렉토리에 있으며 pytest로 실행할 수 있습니다.

# Run all tests
pytest

# Run tests with coverage report
pytest --cov=mcp_text_editor --cov-report=term-missing

# Run specific test file
pytest tests/test_text_editor.py -v

현재 테스트 범위: 90%

프로젝트 구조

mcp-text-editor/
├── mcp_text_editor/
│   ├── __init__.py
│   ├── __main__.py      # Entry point
│   ├── models.py        # Data models
│   ├── server.py        # MCP Server implementation
│   ├── service.py       # Core service logic
│   └── text_editor.py   # Text editor functionality
├── tests/               # Test files
└── pyproject.toml       # Project configuration

특허

MIT

기여하다

저장소를 포크하세요
기능 브랜치 생성
변경 사항을 만드세요
테스트 실행 및 코드 품질 검사
풀 리퀘스트 제출

유형 힌트

이 프로젝트는 코드베이스 전체에서 Python 타입 힌트를 사용합니다. 모든 기여는 이 힌트를 유지해야 합니다.

오류 처리

모든 오류 사례는 적절하게 처리되어야 하며, 의미 있는 오류 메시지를 반환해야 합니다. 서버는 잘못된 입력이나 파일 작업으로 인해 충돌해서는 안 됩니다.

테스트

새로운 기능에는 적절한 테스트가 포함되어야 합니다. 현재 테스트 범위를 유지하거나 개선해 보세요.

코드 스타일

모든 코드는 Black으로 포맷하고 Ruff 린팅을 통과해야 합니다. 가져오기 정렬은 isort로 처리해야 합니다.

mcp-text-editor

Integrations

MCP 텍스트 편집기 서버

Claude.app 사용자를 위한 빠른 시작

개요

주요 이점

특징

요구 사항

요구 사항

설치

uvx를 통해 실행

Smithery를 통해 설치

수동 설치

도커 설치

용법

MCP 도구

텍스트 파일 내용 가져오기

패치_텍스트_파일_내용

오류 처리

보안 고려 사항

문제 해결

일반적인 문제

개발

설정

코드 품질 도구

테스트

프로젝트 구조

특허

기여하다

유형 힌트

오류 처리

테스트

코드 스타일

Tools

Appeared in Searches