mcp文本编辑器

MCP 文本编辑器服务器

模型上下文协议 (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 文本编辑器服务器旨在促进客户端-服务器架构中安全高效的基于行的文本文件操作。它实现了模型上下文协议 (MLP)，通过强大的冲突检测和解决功能确保可靠的文件编辑。这种面向行的方法使其成为需要同步文件访问的应用程序的理想选择，例如协作编辑工具、自动文本处理系统，或任何需要多个进程安全修改文本文件的场景。部分文件访问功能对于基于 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  # 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

手动安装

安装 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  # On 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 工具

服务器提供了几个用于文本文件操作的工具：

获取文本文件内容

获取具有行范围规范的一个或多个文本文件的内容。

单一范围请求：

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

补丁文本文件内容

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

请求格式：

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

重要提示：

编辑前务必使用 get_text_file_contents 获取当前 hash 和 range_hash
从下到上应用补丁，以正确处理行号偏移
补丁不得在同一个文件中重叠
行号从 1 开始
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",  // 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
        }
    ]
})

编辑文件内容：

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

处理冲突：

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 哈希进行验证，以防止竞争条件
输入清理：所有用户输入都经过适当的清理和验证
错误处理：错误消息中不会暴露敏感信息

故障排除

常见问题

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

发展

设置

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

代码质量工具

用于除毛的褶边
黑色表示代码格式
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

执照

麻省理工学院

贡献

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

类型提示

该项目在整个代码库中使用了 Python 类型提示。请确保所有贡献都维护这一点。

错误处理

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

测试

新功能应该包含适当的测试。尽量维持或提升当前的测试覆盖率。

代码风格

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

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

面向行的文本文件编辑器。针对 LLM 工具进行了优化，具有高效的部分文件访问功能，可最大限度地减少令牌使用。

Related MCP Servers

mcp-neovim-server
bigcodegen
A
security
A
license
A
quality
Leverages Vim's native text editing commands and workflows, which Claude already understands, to create a lightweight code assistance layer.
Last updated -
8
69
129
TypeScript
MIT License
Edit File Lines MCP Server
oakenai
-
security
A
license
-
quality
A TypeScript-based MCP server that provides tools for making precise line-based edits to text files within allowed directories.
Last updated -
18
TypeScript
MIT License
Doc/docx-MCP
MeterLong
-
security
F
license
-
quality
A powerful Word document processing service based on FastMCP, enabling AI assistants to create, edit, and manage docx files with full formatting support. Preserves original styles when editing content.
Last updated -
12
Python
Code Summarizer MCP
nicobailon
-
security
F
license
-
quality
Allows LLM tools like Claude Desktop and Cursor AI to access and summarize code files through a Model Context Protocol server, providing structured access to codebase content without manual copying.
Last updated -
TypeScript

View all related MCP servers

mcp-text-editor