内容
# FsExt-MCP-Server（TypeScript）
## 概述
一款高性能、安全、生产级别的模型上下文协议（MCP）服务器，使用TypeScript构建，提供全面的文件系统操作、先进的文本搜索和替换、图像处理以及Tesseract OCR功能。设计用于LLM代理集成，提供严格的输入验证、标准化的响应结构、大文件流处理以及多传输远程部署支持。
该服务器完全符合官方MCP规范，支持`stdio`本地集成、`SSE`遗留流传输和现代`Streamable HTTP`双向传输，作为AI代理和自动化工作流系统的通用文件系统工具后端。
## 核心功能
- **完整的 filesystem 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使用）
```bash
npm install -g fsext-mcp-server
```
#### 本地项目安装
```bash
npm install fsext-mcp-server
```
### 启动命令
#### 1. 默认stdio模式（适用于Claude Desktop / Cursor / 本地MCP客户端）
```bash
# 默认stdio传输用于本地代理集成
fsext-mcp-server-ts
fsext-mcp-server
# 别名
fsext-ts
fsext
```
#### 2. SSE远程传输模式
```bash
fsext-mcp-server --transport sse --host 0.0.0.0 --port 8000
```
**端点**：
- SSE流订阅：`http://<host>:<port>/sse`
- 客户端请求通道：`http://<host>:<port>/messages`
#### 3. 现代Streamable HTTP传输模式
```bash
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）
```json
{
"mcpServers": {
"fsext": {
"command": "fsext-mcp-server",
"args": [],
"env": {}
}
}
}
```
## 统一的全局响应规范
所有MCP工具采用一致的顶级响应结构，用于成功和失败场景，实现通用客户端解析逻辑。
### 一般结构
```json
{
"res": {
"success": boolean,
"info": object
}
}
```
### 成功响应
`success: true` - `info`字段携带工具特定的业务数据。
### 错误响应（统一标准）
`success: false` - 所有错误（IO失败、无效参数、路径错误、运行时异常）返回固定的错误结构：
```json
{
"res": {
"success": false,
"info": {
"code": "ERROR_CODE",
"message": "人类可读的详细错误消息"
}
}
}
```
## 完整的MCP工具参考
所有工具启用`additionalProperties: false`严格验证，以拒绝非法输入参数，确保调用安全。
### 1. 目录操作工具
#### fs_list_directory
**描述**：扫描目标目录，返回过滤的绝对路径列表，支持递归遍历、纯文件过滤和后缀过滤。
**参数**：
- `source_dir`（string, 必需）：扫描的目标目录路径
- `recursive`（boolean, 必需）：启用递归子目录扫描
- `only_files`（boolean, 必需）：仅返回文件，排除目录
- `file_extension`（string, 可选，默认=""）：按指定后缀过滤文件
**成功响应**：
```json
{
"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）：清理并覆盖现有目标目录
**成功响应**：
```json
{
"res": {
"success": true,
"info": {}
}
}
```
#### fs_move_directory
**描述**：移动整个目录树，如果目标路径存在则快速失败，以防止意外覆盖。
**参数**：
- `source_dir`（string, 必需）：源目录路径
- `dest_dir`（string, 必需）：目标目录路径
- `overwrite`（boolean, 可选，默认=false）：允许覆盖冲突目录
**成功响应**：带有成功标志的空信息对象
### 2. 文件基本操作工具
#### fs_create_file
**描述**：创建空文件或内容填充文件，自动创建缺失的父目录，支持多编码。
**参数**：
- `file_path`（string, 必需）：目标文件路径
- `content`（string, 可选，默认=""）：初始文本内容
- `charset`（string, 可选，默认=utf-8）：编码枚举：utf-8, ucs-2, utf16le, latin1, ascii, base64, hex
**成功响应**：带有成功标志的空信息对象
#### fs_delete_file
**描述**：仅删除单个常规文件；拒绝目录路径以避免批量删除风险。
**参数**：
- `file_path`（string, 必需）：目标文件路径
**成功响应**：带有成功标志的空信息对象
#### fs_copy_file
**描述**：复制单个文件，保留完整元数据，支持覆盖控制。
**参数**：
- `source_file_path`（string, 必需）：源文件路径
- `dest_file_path`（string, 必需）：目标文件路径
- `overwrite`（boolean, 可选，默认=false）：覆盖现有目标文件
**成功响应**：带有成功标志的空信息对象
#### fs_move_file
**描述**：移动单个文件，支持可配置的覆盖行为。
**参数**：
- `source_file_path`（string, 必需）：源文件路径
- `dest_file_path`（string, 必需）：目标文件路径
- `overwrite`（boolean, 可选，默认=false）：覆盖冲突文件
**成功响应**：带有成功标志的空信息对象
#### fs_get_file_info
**描述**：获取文件/目录的完整元数据，支持可选的SHA-256摘要计算。
**参数**：
- `file_path`（string, 必需）：目标入口路径
- `calc_digest`（boolean, 可选，默认=false）：计算SHA-256哈希
**成功响应**：
```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
**描述**：文件或目录的轻量级存在检查。
**参数**：
- `file_path`（string, 必需）：目标路径
**成功响应**：
```json
{
"res": {
"success": true,
"info": {
"exists": true
}
}
}
```
### 3. 文件读写工具
#### fs_read_full_text
**描述**：读取目标文件的完整文本内容，指定编码。
**参数**：
- `file_path`（string, 必需）：目标文件路径
- `charset`（string, 可选，默认=utf-8）：多编码支持
**成功响应**：
```json
{
"res": {
"success": true,
"info": {
"content": "full-text-file-content"
}
}
}
```
#### fs_read_text_range
**描述**：大文件的分段文本读取，支持跳过前导行和限制读取行数。
**参数**：
- `file_path`（string, 必需）：目标文件路径
- `lines_to_skip`（integer, 必需）：要跳过的前导行数
- `max_lines_to_read`（integer, 必需）：要读取的最大行数
- `line_separator`（string, 可选，默认="\n"）：换行字符
- `charset`（string, 可选，默认=utf-8）：文件编码
**成功响应**：
```json
{
"res": {
"success": true,
"info": {
"lines_count": 5,
"content": "segmented-text-content"
}
}
}
```
#### fs_read_binary_chunk
**描述**：块状二进制文件读取，返回Base64编码数据用于安全网络传输，支持流端检测。
**参数**：
- `file_path`（string, 必需）：目标文件路径
- `bytes_to_skip`（integer, 必需）：要跳过的前导字节
- `max_bytes_to_read`（integer, 必需）：要读取的最大字节数
**成功响应**：
```json
{
"res": {
"success": true,
"info": {
"data_base64": "base64-encoded-binary",
"raw_bytes_length": 5,
"end_of_stream": true
}
}
}
```
#### fs_write_text
**描述**：将文本内容写入文件，支持覆盖或追加模式。
**参数**：
- `file_path`（string, 必需）：目标文件路径
- `text`（string, 必需，最小长度=1）：要写入的文本内容
- `append`（boolean, 可选，默认=false）：追加模式开关
- `charset`（string, 可选，默认=utf-8）：文件编码
**成功响应**：带有成功标志的空信息对象
#### fs_write_binary
**描述**：将Base64解码的二进制数据写入文件，支持追加操作。
**参数**：
- `file_path`（string, 必需）：目标文件路径
- `base64_data`（string, 必需，最小长度=1）：Base64编码的二进制数据
- `append`（boolean, 可选，默认=false）：追加模式开关
**成功响应**：带有成功标志的空信息对象
### 4. 搜索和替换工具
#### fs_search_files_by_content
**描述**：递归扫描目录，返回所有包含目标内容的文件路径，支持正则表达式、不区分大小写、后缀过滤。
**参数**：
- `dir_path`（string, 必需）：扫描根目录
- `recursive`（boolean, 必需）：递归扫描启用
- `search_term`（string, 必需）：搜索关键词或正则表达式
- `is_regex`（boolean, 可选，默认=false）：正则匹配启用
- `ignore_case`（boolean, 可选，默认=true）：不区分大小写匹配
- `file_extension`（string, 可选，默认=""）：后缀过滤
- `charset`（string, 可选，默认=utf-8）：文件编码
#### fs_search_in_files_by_content
**描述**：多文件内容匹配，返回带有可自定义的上下文行数和结果限制的结构化结果。
**参数**：
- `dir_path`（string, 必需）：扫描根目录
- `recursive`（boolean, 必需）：递归扫描启用
- `search_term`（string, 必需）：搜索关键词/正则表达式
- `limit`（integer, 必需）：最大匹配结果数
- `is_regex`（boolean, 可选，默认=false）：启用正则
- `ignore_case`（boolean, 可选，默认=true）：忽略大小写
- `lines_before`（integer, 可选，默认=0）：前置上下文行数
- `lines_after`（integer, 可选，默认=0）：后续上下文行数
- `file_extension`（string, 可选，默认=""）：后缀过滤
- `charset`（string, 可选，默认=utf-8）：文件编码
**成功响应**：
```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
**描述**：精确的单文件内容搜索，带有行上下文预览。
**参数**：类似于多文件搜索，单文件路径输入
**成功响应**：结构化单文件匹配结果
#### fs_file_replace
**描述**：单个文件中就地文本替换，返回总替换计数。
**参数**：
- `file_path`（string, 必需）：目标文件路径
- `search_term`（string, 必需）：要替换的文本
- `replacement`（string, 必需）：新的替换文本
- `line_separator`（string, 可选，默认="\n"）：换行分隔符
**成功响应**：
```json
{
"res": {
"success": true,
"info": {
"count": 1
}
}
}
```
### 5. 图像处理工具
#### fs_image_resize
**描述**：支持宽高比锁定，生成新的输出图像文件。
**参数**：
- `source_path`（string, 必需）：源图像路径
- `dest_path`（string, 必需）：输出图像路径
- `width`（integer, 必需，>0）：目标宽度
- `height`（integer, 必需，>0）：目标高度
- `keep_aspect_ratio`（boolean, 可选，默认=true）：锁定原始宽高比
**成功响应**：带有成功标志的空信息对象
#### fs_image_crop
**描述**：从源图像中裁剪指定的矩形区域并导出新文件。
**参数**：
- `source_path`（string, 必需）：源图像路径
- `dest_path`（string, 必需）：输出图像路径
- `x`（integer, 必需，≥0）：裁剪开始X坐标
- `y`（integer, 必需，≥0）：裁剪开始Y坐标
- `width`（integer, 必需，>0）：裁剪区域宽度
- `height`（integer, 必需，>0）：裁剪区域高度
**成功响应**：带有成功标志的空信息对象
#### fs_image_rotate
**描述**：顺时针旋转图像，自动扩展画布以保留完整内容。
**参数**：
- `source_path`（string, 必需）：源图像路径
- `dest_path`（string, 必需）：输出图像路径
- `degrees`（number, 必需）：顺时针旋转角度
**成功响应**：带有成功标志的空信息对象
### 6. OCR工具
#### fs_ocr_extract_text
**描述**：通过Tesseract OCR从图像中提取文本，支持WASM运行时（无本地引擎）和自定义本地二进制路径。
**参数**：
- `image_path` (string, 必需）：目标图像路径
- `tesseract_bin_path`（string, 可选，默认=""）：自定义Tesseract可执行文件路径
- `tessdata_path`（string, 可选，默认=""）：自定义tessdata语言资源路径
- `lang`（string, 可选，默认 eng）：识别语言前缀
**成功响应**：
```json
{
"res": {
"success": true,
"info": {
"content": "extracted-ocr-text-content"
}
}
}
```
## 项目构建与开发
### 脚本
```bash
# 清理构建产物
npm run clean
# 编译TypeScript源代码
npm run build
# 监视模式用于开发
npm run dev
# 完整重建（清理 + 构建）
npm run rebuild
# 启动SSE传输服务器
npm run server
# FastMCP开发模式
npm run fastmcp
# MCP Inspector调试
npm run inspect
# 构建并运行测试用例
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](https://github.com/kurtzhi/fsext-mcp-server-typescript)
- **问题**：[报告错误或请求功能](https://github.com/kurtzhi/fsext-mcp-server-typescript/issues)
