⚙

文本编辑服务器

MCP文本编辑服务器是一个基于Model Context Protocol的服务器，提供面向行的文本文件编辑功能，特别优化了LLM工具的集成，支持高效的部分文件访问以减少令牌使用。适用于协作编辑工具、自动化文本处理系统等场景。

作者 By tumf

本地部署文本编辑 LLM工具集成

GitHub

MCP文本编辑器服务器

一种模型上下文协议（MCP）服务器，通过标准化的API提供面向行的文本文件编辑功能。针对LLM工具进行了优化，具有高效的部分文件访问功能，可最大限度地减少令牌使用。

Claude.app用户快速入门

要将此编辑器与Claude.app一起使用，请在提示符中添加以下配置：

SHELL``` 1code ~/Library/Application\ Support/Claude/claude_desktop_config.json


JSON```
1
2
3
4
5
6
7
8
9
10{
  "mcpServers": {
    "text-editor": {
      "command": "uvx",
      "args": [
        "mcp-text-editor"
      ]
    }
  }
}

概述

MCP文本编辑器服务器旨在在客户端-服务器架构中促进安全高效的基于行的文本文件操作。它实现了模型上下文协议，确保了可靠的文件编辑，具有强大的冲突检测和解决能力。面向行的方法使其成为需要同步文件访问的应用程序的理想选择，例如协作编辑工具、自动化文本处理系统，或多个进程需要安全修改文本文件的任何场景。部分文件访问功能对于基于LLM的工具特别有价值，因为它通过仅加载文件的必要部分来帮助减少令牌消耗。

关键利益

基于行的编辑操作
具有行范围规范的令牌高效部分文件访问
针对LLM工具集成进行了优化
基于哈希验证的安全并发编辑
原子多文件操作
使用自定义错误类型进行稳健的错误处理
全面的编码支持（utf-8、shift_jis、latin1等）

特性

面向行的文本文件编辑和读取
智能部分文件访问，最大限度地减少LLM应用程序中的令牌使用
获取具有行范围规范的文本文件内容
在一次操作中从多个文件读取多个范围
基于线路的补丁应用程序，可正确处理线路编号偏移
使用冲突检测编辑文本文件内容
灵活的字符编码支持（utf-8、shift_jis、latin1等）
支持多种文件操作
使用基于哈希的验证正确处理并发编辑
大文件的内存高效处理

需求

Python 3.11或更高版本
符合POSIX标准的操作系统（Linux、macOS等）或Windows
足够的磁盘空间用于文本文件操作
读/写操作的文件系统权限

安装Python 3.11+

BASH``` 1 2pyenv install 3.11.6 pyenv local 3.11.6


1. 安装紫外线（推荐）或管道


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

创建虚拟环境并安装依赖项

BASH``` 1 2 3uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e ”.[dev]“


## 需求


- Python 3.13+
- 符合POSIX标准的操作系统（Linux、macOS等）或Windows
- 读/写操作的文件系统权限


## 安装


### 通过uvx运行


BASH```
1uvx mcp-text-editor

通过Smithery安装

通过以下方式自动安装Claude Desktop的文本编辑器服务器史密瑟里:

BASH``` 1npx -y @smithery/cli install mcp-text-editor —client claude


### 手动安装


1. 安装Python 3.13+


BASH```
1
2pyenv install 3.13.0
pyenv local 3.13.0

安装紫外线（推荐）或管道

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


1. 创建虚拟环境并安装依赖项


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

用法

启动服务器：

BASH``` 1python -m mcp_text_editor


### MCP工具


服务器提供了几个用于文本文件操作的工具：


#### get_text_file_内容


获取一个或多个具有行范围规范的文本文件的内容。


**单范围请求：**


JSON```
1
2
3
4
5
6{
  "file_path": "path/to/file.txt",
  "line_start": 1,
  "line_end": 10,
  "encoding": "utf-8"  // Optional, defaults to utf-8
}

多范围请求：

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18{ “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`：要结束的行号（包括在内，空表示文件结束）
- `encoding`：文件编码（默认：“utf-8”）。指定文本文件的编码（例如，“shift_jis”、“latin1”）


**单量程响应：**


JSON```
1
2
3
4
5
6
7
8{
  "contents": "File contents",
  "line_start": 1,
  "line_end": 10,
  "hash": "sha256-hash-of-contents",
  "file_lines": 50,
  "file_size": 1024
}

多范围响应：

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30{ “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 } ] }


#### patch_text_file_内容


通过强大的错误处理和冲突检测将补丁应用于文本文件。支持在一次操作中编辑多个文件。


**请求格式：**


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23{
  "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中使用的编码匹配

成功响应：

JSON``` 1 2 3 4 5 6{ “file1.txt”: { “result”: “ok”, “hash”: “sha256-hash-of-new-contents” } }


**带有提示的错误响应：**


JSON```
1
2
3
4
5
6
7
8{
  "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"
  }
}

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

} }

1
2
3
4
5
6
7
8
9
10
11### 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
        }
    ]
})

编辑文件内容：

PYTHON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16result = 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” } ] } ] })


1. 处理冲突：


PYTHON```
1
2
3
4
5if 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运行：

BASH``` 1 2 3 4 5 6# 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%


### 项目结构

1 2 3 4 5 6 7 8 9 10mcp-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


## 许可证


麻省理工学院


## 贡献


1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试和代码质量检查
5. 提交拉取请求


### 类型提示


这个项目在整个代码库中使用Python类型提示。请确保任何捐款都能保持这一点。


### 错误处理


所有错误情况都应得到适当处理，并返回有意义的错误消息。服务器不应因无效的输入或文件操作而崩溃。


### 测试


新功能应包括适当的测试。尝试保持或提高当前的测试覆盖率。


### 代码的风格


所有代码都应该用黑色格式化，并传递Ruff linting。进口分拣应由isort处理。