FsExt-MCP-Server (TypeScript)

Overview

A high-performance, secure, and production-grade Model Context Protocol (MCP) server built with TypeScript, providing comprehensive filesystem operations, advanced text search & replace, image processing, and Tesseract OCR capabilities. Designed for LLM agent integration, it delivers strict input validation, standardized response structures, streaming large-file processing, and multi-transport remote deployment support.

This server fully complies with the official MCP specification, supportingstdio local integration, SSE legacy streaming transport, and modern Streamable HTTP bidirectional transport, serving as a universal filesystem tool backend for AI agents and automated workflow systems.

Related MCP server: MCP Server

Core Features

• Full Filesystem CRUD & Directory Management：Complete file/directory creation, deletion, copy, move, metadata query, and existence verification. Supports recursive full-directory tree replication and safe move operations with conflict protection.

• Streaming File I/O for Large Files：Implements segmented text reading, chunked binary streaming reading, text/binary overwriting and appending. Avoids full memory loading, perfectly supporting GB-level large file processing.

• Advanced Text Search & In-Place Replace：Directory-wide recursive content search, single/multi-file contextual matching with preview lines, regular expression support, case-insensitive matching, and precise in-file text replacement with change statistics.

• Professional Image Processing Suite：Built-in high-performance image resize (aspect ratio lock support), precise crop, and arbitrary-angle rotation based on Sharp, covering mainstream image editing scenarios.

• Cross-Platform Tesseract OCR：WASM-first OCR recognition with customizable local Tesseract binary and tessdata paths, supporting multi-language text extraction from images without local engine installation dependency.

• Strict Strict Input Validation & Standardized Response：All tool schemas enable strict additional property prohibition, with unified success/error response structures for consistent client parsing and error handling.

• Multi-Standard MCP Transports：Natively supports three official MCP transports: stdio (local client), SSE (legacy remote stream), Streamable HTTP (modern bidirectional remote transport).

• Full TypeScript Type Safety：Complete type definitions for all tool parameters, response structures, and transport configurations, ensuring runtime stability and development friendliness.

Quick Start

Prerequisites

Node.js >=22.0.0 <27.0.0

Installation

Global Installation (Recommended for CLI Usage)

npm install -g fsext-mcp-server

Local Project Installation

npm install fsext-mcp-server

Startup Commands

1. Default Stdio Mode (For Claude Desktop / Cursor / Local MCP Clients)

# Default stdio transport for local agent integration
fsext-mcp-server

# Short alias
fsext

2. SSE Remote Transport Mode

fsext-mcp-server --transport sse --host 0.0.0.0 --port 8000

Endpoints:

• SSE Stream Subscription:http://<host>:<port>/sse

• Client Request Channel: http://<host>:<port>/messages

3. Modern Streamable HTTP Transport Mode

fsext-mcp-server --transport http --host 0.0.0.0 --port 8000

Unified Bidirectional Endpoint: http://<host>:<port>/mcp

Transport Mode Comparison

Client Configuration Example

MCP Client JSON Config (Cursor / Claude Desktop)

{
  "mcpServers": {
    "fsext": {
      "command": "fsext-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Unified Global Response Specification

All MCP tools adopt a consistent top-level response structure for both success and failure scenarios, enabling universal client parsing logic.

General Structure

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

Success Response

success: true - The info field carries tool-specific business data.

Error Response (Unified Standard)

success: false - All errors (IO failure, invalid params, path error, runtime exception) return fixed error structure:

{
  "res": {
    "success": false,
    "info": {
      "code": "ERROR_CODE",
      "message": "Human-readable detailed error message"
    }
  }
}

Full MCP Tools Reference

All tools enable additionalProperties: false strict validation to reject illegal input parameters, ensuring invocation safety.

1. Directory Operation Tools

fs_list_directory

Description: Scan target directory, return filtered absolute path list, support recursive traversal, pure file filtering, and suffix filtering.

Parameters:

• source_dir (string, required): Target directory path for scanning

• recursive (boolean, required): Enable recursive subdirectory scanning

• only_files (boolean, required): Return only files, exclude directories

• file_extension (string, optional, default=""): Filter files by specified suffix

Success Response:

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

fs_copy_directory

Description: Recursively copy full directory tree, support overwriting existing target directories.

Parameters:

• source_dir (string, required): Source directory path

• copy_dest_dir (string, required): Target directory path

• overwrite (boolean, optional, default=false): Clean and overwrite existing target directory

Success Response:

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

fs_move_directory

Description: Move entire directory tree, fail fast if target path exists to prevent accidental overwriting.

Parameters:

• source_dir (string, required): Source directory path

• dest_dir (string, required): Target directory path

• overwrite (boolean, optional, default=false): Allow overwriting conflicting directory

Success Response: Empty info object with success flag

2. File Basic Operation Tools

fs_create_file

Description: Create empty or content-filled file, auto-create missing parent directories, support multi-encoding.

Parameters:

• file_path (string, required): Target file path

• content (string, optional, default=""): Initial text content

• charset (string, optional, default=utf-8): Encoding enum: utf-8, ucs-2, utf16le, latin1, ascii, base64, hex

Success Response: Empty info object with success flag

fs_delete_file

Description: Delete single regular file only; reject directory paths to avoid batch deletion risks.

Parameters:

• file_path (string, required): Target file path

Success Response: Empty info object with success flag

fs_copy_file

Description: Copy single file with complete metadata retention, support overwrite control.

Parameters:

• source_file_path (string, required): Source file path

• dest_file_path (string, required): Target file path

• overwrite (boolean, optional, default=false): Overwrite existing target file

Success Response: Empty info object with success flag

fs_move_file

Description: Move single file with configurable overwrite behavior.

Parameters:

• source_file_path (string, required): Source file path

• dest_file_path (string, required): Target file path

• overwrite (boolean, optional, default=false): Overwrite conflicting file

Success Response: Empty info object with success flag

fs_get_file_info

Description: Obtain full metadata of file/directory, support optional SHA-256 digest calculation.

Parameters:

• file_path (string, required): Target entry path

• calc_digest (boolean, optional, default=false): Calculate SHA-256 hash

Success Response:

{
  "res": {
    "success": true,
    "info": {
      "absolute_path": "string",
      "is_readable": true,
      "is_writable": true,
      "size": 1672,
      "is_regular_file": true,
      "is_directory": false,
      "is_symbolic_link": false,
      "creation_millis": 1782288135574,
      "last_modified_millis": 1782279393020,
      "last_access_millis": 1782644004556,
      "sha256_digest": "calculated-hash-string"
    }
  }
}

fs_is_file_exists

Description: Lightweight existence check for file or directory.

Parameters:

• file_path (string, required): Target path

Success Response:

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

3. File Read & Write Tools

fs_read_full_text

Description: Read full text content of target file with specified encoding.

Parameters:

• file_path (string, required): Target file path

• charset (string, optional, default=utf-8): Multi encoding support

Success Response:

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

fs_read_text_range

Description: Segmented text reading for large files, support skip leading lines and limit read lines.

Parameters:

• file_path (string, required): Target file path

• lines_to_skip (integer, required): Number of leading lines to skip

• max_lines_to_read (integer, required): Maximum lines to read

• line_separator (string, optional, default="\n"): Line break character

• charset (string, optional, default=utf-8): File encoding

Success Response:

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

fs_read_binary_chunk

Description: Chunked binary file reading, return Base64 encoded data for safe network transmission, support stream end detection.

Parameters:

• file_path (string, required): Target file path

• bytes_to_skip (integer, required): Leading bytes to skip

• max_bytes_to_read (integer, required): Maximum bytes to read

Success Response:

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

fs_write_text

Description: Write text content to file, support overwrite or append mode.

Parameters:

• file_path (string, required): Target file path

• text (string, required, minLength=1): Text content to write

• append (boolean, optional, default=false): Append mode switch

• charset (string, optional, default=utf-8): File encoding

Success Response: Empty info object with success flag

fs_write_binary

Description: Write Base64 decoded binary data to file, support append operation.

Parameters:

• file_path (string, required): Target file path

• base64_data (string, required, minLength=1): Base64 encoded binary data

• append (boolean, optional, default=false): Append mode switch

Success Response: Empty info object with success flag

4. Search & Replace Tools

fs_search_files_by_content

Description: Recursively scan directory, return all file paths containing target content, support regex, case ignore, suffix filter.

Parameters:

• dir_path (string, required): Scan root directory

• recursive (boolean, required): Recursive scan enable

• search_term (string, required): Search keyword or regex pattern

• is_regex (boolean, optional, default=false): Regex matching enable

• ignore_case (boolean, optional, default=true): Case-insensitive matching

• file_extension (string, optional, default=""): File suffix filter

• charset (string, optional, default=utf-8): File encoding

fs_search_in_files_by_content

Description: Multi-file content matching, return structured results with customizable context lines and result limit.

Parameters:

• dir_path (string, required): Scan root directory

• recursive (boolean, required): Recursive scan enable

• search_term (string, required): Search keyword/regex

• limit (integer, required): Max matching result count

• is_regex (boolean, optional, default=false): Regex enable

• ignore_case (boolean, optional, default=true): Case ignore

• lines_before (integer, optional, default=0): Preceding context lines

• lines_after (integer, optional, default=0): Subsequent context lines

• file_extension (string, optional, default=""): Suffix filter

• charset (string, optional, default=utf-8): File encoding

Success Response:

{
  "res": {
    "success": true,
    "info": {
      "results": [
        {
          "file_path": "/test/file.ts",
          "start_line": 1,
          "end_line": 1,
          "text": "matched-content-line"
        }
      ]
    }
  }
}

fs_search_in_file_by_content

Description: Precise single-file content search with line context preview.

Parameters: Similar to multi-file search, single file path input

Success Response: Structured single-file matching results

fs_file_replace

Description: In-place text replacement in single file, return total replaced count.

Parameters:

• file_path (string, required): Target file path

• search_term (string, required): Text to replace

• replacement (string, required): New replacement text

• line_separator (string, optional, default="\n"): Line break separator

Success Response:

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

5. Image Processing Tools

fs_image_resize

Description: Resize image with aspect ratio lock support, generate new output image file.

Parameters:

• source_path (string, required): Source image path

• dest_path (string, required): Output image path

• width (integer, required, >0): Target width

• height (integer, required, >0): Target height

• keep_aspect_ratio (boolean, optional, default=true): Lock original aspect ratio

Success Response: Empty info object with success flag

fs_image_crop

Description: Crop specified rectangular region from source image and export new file.

Parameters:

• source_path (string, required): Source image path

• dest_path (string, required): Output image path

• x (integer, required, ≥0): Crop start X coordinate

• y (integer, required, ≥0): Crop start Y coordinate

• width (integer, required, >0): Crop region width

• height (integer, required, >0): Crop region height

Success Response: Empty info object with success flag

fs_image_rotate

Description: Rotate image clockwise by arbitrary degrees, auto expand canvas to preserve full content.

Parameters:

• source_path (string, required): Source image path

• dest_path (string, required): Output image path

• degrees (number, required): Clockwise rotation angle

Success Response: Empty info object with success flag

6. OCR Tool

fs_ocr_extract_text

Description: Extract text from images via Tesseract OCR, support WASM runtime (no local engine) and custom local binary path.

Parameters:

• image_path (string, required): Target image path

• tesseract_bin_path (string, optional, default=""): Custom Tesseract executable path

• tessdata_path (string, optional, default=""): Custom tessdata language resource path

• lang (string, optional, default eng): Recognition language prefix

Success Response:

{
  "res": {
    "success": true,
    "info": {
      "content": "extracted-ocr-text-content"
    }
  }
}

Project Build & Development

Scripts

# Clean build artifacts
npm run clean

# Compile TypeScript source
npm run build

# Watch mode for development
npm run dev

# Full rebuild (clean + build)
npm run rebuild

# Start SSE transport server
npm run server

# FastMCP dev mode
npm run fastmcp

# MCP Inspector debugging
npm run inspect

# Build and run test cases
npm run test

Dependencies

Core Runtime Dependencies

• fastmcp: Official MCP server runtime framework

• sharp: High-performance image processing engine

• tesseract.js: WASM-based cross-platform OCR engine

• winston: Standard logging system

• zod: Strict schema validation for tool parameters

• chardet / iconv-lite: Multi-encoding detection and conversion

• cors: Cross-origin resource sharing support for HTTP transport

• minimist: CLI parameter parsing

License

This project is open-sourced under the Apache License 2.0. See the LICENSE file in the project root for full license details.

Repository & Issues

• GitHub: https://github.com/kurtzhi/fsext-mcp-server-typescript

• Issues: Report bugs or request features