MCP Text Editor Server

Model Context Protocol (MCP) sunucusu, standardlaştırılmış bir API üzerinden satır odaklı metin dosyası düzenleme yetenekleri sağlar. LLM araçları için optimize edilmiş, token kullanımını en aza indirmek için verimli kısmi dosya erişimi.

Claude.app Kullanıcıları için Hızlı Başlangıç

Bu editörü Claude.app ile kullanmak için aşağıdaki konfigürasyonu eklemeniz gerekmektedir:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

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

Genel Bakış

MCP Text Editor Server, istemci-sunucu mimarisinde güvenli ve verimli satır tabanlı metin dosyası işlemlerini kolaylaştırmak için tasarlanmıştır. Model Context Protocol'ü uygular, güçlü çakışma algılama ve çözümü ile güvenilir dosya düzenlemesi sağlar. Satır odaklı yaklaşım, senkronize dosya erişimi gerektiren uygulamalar için ideal hale getiriyor; örneğin işbirlikçi düzenleme araçları, otomatik metin işleme sistemleri veya birden fazla işlemin metin dosyalarını güvenli bir şekilde değiştirmesi gereken her senaryo. Kısmi dosya erişim yeteneği, LLM tabanlı araçlar için özellikle değerlidir çünkü yalnızca gerekli dosya bölümlerini yükleyerek token tüketimini azaltmaya yardımcı olur.

Ana Faydalar

• Satır tabanlı düzenleme işlemleri
• Satır aralığı belirtimlerinde token-verimli kısmi dosya erişimi
• LLM araç entegrasyonu için optimize edilmiş
• Hash tabanlı doğrulama ile güvenli eşzamanlı düzenleme
• Atomik çok dosyalı işlemler
• Özel hata türleri ile sağlam hata işleme
• Kapsamlı kodlama desteği (utf-8, shift_jis, latin1, vb.)

Özellikler

• Satır odaklı metin dosyası düzenleme ve okuma
• LLM uygulamalarında token kullanımını en aza indirmek için akıllı kısmi dosya erişimi
• Satır aralığı belirtimi ile metin dosyası içeriğini al
• Tek bir işlemde birden fazla dosyadan birden fazla aralık oku
• Satır numarası kaymalarını doğru şekilde işleyen satır tabanlı patch uygulaması
• Çakışma algılama ile metin dosyası içeriğini düzenle
• Esnek karakter kodlama desteği (utf-8, shift_jis, latin1, vb.)
• Birden fazla dosya operasyonları desteği
• Hash tabanlı doğrulama ile eşzamanlı düzenlemelerin düzgün işlenmesi
• Büyük dosyaların bellek-verimli işlenmesi

Gereksinimler

• Python 3.11 veya daha yükseği
• POSIX uyumlu işletim sistemi (Linux, macOS, vb.) veya Windows
• Metin dosyası işlemleri için yeterli disk alanı
• Okuma/yazma işlemleri için dosya sistemi izinleri

1. Python 3.11+ yükleyin

pyenv install 3.11.6
pyenv local 3.11.6

2. uv (önerilen) veya pip yükleyin

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

3. Sanal ortam oluşturun ve bağımlılıkları yükleyin

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

Gereksinimler

• Python 3.13+
• POSIX uyumlu işletim sistemi (Linux, macOS, vb.) veya Windows
• Okuma/yazma işlemleri için dosya sistemi izinleri

Kurulum

uvx ile Çalıştırın

uvx mcp-text-editor

Smithery Üzerinden Kurulum

Text Editor Server'ı Claude Desktop'a Smithery üzerinden otomatik olarak kurmak için:

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

Manuel Kurulum

1. Python 3.13+ yükleyin

pyenv install 3.13.0
pyenv local 3.13.0

2. uv (önerilen) veya pip yükleyin

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

3. Sanal ortam oluşturun ve bağımlılıkları yükleyin

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

Kullanım

Sunucuyu başlatın:

python -m mcp_text_editor

MCP Tools

Sunucu, metin dosyası manipülasyonu için birkaç araç sağlar:

get_text_file_contents

Bir veya daha fazla metin dosyasının içeriğini satır aralığı belirtimi ile alın.

Tek Aralık İsteği:

{
  "file_path": "path/to/file.txt",
  "line_start": 1,
  "line_end": 10,
  "encoding": "utf-8"  // İsteğe bağlı, varsayılan utf-8
}

Birden Fazla Aralık İsteği:

{
  "files": [
    {
      "file_path": "file1.txt",
      "ranges": [
        {"start": 1, "end": 10},
        {"start": 20, "end": 30}
      ],
      "encoding": "shift_jis"  // İsteğe bağlı, varsayılan utf-8
    },
    {
      "file_path": "file2.txt",
      "ranges": [
        {"start": 5, "end": 15}
      ]
    }
  ]
}

Parametreler:

• file_path: Metin dosyasının yolu
• line_start/start: Başlanacak satır numarası (1 tabanlı)
• line_end/end: Bitecek satır numarası (kapsayıcı, dosyanın sonu için null)
• encoding: Dosya kodlaması (varsayılan: "utf-8"). Metin dosyasının kodlamasını belirtin (örneğin, "shift_jis", "latin1")

Tek Aralık Yanıtı:

{
  "contents": "Dosya içeriği",
  "line_start": 1,
  "line_end": 10,
  "hash": "sha256-hash-of-contents",
  "file_lines": 50,
  "file_size": 1024
}

Birden Fazla Aralık Yanıtı:

{
  "file1.txt": [
    {
      "content": "Satırlar 1-10 içeriği",
      "start": 1,
      "end": 10,
      "hash": "sha256-hash-1",
      "total_lines": 50,
      "content_size": 512
    },
    {
      "content": "Satırlar 20-30 içeriği",
      "start": 20,
      "end": 30,
      "hash": "sha256-hash-2",
      "total_lines": 50,
      "content_size": 512
    }
  ],
  "file2.txt": [
    {
      "content": "Satırlar 5-15 içeriği",
      "start": 5,
      "end": 15,
      "hash": "sha256-hash-3",
      "total_lines": 30,
      "content_size": 256
    }
  ]
}

patch_text_file_contents

Sağlam hata işleme ve çakışma algılama ile metin dosyalarına patch'ler uygulayın. Tek bir işlemde birden fazla dosyayı düzenlemeyi destekler.

İstek Formatı:

{
  "files": [
    {
      "file_path": "file1.txt",
      "hash": "sha256-hash-from-get-contents",
      "encoding": "utf-8",  // İsteğe bağlı, varsayılan utf-8
      "patches": [
        {
          "start": 5,
          "end": 8,
          "range_hash": "sha256-hash-of-content-being-replaced",
          "contents": "Satırlar 5-8 için yeni içerik\n"
        },
        {
          "start": 15,
          "end": null,  // null, dosyanın sonunu ifade eder
          "range_hash": "sha256-hash-of-content-being-replaced",
          "contents": "Eklenecek içerik\n"
        }
      ]
    }
  ]
}

Önemli Notlar:

1. Düzenlemeden önce her zaman get_text_file_contents kullanarak mevcut hash ve range_hash'ı alın
2. Patch'ler satır numarası kaymalarını doğru şekilde işlemek için aşağıdan yukarıya uygulanır
3. Patch'ler aynı dosya içinde çakışmamalıdır
4. Satır numaraları 1 tabanlıdır
5. end: null dosyanın sonuna içerik eklemek için kullanılabilir
6. Dosya kodlaması, get_text_file_contents içinde kullanılan kodlamaya uymalıdır

Başarılı Yanıt:

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

İpuçlarını İçeren Hata Yanıtı:

{
  "file1.txt": {
    "result": "error",
    "reason": "Content hash mismatch",
    "suggestion": "get",  // get_text_file_contents kullanmayı önerir
    "hint": "Lütfen mevcut içerik ve hash'ları almak için önce get_text_file_contents'i çalıştırın"
  }
}

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

} }

### Yaygın Kullanım Deseni

1. Mevcut içeriği ve hash'ı alın:

```python
contents = await get_text_file_contents({
    "files": [
        {
            "file_path": "file.txt",
            "ranges": [{"start": 1, "end": null}]  # Tüm dosyayı oku
        }
    ]
})

2. Dosya içeriğini düzenleyin:

result = await edit_text_file_contents({
    "files": [
        {
            "path": "file.txt",
            "hash": contents["file.txt"][0]["hash"],
            "encoding": "utf-8",  // İsteğe bağlı, varsayılan "utf-8"
            "patches": [
                {
                    "line_start": 5,
                    "line_end": 8,
                    "contents": "Yeni içerik\n"
                }
            ]
        }
    ]
})

3. Çakışmaları işleyin:

if result["file.txt"]["result"] == "error":
    if "hash mismatch" in result["file.txt"]["reason"]:
        # Dosya başka bir işlem tarafından değiştirildi
        # Yeni içerik alın ve tekrar deneyin
        pass

Hata İşleme

Sunucu çeşitli hata durumlarını işler:

• Dosya bulunamadı
• İzin hataları
• Hash uyuşmazlıkları (eşzamanlı düzenleme algılama)
• Geçersiz patch aralıkları
• Çakışan patch'ler
• Kodlama hataları (dosya belirtilen kodlamaya çözülemezse)
• Satır numarası sınırı dışında

Güvenlik Önerileri

• Dosya Yolu Doğrulaması: Sunucu, dizin geçiş saldırılarını önlemek için tüm dosya yollarını doğrular
• Erişim Kontrolü: Yetkili dizinlere erişimi kısıtlamak için uygun dosya sistemi izinleri ayarlanmalıdır
• Hash Doğrulaması: Tüm dosya değişiklikleri, yarış koşullarını önlemek için SHA-256 hash'ları kullanılarak doğrulanır
• Giriş Sanitasyonu: Tüm kullanıcı girdileri düzgün şekilde temizlenir ve doğrulanır
• Hata İşleme: Hassas bilgiler hata mesajlarında açığa çıkarılmaz

Sorun Giderme

Yaygın Sorunlar

1. İzin Reddedildi

   • Dosya ve dizin izinlerini kontrol edin
   • Sunucu işleminin gerekli okuma/yazma erişimi olduğundan emin olun

2. Hash Uyuşmazlığı ve Range Hash Hataları

   • Dosya başka bir işlem tarafından değiştirildi
   • Değiştirilen içerik değişti
   • Yeni hash'ları almak için get_text_file_contents çalıştırın

3. Kodlama Sorunları

   • Dosya kodlamasının belirtilen kodlamaya uyduğunu doğrulayın
   • Yeni dosyalar için utf-8 kullanın
   • Dosyalardaki BOM işaretlerini kontrol edin

4. Bağlantı Sorunları

   • Sunucunun çalıştığını ve erişilebilir olduğunu doğrulayın
   • Ağ yapılandırması ve güvenlik duvarı ayarlarını kontrol edin

5. Performans Sorunları

   • Büyük dosyalar için daha küçük satır aralıkları kullanmayı düşünün
   • Sistem kaynaklarını (bellek, disk alanı) izleyin
   • Dosya türü için uygun kodlama kullanın

Geliştirme

Kurulum

1. Repository'yi klonlayın
2. Python sanal ortamı oluşturun ve etkinleştirin
3. Geliştirme bağımlılıklarını yükleyin: uv pip install -e ".[dev]"
4. Testleri çalıştırın: make all

Kod Kalitesi Araçları

• Ruff linting için
• Black kod formatlaması için
• isort import sıralaması için
• mypy tip kontrolü için
• pytest-cov test kapsamı için

Test Etme

Testler tests dizininde bulunur ve pytest ile çalıştırılabilir:

# Tüm testleri çalıştır
pytest

# Kapsam raporu ile testleri çalıştır
pytest --cov=mcp_text_editor --cov-report=term-missing

# Belirli test dosyasını çalıştır
pytest tests/test_text_editor.py -v

Mevcut test kapsamı: 90%

Proje Yapısı

mcp-text-editor/
├── mcp_text_editor/
│   ├── __init__.py
│   ├── __main__.py      # Giriş noktası
│   ├── models.py        # Veri modelleri
│   ├── server.py        # MCP Sunucu uygulaması
│   ├── service.py       # Çekirdek hizmet mantığı
│   └── text_editor.py   # Metin editörü işlevselliği
├── tests/               # Test dosyaları
└── pyproject.toml       # Proje yapılandırması

Lisans

MIT

Katkı

1. Repository'yi fork edin
2. Bir özellik dalı oluşturun
3. Değişikliklerinizi yapın
4. Testleri ve kod kalitesi kontrollerini çalıştırın
5. Pull request gönderin

Tip İpuçları

Bu proje, kodun tamamında Python tip ipuçlarını kullanır. Lütfen herhangi bir katkının bunu koruduğundan emin olun.

Hata İşleme

Tüm hata durumları uygun şekilde işlenmelidir ve anlamlı hata mesajları döndürmelidir. Sunucu, geçersiz giriş veya dosya işlemleri nedeniyle hiçbir zaman çökmemelidir.

Test Etme

Yeni özellikler uygun testleri içermelidir. Mevcut test kapsamını korumaya veya geliştirmeye çalışın.

Kod Stili

Tüm kod Black ile formatlanmalı ve Ruff linting'ini geçmelidir. İmport sıralaması isort tarafından işlenmelidir.