Fsext Mcp Server Typescript

FsExt-MCP-Server (TypeScript)

概要

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（最新の双方向リモートトランスポート）の 3 種類をネイティブにサポートします。

• 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
エンドポイント構成	2 つのエンドポイント（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 - すべてのエラー (I/O の失敗、無効なパラメーター、パスエラー、実行時例外) は、固定のエラー構造を返します：

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

MCP ツールの完全リファレンス

すべてのツールで additionalProperties: false による厳格な検証が有効になっており、不正な入力パラメーターを拒否して安全な呼び出しを実現します.

1. ディレクトリ操作ツール

fs_list_directory

説明：対象ディレクトリをスキャンし、フィルター処理済みの絶対パスの一覧を返します。再帰的な走査、ファイルのみのフィルタリング、拡張子によるフィルタリングに対応しています.

パラメーター：

• source_dir (string, required)：スキャン対象のディレクトリパス

• recursive (boolean, required)：サブディレクトリの再帰的なスキャンを有効にします

• only_files (boolean, required)：ディレクトリを除外し、ファイルのみを返します

• file_extension (string, optional, default="")：指定した拡張子でファイルをフィルタリングします

成功レスポンス：

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

fs_copy_directory

説明：ディレクトリツリー全体を再帰的にコピーします。既存の対象ディレクトリの上書きに対応しています.

パラメーター：

• source_dir (string, required)：コピー元のディレクトリパス

• copy_dest_dir (string, required)：コピー先のディレクトリパス

• overwrite (boolean, optional, default=false)：既存の対象ディレクトリを消去して上書きします

成功レスポンス：

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

fs_move_directory

説明：ディレクトリツリー全体を移動します。誤って上書きしないよう、対象パスが存在する場合は即座に失敗します.

パラメーター：

• source_dir (string, required)：移動元のディレクトリパス

• dest_dir (string, required)：移動先のディレクトリパス

• overwrite (boolean, optional, default=false)：競合するディレクトリの上書きを許可します

成功レスポンス：成功フラグと空の info オブジェクト

2. ファイルの基本操作ツール

fs_create_file

説明：空のファイル、または内容が入力されたファイルを作成します。不足している親ディレクトリは自動的に作成し、複数のエンコーディングに対応しています.

パラメーター：

• file_path (string, required)：対象のファイルパス

• content (string, optional, default="")：初期テキストコンテンツ

• charset (string, optional, default=utf-8)：エンコーディングの列挙値：utf-8、ucs-2、utf16le、latin1、ascii、base64、hex

成功レスポンス：成功フラグと空の info オブジェクト

fs_delete_file

説明：単一の通常ファイルのみを削除します。複数ファイルの一括削除によるリスクを避けるため、ディレクトリパスは拒否します.

パラメーター：

• file_path (string, required)：対象のファイルパス

成功レスポンス：成功フラグと空の info オブジェクト

fs_copy_file

説明：メタデータをすべて保持して単一ファイルをコピーします。上書きの制御に対応しています.

パラメーター：

• source_file_path (string, required)：コピー元のファイルパス

• dest_file_path (string, required)：コピー先のファイルパス

• overwrite (boolean, optional, default=false)：既存の対象ファイルを上書きします

成功レスポンス：成功フラグと空の info オブジェクト

fs_move_file

説明：上書き動作を設定して、単一ファイルを移動します.

パラメーター：

• source_file_path (string, required)：移動元のファイルパス

• dest_file_path (string, required)：移動先のファイルパス

• overwrite (boolean, optional, default=false)：競合するファイルを上書きします

成功レスポンス：成功フラグと空の info オブジェクト

fs_get_file_info

説明：ファイル／ディレクトリのメタデータ全体を取得します。オプションで SHA-256 ダイジェストの計算に対応しています.

パラメーター：

• file_path (string, required)：対象エントリーのパス

• calc_digest (boolean, optional, default=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, required)：対象パス

成功レスポンス：

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

• 課題：バグの報告または機能のリクエスト