使用 Python 和 MCP 构建本地文件操作服务

使用 Python 和 MCP 构建本地文件操作服务

本文演示如何在 Windows 平台上使用 Python 开发一个基于 Model Context Protocol (MCP) 的本地文件操作服务（包括创建文件夹、删除文件/文件夹、重命名、列出目录内容、移动文件等功能），并在 VS Code 中通过 Cline 插件进行开发和调试。MCP 是 Anthropic 提出的开放协议，可让 AI 模型像调用 Web API 一样调用您定义的本地工具。以下步骤面向开发新手，详细说明了环境搭建、代码结构、调试与集成测试等内容。

环境准备

  • 安装 Python (>=3.10)：首先确保安装了 Python 3.10 或更高版本（[27†L75-L83]）。在命令行运行 python --version 验证安装。

  • 安装 VS Code：下载并安装 Visual Studio Code，并在扩展市场中安装“Python”扩展（提供语法高亮和调试支持）。

  • 安装 Cline 扩展：打开 VS Code，点击左侧扩展图标，搜索 “Cline” 并安装。Cline 是一个 AI 编码助手插件，支持 MCP 协议，可通过对话调用您的工具。安装完成后，按照提示创建 Cline 帐号并添加 API 密钥（可前往 Cline 网站注册并获取）。

  • 创建虚拟环境并安装依赖：在项目文件夹中打开终端（可使用 VS Code 集成终端），创建并激活虚拟环境：

    python -m venv venv
.\venv\Scripts\activate   # Windows 下激活虚拟环境

    然后使用 pip 安装 MCP Python SDK：

    pip install "mcp[cli]"     # 安装 MCP SDK 及命令行工具:contentReference[oaicite:3]{index=3}

    mcp[cli] 包含了所有 MCP 开发所需组件，并会在虚拟环境中提供 mcp 命令。安装完成后，确保 VS Code 已选中该虚拟环境的 Python 解释器（可通过左下角的 Python 版本指示或命令面板进行切换）。

项目目录配置

  1. 创建项目文件夹：例如在 Documents 目录下创建一个文件夹 fileops_project，在 VS Code 中用 “文件 -> 打开文件夹” 功能打开它。

  2. 基础目录结构：在项目根目录下创建主要脚本文件，如 server.py（MCP 服务入口）和可选的工具模块文件（例如 fileops_tools.py）。最终结构示例如下：

    fileops_project/
├── server.py          # MCP 服务主脚本
├── fileops_tools.py   # （可选）工具函数模块
└── venv/              # Python 虚拟环境

    这里所有需要的代码都放在项目文件夹内，有助于安全控制。

  3. 激活环境并测试依赖：在 VS Code 终端确认虚拟环境已激活（提示符应带有 (venv)）。运行 pip show mcp 验证 mcp 包已安装。到此时，开发环境就绪。

编写 MCP 服务代码

MCP 采用客户端-服务器架构：我们编写一个本地 MCP 服务器来实现文件操作功能。使用 FastMCP 类创建服务实例，并用 @mcp.tool() 装饰器将 Python 函数注册为可供模型调用的“工具”。下面是一个简单示例代码，可将其保存为 server.py：

from mcp.server.fastmcp import FastMCP
import os, shutil

# 创建命名为 "fileops" 的 MCP 服务
mcp = FastMCP("fileops")

@mcp.tool()
def create_folder(path: str) -> str:
    """创建新文件夹"""
    try:
        os.makedirs(path, exist_ok=True)
        return f"Created folder: {path}"
    except Exception as e:
        return f"Error: {e}"

@mcp.tool()
def list_directory(path: str) -> list:
    """列出指定目录下的所有文件和子目录"""
    try:
        return os.listdir(path)
    except Exception as e:
        return [f"Error: {e}"]

@mcp.tool()
def delete_item(path: str) -> str:
    """删除指定的文件或文件夹"""
    try:
        if os.path.isdir(path):
            shutil.rmtree(path)
        else:
            os.remove(path)
        return f"Deleted: {path}"
    except Exception as e:
        return f"Error: {e}"

@mcp.tool()
def rename_item(src: str, dest: str) -> str:
    """重命名文件或文件夹"""
    try:
        os.rename(src, dest)
        return f"Renamed {src} to {dest}"
    except Exception as e:
        return f"Error: {e}"

@mcp.tool()
def move_file(src: str, dest: str) -> str:
    """移动文件到新路径"""
    try:
        shutil.move(src, dest)
        return f"Moved {src} to {dest}"
    except Exception as e:
        return f"Error: {e}"

# 在命令行执行本脚本时启动 MCP 服务器
if __name__ == "__main__":
    mcp.run()

上述代码中，我们定义了五个工具函数：create_folder、list_directory、delete_item、rename_item、move_file，分别对应创建文件夹、列出目录内容、删除文件或文件夹、重命名，以及移动文件等功能。每个函数前都加了 @mcp.tool() 装饰器，使其自动注册为 MCP 工具。最后，在 __main__ 中调用 mcp.run() 启动服务器并监听调用。这样，MCP 客户端（如 Cline）就可以通过 JSON 函数调用协议来执行这些 Python 函数。

VS Code + Cline 调试与集成

  1. 启动 MCP 服务：确保虚拟环境激活后，在 VS Code 终端运行：

    python server.py

    这将启动你的 MCP 服务器（后台运行并等待请求）。如果看到没有报错而终端挂起，说明服务器启动成功，等待来自客户端的连接。

  2. 配置 Cline MCP 服务器：打开 VS Code 中 Cline 插件的顶部工具栏，点击 “MCP Servers” 图标进入服务器管理界面（若无图标，请通过命令面板搜索 “Cline: MCP Servers”）。点击 “Configure MCP Servers” 打开全局配置文件 cline_mcp_settings.json。添加如下配置示例：

    {
  "mcpServers": {
    "fileops": {
      "command": "python",
      "args": ["server.py"],#改为你的目录下/文件
      "alwaysAllow": ["*"],
      "disabled": false
    }
  }
}

    该 JSON 配置告诉 Cline 用 python server.py 命令启动名为 fileops 的 MCP 服务器，并自动允许所有注册的工具调用。保存后关闭编辑器，Cline 将识别并启动该服务器（无需额外手动操作）。

  3. 使用工具进行集成测试：在 Cline 的对话窗口中输入自然语言请求，例如：

    “请帮我列出当前项目文件夹下所有文件。”

    Cline 会自动识别你的 list_directory 工具能够完成此任务，并提示调用它。确认后，Cline 会向你的 Python 服务器发送工具调用请求，服务器执行 list_directory 函数，并把返回结果（文件列表）展示在 Cline 聊天结果中。类似地，你也可以请求创建文件夹、删除/移动文件等操作，Cline 会发现对应的工具并执行。完成后，相应的文件操作将在你的项目文件系统中生效。

    另外，你还可以使用 MCP SDK 提供的命令行工具来测试。例如，安装 mcp[cli] 后可以运行：

    mcp dev server.py

    然后在 MCP Inspector（MCP 调试工具）中查看和调用工具。对于新手来说，直接通过 Cline 对话调用是最直观的测试方式。

注意事项

  • 操作安全：务必限制文件操作范围在项目目录内，以防误删系统文件。示例文件服务器一般都会如此设计。本例中，你可在代码中自行检查路径（如只允许相对路径或加上路径前缀）。
  • 路径格式：Windows 下路径使用反斜杠 \，注意在字符串中转义（或使用原始字符串）。例如，传参 "C:\\Users\\Name\\Folder"。相对路径也可使用，如 "./subfolder"。
  • 返回类型：MCP 要求工具返回值可序列化为 JSON，因此尽量返回简单类型（字符串、列表、数字等）。示例中返回了列表或字符串，满足要求。
  • 异常处理：工具函数中应捕获并返回错误信息，避免抛出异常终止服务器。上例每个函数都用 try/except 捕获异常并返回错误文本。
  • 配置白名单：如上例所示，alwaysAllow: ["*"] 表示自动允许所有工具。你也可以仅允许特定工具名称，提升安全性。
  • 调试方法：修改代码后需重启服务（停止再重新运行 python server.py），Cline 才会加载最新的工具。可在 VS Code 中对 server.py 设置断点，然后在终端或 Cline 调用工具时触发调试。也可通过 print() 输出日志，查看控制台或 Cline 日志。
  • MCP 协议了解：本例仅用到了“工具调用”部分。MCP 还支持“资源”和“提示”概念，可根据需要扩展。详细原理可参考 MCP 官方文档。

通过以上步骤，你就构建了一个可以被 AI 模型调用的本地文件操作服务。AI 代码助手（如 Cline）会将你的自然语言请求转换为工具调用，实现文件夹创建、文件删除、重命名等操作。借助 MCP 框架，将复杂的文件操作过程封装为易于调用的接口，使非专业用户也能以自然语言控制本地文件，极大简化了交互流程。

参考资料： 上述方法基于 MCP 官方示例与文档，以及 MCP Python SDK 和 Cline 扩展文档。

posted @ 2025-07-05 21:50  daligh  阅读(538)  评论(0)    收藏  举报