MCP文本编辑器服务器

这是一个基于模型上下文协议(Model Context Protocol, 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文本编辑器服务器旨在客户端-服务器架构中实现安全高效的基于行的文本文件操作。它实现了模型上下文协议，确保可靠的文件编辑功能，并具备强大的冲突检测与解决能力。面向行的方法使其非常适合需要同步文件访问的应用程序，例如协作编辑工具、自动化文本处理系统，或任何需要多个进程安全修改文本文件的场景。部分文件访问功能对于基于LLM的工具特别有价值，因为它通过仅加载文件的必要部分来帮助减少令牌消耗。

主要优势

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

功能

• 面向行的文本文件编辑和读取
• 智能部分文件访问以最小化LLM应用中的令牌使用
• 指定行范围获取文本文件内容
• 单次操作中从多个文件读取多个范围
• 正确处理行号偏移的基于行的补丁应用
• 带有冲突检测的文本文件内容编辑
• 灵活的字符编码支持（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  # 在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

Docker安装

docker build --network=host -t mcp/text-editor .

2. 安装uv（推荐）或pip

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

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

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

使用检查器：

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开始）
• 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": "哈希1",
      "total_lines": 50,
      "content_size": 512
    },
    {
      "content": "第20-30行内容",
      "start": 20,
      "end": 30,
      "hash": "哈希2",
      "total_lines": 50,
      "content_size": 512
    }
  ],
  "file2.txt": [
    {
      "content": "第5-15行内容",
      "start": 5,
      "end": 15,
      "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获取当前哈希和范围哈希
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以获取当前内容和哈希"
  }
}

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

} }

### 常见使用模式

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

```python
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用于代码检查
• 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. 分叉存储库
2. 创建功能分支
3. 进行更改
4. 运行测试和代码质量检查
5. 提交拉取请求

类型提示

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

错误处理

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

测试

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

代码风格

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