MCP Text Editor

🚀 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

✨ 主要特性

核心功能模塊

1. 獲取文件內容

   • 可從指定路徑讀取文件內容。
   • 支持按行號範圍獲取部分文件內容。

2. 編輯文件內容

   • 能在指定位置插入或覆蓋文件內容。
   • 支持一次性提交多處修改。
   • 具備衝突檢測機制，避免併發編輯導致的數據不一致問題。

3. 錯誤處理與恢復

   • 可檢測文件狀態變化（如其他進程修改）。
   • 發現衝突時提供詳細錯誤信息，便於用戶重試或修復。

📦 安裝指南

安裝依賴

pip install requests

運行測試

python tests.py

📚 詳細文檔

錯誤處理

服務端會處理多種錯誤情況：

• 文件未找到：驗證所有文件路徑以防止目錄遍歷攻擊。
• 權限 denied：檢查文件和目錄的權限設置。
• 哈希不匹配（併發編輯檢測）：內容被其他進程修改。
• 無效補丁範圍：重疊或越界行號。
• 編碼錯誤：指定的文件無法使用指定編碼解碼。

安全注意事項

• 文件路徑驗證：服務器會對所有文件路徑進行嚴格驗證，防止目錄遍歷攻擊。
• 訪問控制：請確保文件系統權限設置合理，以限制未經授權的訪問。
• 哈希驗證：所有文件修改均通過 SHA - 256 哈希值進行校驗，避免競態條件問題。
• 輸入清理：所有用戶輸入都會經過嚴格淨化和驗證處理。
• 錯誤處理：錯誤信息中絕不會暴露任何敏感數據。

故障排除

常見問題

1. 權限 denied

   • 檢查文件和目錄的權限設置。
   • 確保運行進程有足夠權限訪問目標文件。

2. 哈希不匹配

   • 在獲取最新內容後重試編輯操作。
   • 查看錯誤信息以瞭解具體原因。

3. 編碼問題

   • 確保指定的編碼與文件實際編碼一致。
   • 嘗試使用其他編碼格式重新加載文件。

項目結構

mcp-text-editor/
├── README.md               # 項目文檔
├── requirements.txt       # 項目依賴
├── src/
│   ├── __init__.py
│   ├── client.py          # HTTP 客戶端實現
│   └── server.py          # HTTP 服務器實現
└── tests/
    └── test_*.py         # 測試用例

🔧 技術細節

開發設置

項目結構

mcp-text-editor/
├── README.md               # 項目說明文檔
├── requirements.txt       # 依賴管理文件
├── src/
│   ├── __init__.py        # 包根目錄初始化
│   ├── client.py          # 客戶端實現
│   └── server.py          # 服務器端實現
└── tests/
    ├── test_client.py     # 客戶端單元測試
    └── test_server.py     # 服務端集成測試

代碼質量工具

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

📄 許可證

該項目遵循 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 或功能請求。

📖 參考文獻

1. HTTP 協議
2. JSON 格式規範
3. SHA - 256 加密算法