MCP 文本编辑器服务器

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

Claude.app 用户快速入门

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

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "text-editor": {
      "command": "uvx",
      "args": [
        "mcp-text-editor"
      ]
    }
  }
}

概述

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

主要优势

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

特性

• 面向行的文本文件编辑和读取
• 智能部分文件访问，最大限度地减少 LLM 应用程序中的 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 自动安装文本编辑器服务器：

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

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

单范围请求：

{
  "file_path": "path/to/file.txt",
  "line_start": 1,
  "line_end": 10,
  "encoding": "utf-8"  // 可选，默认为 utf-8
}

多范围请求：

{
  "files": [
    {
      "file_path": "file1.txt",
      "ranges": [
        {"start": 1, "end": 10},
        {"start": 20, "end": 30}
      ],
      "encoding": "shift_jis"  // 可选，默认为 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": "文件内容",
  "line_start": 1,
  "line_end": 10,
  "hash": "内容的 sha256 哈希值",
  "file_lines": 50,
  "file_size": 1024
}

多范围响应：

{
  "file1.txt": [
    {
      "content": "第 1-10 行内容",
      "start": 1,
      "end": 10,
      "hash": "sha256-hash-1",
      "total_lines": 50,
      "content_size": 512
    },
    {
      "content": "第 20-30 行内容",
      "start": 20,
      "end": 30,
      "hash": "sha256-hash-2",
      "total_lines": 50,
      "content_size": 512
    }
  ],
  "file2.txt": [
    {
      "content": "第 5-15 行内容",
      "start": 5,
      "end": 15,
      "hash": "sha256-hash-3",
      "total_lines": 30,
      "content_size": 256
    }
  ]
}

patch_text_file_contents

将补丁应用于文本文件，具有强大的错误处理和冲突检测功能。 支持在单个操作中编辑多个文件。

请求格式：

{
  "files": [
    {
      "file_path": "file1.txt",
      "hash": "从 get-contents 获取的 sha256 哈希值",
      "encoding": "utf-8",  // 可选，默认为 utf-8
      "patches": [
        {
          "start": 5,
          "end": 8,
          "range_hash": "要替换的内容的 sha256 哈希值",
          "contents": "第 5-8 行的新内容\n"
        },
        {
          "start": 15,
          "end": null,  // null 表示文件末尾
          "range_hash": "要替换的内容的 sha256 哈希值",
          "contents": "要追加的内容\n"
        }
      ]
    }
  ]
}

重要说明：

1. 在编辑之前，始终使用 get_text_file_contents 获取当前的哈希值和 range_hash
2. 补丁从下到上应用，以正确处理行号偏移
3. 补丁在同一文件中不得重叠
4. 行号从 1 开始
5. end: null 可用于将内容追加到文件末尾
6. 文件编码必须与 get_text_file_contents 中使用的编码匹配

成功响应：

{
  "file1.txt": {
    "result": "ok",
    "hash": "新内容的 sha256 哈希值"
  }
}

带有提示的错误响应：

{
  "file1.txt": {
    "result": "error",
    "reason": "内容哈希不匹配",
    "suggestion": "get",  // 建议使用 get_text_file_contents
    "hint": "请先运行 get_text_file_contents 以获取当前内容和哈希值"
  }
}

{
  "file1.txt": {
    "result": "error",
    "reason": "内容哈希不匹配 - 文件已被修改",
    "hash": "当前哈希值",
    "content": "当前文件内容"
  }
}

常用用法模式

1. 获取当前内容和哈希值：

contents = await get_text_file_contents({
    "files": [
        {
            "file_path": "file.txt",
            "ranges": [{"start": 1, "end": null}]  # 读取整个文件
        }
    ]
})

2. 编辑文件内容：

result = await edit_text_file_contents({
    "files": [
        {
            "path": "file.txt",
            "hash": contents["file.txt"][0]["hash"],
            "encoding": "utf-8",  # 可选，默认为 "utf-8"
            "patches": [
                {
                    "line_start": 5,
                    "line_end": 8,
                    "contents": "新内容\n"
                }
            ]
        }
    ]
})

3. 处理冲突：

if result["file.txt"]["result"] == "error":
    if "hash mismatch" in result["file.txt"]["reason"]:
        # 文件已被另一个进程修改
        # 获取新内容并重试
        pass

错误处理

服务器处理各种错误情况：

• 文件未找到
• 权限错误
• 哈希不匹配（并发编辑检测）
• 无效的补丁范围
• 重叠的补丁
• 编码错误（当文件无法使用指定的编码解码时）
• 行号超出范围

安全注意事项

• 文件路径验证：服务器验证所有文件路径以防止目录遍历攻击
• 访问控制：应设置适当的文件系统权限以限制对授权目录的访问
• 哈希验证：所有文件修改都使用 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 用于 linting
• Black 用于代码格式化
• isort 用于导入排序
• mypy 用于类型检查
• pytest-cov 用于测试覆盖率

测试

测试位于 tests 目录中，可以使用 pytest 运行：

# 运行所有测试
pytest

# 运行带有覆盖率报告的测试
pytest --cov=mcp_text_editor --cov-report=term-missing

# 运行特定的测试文件
pytest tests/test_text_editor.py -v

当前测试覆盖率：90%

项目结构

mcp-text-editor/
├── mcp_text_editor/
│   ├── __init__.py
│   ├── __main__.py      # 入口点
│   ├── models.py        # 数据模型
│   ├── server.py        # MCP 服务器实现
│   ├── service.py       # 核心服务逻辑
│   └── text_editor.py   # 文本编辑器功能
├── tests/               # 测试文件
└── pyproject.toml       # 项目配置

许可证

MIT

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 进行更改
4. 运行测试和代码质量检查
5. 提交 pull request

类型提示

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

错误处理

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

测试

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

代码风格

所有代码都应使用 Black 进行格式化，并通过 Ruff linting。 导入排序应由 isort 处理。