MCP Text Editor Server

MCP 文本编辑器服务

一个 Model Context Protocol（MCP）服务，通过标准化 API 提供按行操作文本文件的能力。专为大模型工具优化，可高效访问部分文件内容，减少 Token 用量。

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，可通过可靠的冲突检测与解决机制，确保文件编辑安全。按行操作的方式非常适用于需要同步访问文件的应用，例如协作编辑工具、自动化文本处理系统，或任何需要多个进程安全修改文本文件的场景。对于基于大模型的工具，部分文件访问功能尤其有用，因为它只加载必要的文件片段，有助于减少 Token 消耗。

主要优势

• 基于行的编辑操作
• 通过指定行范围高效访问部分文件，节省 Token
• 针对大模型工具集成进行优化
• 通过基于哈希的验证安全地并发编辑
• 原子性多文件操作
• 通过自定义错误类型实现可靠的错误处理
• 全面的编码格式支持（utf-8、shift_jis、latin1 等）

功能

• 按行编辑和读取文本文件
• 智能访问部分文件，减少大模型应用中的 Token 用量
• 按指定行范围获取文本文件内容
• 在单次操作中读取多个文件的多个范围
• 基于行应用补丁，并正确处理行号偏移
• 编辑文本文件内容并检测冲突
• 灵活支持字符编码（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

读取一个或多个文本文件的内容，并指定行范围。

请求：

该工具接受一个 files 数组。每个文件包含一个或多个使用 start 和 end 指定的行范围。文件路径必须是绝对路径。

{
  "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

对一个文件应用一个或多个互不重叠的补丁。请先读取目标范围，并传入当前的 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 处理。