FsExt-MCP-Server (Python)

概述

这是一个功能齐全的安全MCP服务器，用于本地文件系统操作，内置图像处理、OCR和媒体工具。完全符合官方Model Context Protocol规范，提供标准化的请求/响应模式、大文件流式I/O、多传输远程部署以及全面的文本搜索和替换功能，以支持LLM代理集成。

核心特性

• 完整的文件和目录管理：支持文件创建、删除、复制、移动、元数据查询、存在性检查；全目录树递归复制和移动，并具有覆盖安全控制。
• 流式文件读写：集成全文读取、分段行文本读取、块状二进制读取、文本/二进制覆盖写入和追加写入，优化以避免将整个大文件加载到内存中。
• 强大的搜索与替换：支持目录范围内的递归文件内容搜索，单/多文件上下文匹配（可配置前后匹配行数），正则表达式匹配，不区分大小写的搜索，以及带匹配计数统计的就地文本替换。
• 图像处理工具：内置高性能图像工具包，由Pillow驱动，包括调整大小（保持纵横比+画布填充支持）、裁剪和任意角度顺时针旋转。
• 原生Tesseract OCR识别：依赖于本地安装的Tesseract二进制文件进行可靠的图像文本提取。没有WASM回退选项；空的二进制路径参数不会触发基于JS的替代OCR引擎。支持多语言tessdata资源，可配置二进制文件和数据路径。
• 严格的输入验证和统一的响应格式：每个工具都启用严格的additionalProperties: false模式验证，以阻止意外的输入字段。所有操作共享一个通用的成功/错误封装结构，以便客户端一致解析。
• 多传输支持：兼容官方标准MCP传输方式：stdio（本地桌面客户端集成）、sse（传统轻量级远程流）和可流化的HTTP（现代双向远程流传输）。
• 工作区安全隔离：提供--lock-root目录限制功能。所有文件/目录操作严格限制在指定的工作区根目录内，以防止未经授权的跨目录路径逃逸攻击。

快速开始：直接使用uvx运行（无需预安装）

uvx会自动拉取已发布的PyPI包并启动一个隔离的运行环境，从而消除了手动安装依赖或设置虚拟环境的需求。

1. 基本的uvx启动命令

简短命令（推荐）

# Default stdio mode, unrestricted full filesystem access
uvx fsext-mcp-server

# Lock all operations to a dedicated workspace (production security recommended)
uvx fsext-mcp-server --lock-root /your/workspace

完整命令

# Stdio mode with workspace isolation
uvx fsext-mcp-server --transport stdio --lock-root /your/workspace

# Remote SSE streaming service
uvx fsext-mcp-server --transport sse --host 0.0.0.0 --port 8000 --lock-root /your/workspace

# Modern Streamable HTTP remote service
uvx fsext-mcp-server --transport http --host 0.0.0.0 --port 8000 --lock-root /your/workspace

2. 将FsExt工具与LLM框架集成

无需在主机上预先部署；当MCP客户端建立连接时，uvx会动态实例化服务器。

客户端配置示例（Claude Desktop / Cursor MCP json）

{
  "mcpServers": {
    "fsext": {
      "command": "uvx",
      "args": [
        "fsext-mcp-server",
        "--lock-root",
        "/your/workspace"
      ],
      "env": {"PYTHONUTF8": "1"}
    }
  }
}

LangChain / LangGraph核心集成代码片段

在官方langchain-mcp-adapters中存在会话生命周期限制；实现完整的稳定长连接逻辑需要额外的适配器定制。以下是标准的最小连接模板：

# Core config: Connect to FsExt MCP via uvx stdio transport
server_config = {
    "fsext": {
        "transport": "stdio",
        "command": "uvx",
        "args": ["fsext-mcp-server", "--lock-root", r"/your/workspace"],
        "env": {"PYTHONUTF8": "1"}
    }
}

# Load all exposed filesystem MCP tools
client = MultiServerMCPClient(server_config)
async with client.session("fsext") as session:
    mcp_tools = await load_mcp_tools(session)

# Bind loaded MCP tools to LLM instance for agent workflows
llm = ChatOpenAI(base_url="your-local-llm-api").bind_tools(mcp_tools)

通过pip的传统安装与启动

安装已发布的PyPI包

pip install fsext-mcp-server

pip安装后的启动命令

# Default stdio local mode
fsext-mcp-server-py
fsext-mcp-server

# Short alias
fsext-py
fsext

# Secure workspace locked mode
fsext --lock-root /your/workspace

# Remote SSE streaming server
fsext --transport sse --port 8000

本地源代码仓库开发设置

建议使用uv进行快速且确定性的环境部署：

# Clone official source repository
git clone https://github.com/kurtzhi/fsext-mcp-server-python
cd fsext-mcp-server-python

# Install full runtime + dev dependencies
uv sync

核心运行时依赖项说明

• chardet：自动文本文件编码检测
• Pillow：用于调整大小、裁剪、旋转等核心图像处理后端
• python-magic：准确的跨平台文件MIME类型识别
• fastmcp：官方Python MCP服务器框架
• uvicorn / starlette：HTTP/SSE传输服务器运行时- pydantic: 为所有工具输入参数提供严格的模式验证
• tesseract: 本地 Tesseract OCR 二进制文件的原生绑定

启动使用

服务器支持三种官方 MCP 传输模式，并通过 CLI 标志配置灵活的工作空间根隔离。

启动参数参考表

参数	默认值	描述
--transport	stdio	MCP 传输类型：stdio / sse / http
--host	127.0.0.1	网络绑定地址（在 stdio 传输模式下忽略）
--port	8000	服务绑定端口（在 stdio 传输模式下忽略）
--lock-root	None	将所有文件系统操作限制在此根目录；如果省略则完全不受限制

常见生产启动命令

1. 默认本地 Stdio 模式（适用于 Claude Desktop / Cursor AI 客户端）

uv run -m fsext

2. 带强制工作空间锁定的 Stdio 模式（安全本地代理使用）

uv run -m fsext --lock-root /your/workspace/path

3. 远程 SSE 传输模式

uv run -m fsext --transport sse --host 0.0.0.0 --port 8000

访问端点

1. SSE 长连接订阅通道（服务器事件推送）:
   http://<host>:<port>/sse
2. 客户端 JSON-RPC 请求提交通道:
   http://<host>:<port>/messages

MCP Inspector 连接配置

• 传输类型: SSE
• 连接地址输入: http://127.0.0.1:8000/sse

4. 标准可流式 HTTP 远程传输（现代双向）

uv run -m fsext --transport http --host 0.0.0.0 --port 8000

统一的双向访问端点

客户端请求和服务器流式传输的单一共享入口点：
http://<host>:<port>/mcp

MCP Inspector 连接配置

• 传输类型: 可流式 HTTP
• 连接地址输入: http://127.0.0.1:8000/mcp

5. SSE 与可流式 HTTP 传输功能比较

功能	SSE 双端点传输	可流式 HTTP 单端点传输
端点架构	两个独立的端点：GET 流订阅 + POST 消息发送	单一统一 URL 处理所有双向流量
通信模式	仅单向服务器到客户端事件推送	全双工请求/流混合能力
连接可靠性	会话频繁丢失，跨端点状态管理复杂	自动会话恢复，优化高并发远程连接
官方规范状态	兼容旧版实现，不推荐用于新部署	当前官方 MCP 标准，适用于远程网络集成

统一全局响应规范

所有 MCP 工具在成功执行和运行时失败状态下共享相同的顶级包装 JSON 结构。每个工具的业务负载嵌套在根 res 字段下的 info 子对象中。

核心结构定义

{
  "res": {
    "success": boolean,
    "info": object
  }
}

• success: 全局操作状态标志
  • true: 工具逻辑无异常执行；info 包含工具特定的返回数据
  • false: 操作失败（工作空间逃逸阻止、缺少文件、IO 错误、无效输入模式、权限拒绝等）
• info 字段的双重行为：
  1. 成功模式 (success: true)：每个工具特有的自定义结构化业务负载
  2. 失败模式 (success: false)：具有机器可读错误代码和人类可读解释的固定标准化错误对象

     "info": {
       "code": "ERROR_CODE_IDENTIFIER",
       "message": "Detailed human-readable failure description"
     }
     

完整示例响应

1. 成功响应示例 (fs_list_directory)

{
  "res": {
    "success": true,
    "info": {
      "paths": [
        "/tmp/tests/test_util.py",
        "/tmp/tests/__init__.py",
        "/tmp/tests/img/cochem_castle.jpg"
      ]
    }
  }
}

2. 失败响应示例 (工作空间路径逃逸限制)

{
  "res": {
    "success": false,
    "info": {
      "code": "WORKSPACE_ESCAPE_FORBIDDEN",
      "message": "Access restricted: Path `/tmp/test2` is outside allowed workspace `/tmp/tests`"
    }
  }
}

所有工具都强制执行工作空间根隔离，并完全遵循下面列出的标准输入/输出模式定义。

完整的 MCP 工具参考

所有工具输入模式启用 additionalProperties: false 严格验证以拒绝未识别的参数并防止恶意路径注入。

1. 目录操作工具

fs_list_directory描述: 递归或浅层扫描目标目录，返回带有文件类型和扩展名过滤控制的过滤后的绝对文件系统路径列表。

参数:

• source_dir (字符串, 必需): 扫描的根目录路径
• recursive (布尔值, 必需): 启用对所有子目录的完全递归遍历
• only_files (布尔值, 必需): 过滤输出以仅返回常规文件，排除目录
• file_extension (字符串, 可选, 默认=""): 过滤结果以匹配指定后缀扩展名的文件
  成功响应负载:

{
  "res": {
    "success": true,
    "info": {
      "paths": ["/absolute/path/file1.txt", "/absolute/path/file2.py"]
    }
  }
}

fs_copy_directory

描述: 递归复制整个目录树，并可配置覆盖行为以处理已存在的目标目录。
参数:

• source_dir (字符串, 必需): 源目录树路径
• copy_dest_dir (字符串, 必需): 目标输出目录路径
• overwrite (布尔值, 可选, 默认=false): 清除并覆盖现有目标目录内容
  成功响应负载:

{
  "res": {
    "success": true,
    "info": {}
  }
}

fs_move_directory

描述: 原子性地将整个目录树移动到新的目标路径。如果目标存在，则立即失败，除非显式启用覆盖以避免意外数据丢失。
参数:

• source_dir (字符串, 必需): 源目录路径
• dest_dir (字符串, 必需): 目标目录路径
• overwrite (布尔值, 可选, 默认=false): 允许覆盖冲突的目标目录
  成功响应负载: 包含成功标志的空 info 对象包装器。

2. 单个文件基本操作工具

fs_create_file

描述: 创建一个新的文本文件，自动生成缺失的父目录，支持可配置的文本编码和初始文件内容。
参数:

• file_path (字符串, 必需): 目标绝对文件路径
• content (字符串, 可选, 默认=""): 写入新文件的初始文本内容
• charset (字符串, 可选, 默认="utf-8"): 文本编码枚举值（完整字符集列表如下）
  支持的字符集枚举值:
  utf-8, utf-16, latin-1, iso-8859-1, cp1252, Windows-1252, gbk, gb2312, shift_jis, euc_jp, euc_kr
  成功响应负载: 包含成功标志的空 info 对象包装器。

fs_delete_file

描述: 永久删除单个常规文件；拒绝目录路径输入以阻止大规模递归删除风险。
参数:

• file_path (字符串, 必需): 目标常规文件的绝对路径
  成功响应负载: 包含成功标志的空 info 对象包装器。

fs_copy_file

描述: 复制单个文件同时保留原始文件系统元数据，可配置覆盖冲突的目标文件。
参数:

• source_file_path (字符串, 必需): 源文件的绝对路径
• dest_file_path (字符串, 必需): 目标输出文件的绝对路径
• overwrite (布尔值, 可选, 默认=false): 覆盖已存在的目标文件
  成功响应负载: 包含成功标志的空 info 对象包装器。

fs_move_file

描述: 原子性地将单个文件移动到新的绝对路径，可配置覆盖冲突的目标文件的行为。
参数:

• source_file_path (字符串, 必需): 源文件的绝对路径
• dest_file_path (字符串, 必需): 目标文件的绝对路径
• overwrite (布尔值, 可选, 默认=false): 允许覆盖冲突的目标文件
  成功响应负载: 包含成功标志的空 info 对象包装器。

fs_get_file_info

描述: 检索文件或目录的完整元数据，可选计算SHA-256加密摘要以进行完整性验证。
参数:

• file_path (字符串, 必需): 目标文件系统条目的绝对路径
• calc_digest (布尔值, 可选, 默认=false): 计算文件内容的SHA-256哈希
  成功响应负载:
  PLACEHOLDER_CODE_17### fs_is_file_exists
  描述: 对任何文件系统条目（文件或目录）进行轻量级的存在性检查，无需加载完整的元数据。
  参数:
• file_path (字符串, 必需): 要验证的目标绝对路径
  成功响应负载:

{
  "res": {
    "success": true,
    "info": {
      "exists": true
    }
  }
}

3. 文件读写工具

fs_read_full_text

描述: 使用用户指定的文本编码读取目标文件的完整文本内容。
参数:

• file_path (字符串, 必需): 目标文本文件的绝对路径
• charset (字符串, 可选, 默认="utf-8"): 文本编码枚举值
  成功响应负载:

{
  "res": {
    "success": true,
    "info": {
      "content": "complete-text-file-content-here"
    }
  }
}

fs_read_text_range

描述: 针对大文件优化的分段文本流读取；跳过前导行并限制总读取行数以避免内存过载。
参数:

• file_path (字符串, 必需): 目标文本文件的绝对路径
• lines_to_skip (整数, 必需, 最小值=0): 读取时要跳过的初始行数
• max_lines_to_read (整数, 必需, 最小值=0): 从文件中提取的最大行数
• line_separator (字符串, 可选, 默认="\n"): 行分隔符字符
• charset (字符串, 可选, 默认="utf-8"): 文本编码枚举值
  成功响应负载:

{
  "res": {
    "success": true,
    "info": {
      "lines_count": 5,
      "content": "segmented-text-content-block"
    }
  }
}

fs_read_binary_chunk

描述: 二进制文件的块式流读取；返回Base64编码的字节负载以便安全地通过网络JSON-RPC传输，并检测到流结束标记。
参数:

• file_path (字符串, 必需): 目标二进制文件的绝对路径
• bytes_to_skip (整数, 必需, 最小值=0): 在读取块之前要跳过的前导字节数
• max_bytes_to_read (整数, 必需, 最小值=0): 单个块中最大可读字节长度
  成功响应负载:

{
  "res": {
    "success": true,
    "info": {
      "data_base64": "base64-encoded-binary-byte-data",
      "raw_bytes_length": 5,
      "end_of_stream": true
    }
  }
}

fs_write_text

描述: 将UTF或多编码的文本内容写入目标文件，支持完全覆盖或仅追加写入模式。
参数:

• file_path (字符串, 必需): 目标输出文件的绝对路径
• text (字符串, 必需, 最小长度=1): 要持久化的原始文本内容
• append (布尔, 可选, 默认=false): 追加模式标志 (false = 覆盖整个文件)
• charset (字符串, 可选, 默认="utf-8"): 文本编码枚举值
  成功响应负载: 包含成功标志的空info对象。

fs_write_binary

描述: 解码Base64编码的二进制负载并将原始字节写入目标文件，支持多块二进制上传的追加模式。
参数:

• file_path (字符串, 必需): 目标输出文件的绝对路径
• base64_data (字符串, 必需, 最小长度=1): Base64编码的原始二进制字节负载
• append (布尔, 可选, 默认=false): 将二进制数据追加到文件末尾 (false = 覆盖)
  成功响应负载: 包含成功标志的空info对象。

4. 内容搜索与原位替换工具

fs_search_files_by_content

描述: 递归扫描目录树并返回包含匹配目标文本模式的所有文件的绝对路径；支持正则表达式匹配、大小写不敏感和文件扩展名过滤。
参数:

• dir_path (字符串, 必需): 用于递归内容扫描的根目录
• recursive (布尔, 必需): 启用全子目录递归
• search_term (字符串, 必需): 纯文本关键字或正则表达式模式
• is_regex (布尔, 可选, 默认=false): 当为true时将search_term视为正则表达式模式
• ignore_case (布尔, 可选, 默认=true): 大小写不敏感模式匹配
• file_extension (字符串, 可选, 默认=""): 按扩展名后缀过滤扫描文件
• charset (字符串, 可选, 默认="utf-8"): 用于文件解析的文本编码枚举值

fs_search_in_files_by_content描述: 多目录批量内容匹配，返回带有可配置的前后上下文行的结构化匹配结果，以及全局结果数量限制。

参数:

• dir_path (字符串, 必需): 根扫描目录的绝对路径
• recursive (布尔值, 必需): 启用完整的递归子目录遍历
• search_term (字符串, 必需): 搜索关键字或正则表达式模式
• limit (整数, 必需): 返回匹配条目的硬性最大限制
• is_regex (布尔值, 可选, 默认=false): 启用正则表达式匹配
• ignore_case (布尔值, 可选, 默认=true): 禁用区分大小写的匹配
• lines_before (整数, 可选, 默认=0): 每个匹配行之前的上下文行数
• lines_after (整数, 可选, 默认=0): 每个匹配行之后的上下文行数
• file_extension (字符串, 可选, 默认=""): 通过文件扩展名后缀过滤扫描文件
• charset (字符串, 可选, 默认="utf-8"): 用于文件解析的文本编码枚举值
  成功响应负载:

{
  "res": {
    "success": true,
    "info": {
      "results": [
        {
          "file_path": "/absolute/path/source.py",
          "start_line": 1,
          "end_line": 1,
          "text": "full-matched-line-content-with-context"
        }
      ]
    }
  }
}

fs_search_in_file_by_content

描述: 精确单文件内容搜索，返回带有可配置前/后上下文行的结构化匹配段落，适用于代码和文档检查工作流程。
参数:

• file_path (字符串, 必需): 目标单个文件的绝对路径
• search_term (字符串, 必需): 搜索关键字或正则表达式模式
• is_regex (布尔值, 可选, 默认=false): 启用正则表达式匹配逻辑
• ignore_case (布尔值, 可选, 默认=true): 区分大小写匹配切换
• lines_before (整数, 可选, 默认=0): 每个匹配项之前的上下文行数
• lines_after (整数, 可选, 默认=0): 每个匹配项之后的上下文行数
• charset (字符串, 可选, 默认="utf-8"): 用于文件解析的文本编码枚举值
  成功响应负载: 结构化的行匹配对象数组，格式与多文件搜索输出格式相同。

fs_file_replace

描述: 在单个目标文件中执行全局就地文本替换；在写入后返回匹配并替换的文本段总数。
参数:

• file_path (字符串, 必需): 目标可编辑文件的绝对路径
• search_term (字符串, 必需): 要定位和替换的文本子串
• replacement (字符串, 必需): 新的替换文本载荷
• line_separator (字符串, 可选, 默认="\n"): 用于文件解析的行分隔符
  成功响应负载:

{
  "res": {
    "success": true,
    "info": {
      "count": 1
    }
  }
}

5. 图像处理工具

fs_image_resize

描述: 将源图像调整到指定的宽度/高度尺寸，支持保持纵横比和画布填充以达到精确的目标分辨率尺寸。
参数:

• source_path (字符串, 必需): 源输入图像的绝对路径
• dest_path (字符串, 必需): 调整大小后的输出图像的绝对路径
• width (整数, 必需, exclusiveMinimum=0): 目标像素宽度
• height (整数, 必需, exclusiveMinimum=0): 目标像素高度
• keep_aspect_ratio (布尔值, 可选, 默认=true): 在缩放时锁定原始图像的纵横比
• pad_to_target (布尔值, 可选, 默认=true): 当锁定纵横比时，添加透明填充以填满确切的目标宽度/高度
  成功响应负载: 带有成功标志的空 info 对象包装器。

fs_image_crop

描述: 从源图像中提取一个矩形像素区域，并导出为独立的输出图像文件。
参数:

• source_path (字符串, 必需): 源输入图像的绝对路径
• dest_path (字符串, 必需): 裁剪后的输出图像的绝对路径
• x (整数, 必需, minimum=0): 裁剪区域原点的左像素坐标
• y (整数, 必需, minimum=0): 裁剪区域原点的顶像素坐标- width (整数，必填，exclusiveMinimum=0)：裁剪后的矩形区域的像素宽度
• height (整数，必填，exclusiveMinimum=0)：裁剪后的矩形区域的像素高度
  成功响应负载：带有成功标志的空 info 对象包装器。

fs_image_rotate

描述：将源图像顺时针旋转任意浮点度数；自动扩展输出画布尺寸以保留完整图像内容而不裁剪边缘。
参数：

• source_path (字符串，必填)：源输入图像的绝对路径
• dest_path (字符串，必填)：旋转后输出图像的绝对路径
• degrees (数字，必填)：顺时针旋转的角度（单位：度）
  成功响应负载：带有成功标志的空 info 对象包装器。

6. OCR 文本提取工具

fs_ocr_extract_text

描述：通过本地安装的 Tesseract OCR 二进制文件从光栅图像文件中提取可读文本。没有 WASM JavaScript 备用实现；空的 tesseract_bin_path 参数不会初始化替代的基于 Web 的 OCR 引擎。
参数：

• image_path (字符串，必填)：用于文本识别的输入图像的绝对路径
• tesseract_bin_path (字符串，可选，默认="")：本地 Tesseract 可执行二进制文件的绝对路径；空值仅使用系统 PATH 查找
• tessdata_path (字符串，可选，默认="")：包含 Tesseract 语言训练数据文件的绝对目录路径
• lang (字符串，可选，默认="eng")：与可用 tessdata 训练文件匹配的语言代码前缀
  成功响应负载：

{
  "res": {
    "success": true,
    "info": {
      "content": "full-ocr-extracted-text-from-input-image"
    }
  }
}

项目构建和开发脚本

所有标准化的 npm 等效 uv 开发脚本供源代码仓库贡献者使用：

# Clean compiled build artifacts and temporary output directories
uv run -m scripts.clean

# Compile source code and type validation
uv run -m scripts.build

# Watch source files for incremental development rebuilds
uv run -m scripts.dev

# Full rebuild pipeline: clean artifacts + full source compilation
uv run -m scripts.rebuild

# Launch remote SSE transport server instance
uv run -m scripts.server

# FastMCP interactive development mode
uv run -m scripts.fastmcp

# MCP Inspector debug connection launcher
uv run -m scripts.inspect

# Execute full test suite with compiled test artifacts
uv run -m scripts.test

核心运行时依赖项

• fastmcp：官方 Python MCP 服务器运行时框架
• Pillow：跨平台图像处理后端，用于调整大小、裁剪和旋转管道
• tesseract：本地 Tesseract OCR 二进制文件的原生 Python 绑定
• chardet：多编码文本文件检测
• iconv-lite 等效后端：跨平台文本编码转换工具
• cors：CORS 中间件，用于 HTTP/SSE 远程传输服务器
• minimist 等效 CLI 解析器：启动标志的命令行参数解析
• pydantic：所有 MCP 工具输入模式的严格类型模式验证
• uvicorn / starlette：远程传输部署的 ASGI HTTP 服务器运行时

许可证

该项目在 Apache License 2.0 下开源。请参阅项目根目录中的 LICENSE 文件以获取完整的法律许可条款和条件。

第三方组件许可证

该项目集成了多个开源依赖库，包括 chardet、Pillow、python-magic 和 Tesseract 绑定。所有第三方库保留其各自的原始开源许可协议和版权声明。

重要说明：此分发包中不包含任何 FFmpeg 二进制文件。如果启用了外部媒体处理扩展，最终用户必须单独遵守 FFmpeg 的官方许可条款。

仓库和问题跟踪

• GitHub 源代码仓库：https://github.com/kurtzhi/fsext-mcp-server-python
• 错误报告和功能请求：https://github.com/kurtzhi/fsext-mcp-server-python/issues