Fsext Mcp Server Typescript

FsExt-MCP-Server (TypeScript)

概述

一个使用 TypeScript 构建的高性能、安全且可用于生产环境的模型上下文协议 (MCP) 服务，提供全面的文件系统操作、高级文本搜索与替换、图像处理和 Tesseract OCR 功能。专为大模型 Agent 集成设计，支持严格的输入验证、标准化响应结构、大文件流式处理，以及多种传输方式的远程部署。

此服务完全符合官方 MCP 规范，支持 stdio 本地集成、SSE 旧版流式传输，以及现代 Streamable HTTP 双向传输，可作为 AI Agent 和自动化工作流系统的通用文件系统工具后端。

核心功能

• 完整的文件系统 CRUD 与目录管理：全面支持文件和目录的创建、删除、复制、移动、元数据查询及存在性验证。支持递归复制完整目录树，以及具备冲突保护的安全移动操作。

• 适用于大文件的流式文件 I/O：支持分段读取文本、分块流式读取二进制文件，以及覆盖和追加文本或二进制内容。避免将文件完整载入内存，可完美处理 GB 级大文件。

• 高级文本搜索与原位替换：支持在整个目录中递归搜索内容、在单个或多个文件中进行上下文匹配并提供预览行、使用正则表达式、不区分大小写匹配，以及在文件中精准替换文本并统计更改情况。

• 专业图像处理套件：基于 Sharp 构建，内置高性能图像缩放（支持锁定纵横比）、精准裁剪和任意角度旋转，涵盖主流图像编辑场景。

• 跨平台 Tesseract OCR：优先使用 WASM 进行 OCR 识别，可自定义本地 Tesseract 二进制文件和 tessdata 路径，支持从图像中提取多语言文本，且无需依赖本地引擎安装。

• 严格的输入验证与标准化响应：所有工具架构均启用严格的额外属性限制，并采用统一的成功／错误响应结构，便于客户端一致地解析和处理错误。

• 支持多种标准的 MCP 传输方式：原生支持三种官方 MCP 传输方式：stdio（本地客户端）、SSE（旧版远程流传输）和 Streamable HTTP（现代双向远程传输）。

• 完整的 TypeScript 类型安全：为所有工具参数、响应结构和传输配置提供完整的类型定义，确保运行时稳定性并提升开发体验。

快速开始

前置条件

Node.js >=22.0.0 <27.0.0

安装

全局安装（推荐用于 CLI）

npm install -g fsext-mcp-server

本地项目安装

npm install fsext-mcp-server

启动命令

1. 默认 Stdio 模式（用于 Claude Desktop / Cursor / 本地 MCP 客户端）

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

# Short alias
fsext-ts
fsext

2. SSE 远程传输模式

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

端点：

• SSE 流订阅：http://<host>:<port>/sse

• 客户端请求通道：http://<host>:<port>/messages

3. 现代 Streamable HTTP 传输模式

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

统一双向端点：http://<host>:<port>/mcp

传输模式对比

功能	SSE 传输	Streamable HTTP
端点架构	双端点（GET 流 + POST 消息）	单一统一双向端点
通信模式	服务器到客户端的单向流式传输	完整双向流式传输与标准 HTTP 响应
连接稳定性	容易出现会话不一致	自动恢复会话，并针对高并发进行了优化
规范状态	兼容旧版	最新官方 MCP 标准

客户端配置示例

MCP 客户端 JSON 配置（Cursor / Claude Desktop）

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

统一全局响应规范

所有 MCP 工具在成功和失败场景下均采用一致的顶层响应结构，便于客户端使用通用解析逻辑。

通用结构

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

成功响应

success: true - info 字段承载特定于工具的业务数据\。

错误响应 (统一标准)

success: false - 所有错误 (IO 失败、参数无效、路径错误、运行时异常) 均返回固定的错误结构：

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

MCP 工具完整参考

所有工具均启用 additionalProperties: false 严格验证，以拒绝非法输入参数，确保调用安全\。

1. 目录操作工具

fs_list_directory

说明：扫描目标目录，返回经过筛选的绝对路径列表，支持递归遍历、仅筛选文件以及按后缀筛选\。

参数：

• source_dir (string，必填)：要扫描的目标目录路径

• recursive (boolean，必填)：启用递归子目录扫描

• only_files (boolean，必填)：仅返回文件，不包含目录

• file_extension (string，可选，默认值="")：按指定后缀筛选文件

成功响应：

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

fs_copy_directory

说明：递归复制完整目录树，支持覆盖已存在的目标目录\。

参数：

• source_dir (string，必填)：源目录路径

• copy_dest_dir (string，必填)：目标目录路径

• overwrite (boolean，可选，默认值=false)：清理并覆盖已存在的目标目录

成功响应：

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

fs_move_directory

说明：移动整个目录树；如果目标路径已存在，则立即失败，以防意外覆盖\。

参数：

• source_dir (string，必填)：源目录路径

• dest_dir (string，必填)：目标目录路径

• overwrite (boolean，可选，默认值=false)：允许覆盖冲突目录

成功响应：带有成功标志的空 info 对象

2. 文件基本操作工具

fs_create_file

说明：创建空文件或包含内容的文件，自动创建缺失的父目录，并支持多种编码\。

参数：

• file_path (string，必填)：目标文件路径

• content (string，可选，默认值="")：初始文本内容

• charset (string，可选，默认值=utf-8)：编码枚举：utf-8、ucs-2、utf16le、latin1、ascii、base64、hex

成功响应：带有成功标志的空 info 对象

fs_delete_file

说明：仅删除单个常规文件；拒绝目录路径，以避免批量删除风险\。

参数：

• file_path (string，必填)：目标文件路径

成功响应：带有成功标志的空 info 对象

fs_copy_file

说明：复制单个文件并完整保留元数据，支持控制是否覆盖\。

参数：

• source_file_path (string，必填)：源文件路径

• dest_file_path (string，必填)：目标文件路径

• overwrite (boolean，可选，默认值=false)：覆盖已存在的目标文件

成功响应：带有成功标志的空 info 对象

fs_move_file

说明：移动单个文件，并可配置覆盖行为\。

参数：

• source_file_path (string，必填)：源文件路径

• dest_file_path (string，必填)：目标文件路径

• overwrite (boolean，可选，默认值=false)：覆盖冲突文件

成功响应：带有成功标志的空 info 对象

fs_get_file_info

说明：获取文件/目录的完整元数据，支持选择性计算 SHA-256 摘要\。

参数：

• file_path (string，必填)：目标条目路径

• calc_digest (boolean，可选，默认值=false)：计算 SHA-256 哈希值

成功响应：

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

说明：轻量检查文件或目录是否存在\。

参数：

• file_path (string，必填)：目标路径

成功响应：

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

3. 文件读写工具

fs_read_full_text

描述：读取目标文件的完整文本内容，支持指定编码。

参数：

• file_path (string, required)：目标文件路径

• charset (string, optional, default=utf-8)：支持多种编码

成功响应：

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

fs_read_text_range

描述：分段读取文本，适用于大型文件，支持跳过开头的行并限制读取行数。

参数：

• file_path (string, required)：目标文件路径

• lines_to_skip (integer, required)：要跳过的开头行数

• max_lines_to_read (integer, required)：最多读取的行数

• line_separator (string, optional, default="\n")：换行符

• charset (string, optional, default=utf-8)：文件编码

成功响应：

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

fs_read_binary_chunk

描述：分块读取二进制文件，返回 Base64 编码的数据以便安全传输，支持检测数据流结束。

参数：

• file_path (string, required)：目标文件路径

• bytes_to_skip (integer, required)：要跳过的开头字节数

• max_bytes_to_read (integer, required)：最多读取的字节数

成功响应：

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

fs_write_text

描述：将文本内容写入文件，支持覆盖或追加模式。

参数：

• file_path (string, required)：目标文件路径

• text (string, required, minLength=1)：要写入的文本内容

• append (boolean, optional, default=false)：追加模式开关

• charset (string, optional, default=utf-8)：文件编码

成功响应：包含成功标志的空信息对象

fs_write_binary

描述：将 Base64 解码后的二进制数据写入文件，支持追加操作。

参数：

• file_path (string, required)：目标文件路径

• base64_data (string, required, minLength=1)：Base64 编码的二进制数据

• append (boolean, optional, default=false)：追加模式开关

成功响应：包含成功标志的空信息对象

4. 搜索与替换工具

fs_search_files_by_content

描述：递归扫描目录，返回包含目标内容的所有文件路径，支持正则表达式、忽略大小写和后缀筛选。

参数：

• dir_path (string, required)：扫描根目录

• recursive (boolean, required)：是否启用递归扫描

• search_term (string, required)：搜索关键字或正则表达式模式

• is_regex (boolean, optional, default=false)：是否启用正则表达式匹配

• ignore_case (boolean, optional, default=true)：是否忽略大小写

• file_extension (string, optional, default="")：文件后缀筛选条件

• charset (string, optional, default=utf-8)：文件编码

fs_search_in_files_by_content

描述：在多个文件中匹配内容，返回结构化结果，并可自定义上下文行数和结果数量上限。

参数：

• dir_path (string, required)：扫描根目录

• recursive (boolean, required)：是否启用递归扫描

• search_term (string, required)：搜索关键字/正则表达式

• limit (integer, required)：匹配结果数量上限

• is_regex (boolean, optional, default=false)：是否启用正则表达式

• ignore_case (boolean, optional, default=true)：是否忽略大小写

• lines_before (integer, optional, default=0)：前置上下文行数

• lines_after (integer, optional, default=0)：后置上下文行数

• file_extension (string, optional, default="")：后缀筛选条件

• charset (string, optional, default=utf-8)：文件编码

成功响应：

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

描述：在单个文件中精确搜索内容，并预览行上下文。

参数：与多文件搜索类似，输入单个文件路径

成功响应：结构化的单文件匹配结果

fs_file_replace

描述：在单个文件中原地替换文本，并返回替换总数。

参数：

• file_path (string, required)：目标文件路径

• search_term (string, required)：要替换的文本

• replacement (string, required)：新的替换文本

• line_separator (string, optional, default="\n")：换行分隔符

成功响应：

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

5. 图像处理工具

fs_image_resize

描述：调整图像大小，支持锁定宽高比，并生成新的输出图像文件。

参数：

• source_path (string, required)：源图像路径

• dest_path (string, required)：输出图像路径

• width (integer, required, >0)：目标宽度

• height (integer, required, >0)：目标高度

• keep_aspect_ratio (boolean, optional, default=true)：锁定原始宽高比

成功响应：带有成功标志的空信息对象

fs_image_crop

描述：从源图像中裁剪指定矩形区域，并导出新文件。

参数：

• source_path (string, required)：源图像路径

• dest_path (string, required)：输出图像路径

• x (integer, required, ≥0)：裁剪起始 X 坐标

• y (integer, required, ≥0)：裁剪起始 Y 坐标

• width (integer, required, >0)：裁剪区域宽度

• height (integer, required, >0)：裁剪区域高度

成功响应：带有成功标志的空信息对象

fs_image_rotate

描述：按任意角度顺时针旋转图像，并自动扩展画布以保留完整内容。

参数：

• source_path (string, required)：源图像路径

• dest_path (string, required)：输出图像路径

• degrees (number, required)：顺时针旋转角度

成功响应：带有成功标志的空信息对象

6. OCR 工具

fs_ocr_extract_text

描述：通过 Tesseract OCR 从图像中提取文本，支持 WASM 运行时（无需本地引擎）和自定义本地二进制文件路径。

参数：

• image_path (string, required)：目标图像路径

• tesseract_bin_path (string, optional, default="")：自定义 Tesseract 可执行文件路径

• tessdata_path (string, optional, default="")：自定义 tessdata 语言资源路径

• lang (string, optional, default eng)：识别语言前缀

成功响应：

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

项目构建与开发

脚本

# 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

依赖项

核心运行时依赖项

• fastmcp：官方 MCP 服务运行时框架

• sharp：高性能图像处理引擎

• tesseract.js：基于 WASM 的跨平台 OCR 引擎

• winston：标准日志系统

• zod：工具参数的严格模式验证

• chardet / iconv-lite：多编码检测与转换

• cors：支持 HTTP 传输的跨源资源共享

• minimist：CLI 参数解析

许可证

本项目基于 Apache License 2.0 开源。完整许可证详情请参阅项目根目录中的 LICENSE 文件。

仓库与问题反馈

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

• 问题反馈：报告错误或申请功能