FsExt-MCP-Server (Java)

概述

FsExt-MCP-Server 是一个高性能、安全的模型上下文协议（MCP）服务器，使用 Quarkus 构建，用于本地文件系统操作。它配备了原生图像处理、Tesseract OCR 和媒体工具。完全符合官方 MCP 规范，提供标准化的请求/响应模式、大文件流式 I/O、多传输远程部署以及强大的文本搜索和替换工作流程，适用于 LLM 代理集成。

核心功能

• 完整的文件和目录管理：支持文件创建、删除、复制、移动、元数据检查和存在验证；递归全目录树复制/移动，并带有覆盖安全保护。
• 流式文件读写管道：全文加载、分段逐行文本流、分块二进制 I/O 以及文本/二进制覆盖/追加逻辑，设计为避免将整个大文件加载到 JVM 堆内存中。
• 高级搜索和就地替换：递归目录范围的内容扫描、多文件上下文匹配（可配置的前后文行数）、正则表达式支持、不区分大小写的匹配以及原子性的就地文本替换，并提供匹配计数统计。
• 原生图像处理工具包：由 Tess4J 提供支持的高速图像工具，包括锁定宽高比的调整大小（带画布填充）、精确矩形裁剪和任意顺时针旋转。
• Tesseract OCR 文本提取：通过本地 Tesseract 二进制文件支持从光栅图像可靠地识别文本。没有 WASM 回退实现；空的二进制路径配置不会触发基于 JS 的替代 OCR 引擎。支持多语言 tessdata，并可配置二进制文件和数据目录。
• 严格的输入验证和统一的响应模式：每个工具都强制执行严格的 additionalProperties: false JSON 模式验证，以阻止未识别的输入字段并减轻注入风险。所有操作返回一致的封装成功/错误负载，以便客户端进行统一解析。
• 多传输兼容性：实现了所有官方 MCP 标准传输：
  • stdio：本地桌面 MCP 客户端（如 Claude Desktop、Cursor 等）的原生集成
  • sse：传统的轻量级远程事件流传输
  • http：现代双向远程流式 HTTP 传输
• 工作区安全沙箱隔离：--lock-root 标志将所有文件系统操作限制在指定的目录树内，消除路径逃逸漏洞和未经授权的跨文件夹访问。
• 动态端口分配：自动检测默认端口 8000 是否被占用，并在未提供自定义 --port 值时分配一个高于 1024 的可用 TCP 端口。
• Quarkus 原生运行时优化：低启动延迟、最小内存占用、内置 CORS 支持用于远程 HTTP/SSE 部署，以及针对长生命周期远程客户端会话的优雅连接关闭逻辑。

快速开始

前提条件

• Java 17+
• Gradle（仓库中包含 Gradle 包装器，无需全局安装）
• Tesseract 二进制文件（可选，仅 OCR 工具功能需要）

1. 构建可执行的 Uber Jar

使用捆绑的 Gradle 包装器编译并打包一个自包含的可执行 jar：
bash

# Windows
./gradlew.bat clean buildRunJar

# macOS / Linux
./gradlew clean buildRunJar

输出工件路径：build/fsext-mcp-server-<version>.jar

2. 从打包的 Jar 启动服务器

将 <x.y.z> 替换为实际构建版本字符串。
bash

# Default stdio mode, unrestricted full filesystem access
java -jar build/fsext-mcp-server-x.y.z.jar

# Secure locked workspace mode (recommended for production agent usage)
java -jar build/fsext-mcp-server-x.y.z.jar --lock-root /my/workspace

# Remote SSE streaming service
java -jar build/fsext-mcp-server-x.y.z.jar --transport sse --host 0.0.0.0 --port 8000 --lock-root /my/workspace

# Modern Streamable HTTP remote service
java -jar build/fsext-mcp-server-x.y.z.jar --transport http --host 127.0.0.1 --port 8080 --lock-root /my/workspace

3. 与 MCP 桌面客户端（Claude Desktop / Cursor）集成

示例客户端配置 JSON 用于 stdio 传输本地集成：
json

{
  "mcpServers": {
    "fsext-java": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/fsext-mcp-server-x.y.z.jar",
        "--lock-root",
        "/my/workspace"
      ]
    }
  }
}

本地源代码库开发设置

bash

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

# Build full executable uber jar
./gradlew clean buildRunJar

CLI 启动参数参考表

参数	默认值	描述
--transport	stdio	MCP 传输实现：stdio / sse / http
--host	127.0.0.1	网络绑定地址；在 stdio 传输下完全忽略
--origin	*	允许的CORS来源列表（以逗号分隔），适用于HTTP/SSE远程传输
--lock-root	空	将所有文件系统操作限制在此根目录内；如果省略，则具有完全不受限制的操作系统访问权限

生产部署启动示例

1. 本地Stdio模式（桌面MCP客户端）

java -jar build/fsext-mcp-server-x.y.z.jar --lock-root /my/workspace

2. 远程SSE传输模式

java -jar build/fsext-mcp-server-x.y.z.jar --transport sse --host 0.0.0.0 --port 8000 --lock-root /my/workspace

SSE端点

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

MCP Inspector连接配置

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

3. 可流式处理的HTTP远程传输（官方现代标准）

java -jar build/fsext-mcp-server-x.y.z.jar --transport http --host 0.0.0.0 --port 8000 --lock-root /my/workspace

统一的双向端点

单个共享入口点处理所有客户端请求和服务器流式传输流量:
http://<host>:<port>/mcp

MCP Inspector连接配置

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

4. SSE与可流式处理的HTTP传输比较

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

支持的文本文件字符集

所有字符集标识符不区分大小写；有效的文本读写操作值：

• utf-8 / UTF_8
• iso-8859-1 / ISO_8859_1
• utf-16 / UTF_16
• utf-16be / UTF_16BE
• utf-16le / UTF_16LE
• ascii / US_ASCII

统一全局响应规范

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

核心模式定义

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

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

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

示例响应负载

1. 成功的目录列表响应

{
  "res": {
    "success": true,
    "info": {
      "paths": [
        "/workspace/demo/Main.java",
        "/workspace/demo/util/FileTool.java"
      ]
    }
  }
}

2. 工作区逃逸安全阻止失败响应

{
  "res": {
    "success": false,
    "info": {
      "code": "WORKSPACE_ESCAPE_FORBIDDEN",
      "message": "Access restricted: Path `/etc/passwd` is outside allowed workspace `/my/workspace`"
    }
  }
}

完整的MCP工具参考

所有工具输入模式强制执行additionalProperties: false严格验证，以拒绝未识别的参数并减轻恶意路径注入攻击向量。

1. 目录操作工具

fs_list_directory

扫描目标目录（浅层或递归），并返回过滤后的绝对文件路径，支持类型和扩展名过滤。
参数

• source_dir (字符串, 必需): 扫描的根目录
• recursive (布尔值, 必需): 启用对所有子目录的完全递归遍历
• only_files (布尔值, 必需): 仅返回常规文件，排除目录- file_extension (string, optional, default=""): 按目标文件后缀扩展名过滤输出

fs_copy_directory

递归复制整个目录树，并可配置冲突目标目录的覆盖行为。
参数

• source_dir (string, required): 源目录树路径
• copy_dest_dir (string, required): 目标输出目录路径
• overwrite (boolean, optional, default=false): 清除并覆盖已存在的目标目录内容

fs_move_directory

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

• source_dir (string, required): 源目录路径
• dest_dir (string, required): 目标目录路径
• overwrite (boolean, optional, default=false): 允许覆盖冲突的目标目录

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

fs_create_file

创建一个新的文本文件，自动生成缺失的父目录，并可配置初始文本内容和字符集编码。
参数

• file_path (string, required): 目标绝对文件路径
• content (string, optional, default=""): 写入新文件的初始文本内容
• charset (string, optional, default="utf-8"): 支持的字符集标识符（参见上面的字符集列表）

fs_delete_file

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

• file_path (string, required): 目标常规文件的绝对路径

fs_copy_file

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

• source_file_path (string, required): 源文件绝对路径
• dest_file_path (string, required): 目标输出文件绝对路径
• overwrite (boolean, optional, default=false): 覆盖已存在的目标文件

fs_move_file

原子性地将单个文件移动到新的绝对路径，可配置覆盖逻辑以处理冲突的目标文件。
参数

• source_file_path (string, required): 源文件绝对路径
• dest_file_path (string, required): 目标文件绝对路径
• overwrite (boolean, optional, default=false): 允许覆盖冲突的目标文件

fs_get_file_info

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

• file_path (string, required): 目标文件系统条目的绝对路径
• calc_digest (boolean, optional, default=false): 计算文件内容的SHA-256哈希值

fs_is_file_exists

轻量级检查任何文件系统条目（文件或目录）是否存在，而不加载完整的元数据。
参数

• file_path (string, required): 验证存在的绝对路径

3. 文件读写工具

fs_read_full_text

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

• file_path (string, required): 目标文本文件的绝对路径
• charset (string, optional, default="utf-8"): 支持的字符集标识符

fs_read_text_range

针对大文件优化的分段行基文本流；跳过前导行并限制总读取行数以避免过多的堆分配。
参数

• file_path (string, required): 目标文本文件的绝对路径
• lines_to_skip (integer, required, min=0): 读取时要跳过的初始行数
• max_lines_to_read (integer, required, min=0): 从文件中提取的最大行数
• line_separator (string, optional, default="\n"): 行分隔符字符
• charset (string, optional, default="utf-8"): 支持的字符集标识符

fs_read_binary_chunk

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

• file_path (字符串, 必需): 目标二进制文件的绝对路径
• bytes_to_skip (整数, 必需, 最小值=0): 在读取块之前要跳过的前导字节偏移量
• max_bytes_to_read (整数, 必需, 最小值=0): 单次读取的最大字节长度

fs_write_text

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

• file_path (字符串, 必需): 目标输出文件的绝对路径
• text (字符串, 必需, 最小长度=1): 要持久化的原始文本内容
• append (布尔值, 可选, 默认=false): 追加模式开关（false = 完全覆盖文件）
• charset (字符串, 可选, 默认="utf-8"): 支持的字符集标识符

fs_write_binary

解码Base64二进制负载并将原始字节写入目标文件；支持多块二进制上传工作流中的追加模式。
参数

• file_path (字符串, 必需): 目标输出文件的绝对路径
• base64_data (字符串, 必需, 最小长度=1): Base64编码的原始二进制字节负载
• append (布尔值, 可选, 默认=false): 将二进制数据追加到文件末尾（false = 完全覆盖）

4. 内容搜索与就地替换工具

fs_search_files_by_content

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

• dir_path (字符串, 必需): 用于递归内容扫描的根目录
• recursive (布尔值, 必需): 启用完整的子目录递归
• search_term (字符串, 必需): 纯文本关键字或正则表达式模式
• is_regex (布尔值, 可选, 默认=false): 将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"): 用于解析目标文件的字符集

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"): 用于文件解析的行分隔符

5. 图像处理工具

fs_image_resize

将源图像调整为指定的像素尺寸，保持原始纵横比，并使用透明画布填充以达到确切的目标分辨率尺寸。
参数

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

fs_image_crop

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

• source_path (字符串, 必需): 源输入图像的绝对路径
• dest_path (字符串, 必需): 裁剪后的输出图像的绝对路径
• x (整数, 必需, ≥0): 裁剪区域左边缘的像素坐标
• y (整数, 必需, ≥0): 裁剪区域顶边的像素坐标
• width (整数, 必需, >0): 裁剪矩形区域的像素宽度
• height (整数, 必需, >0): 裁剪矩形区域的像素高度

fs_image_rotate

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

• source_path (字符串, 必需): 源输入图像的绝对路径
• dest_path (字符串, 必需): 旋转后的输出图像的绝对路径
• degrees (数字, 必需): 顺时针旋转的角度（度）

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 训练文件匹配的语言代码前缀

核心运行时依赖

• io.quarkus:quarkus-bom:3.37.1: Quarkus 版本对齐 BOM
• io.quarkus:quarkus-arc: Quarkus CDI 依赖注入容器
• io.quarkus:quarkus-reactive-routes: 反应式 HTTP 路由核心
• io.quarkiverse.mcp:quarkus-mcp-server-http:1.13.1: 可流式传输的 HTTP & SSE MCP 传输实现
• io.quarkiverse.mcp:quarkus-mcp-server-stdio:1.13.1: Stdio MCP 传输实现
• net.sourceforge.tess4j:tess4j:5.18.0: Java Tesseract OCR 绑定库

项目构建与开发 Gradle 任务

# Clean all compiled build artifacts and temporary directories
./gradlew clean

# Full clean + compile + package self-contained uber jar
./gradlew clean buildRunJar

许可证

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

第三方软件声明

该软件捆绑了多个开源依赖库。所有第三方组件保留其原始版权所有者及其各自的开源许可协议。所有第三方库、版本和许可证的详细信息可以在根目录级别的 THIRD-PARTY-NOTICES 文件中找到，该文件也打包在 JAR 文件中的 /META-INF/THIRD-PARTY-NOTICES 路径下。

代码仓库与问题跟踪

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