MCP Simple TextEdit 服务器使用说明

项目简介

mcp-simple-textedit 是一个实验性的 MCP 服务器，旨在为 AI 提供优化的文本编辑能力。它允许 LLM 客户端通过预定义的工具，以安全和可控的方式编辑服务器文件系统上的文本文件。该服务器的核心理念是基于模式匹配的文本编辑，而非传统的行号或视觉编辑，这更符合 AI 理解和处理文本的逻辑，并提高了操作的安全性。

请注意： 此服务器为实验性项目，使用风险自负。在用 AI 编辑重要文件前，请务必备份。目前 'append_text' （追加文本）功能相对可靠，'edit_file'（编辑文件）功能请谨慎使用。

主要功能点

基于模式匹配的文本块定位： AI 可以通过正则表达式模式精准定位到需要编辑的文本块，而非依赖不稳定的行号。
内容验证机制： 在执行编辑操作前，可以验证目标文本内容是否与预期一致，防止误操作，提高安全性。
安全的文件访问控制： 服务器限定了可访问的基础目录 (base path)，所有文件操作都只能在该目录及其子目录内进行，防止越权访问。
支持多种编辑操作： 提供 'delete' (删除), 'replace' (替换), 'insert' (插入) 三种基本的文本编辑操作。
安全的追加文本功能： 提供 'append_text' 工具，用于安全地向文件末尾追加文本内容。
UTF-8 编码支持： 所有文件读写均使用 UTF-8 编码，确保兼容各种字符，包括国际字符、特殊符号和 Emoji。
操作日志记录： 所有文件操作都会被记录，方便审计和问题追踪。

安装步骤

安装 Python 模块: 打开终端或命令提示符，运行以下命令安装 'mcp-simple-textedit' 模块：
```
pip install mcp-simple-textedit
```

服务器配置

要将 'mcp-simple-textedit' 服务器与 MCP 客户端（例如 Claude 桌面应用）连接，您需要配置客户端的 MCP 服务器设置。配置信息通常以 JSON 格式添加到客户端的配置文件中。

通用配置说明：

以下是一个通用的配置模板，您需要根据您的操作系统和实际情况进行调整。

"mcpServers": {
  "textedit": {  // 服务器名称，可以自定义，例如 "my_text_editor"
    "command": "python",  // 启动服务器的命令，通常是 python 或 python3
    "args": [     // 启动服务器的参数列表
      "-m",
      "mcp_simple_textedit", // 模块名，用于运行 mcp_simple_textedit 服务器
      "--base-path",        // 服务器参数：指定允许编辑的基础目录
      "/path/to/your/base/directory" //  **请替换为实际的基础目录路径**，例如 "/Users/your_username/Documents/my_editable_files" (macOS/Linux) 或 "C:\\Users\\your_username\\Documents\\editable_files" (Windows)
    ]
  }
}

不同操作系统下的配置示例：

macOS:

将以下 JSON 代码块添加到 '~/Library/Application Support/Claude/claude_desktop_config.json' 文件中。 请务必将 '/Users/YOUR_USERNAME/path/to/edit' 替换为您希望允许 AI 编辑文件的实际目录路径。

"mcpServers": {
  "textedit": {
    "command": "python",
    "args": [
      "-m",
      "mcp_simple_textedit",
      "--base-path",
      "/Users/YOUR_USERNAME/path/to/edit"
    ]
  }
}

Windows:

检查 Python 路径： 在命令提示符 (cmd) 中运行 'where python' 命令，查找 Python 可执行文件的完整路径。例如，可能输出 'C:\Users\YOUR_USERNAME\AppData\Local\Programs\Python\Python311\python.exe'。
配置 JSON: 将以下 JSON 代码块添加到 '%APPDATA%\Claude\claude_desktop_config.json' 文件中。请务必将 'C:\Users\YOUR_USERNAME\AppData\Local\Programs\Python\Python311\python.exe' 替换为您在步骤 1 中找到的 Python 路径，并将 'C:\Users\YOUR_USERNAME\path\to\edit' 替换为您希望允许 AI 编辑文件的实际目录路径。

"mcpServers": {
  "textedit": {
    "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
    "args": [
      "-m",
      "mcp_simple_textedit",
      "--base-path",
      "C:\\Users\\YOUR_USERNAME\\path\\to\\edit"
    ]
  }
}

'--base-path' 参数说明:

'--base-path': 这是至关重要的安全参数！ 您必须指定一个目录路径作为服务器的基础目录。服务器只能访问和编辑该目录及其子目录下的文件。任何尝试访问基础目录之外文件的操作都将被拒绝。
请根据您的实际需求，谨慎选择 'base-path'。 建议创建一个专门用于 AI 编辑的目录，避免将重要的系统目录或敏感数据目录设置为 'base-path'。

基本使用方法

配置完成后，您的 MCP 客户端（例如 Claude 桌面应用）应该能够检测到 'textedit' 服务器。您可以通过客户端的功能调用 'textedit' 服务器提供的工具，例如：

'edit_file' (编辑文件): 允许 AI 根据您提供的操作指令（'operations'）编辑指定路径的文件内容。'operations' 可以包含 'delete', 'replace', 'insert' 等操作类型，并支持使用 'start_pattern', 'end_pattern', 'after_pattern', 'before_pattern' 等模式来精确定位编辑位置。 请务必仔细设计您的操作指令，并尽可能使用 'expected_content' 进行内容验证，以确保编辑操作的准确性和安全性。
'append_text' (追加文本): 允许 AI 向指定路径的文件末尾安全地追加文本内容。这是一个相对安全的操作，适用于添加日志、笔记等场景。

使用示例 (假设在 Claude 客户端中):

您可以指示 Claude 使用 'edit_file' 工具编辑文件，例如：

{
  "tool_calls": [
    {
      "id": "tool_call_123",
      "type": "function",
      "function": {
        "name": "textedit/edit_file", // 注意格式: serverName/toolName
        "arguments": {
          "file_path": "my_document.txt", // 相对于 base-path 的文件路径
          "operations": [
            {
              "type": "replace",
              "start_pattern": "旧文本内容",
              "content": ["新文本内容"]
            }
          ]
        }
      }
    }
  ]
}

或者使用 'append_text' 工具追加文本：

{
  "tool_calls": [
    {
      "id": "tool_call_456",
      "type": "function",
      "function": {
        "name": "textedit/append_text", // 注意格式: serverName/toolName
        "arguments": {
          "file_path": "log.txt",      // 相对于 base-path 的文件路径
          "content": ["新的日志记录"]
        }
      }
    }
  ]
}

重要提示:

请仔细阅读 'README.md' 文件和代码注释，了解更多关于模式匹配规则、安全特性和使用限制的信息。
在实际使用中，务必充分测试和验证编辑操作，确保其符合您的预期。
对于重要的文件，请务必做好备份，以防意外情况发生。

关键词