Content
# 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, supporting`stdio` 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\.
## 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\)
```bash
npm install -g fsext-mcp-server
```
#### Local Project Installation
```bash
npm install fsext-mcp-server
```
### Startup Commands
#### 1\. Default Stdio Mode \(For Claude Desktop / Cursor / Local MCP Clients\)
```bash
# Default stdio transport for local agent integration
fsext-mcp-server-ts
fsext-mcp-server
# Short alias
fsext-ts
fsext
```
#### 2\. SSE Remote Transport Mode
```bash
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
```bash
fsext-mcp-server --transport http --host 0.0.0.0 --port 8000
```
**Unified Bidirectional Endpoint**: `http://<host>:<port>/mcp`
### Transport Mode Comparison
|Feature|SSE Transport|Streamable HTTP|
|---|---|---|
|Endpoint Architecture|Dual endpoints \(GET stream \+ POST message\)|Single unified bidirectional endpoint|
|Communication Mode|Unidirectional server\-to\-client streaming|Full bidirectional streaming \& standard HTTP response|
|Connection Stability|Prone to session inconsistency|Auto session recovery, high concurrency optimized|
|Specification Status|Legacy compatible|Latest official MCP standard|
## Client Configuration Example
### MCP Client JSON Config \(Cursor / Claude Desktop\)
```json
{
"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
```json
{
"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:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"res": {
"success": true,
"info": {
"content": "extracted-ocr-text-content"
}
}
}
```
## Project Build \& Development
### Scripts
```bash
# 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](https://github.com/kurtzhi/fsext-mcp-server-typescript)
- **Issues**: [Report bugs or request features](https://github.com/kurtzhi/fsext-mcp-server-typescript/issues)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available