使用说明

项目简介

MCP Text Editor Server 是一个实现了 Model Context Protocol (MCP) 的服务器，专注于提供安全高效的文本文件编辑功能。它通过标准化的API，允许LLM客户端以行粒度访问和修改文本文件，特别优化了对大型文件的部分读取，以减少token消耗。服务器具备冲突检测机制，确保并发编辑的安全性和数据一致性。

主要功能点

行级别文本编辑: 支持对文本文件进行行级别的读取和编辑操作。
高效分段读取: 允许客户端只读取文件的指定行范围，减少不必要的token使用，特别为LLM应用优化。
并发安全: 通过哈希校验机制，检测并处理并发编辑冲突，保证文件内容的一致性。
原子操作: 支持多文件操作，保证操作的原子性。
多种字符编码: 支持如 utf-8, shift_jis, latin1 等多种字符编码。
错误处理: 提供完善的错误处理和恢复机制。

安装步骤

安装 Python 3.11+: 确保你的系统安装了 Python 3.11 或更高版本。推荐使用 'pyenv' 进行安装和版本管理。
```
pyenv install 3.11.6
pyenv local 3.11.6
```

安装 uv (推荐) 或 pip: 'uv' 是一个更快的 Python 包安装工具，推荐使用。

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

创建虚拟环境并安装依赖: 创建 Python 虚拟环境并安装项目依赖。

uv venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows
uv pip install -e ".[dev]"

或者使用 'pip':

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows
pip install -e ".[dev]"

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令和参数，以下是 'Claude.app' 客户端的配置示例。将以下 JSON 配置添加到 'claude_desktop_config.json' 文件中：

{
  "mcpServers": {
    "text-editor": {  // 服务器名称，客户端配置中引用
      "command": "uvx", // 启动命令，uvx 启动器，如果使用 pip 安装，则为 python
      "args": [
        "mcp-text-editor" // 服务器启动参数，这里是 mcp_text_editor 模块名
      ]
    },
    // ... 其他 MCP 服务器配置
  }
}

参数说明:

'server name': 'text-editor' (可以自定义，客户端根据此名称引用服务器)
'command': 'uvx' (推荐使用 'uvx' 启动器，如果使用 'pip' 安装，且 'python' 命令已正确配置，则可以使用 'python' )
'args': '["mcp-text-editor"]' (服务器启动参数，指定运行 'mcp_text_editor' 模块)

基本使用方法

启动服务器: 在项目根目录下，运行以下命令启动 MCP Text Editor Server。
```
python -m mcp_text_editor
```

客户端请求: 客户端通过 JSON-RPC 协议与服务器通信，调用服务器提供的工具。

示例工具: 'get_text_file_contents' (获取文件内容)

请求示例 (JSON):

{
  "jsonrpc": "2.0",
  "method": "call_tool",
  "params": {
    "tool_name": "get_text_file_contents",
    "arguments": {
      "files": [
        {
          "file_path": "/absolute/path/to/your/file.txt", // 文件绝对路径
          "ranges": [
            {"start": 1, "end": 10} // 读取 1-10 行
          ]
        }
      ]
    }
  },
  "id": 1
}

响应示例 (JSON):

{
  "jsonrpc": "2.0",
  "result": [
    {
      "type": "text",
      "text": "{\n  \"/absolute/path/to/your/file.txt\": {\n    \"ranges\": [\n      {\n        \"content\": \"Line 1\\nLine 2\\nLine 3\\nLine 4\\nLine 5\\nLine 6\\nLine 7\\nLine 8\\nLine 9\\nLine 10\\n\",\n        \"start\": 1,\n        \"end\": 10,\n        \"range_hash\": \"...\",\n        \"total_lines\": 50,\n        \"content_size\": 512\n      }\n    ],\n    \"file_hash\": \"...\"\n  }\n}\n"
    }
  ],
  "id": 1
}

示例工具: 'edit_text_file_contents' (编辑文件内容)