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

概览

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

1. 安装uv（推荐）或pip

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

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

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

1. 安装 uv（推荐）或 pip

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

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

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"  // Optional, defaults to utf-8
}

多个范围请求：

{
  "files": [
    {
      "file_path": "file1.txt",
      "ranges": [
        {"start": 1, "end": 10},
        {"start": 20, "end": 30}
      ],
      "encoding": "shift_jis"  // Optional, defaults to 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": "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",  // Optional, defaults to 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 means end of file
          "range_hash": "sha256-hash-of-content-being-replaced",
          "contents": "Content to append\n"
        }
      ]
    }
  ]
}

重要提示：

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

成功响应：

{
  "file1.txt": {
    "result": "ok",
    "hash": "sha256-hash-of-new-contents"
  }
}

带提示的错误响应：

{
  "file1.txt": {
    "result": "error",
    "reason": "Content hash mismatch",
    "suggestion": "get",  // Suggests using get_text_file_contents
    "hint": "Please run get_text_file_contents first to get current content and hashes"
  }
}

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

}
}

### Common Usage Pattern

1. Get current content and hash:

```python
contents = await get_text_file_contents({
    "files": [
        {
            "file_path": "file.txt",
            "ranges": [{"start": 1, "end": null}]  # Read entire file
        }
    ]
})

1. 编辑文件内容：

result = await edit_text_file_contents({
    "files": [
        {
            "path": "file.txt",
            "hash": contents["file.txt"][0]["hash"],
            "encoding": "utf-8",  # Optional, defaults to "utf-8"
            "patches": [
                {
                    "line_start": 5,
                    "line_end": 8,
                    "contents": "New content\n"
                }
            ]
        }
    ]
})

1. 处理冲突：

if result["file.txt"]["result"] == "error":
    if "hash mismatch" in result["file.txt"]["reason"]:
        # File was modified by another process
        # Get new content and retry
        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 运行：

# 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 处理。