MCP 文本编辑器服务器
模型上下文协议 (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"
]
}
}
}
或者使用 docker：
{
"mcpServers": {
"text-editor": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=/some/path/src,dst=/some/path/dst",
"mcp/text-editor"
]
}
}
}
概述
MCP 文本编辑器服务器旨在促进客户端-服务器架构中安全高效的基于行的文本文件操作。它实现了模型上下文协议 (MLP)，通过强大的冲突检测和解决功能确保可靠的文件编辑。这种面向行的方法使其成为需要同步文件访问的应用程序的理想选择，例如协作编辑工具、自动文本处理系统，或任何需要多个进程安全修改文本文件的场景。部分文件访问功能对于基于 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
- 安装 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 3.13+
- 符合 POSIX 标准的操作系统（Linux、macOS 等）或 Windows
- 读/写操作的文件系统权限
安装
通过 uvx 运行
通过 Smithery 安装
要通过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
Docker 安装
docker 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_editor
使用docker启动服务器：
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
MCP 工具
服务器提供了几个用于文本文件操作的工具：
获取文本文件内容
获取具有行范围规范的一个或多个文本文件的内容。
单一范围请求：
{
"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
}
]
}
补丁文本文件内容
使用强大的错误处理和冲突检测功能，将补丁应用于文本文件。支持单次操作编辑多个文件。
请求格式：
{
"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 获取当前 hash 和 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 linting。导入排序应使用 isort 处理。