JinDaGe - mcp-text-editor MCP Details

article

README

🚀 MCP 文本编辑器

MCP 文本编辑器是一款基于文本的协作工具，借助 HTTP API 可实现文件的读取、写入和更新操作。它专为实时协作场景打造，支持多用户同时编辑同一文件，还具备冲突检测与解决机制，为协作编辑提供了可靠保障。

🚀 快速开始

MCP 文本编辑器为需要实时协作编辑文件的场景提供了便捷的解决方案。通过 HTTP API，用户可以轻松地进行文件内容的获取、编辑等操作。

✨ 主要特性

核心功能模块

获取文件内容
- 可从指定路径读取文件内容。
- 支持按行号范围获取部分文件内容。
编辑文件内容
- 能在指定位置插入或覆盖文件内容。
- 支持一次性提交多处修改。
- 具备冲突检测机制，避免并发编辑导致的数据不一致。
错误处理与恢复
- 检测文件状态变化（如被其他进程修改）。
- 发现冲突时提供详细错误信息，方便用户重试或修复。

💻 使用示例

基础用法

获取当前内容

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": "新内容\n"
                }
            ]
        }
    ]
})

处理冲突

if result["file.txt"]["result"] == "error":
    if "hash mismatch" in result["file.txt"]["reason"]:
        # 文件被其他进程修改，获取最新内容并重试
        pass

📚 详细文档

错误处理

服务端会处理多种错误情况：

文件未找到：验证所有文件路径以防止目录遍历攻击。
权限 denied：检查文件和目录的权限设置。
哈希不匹配（并发编辑检测）：内容被其他进程修改。
无效补丁范围：重叠或越界行号。
编码错误：指定的文件无法使用指定编码解码。

安全注意事项

文件路径验证：服务器会对所有文件路径进行严格验证，防止目录遍历攻击。
访问控制：请确保文件系统权限设置合理，以限制未经授权的访问。
哈希验证：所有文件修改均通过 SHA - 256 哈希值进行校验，避免竞态条件问题。
输入清理：所有用户输入都会经过严格净化和验证处理。
错误处理：错误信息中绝不会暴露任何敏感数据。

故障排除

常见问题

权限 denied
- 检查文件和目录的权限设置。
- 确保运行进程有足够权限访问目标文件。
哈希不匹配
- 在获取最新内容后重试编辑操作。
- 查看错误信息以了解具体原因。
编码问题
- 确保指定的编码与文件实际编码一致。
- 尝试使用其他编码格式重新加载文件。

📦 安装指南

安装依赖

pip install requests

运行测试

python tests.py

🔧 技术细节

项目结构

mcp-text-editor/
├── README.md               # 项目说明文档
├── requirements.txt       # 依赖管理文件
├── src/
│   ├── __init__.py        # 包根目录初始化
│   ├── client.py          # HTTP 客户端实现
│   └── server.py          # HTTP 服务器实现
└── tests/
    ├── test_client.py     # 客户端单元测试
    └── test_server.py     # 服务端集成测试

📄 许可证

该项目遵循 MIT 许可证。请查看 LICENSE 文件获取详细信息。

🤝 贡献指南

提交代码

git clone https://github.com/yourusername/mcp-text-editor.git
cd mcp-text-editor
git branch -b feature/new-feature
git add .
git commit -m "添加新功能"
git push origin feature/new-feature

问题报告

请通过 GitHub Issues 提交 bug 或功能请求。

🌟 代码质量工具

black .  # 格式化代码
flake8 .  # 检查代码风格
mypy .  # 静态类型检查

🧪 测试

单元测试

import unittest
from src.client import MCPClient

class TestMCPClient(unittest.TestCase):
    def setUp(self):
        self.client = MCPClient('http://localhost:8000')

    def test_get_file_contents(self):
        result = self.client.get_file_contents('file.txt')
        self.assertIsInstance(result, dict)

if __name__ == '__main__':
    unittest.main()

集成测试

import pytest
from src.server import MCPServer

def test_server_response():
    server = MCPServer()
    server.start()
    assert 200 in server.responses

mcp-text-editor