MCP Text Editor Server

MCP テキストエディターサーバー

標準化された API を通じて、行単位のテキストファイル編集機能を提供する Model Context Protocol（MCP）サーバーです。トークンの使用量を最小限に抑えるため、効率的な部分的ファイルアクセスを備え、LLM ツール向けに最適化されています。

Claude.app ユーザー向けクイックスタート

このエディターを Claude.app で使用するには、次の設定をプロンプトに追加してください。

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

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

概要

MCP Text Editor Server は、クライアント・サーバーアーキテクチャで、安全かつ効率的な行ベースのテキストファイル操作を実現するように設計されています。Model Context Protocol を実装しており、堅牢な競合検出と解決によって信頼性の高いファイル編集を実現します。行指向のアプローチは、共同編集ツール、自動テキスト処理システム、安全にテキストファイルを変更する必要がある複数プロセスのシナリオなど、同期されたファイルアクセスが必要なアプリケーションに最適です。部分的なファイルアクセス機能は、必要なファイル部分のみを読み込むことでトークン消費量を削減できるため、LLM ベースのツールにとって特に有用です。

主なメリット

• 行ベースの編集操作
• 行範囲を指定した、トークン効率の高い部分的ファイルアクセス
• LLM ツールとの連携に最適化
• ハッシュベースの検証による安全な並行編集
• 複数ファイルに対するアトミック操作
• カスタムエラー型による堅牢なエラー処理
• 幅広いエンコーディングに対応（utf-8、shift_jis、latin1 など）

機能

• 行指向のテキストファイル編集と読み取り
• LLM アプリケーションでのトークン使用量を最小限に抑える、スマートな部分的ファイルアクセス
• 行範囲を指定したテキストファイルの内容の取得
• 1 回の操作で複数ファイルから複数の範囲を読み取り
• 行番号のずれを適切に処理する、行ベースのパッチ適用
• 競合検出を備えたテキストファイルの編集
• 柔軟な文字エンコーディングへの対応（utf-8、shift_jis、latin1 など）
• 複数ファイル操作への対応
• ハッシュベースの検証による、並行編集の適切な処理
• 大容量ファイルのメモリー効率に優れた処理

要件

• Python 3.11 以降
• POSIX 準拠のオペレーティングシステム（Linux、macOS など）または Windows
• テキストファイル操作に必要なディスク容量
• 読み取り／書き込み操作のためのファイルシステム権限

1. Python 3.11 以降をインストールします

pyenv install 3.11.6
pyenv local 3.11.6

2. uv（推奨）または pip をインストールします

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

3. 仮想環境を作成し、依存関係をインストールします

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

要件

• Python 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

手動インストール

1. Python 3.13 以降をインストールします

pyenv install 3.13.0
pyenv local 3.13.0

2. uv（推奨）または pip をインストールします

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

3. 仮想環境を作成し、依存関係をインストールします

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

使用方法

サーバーを起動します：

python -m mcp_text_editor

MCP ツール

サーバーは、テキストファイルを操作するための複数のツールを提供します。

get_text_file_contents

行範囲を指定して、1つ以上のテキストファイルの内容を取得します。

リクエスト：

このツールはfiles配列を受け取ります。各ファイルには、startとendを使用して1つ以上の行範囲を指定します。ファイルパスは絶対パスである必要があります。

{
  "files": [
    {
      "file_path": "/absolute/path/to/file.txt",
      "ranges": [
        {"start": 1, "end": 10},
        {"start": 20, "end": null}
      ]
    }
  ],
  "encoding": "utf-8"
}

パラメーター：

• file_path：テキストファイルの絶対パス
• start：読み取る最初の行（1始まり）
• end：読み取る最後の行（この行を含む）。nullの場合はファイルの末尾まで読み取ります
• encoding：リクエストしたすべてのファイルのエンコーディング（デフォルト：utf-8）

レスポンス：

最上位のオブジェクトのキーには絶対ファイルパスが使用されます。file_hashはファイル全体の状態を保護し、各range_hashは対応する範囲を保護します。

{
  "/absolute/path/to/file.txt": {
    "file_hash": "sha256-hash-of-the-file",
    "ranges": [
      {
        "content": "Lines 1-10 content",
        "start": 1,
        "end": 10,
        "range_hash": "sha256-hash-of-this-range",
        "total_lines": 50,
        "content_size": 512
      }
    ]
  }
}

patch_text_file_contents

1つのファイルに、重複しないパッチを1つ以上適用します。対象範囲を先に読み取り、現在のfile_hashと、一致する各range_hashを渡してください。

リクエスト：

{
  "file_path": "/absolute/path/to/file.txt",
  "file_hash": "sha256-hash-from-get-response",
  "patches": [
    {
      "start": 5,
      "end": 8,
      "range_hash": "sha256-hash-of-lines-5-through-8",
      "contents": "New content for lines 5-8\n"
    }
  ],
  "encoding": "utf-8"
}

重要な注意事項：

1. 編集の直前にget_text_file_contentsで最新のハッシュを取得してください。
2. startとendを使用してください。line_startとline_endは受け付けられません。
3. パッチは下から上の順に適用され、重複してはなりません。
4. 行番号は1始まりです。
5. 専用の操作には、append_text_file_contents、insert_text_file_contents、またはdelete_text_file_contentsを使用してください。
6. 読み取りとパッチの呼び出しでは、同じエンコーディングを使用してください。

成功レスポンス：

{
  "result": "ok",
  "file_hash": "sha256-hash-of-new-file-contents",
  "reason": null,
  "suggestion": null,
  "hint": null
}

エラーレスポンス：

{
  "result": "error",
  "reason": "Content range hash mismatch",
  "suggestion": "get",
  "hint": "Please run get_text_file_contents first to get current content and hashes"
}

一般的な使用パターン

1. 置換する正確な範囲に対してget_text_file_contentsを呼び出します。
2. キー付きレスポンスからfile_hashと、その範囲のrange_hashを読み取ります。
3. それらのハッシュと同じ範囲を指定して、patch_text_file_contentsを呼び出します。
4. 結果がエラーの場合は、再試行する前にファイルを再度読み取ります。

path = "/absolute/path/to/file.txt"
contents = await get_text_file_contents({
    "files": [{
        "file_path": path,
        "ranges": [{"start": 5, "end": 8}]
    }]
})
file_info = contents[path]
selected_range = file_info["ranges"][0]

result = await patch_text_file_contents({
    "file_path": path,
    "file_hash": file_info["file_hash"],
    "patches": [{
        "start": 5,
        "end": 8,
        "range_hash": selected_range["range_hash"],
        "contents": "New content\n"
    }]
})

エラー処理

サーバーはさまざまなエラーケースに対応します：

• ファイルが見つからない
• 権限エラー
• ハッシュの不一致（同時編集の検出）
• 無効なパッチ範囲
• パッチの重複
• エンコーディングエラー（指定されたエンコーディングでファイルをデコードできない場合）
• 行番号が範囲外

セキュリティに関する考慮事項

• ファイルパスの検証：サーバーは、ディレクトリトラバーサル攻撃を防ぐため、すべてのファイルパスを検証します
• アクセス制御：許可されたディレクトリへのアクセスを制限するため、適切なファイルシステム権限を設定してください
• ハッシュの検証：競合状態を防ぐため、すべてのファイル変更をSHA-256ハッシュで検証します
• 入力のサニタイズ：すべてのユーザー入力を適切にサニタイズし、検証します
• エラー処理：エラーメッセージで機密情報を公開しません

トラブルシューティング

よくある問題

1. アクセス拒否

   • ファイルとディレクトリの権限を確認してください
   • サーバープロセスに必要な読み取り／書き込みアクセス権があることを確認してください

2. ハッシュの不一致と範囲ハッシュのエラー

   • 別のプロセスによってファイルが変更されました
   • 置換対象の内容が変更されています
   • get_text_file_contentsを実行して最新のハッシュを取得してください

3. エンコーディングの問題

   • ファイルのエンコーディングが指定したエンコーディングと一致していることを確認してください
   • 新しいファイルにはutf-8を使用してください
   • ファイルにBOMマーカーがないか確認してください

4. 接続の問題

   • サーバーが実行中でアクセス可能であることを確認してください
   • ネットワーク設定とファイアウォールの設定を確認してください

5. パフォーマンスの問題

   • 大きなファイルでは、より小さな行範囲を使用することを検討してください
   • システムリソース（メモリ、ディスク容量）を監視してください
   • ファイルの種類に適したエンコーディングを使用してください

開発

セットアップ

1. リポジトリをクローンします
2. Python仮想環境を作成して有効化します
3. 開発用依存関係をインストールします：uv pip install -e ".[dev]"
4. テストを実行します：make all

コード品質ツール

• Ruff：リント
• Black：コードのフォーマット
• 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

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. テストとコード品質チェックを実行します
5. プルリクエストを送信します

型ヒント

このプロジェクトでは、コードベース全体で Python の型ヒントを使用しています。貢献の際も、これを維持してください。

エラー処理

すべてのエラーケースを適切に処理し、意味のあるエラーメッセージを返してください。無効な入力やファイル操作が原因でサーバーがクラッシュしないようにしてください。

テスト

新機能には適切なテストを追加してください。現在のテストカバレッジを維持、または向上させるようにしてください。

コードスタイル

すべてのコードを Black でフォーマットし、Ruff のリンティングに合格するようにしてください。インポートの並べ替えには isort を使用してください。