F

FsExt-MCP-Server

kurtzhi/fsext-mcp-server-typescript
0 Stars 7 次浏览 更新于 2026-08-23

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

文件系统

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "fsext": {
      "args": [
        "-y",
        "fsext-mcp-server",
        "--transport",
        "stdio | sse | http",
        "--lock-root",
        "/my/workspace"
      ],
      "command": "npx",
      "env": {}
    }
  }
}

服务介绍

FsExt-MCP-Server (TypeScript)

概述

FsExt-MCP-Server 是一个使用 TypeScript 构建的高性能、安全且生产级的 Model Context Protocol (MCP) 服务器，提供全面的文件系统操作、高级文本搜索与替换、图像处理和 Tesseract OCR 功能。该服务器专为 LLM 代理集成设计，提供严格的输入验证、标准化的响应结构、大文件流式处理以及多传输远程部署支持。

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

核心功能

  • 完整的文件系统 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 (字符串, 必需): 要扫描的目标目录路径
  • recursive (布尔值, 必需): 启用递归子目录扫描
  • only_files (布尔值, 必需): 仅返回文件，排除目录
  • file_extension (字符串, 可选, 默认=""): 按指定后缀过滤文件

成功响应:


{

  "res": {

    "success": true,

    "info": {

      "paths": ["/absolute/path/file1.txt", "/absolute/path/file2.js"]

    }

  }

}

fs_copy_directory

描述: 递归复制整个目录树，支持覆盖现有目标目录。

参数:

  • source_dir (字符串, 必需): 源目录路径
  • copy_dest_dir (字符串, 必需): 目标目录路径
  • overwrite (布尔值, 可选, 默认=false): 清除并覆盖现有目标目录

成功响应:


{

  "res": {

    "success": true,

    "info": {}

  }

}

fs_move_directory

描述: 移动整个目录树，如果目标路径存在则快速失败，以防止意外覆盖。

参数:

  • source_dir (字符串, 必需): 源目录路径
  • dest_dir (字符串, 必需): 目标目录路径
  • overwrite (布尔值, 可选, 默认=false): 允许覆盖冲突目录

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

2. 文件基本操作工具

fs_create_file

描述: 创建空文件或填充内容的文件，自动创建缺失的父目录，支持多编码。

参数:

  • file_path (字符串, 必需): 目标文件路径
  • content (字符串, 可选, 默认=""): 初始文本内容
  • charset (字符串, 可选, 默认=utf-8): 编码枚举: utf-8, ucs-2, utf16le, latin1, ascii, base64, hex

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

fs_delete_file

描述: 仅删除单个常规文件；拒绝目录路径以避免批量删除风险。

参数:

  • file_path (字符串, 必需): 目标文件路径

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

fs_copy_file

描述: 复制单个文件并保留完整的元数据，支持覆盖控制。

参数:

  • source_file_path (字符串, 必需): 源文件路径
  • dest_file_path (字符串, 必需): 目标文件路径
  • overwrite (布尔值, 可选, 默认=false): 覆盖现有目标文件

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

fs_move_file

描述: 移动单个文件，并可配置覆盖行为。

参数:

  • source_file_path (字符串, 必需): 源文件路径
  • dest_file_path (字符串, 必需): 目标文件路径
  • overwrite (布尔值, 可选, 默认=false): 覆盖冲突文件

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

fs_get_file_info

描述: 获取文件/目录的完整元数据，支持可选的SHA-256摘要计算。

参数:

  • file_path (字符串, 必需): 目标条目路径
  • calc_digest (布尔值, 可选, 默认=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 (字符串, 必需): 目标路径

成功响应:


{

  "res": {

    "success": true,

    "info": {

      "exists": true

    }

  }

}

3. 文件读写工具

fs_read_full_text

描述: 以指定编码读取目标文件的全部文本内容。

参数:

  • file_path (字符串, 必需): 目标文件路径
  • charset (字符串, 可选, 默认=utf-8): 支持多种编码

成功响应:


{

  "res": {

    "success": true,

    "info": {

      "content": "full-text-file-content"

    }

  }

}

fs_read_text_range

描述: 分段读取大文件，支持跳过前导行和限制读取行数。

参数:

  • file_path (字符串, 必需): 目标文件路径
  • lines_to_skip (整数, 必需): 要跳过的前导行数
  • max_lines_to_read (整数, 必需): 最大读取行数
  • line_separator (字符串, 可选, 默认="\n"): 换行符
  • charset (字符串, 可选, 默认=utf-8): 文件编码

成功响应:


{

  "res": {

    "success": true,

    "info": {

      "lines_count": 5,

      "content": "segmented-text-content"

    }

  }

}

fs_read_binary_chunk

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

参数:

  • file_path (字符串, 必需): 目标文件路径
  • bytes_to_skip (整数, 必需): 要跳过的前导字节数
  • max_bytes_to_read (整数, 必需): 最大读取字节数

成功响应:


{

  "res": {

    "success": true,

    "info": {

      "data_base64": "base64-encoded-binary",

      "raw_bytes_length": 5,

      "end_of_stream": true

    }

  }

}

fs_write_text

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

参数:

  • file_path (字符串, 必需): 目标文件路径
  • text (字符串, 必需, minLength=1): 要写入的文本内容
  • append (布尔值, 可选, 默认=false): 追加模式开关
  • charset (字符串, 可选, 默认=utf-8): 文件编码

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

fs_write_binary

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

参数:

  • file_path (字符串, 必需): 目标文件路径
  • base64_data (字符串, 必需, minLength=1): Base64编码的二进制数据
  • append (布尔值, 可选, 默认=false): 追加模式开关

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

4. 搜索与替换工具

fs_search_files_by_content

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

参数:

  • dir_path (字符串, 必需): 扫描根目录
  • recursive (布尔值, 必需): 是否启用递归扫描
  • search_term (字符串, 必需): 搜索关键词或正则表达式模式
  • is_regex (布尔值, 可选, 默认=false): 是否启用正则匹配
  • ignore_case (布尔值, 可选, 默认=true): 是否忽略大小写
  • file_extension (字符串, 可选, 默认=""): 文件后缀过滤
  • charset (字符串, 可选, 默认=utf-8): 文件编码

fs_search_in_files_by_content

描述: 多文件内容匹配，返回结构化结果，可自定义上下文行数和结果限制。

参数:

  • dir_path (字符串, 必需): 扫描根目录
  • recursive (布尔值, 必需): 是否启用递归扫描
  • search_term (字符串, 必需): 搜索关键词/正则表达式
  • limit (整数, 必需): 最大匹配结果数量
  • is_regex (布尔值, 可选, 默认=false): 是否启用正则表达式
  • ignore_case (布尔值, 可选, 默认=true): 是否忽略大小写
  • lines_before (整数, 可选, 默认=0): 前置上下文行数
  • lines_after (整数, 可选, 默认=0): 后置上下文行数
  • file_extension (字符串, 可选, 默认=""): 文件后缀过滤
  • charset (字符串, 可选, 默认=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 (字符串, 必填): 目标文件路径
  • search_term (字符串, 必填): 要替换的文本
  • replacement (字符串, 必填): 新的替换文本
  • line_separator (字符串, 可选, 默认="\n"): 行分隔符

成功响应:


{

  "res": {

    "success": true,

    "info": {

      "count": 1

    }

  }

}

5. 图像处理工具

fs_image_resize

描述: 支持锁定宽高比的图像缩放，生成新的输出图像文件。

参数:

  • source_path (字符串, 必填): 源图像路径
  • dest_path (字符串, 必填): 输出图像路径
  • width (整数, 必填, >0): 目标宽度
  • height (整数, 必填, >0): 目标高度
  • keep_aspect_ratio (布尔值, 可选, 默认=true): 锁定原始宽高比

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

fs_image_crop

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

参数:

  • source_path (字符串, 必填): 源图像路径
  • dest_path (字符串, 必填): 输出图像路径
  • x (整数, 必填, ≥0): 裁剪起始X坐标
  • y (整数, 必填, ≥0): 裁剪起始Y坐标
  • width (整数, 必填, >0): 裁剪区域宽度
  • height (整数, 必填, >0): 裁剪区域高度

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

fs_image_rotate

描述: 顺时针旋转图像任意角度，自动扩展画布以保留全部内容。

参数:

  • source_path (字符串, 必填): 源图像路径
  • dest_path (字符串, 必填): 输出图像路径
  • degrees (数字, 必填): 顺时针旋转角度

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

6. OCR 工具

fs_ocr_extract_text

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

参数:

  • image_path (字符串, 必填): 目标图像路径
  • tesseract_bin_path (字符串, 可选, 默认=""): 自定义 Tesseract 可执行文件路径
  • tessdata_path (字符串, 可选, 默认=""): 自定义 tessdata 语言资源路径
  • lang (字符串, 可选, 默认 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 文件以获取完整的许可证详细信息。

仓库与问题

查看源码 项目主页

相关 MCP 服务

文件系统
@modelcontextprotocol/filesystem
实现用于文件系统操作的模型上下文协议（MCP）的 Node.js 服务器。
E
Excel文件服务
@negokaz/excel-mcp-server
一个模型上下文协议服务器，使人工智能助手能够读取和写入Microsoft Excel文件，支持xlsx、xlsm、xltx和xltm等格式。
A
AI Word文档助手
@GongRzhe/Office-Word-MCP-Server
一个模型上下文协议服务器，它使人工智能助手能够通过标准化的工具和资源创建、读取、编辑和格式化Microsoft Word文档。
D
DOCX/PDF文档生成服务-MCP（MCP&Agent挑战赛）
KUN03036/LLM_output_with_docxpdf_MCP_Agent_Challenge
暂无简介