標準化されたAPIを通じて行指向のテキストファイル編集機能を提供するモデルコンテキストプロトコル（MCP）サーバー。効率的な部分ファイルアクセスによりトークン使用量を最小限に抑え、LLMツール向けに最適化されています。
このエディターを Claude.app で使用するには、プロンプトに次の構成を追加します。
code ~/Library/Application\ Support/Claude/claude_desktop_config.json{
"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"
]
}
}
}Related MCP server: RBT Document Editor
MCPテキストエディターサーバーは、クライアントサーバーアーキテクチャにおいて、安全かつ効率的な行ベースのテキストファイル操作を可能にするように設計されています。モデルコンテキストプロトコル（Model Context Protocol）を実装し、堅牢な競合検出と解決により、信頼性の高いファイル編集を実現します。行指向のアプローチは、共同編集ツール、自動テキスト処理システム、複数のプロセスがテキストファイルを安全に変更する必要があるシナリオなど、同期ファイルアクセスを必要とするアプリケーションに最適です。部分ファイルアクセス機能は、ファイルの必要な部分のみを読み込むことでトークン消費量を削減できるため、LLMベースのツールにとって特に有用です。
行ベースの編集操作
行範囲指定によるトークン効率の良い部分ファイルアクセス
LLMツール統合に最適化
ハッシュベースの検証による安全な同時編集
アトミックなマルチファイル操作
カスタムエラータイプによる堅牢なエラー処理
包括的なエンコーディング サポート (utf-8、shift_jis、latin1 など)
行指向のテキストファイルの編集と読み取り
LLM アプリケーションでのトークンの使用を最小限に抑えるスマートな部分ファイル アクセス
行範囲指定でテキストファイルの内容を取得する
1 回の操作で複数のファイルから複数の範囲を読み取る
行番号シフトを正しく処理する行ベースのパッチ適用
競合検出機能を使用してテキストファイルの内容を編集する
柔軟な文字エンコードのサポート (utf-8、shift_jis、latin1 など)
複数のファイル操作のサポート
ハッシュベースの検証による同時編集の適切な処理
大容量ファイルのメモリ効率の高い処理
Python 3.11以上
POSIX準拠のオペレーティングシステム（Linux、macOSなど）またはWindows
テキストファイル操作に十分なディスク容量
読み取り/書き込み操作のファイルシステム権限
Python 3.11以降をインストールする
pyenv install 3.11.6
pyenv local 3.11.6uv（推奨）または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 3.13以上
POSIX準拠のオペレーティングシステム（Linux、macOSなど）またはWindows
読み取り/書き込み操作のファイルシステム権限
uvx mcp-text-editorSmithery経由で Claude Desktop のテキスト エディター サーバーを自動的にインストールするには:
npx -y @smithery/cli install mcp-text-editor --client claudePython 3.13以降をインストールする
pyenv install 3.13.0
pyenv local 3.13.0docker 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_editordocker でサーバーを起動します。
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サーバーはテキスト ファイルの操作用にいくつかのツールを提供します。
行範囲を指定して 1 つ以上のテキスト ファイルの内容を取得します。
単一範囲リクエスト:
{
"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
}
]
}堅牢なエラー処理と競合検出機能を備え、テキストファイルにパッチを適用します。1回の操作で複数のファイルを編集できます。
リクエスト形式:
{
"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マサチューセッツ工科大学
リポジトリをフォークする
機能ブランチを作成する
変更を加える
テストとコード品質チェックを実行する
プルリクエストを送信する
このプロジェクトでは、コードベース全体でPythonの型ヒントを使用しています。貢献する場合には、必ずこれを維持するようにしてください。
すべてのエラーケースは適切に処理され、意味のあるエラーメッセージが返される必要があります。無効な入力やファイル操作によってサーバーがクラッシュすることは決してあってはなりません。
新機能には適切なテストを含める必要があります。現在のテスト範囲を維持または改善するよう努めてください。
すべてのコードはBlackでフォーマットされ、Ruffリンティングに合格する必要があります。インポート時のソートはisortで処理する必要があります。
Append content to an existing text file. The file must exist.
| Name | Required | Description | Default |
|---|---|---|---|
| contents | Yes | Content to append to the file | |
| encoding | No | Text encoding (default: 'utf-8') | utf-8 |
| file_hash | Yes | Hash of the file contents for concurrency control. it should be matched with the file_hash when get_text_file_contents is called. | |
| file_path | Yes | Path to the text file. File path must be absolute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It mentions the existence constraint but does not disclose side effects (mutation) or concurrency behavior despite file_hash being required. Some transparency, but gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences with no wasted words. Front-loaded with the action and key constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool modifies files and has a concurrency mechanism, the description omits details about return values, error conditions (e.g., hash mismatch, file not found), and side effects. Not complete for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; the file_hash parameter's role is mentioned in the schema but not elaborated in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('append') and the resource ('text file'), and distinguishes from siblings like 'create_text_file' and 'insert_text_file_contents'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only states 'The file must exist' but does not provide guidance on when to use this tool versus alternatives like 'create_text_file' or 'insert_text_file_contents'. No explicit when-to-use or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new text file with given content. The file must not exist already.
| Name | Required | Description | Default |
|---|---|---|---|
| contents | Yes | Content to write to the file | |
| encoding | No | Text encoding (default: 'utf-8') | utf-8 |
| file_path | Yes | Path to the text file. File path must be absolute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. It discloses the creation action and file existence precondition, but lacks details on error handling (e.g., what happens if file exists), encoding usage, or side effects. It is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence plus a condition. No unnecessary words. The essential information is front-loaded, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and no annotations, the description is minimal. It covers core purpose and a key precondition but omits details like error handling, encoding behavior, and any side effects (e.g., directory creation). It is adequate but could be more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds minimal value beyond schema. It mentions 'given content' for contents (schema already says 'Content to write') and restates 'File path must be absolute' (already in schema). Encoding is not mentioned in description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a new text file with given content', which is a specific verb and resource. It also adds the precondition that the file must not already exist, distinguishing it from siblings like append or patch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'The file must not exist already', guiding when to use (for new files) and implying when not to use (file already exists). However, it does not explicitly name alternatives or contrast with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete specified content ranges from a text file. The file must exist. File paths must be absolute. You need to provide the file_hash comes from get_text_file_contents.
| Name | Required | Description | Default |
|---|---|---|---|
| ranges | Yes | List of line ranges to delete | |
| encoding | No | Text encoding (default: 'utf-8') | utf-8 |
| file_hash | Yes | Hash of the file contents for concurrency control. it should be matched with the file_hash when get_text_file_contents is called. | |
| file_path | Yes | Path to the text file. File path must be absolute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the file must exist, paths must be absolute, and that a hash is required for concurrency control. However, it doesn't disclose what happens if the hash mismatches, whether the operation is destructive/reversible, or what the return value is. The destructive nature is implied by 'Delete' but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action. The three sentences each add necessary context: what it does, the file existence/path requirement, and the hash prerequisite. It could be slightly more structured, but it's efficient and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no annotations and no output schema, the description should disclose more about failure modes, hash mismatch behavior, and whether the operation is reversible. It covers the key prerequisites but leaves the agent guessing about what happens on success or failure. The sibling tools and schema provide some context, but the description itself is incomplete for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds the crucial context that file_hash comes from get_text_file_contents and that range_hash should match the one from get_text_file_contents. This adds value beyond the schema, but the schema already covers the basics, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete'), a specific resource ('specified content ranges from a text file'), and the key precondition that the file must exist. It clearly distinguishes itself from siblings like append_text_file_contents, insert_text_file_contents, and patch_text_file_contents by focusing on deletion of ranges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: the file must exist, paths must be absolute, and the file_hash must come from get_text_file_contents. It doesn't explicitly say when to use this tool versus alternatives, but the deletion-specific wording and the mention of get_text_file_contents as a prerequisite provide adequate usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read text file contents from multiple files and line ranges. Returns file contents with hashes for concurrency control and line numbers for reference. The hashes are used to detect conflicts when editing the files. File paths must be absolute.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | List of files and their line ranges to read | |
| encoding | No | Text encoding (default: 'utf-8') | utf-8 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that the tool is read-only, returns hashes for concurrency control, includes line numbers for reference, and requires absolute paths. It does not cover failure modes or size limits, but the core behavioral traits are clearly explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each earning its place: the first defines the operation, the second explains the return payload, and the third explains why hashes matter. There is no redundant phrasing or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the complete input schema, gives an agent enough to invoke the tool correctly. It describes the key return elements (hashes, line numbers) despite no output schema. Minor gaps around error behavior and exact return formatting keep it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter, including the absolute path requirement and range semantics. The description adds no new parameter-level meaning beyond restating that paths must be absolute; the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb 'Read' and resource 'text file contents', and immediately clarifies it handles multiple files and line ranges. This clearly distinguishes it from sibling editing/writing tools like append_text_file_contents and patch_text_file_contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this is for reading files before editing, since it returns hashes 'used to detect conflicts when editing the files.' It provides clear usage context and indirectly positions itself as the read counterpart to the editing siblings, though it does not explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert content before or after a specific line in a text file. Uses hash-based validation for concurrency control. You need to provide the file_hash comes from get_text_file_contents.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Line number after which to insert content (mutually exclusive with 'before') | |
| before | No | Line number before which to insert content (mutually exclusive with 'after') | |
| contents | Yes | Content to insert | |
| encoding | No | Text encoding (default: 'utf-8') | utf-8 |
| file_hash | Yes | Hash of the file contents for concurrency control. it should be matched with the file_hash when get_text_file_contents is called. | |
| file_path | Yes | Path to the text file. File path must be absolute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses hash-based concurrency control and the prerequisite of file_hash. However, it omits error behavior (e.g., out-of-range line, hash mismatch) and the fact that the file is modified in place.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose and followed by an important prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main action and prerequisite, but lacks information on return value (no output schema) and error cases. For a tool with 6 parameters and no output schema, it is adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining the concurrency control purpose of file_hash and the prerequisite relationship with get_text_file_contents. This goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts content before or after a specific line in a text file, using specific verbs and resources. It distinguishes from siblings like append_text_file_contents and patch_text_file_contents by specifying line-based insertion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by requiring the file_hash from get_text_file_contents, but does not explicitly state when to use this tool versus alternatives. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply patches to text files with hash-based validation for concurrency control.you need to use get_text_file_contents tool to get the file hash and range hash every time before using this tool. you can use append_text_file_contents tool to append text contents to the file without range hash, start and end. you can use insert_text_file_contents tool to insert text contents to the file without range hash, start and end.
| Name | Required | Description | Default |
|---|---|---|---|
| patches | Yes | List of patches to apply | |
| encoding | No | Text encoding (default: 'utf-8') | utf-8 |
| file_hash | Yes | Hash of the file contents for concurrency control. | |
| file_path | Yes | Path to the text file. File path must be absolute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions concurrency control via hashes but does not disclose error behavior (e.g., hash mismatch, partial patches) or permissions required. Could be more transparent about failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense paragraph with no superfluous words. It front-loads the main purpose and immediately gives prerequisite and alternative usage, making it efficient for agent parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and complex nested patches, the description provides necessary context: prerequisite hash retrieval and alternative tools for simpler edits. Missing details on return value and errors, but sufficient for typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; each parameter has a description. The tool description adds context about hash usage and the need to fetch them from get_text_file_contents. However, it does not significantly enhance understanding beyond the schema beyond the prerequisite flow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies patches to text files with hash-based concurrency control. It distinguishes itself from siblings by mentioning that append and insert tools do not require range hashes and start/end parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to use get_text_file_contents first to obtain file_hash and range_hash. Also provides alternatives (append, insert) for simpler operations, clearly delimiting when to use this tool and when not to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.2delete_text_file_contents2 fields changedInput schema / properties / ranges / items / properties / end / nullableAdded value: +trueInput schema / properties / ranges / items / properties / end / typePrevious value: -[
- "integer",
- "null"
-]New value: +"integer"get_text_file_contents2 fields changedInput schema / properties / files / items / properties / ranges / items / properties / end / nullableAdded value: +trueInput schema / properties / files / items / properties / ranges / items / properties / end / typePrevious value: -[
- "integer",
- "null"
-]New value: +"integer"v1.0.0append_text_file_contentscreate_text_filedelete_text_file_contentsget_text_file_contentsinsert_text_file_contentspatch_text_file_contentsScored across 6 tools
Each tool targets a distinct operation: create, read, append, insert, delete range, and patch. However, patch_text_file_contents can be seen as overlapping with insert and delete since patches may subsume those operations, so agents might occasionally hesitate between them.
Most tools follow a verb_text_file_contents pattern, which is clear and consistent. The exception is create_text_file, which drops the _contents suffix and breaks the otherwise uniform convention.
Six tools is a well-scoped set for a text file editor. Each tool covers a necessary primitive operation without redundant or bloated additions.
The server provides create, read, append, insert, delete-range, and patch operations, covering the core editing lifecycle. A whole-file overwrite or file deletion operation is missing, but most workflows can be accomplished with the existing tools.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Read and write your Fresh Jots notes from Claude, Cursor, and any MCP client.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
