FsExt-MCP-Server (Java)

Overview

A high-performance, secure Model Context Protocol (MCP) server built with Quarkus for local filesystem operations, equipped with native image processing, Tesseract OCR, and media utility tooling. Fully compliant with the official MCP specification, delivering standardized request/response schemas, large-file streaming I/O, multi-transport remote deployment, and robust text search & replace workflows for LLM agent integration.

Core Features

• Complete File & Directory Management: Supports file creation, deletion, copy, move, metadata inspection, and existence validation; recursive full directory tree copy/move with overwrite safety guards.
• Streaming File Read & Write Pipeline: Full text loading, segmented line-by-line text streaming, chunked binary I/O, and text/binary overwrite/append logic engineered to avoid loading entire large files into JVM heap memory.
• Advanced Search & In-Place Replace: Recursive directory-wide content scanning, multi-file contextual matching with configurable pre/post context lines, regular expression support, case-insensitive matching, and atomic in-place text replacement with match count statistics.
• Native Image Processing Toolkit: High-speed image utilities powered by Tess4J, including aspect-ratio locked resizing with canvas padding, precise rectangular cropping, and arbitrary clockwise rotation.
• Tesseract OCR Text Extraction: Reliable text recognition from raster images backed by local Tesseract binaries. No WASM fallback implementations; empty binary path configuration will not trigger alternative JS-based OCR engines. Multi-language tessdata support with configurable binary and data directories.
• Strict Input Validation & Unified Response Schema: Every tool enforces strict `additionalProperties: false` JSON schema validation to block unrecognized input fields and mitigate injection risks. All operations return a consistent wrapped success/error payload for uniform client-side parsing.
• Multi-Transport Compatibility: Implements all official MCP standard transports:
• Workspace Security Sandbox Isolation: The `--lock-root` flag restricts all filesystem operations exclusively to the specified directory tree, eliminating path escape vulnerabilities and unauthorized cross-folder access.
• Dynamic Port Allocation: Automatically detects default port 8000 occupancy and allocates a free TCP port above 1024 when no custom `--port` value is supplied.
• Quarkus Native Runtime Optimizations: Low startup latency, minimal memory footprint, built-in CORS support for remote HTTP/SSE deployments, and graceful connection shutdown logic for long-lived remote client sessions.

Quick Start

Prerequisites

• Java 17+
• Gradle (wrapper included in repository, no global installation required)
• Tesseract binary (optional, only required for OCR tool functions)

1. Build Executable Uber Jar

Use the bundled Gradle wrapper to compile and package a self-contained executable jar:

# Windows
./gradlew.bat clean buildRunJar

# macOS / Linux
./gradlew clean buildRunJar

Output artifact path: `build/fsext-mcp-server-.jar`

2. Launch Server from Packaged Jar

Replace `` with your actual build version string.

# 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. Integrate with MCP Desktop Clients (Claude Desktop / Cursor)

Sample client configuration JSON for stdio transport local integration:

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

Local Source Repository Development Setup

# 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 Startup Parameter Reference Table

Production Deployment Startup Examples

1. Local Stdio Mode (Desktop MCP Clients)

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

2. Remote SSE Transport Mode

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

SSE Endpoints

1. Long-lived SSE stream subscription channel (server event push):

`http://:/sse`

2. JSON-RPC client request submission channel:

`http://:/messages`

MCP Inspector Connection Config

• Transport Type: SSE
• Connection Address: `http://127.0.0.1:8000/sse`

3. Streamable HTTP Remote Transport (Official Modern Standard)

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

Unified Bidirectional Endpoint

Single shared entry point handling all client requests and server streaming traffic:

`http://:/mcp`

MCP Inspector Connection Config

• Transport Type: Streamable HTTP
• Connection Address: `http://127.0.0.1:8000/mcp`

4. SSE vs Streamable HTTP Transport Comparison

Supported Text File Charsets

All charset identifiers are case-insensitive; valid values for text read/write operations:

• `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`

Unified Global Response Specification

All MCP tools share an identical top-level wrapped JSON structure for both successful execution and runtime failure states. Business payloads for each tool are nested within the `info` sub-object under the root `res` field.

Core Schema Definition

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

• `success`: Global operation status flag
• Dual behavior of `info`:

1. Success state (`success: true`): Structured custom payload unique to each tool

2. Failure state (`success: false`): Standardized error object with machine-readable error code and human-readable explanation

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

Sample Response Payloads

1. Successful Directory Listing Response

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

2. Workspace Escape Security Block Failure Response

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

Complete MCP Tools Reference

All tool input schemas enforce `additionalProperties: false` strict validation to reject unrecognized parameters and mitigate malicious path injection attack vectors.

1. Directory Operation Tools

fs_list_directory

Scan target directory (shallow or recursive) and return filtered absolute file paths with type and extension filtering support.

Parameters

• `source_dir` (string, required): Root directory for scanning
• `recursive` (boolean, required): Enable full recursive traversal of all subdirectories
• `only_files` (boolean, required): Filter results to return regular files only, exclude directories
• `file_extension` (string, optional, default=""): Filter output by target file suffix extension

fs_copy_directory

Recursively copy an entire directory tree with configurable overwrite behavior for conflicting destination directories.

Parameters

• `source_dir` (string, required): Source directory tree path
• `copy_dest_dir` (string, required): Target output directory path
• `overwrite` (boolean, optional, default=false): Clear and overwrite pre-existing destination directory contents

fs_move_directory

Atomically relocate an entire directory tree to a new target path. Fails immediately if destination exists unless overwrite is explicitly enabled to prevent accidental data loss.

Parameters

• `source_dir` (string, required): Source directory path
• `dest_dir` (string, required): Target directory path
• `overwrite` (boolean, optional, default=false): Allow overwriting conflicting destination directories

2. Single File Basic Operation Tools

fs_create_file

Create a new text file, auto-generate missing parent directories, with configurable initial text content and charset encoding.

Parameters

• `file_path` (string, required): Target absolute file path
• `content` (string, optional, default=""): Initial text content to write into the new file
• `charset` (string, optional, default="utf-8"): Supported charset identifier (see charset list above)

fs_delete_file

Permanently delete a single regular file only; rejects directory path inputs to block mass recursive deletion risks.

Parameters

• `file_path` (string, required): Absolute path of target regular file

fs_copy_file

Copy a single file while retaining original filesystem metadata, with configurable overwrite for conflicting target files.

Parameters

• `source_file_path` (string, required): Source file absolute path
• `dest_file_path` (string, required): Target output file absolute path
• `overwrite` (boolean, optional, default=false): Overwrite pre-existing destination file

fs_move_file

Atomically move a single file to a new absolute path, with configurable overwrite logic for conflicting destination files.

Parameters

• `source_file_path` (string, required): Source file absolute path
• `dest_file_path` (string, required): Target file absolute path
• `overwrite` (boolean, optional, default=false): Allow overwriting conflicting destination files

fs_get_file_info

Retrieve complete metadata for files or directories, with optional SHA-256 cryptographic digest calculation for integrity validation.

Parameters

• `file_path` (string, required): Target filesystem entry absolute path
• `calc_digest` (boolean, optional, default=false): Compute SHA-256 hash of file contents

fs_is_file_exists

Lightweight existence check for any filesystem entry (file or directory) without loading full metadata.

Parameters

• `file_path` (string, required): Absolute path to verify existence

3. File Read & Write Tools

fs_read_full_text

Read complete text content of a target file with user-specified text encoding.

Parameters

• `file_path` (string, required): Target text file absolute path
• `charset` (string, optional, default="utf-8"): Supported charset identifier

fs_read_text_range

Segmented line-based text streaming optimized for large files; skip leading lines and cap total read lines to avoid excessive heap allocation.

Parameters

• `file_path` (string, required): Target text file absolute path
• `lines_to_skip` (integer, required, min=0): Number of initial lines to skip during read
• `max_lines_to_read` (integer, required, min=0): Maximum total lines to extract from file
• `line_separator` (string, optional, default="\n"): Line break delimiter character
• `charset` (string, optional, default="utf-8"): Supported charset identifier

fs_read_binary_chunk

Chunked streaming read for binary files; returns Base64 encoded byte payloads for safe JSON-RPC network transmission with end-of-stream marker detection.

Parameters

• `file_path` (string, required): Target binary file absolute path
• `bytes_to_skip` (integer, required, min=0): Leading byte offset to skip before reading chunk
• `max_bytes_to_read` (integer, required, min=0): Maximum byte length to read in single chunk

fs_write_text

Write encoded text content to target file, supporting full overwrite or append-only write modes.

Parameters

• `file_path` (string, required): Target output file absolute path
• `text` (string, required, minLength=1): Raw text content to persist
• `append` (boolean, optional, default=false): Append mode toggle (false = full file overwrite)
• `charset` (string, optional, default="utf-8"): Supported charset identifier

fs_write_binary

Decode Base64 binary payload and write raw bytes to target file; supports append mode for multi-chunk binary upload workflows.

Parameters

• `file_path` (string, required): Target output file absolute path
• `base64_data` (string, required, minLength=1): Base64 encoded raw binary byte payload
• `append` (boolean, optional, default=false): Append binary data to file end (false = full overwrite)

4. Content Search & In-Place Replace Tools

fs_search_files_by_content

Recursively scan directory trees and return absolute paths of all files containing matching text patterns; supports regex, case insensitivity, and file extension filtering.

Parameters

• `dir_path` (string, required): Root directory for recursive content scan
• `recursive` (boolean, required): Enable full subdirectory recursion
• `search_term` (string, required): Plain text keyword or regular expression pattern
• `is_regex` (boolean, optional, default=false): Treat search_term as regex pattern
• `ignore_case` (boolean, optional, default=true): Case-insensitive matching toggle
• `file_extension` (string, optional, default=""): Filter scanned files by extension suffix
• `charset` (string, optional, default="utf-8"): Charset used to parse target files

fs_search_in_files_by_content

Bulk multi-directory content matching, returns structured match results with configurable pre/post context lines around matched content, plus global result count hard limits.

Parameters

• `dir_path` (string, required): Root scan directory absolute path
• `recursive` (boolean, required): Enable full recursive subdirectory traversal
• `search_term` (string, required): Search keyword or regex pattern
• `limit` (integer, required): Hard maximum limit on total returned matching entries
• `is_regex` (boolean, optional, default=false): Enable regular expression matching logic
• `ignore_case` (boolean, optional, default=true): Disable case-sensitive matching
• `lines_before` (integer, optional, default=0): Number of context lines preceding each matched line
• `lines_after` (integer, optional, default=0): Number of context lines following each matched line
• `file_extension` (string, optional, default=""): Filter scanned files by extension suffix
• `charset` (string, optional, default="utf-8"): Charset used to parse target files

fs_search_in_file_by_content

Precision single-file content search, returns structured matching segments with configurable pre/post context lines for code and document inspection workflows.

Parameters

• `file_path` (string, required): Target single file absolute path
• `search_term` (string, required): Search keyword or regex pattern
• `is_regex` (boolean, optional, default=false): Enable regular expression matching logic
• `ignore_case` (boolean, optional, default=true): Case-insensitive matching toggle
• `lines_before` (integer, optional, default=0): Preceding context lines for each match
• `lines_after` (integer, optional, default=0): Subsequent context lines for each match
• `charset` (string, optional, default="utf-8"): Charset used to parse target file

fs_file_replace

Execute global in-place text replacement within a single target file; returns total count of matched and replaced text segments after write operation completes.

Parameters

• `file_path` (string, required): Target editable file absolute path
• `search_term` (string, required): Text substring to locate and replace
• `replacement` (string, required): New replacement text payload
• `line_separator` (string, optional, default="\n"): Line break delimiter for file parsing

5. Image Processing Tools

fs_image_resize

Resize source image to specified pixel dimensions, with native aspect ratio preservation and transparent canvas padding to fill exact target resolution dimensions.

Parameters

• `source_path` (string, required): Source input image absolute path
• `dest_path` (string, required): Resized output image absolute path
• `width` (integer, required, >0): Target pixel width dimension
• `height` (integer, required, >0): Target pixel height dimension
• `keep_aspect_ratio` (boolean, optional, default=true): Lock original image aspect ratio during scaling
• `pad_to_target` (boolean, optional, default=true): Add transparent padding to fill exact target width/height when aspect ratio is locked

fs_image_crop

Extract a rectangular pixel region from source image and export as standalone output image file.

Parameters

• `source_path` (string, required): Source input image absolute path
• `dest_path` (string, required): Cropped output image absolute path
• `x` (integer, required, ≥0): Left pixel coordinate of crop region origin
• `y` (integer, required, ≥0): Top pixel coordinate of crop region origin
• `width` (integer, required, >0): Pixel width of cropped rectangular region
• `height` (integer, required, >0): Pixel height of cropped rectangular region

fs_image_rotate

Rotate source image clockwise by arbitrary floating-point degree values; automatically expand output canvas dimensions to retain full image content without edge clipping.

Parameters

• `source_path` (string, required): Source input image absolute path
• `dest_path` (string, required): Rotated output image absolute path
• `degrees` (number, required): Clockwise rotation angle in degrees

6. OCR Text Extraction Tool

fs_ocr_extract_text

Extract human-readable text from raster image files via local Tesseract OCR binary installation. No WASM JavaScript fallback implementation exists; empty `tesseract_bin_path` will not initialize alternative web-based OCR engines.

Parameters

• `image_path` (string, required): Input image absolute path for text recognition
• `tesseract_bin_path` (string, optional, default=""): Absolute path to local Tesseract executable binary; empty value uses system PATH lookup only
• `tessdata_path` (string, optional, default=""): Absolute directory path containing Tesseract language training data files
• `lang` (string, optional, default="eng"): Language code prefix matching available tessdata training files

Core Runtime Dependencies

• `io.quarkus:quarkus-bom:3.37.1`: Quarkus version alignment BOM
• `io.quarkus:quarkus-arc`: Quarkus CDI dependency injection container
• `io.quarkus:quarkus-reactive-routes`: Reactive HTTP routing core
• `io.quarkiverse.mcp:quarkus-mcp-server-http:1.13.1`: Streamable HTTP & SSE MCP transport implementation
• `io.quarkiverse.mcp:quarkus-mcp-server-stdio:1.13.1`: Stdio MCP transport implementation
• `net.sourceforge.tess4j:tess4j:5.18.0`: Java Tesseract OCR binding library

Project Build & Development Gradle Tasks

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

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

License

This project is open-sourced under the Apache License 2.0. Refer to the root-level `LICENSE` file for complete legal license terms and conditions.

Third-Party Software Notices

This software bundles multiple open-source dependency libraries. All third-party components retain their original copyright holders and respective open-source license agreements.

A full breakdown of all third-party libraries, versions, and licenses is available in the root-level `THIRD-PARTY-NOTICES` file and packaged inside the JAR artifact at `/META-INF/THIRD-PARTY-NOTICES`.

Repository & Issue Tracking

• GitHub Source Repository: https://github.com/kurtzhi/fsext-mcp-server-java
• Bug Reports & Feature Requests: https://github.com/kurtzhi/fsext-mcp-server-java/issues