Fsext Mcp Server Java

FsExt-MCP-Server (Java)

概述

使用 Quarkus 构建的高性能、安全的 Model Context Protocol（MCP）服务，用于本地文件系统操作，并配备原生图像处理、Tesseract OCR 和媒体实用工具。完全符合官方 MCP 规范，提供标准化的请求／响应架构、大文件流式 I/O、多传输方式远程部署，以及稳健的文本搜索与替换工作流，便于与大模型 Agent 集成。

核心功能

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

快速开始

前置条件

• Java 17+
• Gradle（仓库内含 wrapper，无需全局安装）
• Tesseract 二进制程序（可选，仅 OCR 工具功能需要）

1. 构建可执行 Uber Jar

使用随附的 Gradle wrapper 编译并打包独立可执行 jar：

# Windows
./gradlew.bat clean buildRunJar

# macOS / Linux
./gradlew clean buildRunJar

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

2. 从打包的 Jar 启动服务

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

# 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）

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

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

本地源代码仓库开发设置

# 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 传输时完全忽略
--port	8000	服务监听的 TCP 端口。如果默认端口 8000 已被占用且未提供自定义端口，则自动选择一个 ≥1024 的空闲端口；使用 stdio 传输时忽略
--origin	*	以逗号分隔的允许用于 HTTP/SSE 远程传输的 CORS 来源列表
--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. Streamable 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 连接配置

• 传输类型：Streamable HTTP
• 连接地址：http://127.0.0.1:8000/mcp

4. SSE 与 Streamable HTTP 传输对比

特性	SSE 双端点传输	Streamable 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 (string, 必填)：用于扫描的根目录
• recursive (boolean, 必填)：启用对所有子目录的完整递归遍历
• only_files (boolean, 必填)：将结果筛选为仅返回常规文件，不包含目录
• file_extension (string, 可选，默认值="")：按目标文件后缀扩展名筛选输出

fs_copy_directory

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

• source_dir (string, 必填)：源目录树路径
• copy_dest_dir (string, 必填)：目标输出目录路径
• overwrite (boolean, 可选，默认值=false)：清空并覆盖目标目录中已有的内容

fs_move_directory

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

• source_dir (string, 必填)：源目录路径
• dest_dir (string, 必填)：目标目录路径
• overwrite (boolean, 可选，默认值=false)：允许覆盖冲突的目标目录

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

fs_create_file

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

• file_path (string, 必填)：目标绝对文件路径
• content (string, 可选，默认值="")：写入新文件的初始文本内容
• charset (string, 可选，默认值="utf-8")：支持的字符集标识符（见上方字符集列表）

fs_delete_file

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

• file_path (string, 必填)：目标常规文件的绝对路径

fs_copy_file

复制单个文件并保留原始文件系统元数据；发生目标文件冲突时可配置覆盖行为。 参数

• source_file_path (string, 必填)：源文件绝对路径
• dest_file_path (string, 必填)：目标输出文件绝对路径
• overwrite (boolean, 可选，默认值=false)：覆盖目标位置已有的文件

fs_move_file

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

• source_file_path (string, 必填)：源文件绝对路径
• dest_file_path (string, 必填)：目标文件绝对路径
• overwrite (boolean, 可选，默认值=false)：允许覆盖冲突的目标文件

fs_get_file_info

获取文件或目录的完整元数据，并可选择计算 SHA-256 加密摘要以验证完整性。 参数

• file_path (string, 必填)：目标文件系统条目的绝对路径
• calc_digest (boolean, 可选，默认值=false)：计算文件内容的 SHA-256 哈希值

fs_is_file_exists

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

• file_path (string, 必填)：要验证是否存在的绝对路径

3. 文件读写工具

fs_read_full_text

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

• file_path (string, 必填)：目标文本文件绝对路径
• charset (string, 可选，默认值="utf-8")：支持的字符集标识符

fs_read_text_range

基于行的分段文本流读取，针对大型文件进行了优化；可跳过开头的行并限制总读取行数，避免过度分配堆内存。 参数

• file_path（字符串，必填）：目标文本文件的绝对路径
• lines_to_skip（整数，必填，最小值=0）：读取时跳过的开头行数
• max_lines_to_read（整数，必填，最小值=0）：从文件中提取的最大总行数
• line_separator（字符串，可选，默认值="\n"）：换行分隔符
• charset（字符串，可选，默认值="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：Streamable 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
• Bug 报告与功能请求：https://github.com/kurtzhi/fsext-mcp-server-java/issues