Fsext Mcp Server Java

Fsext-MCP-Server(Java): A full-featured secure MCP server for local file system operations, with built-in image processing, OCR and media tools.

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.

- 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 strictadditionalProperties: falseJSON 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:

- stdio: Native integration for local desktop MCP clients (Claude Desktop, Cursor, etc.)
- sse: Legacy lightweight remote event streaming transport
- http: Modern Streamable HTTP bidirectional remote streaming transport

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

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-<version>.jar

Replace<x.y.z>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

1. Local Stdio Mode (Desktop MCP Clients)

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

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

- Long-lived SSE stream subscription channel (server event push):http://<host>:<port>/sse
- JSON-RPC client request submission channel:http://<host>:<port>/messages

- 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

Single shared entry point handling all client requests and server streaming traffic:http://<host>:<port>/mcp

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

4. SSE vs Streamable HTTP Transport Comparison

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

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 theinfosub-object under the rootresfield.

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

- success: Global operation status flag

- true: Tool logic completed without exceptions;infocontains tool-specific return data
- false: Operation failed (workspace escape block, missing file, I/O error, invalid input schema, permission denied, etc.)
- Success state (success: true): Structured custom payload unique to each tool
- 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" }

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" } } }

All tool input schemas enforceadditionalProperties: falsestrict validation to reject unrecognized parameters and mitigate malicious path injection attack vectors.

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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