MCP 文本编辑器服务器

一个通过标准化API提供行式文本文件编辑功能的模型上下文协议（MCP）服务器。针对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 文本编辑器服务器旨在通过客户端-服务器架构促进安全高效的基于行的文本文件操作。它实现了模型上下文协议，确保可靠的文件编辑，并具有强大的冲突检测和解决功能。基于行的处理方式使其非常适合需要同步文件访问的应用程序，例如协作编辑工具、自动化文本处理系统或任何需要多个进程安全地修改文本文件的场景。部分文件访问功能对于基于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 安装文本编辑器服务器：

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  # 在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

带inspector启动：

npx @modelcontextprotocol/inspector docker run -i --rm --mount "type=bind,src=/some/path/src,dst=/some/path/dst" 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-based）
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
    }
  ]
}

patch_text_file_contents

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

请求格式：

{
  "files": [
    {
      "file_path": "file1.txt",
      "hash": "sha256-hash-from-get-contents",
      "encoding": "utf-8",  // 可选，默认为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表示文件末尾
          "range_hash": "sha256-hash-of-content-being-replaced",
          "contents": "Content to append\n"
        }
      ]
    }
  ]
}

重要说明：

编辑前始终使用get_text_file_contents获取当前哈希和range_hash
补丁从下到上应用，以正确处理行号偏移
同一文件内的补丁不得重叠
行号是1-based
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",  // 建议使用get_text_file_contents
    "hint": "请先运行get_text_file_contents获取最新内容和哈希值"
  }
}

"result": "error",
"reason": "Content hash mismatch - file was modified",
"hash": "current-hash",
"content": "Current file content"

} }


### 常见使用模式

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

```python
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": "New content\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处理。

tumf/mcp-text-editor

星标增长

证据时间轴

MCP 文本编辑器服务器

快速入门（Claude.app用户）

概述

主要优势

功能

要求

要求

安装

通过uvx运行

通过Smithery安装

手动安装

Docker安装

使用

MCP工具

get_text_file_contents

patch_text_file_contents

错误处理

安全注意事项

故障排除

常见问题

开发

设置

代码质量工具

测试

项目结构

许可证

贡献

类型提示

错误处理

测试

代码风格