MCP文本编辑器

Name: MCP文本编辑器
Author: tumf

作者：tumf177 星标更新：2025-09-07

安装使用来源：spider==github.com

项目介绍

MCP 文本编辑器服务器

这是一个通过标准化API提供基于行的文本文件编辑功能的Model Context Protocol (MCP)服务器。它优化了LLM工具的部分文件访问效率，以减少令牌使用量。

Claude.app 用户快速入门

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

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

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

概览

MCP 文本编辑器服务器旨在通过客户端-服务器架构促进安全高效的基于行的文本文件操作。它实现了Model Context Protocol，确保可靠的文件编辑并具有强大的冲突检测和解决能力。基于行的方法使其非常适合需要同步文件访问的应用程序，如协作编辑工具、自动化文本处理系统或任何需要多个进程安全修改文本文件的场景。部分文件访问的能力对于基于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  # 在Windows上：.venv\Scripts\activate
uv pip install -e ".[dev]"

要求

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

安装

通过uvx运行

uvx mcp-text-editor

通过Smithery安装

要通过Smithery自动安装Text Editor Server for 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

安装uv（推荐）或pip

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

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

uv venv
source .venv/bin/activate  # 在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哈希值1",
      "total_lines": 50,
      "content_size": 512
    },
    {
      "content": "第20-30行内容",
      "start": 20,
      "end": 30,
      "hash": "sha256哈希值2",
      "total_lines": 50,
      "content_size": 512
    }
  ],
  "file2.txt": [
    {
      "content": "第5-15行内容",
      "start": 5,
      "end": 15,
      "hash": "sha256哈希值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"
        }
      ]
    }
  ]
}

重要注意事项：

编辑前始终使用get_text_file_contents获取当前哈希值和range_hash
补丁从底部向上应用，以正确处理行号偏移
同一文件内的补丁不能重叠
行号从1开始
end: null可用于将内容追加到文件末尾
文件编码必须与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以获取当前内容和哈希值"
  }
}

常用模式

获取当前内容和哈希值：

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

编辑文件内容：

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"
                }
            ]
        }
    ]
})

处理冲突：

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

错误处理

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

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

安全考虑

文件路径验证：服务器验证所有文件路径，防止目录遍历攻击
访问控制：应设置适当的文件系统权限，限制对授权目录的访问
哈希验证：所有文件修改都使用SHA-256哈希进行验证，以防止竞态条件
输入净化：所有用户输入都被适当净化和验证
错误处理：敏感信息不会暴露在错误消息中

故障排除

常见问题

权限被拒绝
- 检查文件和目录权限
- 确保服务器进程具有必要的读写访问权限
哈希不匹配和范围哈希错误
- 文件已被其他进程修改
- 被替换的内容已更改
- 运行get_text_file_contents以获取新鲜的哈希值
编码问题
- 验证文件编码是否与指定的编码匹配
- 对于新文件使用utf-8
- 检查文件中的BOM标记
连接问题
- 确认服务器正在运行且可访问
- 检查网络配置和防火墙设置
性能问题
- 考虑使用较小的行范围处理大文件
- 监控系统资源（内存、磁盘空间）
- 使用适合文件类型的编码

开发

设置

克隆仓库
创建并激活Python虚拟环境
安装开发依赖项：uv pip install -e ".[dev]"
运行测试：make all

代码质量工具

Ruff用于代码检查
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

贡献

分叉仓库
创建功能分支
进行更改
运行测试和代码质量检查
提交拉取请求

类型提示

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

错误处理

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

测试

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

代码风格

所有代码应使用Black格式化并通过Ruff代码检查。导入排序应由isort处理。