MCP 文本编辑器

项目概述

MCP 文本编辑器是一个基于文本的协作工具，允许用户通过 HTTP API 进行文件的读取、写入和更新操作。该工具专为需要实时协作的应用场景设计，支持多用户同时编辑同一文件，并提供冲突检测和解决机制。

核心功能模块

1. 获取文件内容

   • 从指定路径读取文件内容。
   • 支持按范围（行号）获取部分文件内容。

2. 编辑文件内容

   • 在指定位置插入或覆盖文件内容。
   • 支持一次性提交多处修改。
   • 提供冲突检测机制，避免并发编辑导致的数据不一致问题。

3. 错误处理与恢复

   • 检测文件状态变化（如其他进程修改）。
   • 发现冲突时提供详细错误信息，便于用户重试或修复。

常见使用场景

1. 获取当前内容

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

错误处理

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

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

安全注意事项

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

故障排除

常见问题

1. 权限 denied

   • 检查文件和目录的权限设置。
   • 确保运行进程有足够权限访问目标文件。

2. 哈希不匹配

   • 在获取最新内容后重试编辑操作。
   • 查看错误信息以了解具体原因。

3. 编码问题

   • 确保指定的编码与文件实际编码一致。
   • 尝试使用其他编码格式重新加载文件。

开发设置

安装依赖

pip install requests

运行测试

python tests.py

项目结构

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

参考文献

1. HTTP 协议
2. JSON 格式规范
3. SHA-256 加密算法