MCP文本编辑器服务器
 ](https://smithery.ai/server/mcp-text-editor) 
一种模型上下文协议（MCP）服务器，通过标准化的API提供面向行的文本文件编辑功能。针对LLM工具进行了优化，具有高效的部分文件访问功能，可最大限度地减少令牌使用。
Claude.app用户快速入门
要将此编辑器与Claude.app一起使用，请在提示符中添加以下配置：
code ~/Library/Application\ Support/Claude/claude_desktop_config.json{
"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+
pyenv install 3.11.6
pyenv local 3.11.6- 安装紫外线（推荐）或管道
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运行
uvx mcp-text-editor通过Smithery安装
通过以下方式自动安装Claude Desktop的文本编辑器服务器 史密瑟里:
npx -y @smithery/cli install mcp-text-editor --client claude手动安装
- 安装Python 3.13+
pyenv install 3.13.0
pyenv local 3.13.0- 安装紫外线（推荐）或管道
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_editorMCP工具
服务器提供了几个用于文本文件操作的工具：
get_text_file_内容
获取一个或多个具有行范围规范的文本文件的内容。
单范围请求：
{
"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：要结束的行号（包括在内，空表示文件结束）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
}
]
}patch_text_file_内容
通过强大的错误处理和冲突检测将补丁应用于文本文件。支持在一次操作中编辑多个文件。
请求格式：
{
"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:
contents = await get_text_file_contents({ "files": [ { "file_path": "file.txt", "ranges": [{"start": 1, "end": null}] # Read entire file } ] })
2. 编辑文件内容：
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" } ] } ] })
3. 处理冲突：
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哈希进行验证，以防止竞争条件
- 输入消毒：所有用户输入都经过适当的消毒和验证
- 错误处理：敏感信息不会在错误消息中暴露
## 故障排除
### 常见问题
1. 权限不足
- 检查文件和目录权限
- 确保服务器进程具有必要的读/写访问权限
1. 哈希不匹配和范围哈希错误
- 文件已被其他进程修改
- 被替换的内容已更改
- 运行get_text_file_contents以获取新的哈希值
1. 编码问题
- 验证文件编码是否与指定的编码匹配
- 对新文件使用utf-8
- 检查文件中的BOM标记
1. 连接问题
- 验证服务器是否正在运行且可访问
- 检查网络配置和防火墙设置
1. 性能问题
- 考虑对大文件使用较小的行范围
- 监控系统资源（内存、磁盘空间）
- 对文件类型使用适当的编码
## 发展
### 设置
1. 克隆存储库
1. 创建并激活Python虚拟环境
1. 安装开发依赖项： `uv pip install -e ".[dev]"`
1. 运行测试： `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
## 许可证
麻省理工学院
## 贡献
1. 分叉存储库
1. 创建要素分支
1. 进行更改
1. 运行测试和代码质量检查
1. 提交拉取请求
### 类型提示
这个项目在整个代码库中使用Python类型提示。请确保任何捐款都能保持这一点。
### 错误处理
所有错误情况都应得到适当处理，并返回有意义的错误消息。服务器不应因无效的输入或文件操作而崩溃。
### 测试
新功能应包括适当的测试。尝试保持或提高当前的测试覆盖率。
### 代码的风格
所有代码都应该用黑色格式化，并传递Ruff linting。进口分拣应由isort处理。