Fsext Mcp Server Java

FsExt-MCP-Server (Java)

概要

Quarkus で構築された、高性能で安全な、ローカルファイルシステム操作用の Model Context Protocol（MCP）サーバーです。ネイティブ画像処理、Tesseract OCR、メディアユーティリティツールを備えています。公式 MCP 仕様に完全準拠しており、標準化されたリクエスト／レスポンススキーマ、大容量ファイルのストリーミング I/O、複数トランスポートによるリモートデプロイ、LLM エージェント統合向けの堅牢なテキスト検索・置換ワークフローを提供します。

主な機能

• ファイルとディレクトリの包括的な管理：ファイルの作成、削除、コピー、移動、メタデータの確認、存在確認に対応しています。上書き時の安全対策を備えた、ディレクトリツリー全体の再帰的なコピー／移動も可能です。
• ファイルのストリーミング読み書きパイプライン：テキスト全体の読み込み、行単位の分割ストリーミング、チャンク単位のバイナリ I/O、テキスト／バイナリの上書き・追記処理に対応しています。大容量ファイル全体を JVM のヒープメモリに読み込まないよう設計されています。
• 高度な検索とインプレース置換：ディレクトリ全体の再帰的な内容スキャン、設定可能な前後のコンテキスト行を含む複数ファイルのコンテキストマッチング、正規表現、大小文字を区別しない検索、一致件数の統計を伴うアトミックなテキストのインプレース置換に対応しています。
• ネイティブ画像処理ツールキット：Tess4J を活用した高速な画像ユーティリティを提供します。キャンバスの余白追加によるアスペクト比固定のリサイズ、正確な矩形クロップ、任意角度の時計回り回転が可能です。
• Tesseract OCR によるテキスト抽出：ローカルの Tesseract バイナリを使用し、ラスター画像から安定してテキストを認識します。WASM による代替実装はありません。バイナリパスの設定が空でも、代替の JS ベース OCR エンジンは起動しません。バイナリとデータのディレクトリを設定でき、複数言語の tessdata に対応しています。
• 厳格な入力検証と統一レスポンススキーマ：各ツールは、認識されない入力フィールドをブロックしてインジェクションのリスクを軽減するため、厳格な additionalProperties: false JSON スキーマ検証を適用します。すべての操作は、一貫したラップ形式の成功／エラーペイロードを返し、クライアント側で統一的に解析できます。
• 複数トランスポートとの互換性：公式 MCP 標準トランスポートをすべて実装しています。
  • stdio：ローカルのデスクトップ MCP クライアント（Claude Desktop、Cursor など）とのネイティブ統合
  • sse：従来型の軽量なリモートイベントストリーミングトランスポート
  • http：最新の Streamable HTTP 双方向リモートストリーミングトランスポート
• ワークスペースのセキュリティサンドボックス分離：--lock-root フラグにより、すべてのファイルシステム操作を指定したディレクトリツリー内に限定し、パス逸脱の脆弱性や許可されていないフォルダー間アクセスを防ぎます。
• 動的ポート割り当て：カスタムの --port 値が指定されていない場合、デフォルトポート 8000 の使用状況を自動的に検出し、1024 を超える空き TCP ポートを割り当てます。
• Quarkus ネイティブランタイム最適化：起動遅延の短縮、メモリフットプリントの最小化、リモート HTTP／SSE デプロイ向けの組み込み CORS 対応、長時間接続するリモートクライアントセッションのための適切な接続シャットダウン処理を実現します。

クイックスタート

前提条件

• Java 17+
• Gradle（ラッパーがリポジトリに含まれているため、グローバルインストールは不要です）
• Tesseract バイナリ（任意。OCR ツールの機能を使用する場合のみ必要です）

1. 実行可能な Uber Jar をビルドする

同梱の Gradle ラッパーを使用して、依存関係を含む実行可能な jar をコンパイル、パッケージ化します。

# Windows
./gradlew.bat clean buildRunJar

# macOS / Linux
./gradlew clean buildRunJar

成果物のパス：build/fsext-mcp-server-<version>.jar

2. パッケージ化された Jar からサーバーを起動する

<x.y.z> を実際のビルドバージョン文字列に置き換えてください。

# Default stdio mode, unrestricted full filesystem access
java -jar build/fsext-mcp-server-x.y.z.jar

# Secure locked workspace mode (recommended for production agent usage)
java -jar build/fsext-mcp-server-x.y.z.jar --lock-root /my/workspace

# Remote SSE streaming service
java -jar build/fsext-mcp-server-x.y.z.jar --transport sse --host 0.0.0.0 --port 8000 --lock-root /my/workspace

# Modern Streamable HTTP remote service
java -jar build/fsext-mcp-server-x.y.z.jar --transport http --host 127.0.0.1 --port 8080 --lock-root /my/workspace

3. MCP デスクトップクライアント（Claude Desktop／Cursor）と統合する

stdio トランスポートでローカル統合するための、クライアント設定 JSON の例です。

{
  "mcpServers": {
    "fsext-java": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/fsext-mcp-server-x.y.z.jar",
        "--lock-root",
        "/my/workspace"
      ]
    }
  }
}

ローカルソースリポジトリの開発環境セットアップ

# Clone official source repository
git clone https://github.com/kurtzhi/fsext-mcp-server-java
cd fsext-mcp-server-java

# Build full executable uber jar
./gradlew clean buildRunJar

CLI 起動パラメーターのリファレンス表

パラメーター	デフォルト値	説明
--transport	stdio	MCP トランスポートの実装：stdio ／ sse ／ http
--host	127.0.0.1	ネットワークのバインドアドレス。stdio トランスポートでは無視されます
--port	8000	サービスがリッスンする TCP ポート。デフォルトのポート 8000 が使用中で、カスタムポートが指定されていない場合は、1024 以上の空きポートが自動選択されます。stdio トランスポートでは無視されます
--origin	*	HTTP／SSE リモートトランスポートで許可する CORS オリジンのカンマ区切りリスト
--lock-root	空	すべてのファイルシステム操作をこのルートディレクトリ内に制限します。省略した場合、OS へのアクセスに制限はありません

本番環境へのデプロイ時の起動例

1. ローカル Stdio モード（デスクトップ MCP クライアント）

java -jar build/fsext-mcp-server-x.y.z.jar --lock-root /my/workspace

2. リモート SSE トランスポートモード

java -jar build/fsext-mcp-server-x.y.z.jar --transport sse --host 0.0.0.0 --port 8000 --lock-root /my/workspace

SSE エンドポイント

1. 長時間接続する SSE ストリームの購読チャネル（サーバーイベントのプッシュ）： http://<host>:<port>/sse
2. JSON-RPC クライアントリクエストの送信チャネル： http://<host>:<port>/messages

MCP Inspector の接続設定

• トランスポートタイプ：SSE
• 接続アドレス：http://127.0.0.1:8000/sse

3. Streamable HTTP リモートトランスポート（公式の最新標準）

java -jar build/fsext-mcp-server-x.y.z.jar --transport http --host 0.0.0.0 --port 8000 --lock-root /my/workspace

双方向の統合エンドポイント

すべてのクライアントリクエストとサーバーのストリーミング通信を処理する、共通の単一エントリーポイント： http://<host>:<port>/mcp

MCP Inspector の接続設定

• トランスポートタイプ：Streamable HTTP
• 接続アドレス：http://127.0.0.1:8000/mcp

4. SSE と Streamable HTTP のトランスポート比較

機能	SSE のデュアルエンドポイントトランスポート	Streamable HTTP のシングルエンドポイントトランスポート
エンドポイントの構成	2 つの独立したエンドポイント：GET によるストリーム購読 ＋ POST によるメッセージ送信	双方向通信全体に対応する統合 URL が 1 つ
通信パターン	サーバーからクライアントへの一方向のイベントプッシュのみ	双方向のリクエストとストリームを組み合わせた通信
接続の信頼性	セッションが切断されやすく、エンドポイント間の状態同期が複雑	セッションを自動復旧し、高並行のリモートデプロイ向けに最適化
仕様のステータス	旧仕様との互換性を保つ実装であり、新規デプロイには推奨されません	すべてのリモートネットワーク連携における現行の公式 MCP 標準

対応するテキストファイルの文字セット

文字セットの識別子はすべて大文字と小文字を区別しません。テキストの読み取り／書き込み操作では、以下の値を使用できます。

• utf-8 / UTF_8
• iso-8859-1 / ISO_8859_1
• utf-16 / UTF_16
• utf-16be / UTF_16BE
• utf-16le / UTF_16LE
• ascii / US_ASCII

統一されたグローバルレスポンス仕様

すべての MCP ツールは、実行成功時と実行時エラー時の両方で、同一のトップレベルラップ済み JSON 構造を使用します。各ツールのビジネスデータは、ルートの res フィールド内にある info サブオブジェクトに格納されます。

コアスキーマの定義

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

• success：グローバルな操作ステータスフラグ
  • true：例外なくツールの処理が完了しました。info にはツール固有の戻りデータが含まれます
  • false：操作に失敗しました（ワークスペース外へのアクセス制限、ファイルの欠落、I/O エラー、無効な入力スキーマ、アクセス許可の拒否など）
• info の 2 種類の動作：
  1. 成功時（success: true）：各ツール固有の構造化されたカスタムペイロード
  2. 失敗時（success: false）：機械可読なエラーコードと人間が読める説明を含む標準化されたエラーオブジェクト

     "info": {
       "code": "ERROR_CODE_IDENTIFIER",
       "message": "詳細な人間向けエラー説明"
     }
     

レスポンスペイロードの例

1. ディレクトリ一覧取得の成功レスポンス

{
  "res": {
    "success": true,
    "info": {
      "paths": [
        "/workspace/demo/Main.java",
        "/workspace/demo/util/FileTool.java"
      ]
    }
  }
}

2. ワークスペース外へのアクセスを防ぐセキュリティ制限による失敗レスポンス

{
  "res": {
    "success": false,
    "info": {
      "code": "WORKSPACE_ESCAPE_FORBIDDEN",
      "message": "Access restricted: Path `/etc/passwd` is outside allowed workspace `/my/workspace`"
    }
  }
}

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

すべてのツールの入力スキーマでは、additionalProperties: false による厳密な検証を行い、認識されないパラメーターを拒否して、悪意のあるパス注入攻撃のリスクを軽減します。

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

fs_list_directory

対象ディレクトリを（浅く、または再帰的に）スキャンし、ファイルの種類や拡張子によるフィルタリングに対応した絶対パスの一覧を返します。 パラメーター

• source_dir (string, required): スキャンするルートディレクトリ
• recursive (boolean, required): すべてのサブディレクトリを再帰的に走査するかどうか
• only_files (boolean, required): 通常のファイルのみを返し、ディレクトリを除外するかどうか
• file_extension (string, optional, default=""): 対象ファイルの拡張子で出力をフィルタリングします

fs_copy_directory

上書き動作を設定して、ディレクトリツリー全体を再帰的にコピーします。 パラメーター

• source_dir (string, required): コピー元ディレクトリツリーのパス
• copy_dest_dir (string, required): 出力先ディレクトリのパス
• overwrite (boolean, optional, default=false): 既存の出力先ディレクトリの内容を消去して上書きするかどうか

fs_move_directory

ディレクトリツリー全体を新しいパスへアトミックに移動します。誤ってデータを失わないよう、上書きが明示的に有効になっていない場合、移動先が存在するとただちに失敗します。 パラメーター

• source_dir (string, required): 移動元ディレクトリのパス
• dest_dir (string, required): 移動先ディレクトリのパス
• overwrite (boolean, optional, default=false): 移動先に競合するディレクトリがある場合に上書きを許可するかどうか

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

fs_create_file

新しいテキストファイルを作成します。存在しない親ディレクトリは自動的に作成され、初期テキストの内容と文字コードを設定できます。 パラメーター

• file_path (string, required): 対象ファイルの絶対パス
• content (string, optional, default=""): 新しいファイルに書き込む初期テキスト
• charset (string, optional, default="utf-8"): 対応する文字コード識別子（上記の文字コード一覧を参照）

fs_delete_file

通常の単一ファイルのみを完全に削除します。ディレクトリパスは受け付けず、大量のファイルを再帰的に削除するリスクを防ぎます。 パラメーター

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

fs_copy_file

元のファイルシステムメタデータを保持して単一ファイルをコピーし、競合する対象ファイルへの上書きを設定できます。 パラメーター

• source_file_path (string, required): コピー元ファイルの絶対パス
• dest_file_path (string, required): 出力先ファイルの絶対パス
• overwrite (boolean, optional, default=false): 既存の出力先ファイルを上書きするかどうか

fs_move_file

単一ファイルを新しい絶対パスへアトミックに移動し、移動先ファイルと競合する場合の上書き動作を設定できます。 パラメーター

• source_file_path (string, required): 移動元ファイルの絶対パス
• dest_file_path (string, required): 移動先ファイルの絶対パス
• overwrite (boolean, optional, default=false): 移動先に競合するファイルがある場合に上書きを許可するかどうか

fs_get_file_info

ファイルまたはディレクトリの完全なメタデータを取得します。整合性検証のため、オプションで SHA-256 暗号学的ダイジェストを計算できます。 パラメーター

• file_path (string, required): 対象ファイルシステム項目の絶対パス
• calc_digest (boolean, optional, default=false): ファイル内容の SHA-256 ハッシュを計算するかどうか

fs_is_file_exists

完全なメタデータを読み込まずに、ファイルまたはディレクトリなど、あらゆるファイルシステム項目の存在を簡易確認します。 パラメーター

• file_path (string, required): 存在を確認する絶対パス

3. ファイルの読み書きツール

fs_read_full_text

ユーザーが指定したテキストエンコーディングで、対象ファイルのテキスト全体を読み込みます。 パラメーター

• file_path (string, required): 対象テキストファイルの絶対パス
• charset (string, optional, default="utf-8"): 対応する文字コード識別子

fs_read_text_range

大きなファイル向けに最適化された、行単位の分割テキストストリーミングです。先頭の行をスキップし、読み取る行数の上限を設定して、ヒープメモリの過剰な割り当てを防ぎます。 パラメーター

• file_path (string, required): 対象テキストファイルの絶対パス
• lines_to_skip (integer, required, min=0): 読み取り時にスキップする先頭行数
• max_lines_to_read (integer, required, min=0): ファイルから抽出する行数の上限
• line_separator (string, optional, default="\n"): 改行区切り文字
• charset (string, optional, default="utf-8"): サポートされている文字セット識別子

fs_read_binary_chunk

バイナリファイルをチャンク単位でストリーミング読み取りします。安全な JSON-RPC ネットワーク送信のため、Base64 エンコードされたバイトペイロードを返し、ストリーム終端マーカーを検出します。 パラメーター

• file_path (string, required): 対象バイナリファイルの絶対パス
• bytes_to_skip (integer, required, min=0): チャンク読み取り前にスキップする先頭のバイトオフセット
• max_bytes_to_read (integer, required, min=0): 1 回のチャンクで読み取る最大バイト数

fs_write_text

エンコードされたテキストコンテンツを対象ファイルに書き込みます。ファイル全体の上書きと追記のみの書き込みモードに対応しています。 パラメーター

• file_path (string, required): 出力先ファイルの絶対パス
• text (string, required, minLength=1): 保存する生のテキストコンテンツ
• append (boolean, optional, default=false): 追記モードの切り替え（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): ファイル末尾にバイナリデータを追記（false = 全体を上書き）

4. コンテンツ検索とインプレース置換ツール

fs_search_files_by_content

ディレクトリツリーを再帰的にスキャンし、一致するテキストパターンを含むすべてのファイルの絶対パスを返します。正規表現、大文字と小文字を区別しない検索、ファイル拡張子によるフィルタリングに対応しています。 パラメーター

• dir_path (string, required): コンテンツを再帰的にスキャンするルートディレクトリ
• recursive (boolean, required): サブディレクトリをすべて再帰的に検索するかどうか
• search_term (string, required): プレーンテキストのキーワードまたは正規表現パターン
• is_regex (boolean, optional, default=false): search_term を正規表現パターンとして扱う
• 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"): 対象ファイルの解析に使用する文字セット

fs_search_in_file_by_content

単一ファイルの内容を高精度で検索し、一致箇所の前後に表示するコンテキスト行数を設定可能な、構造化された一致セグメントを返します。コードやドキュメントの調査ワークフローに使用できます。 パラメーター

• file_path（文字列、必須）：対象となる単一ファイルの絶対パス
• search_term（文字列、必須）：検索するキーワードまたは正規表現パターン
• is_regex（ブール値、任意、デフォルト=false）：正規表現によるマッチングを有効にします
• ignore_case（ブール値、任意、デフォルト=true）：大文字と小文字を区別せずに検索するかどうかを指定します
• lines_before（整数、任意、デフォルト=0）：各一致箇所の前に表示するコンテキスト行数
• lines_after（整数、任意、デフォルト=0）：各一致箇所の後に表示するコンテキスト行数
• charset（文字列、任意、デフォルト="utf-8"）：対象ファイルの解析に使用する文字コード

fs_file_replace

単一の対象ファイル内でテキストを一括して直接置換します。書き込み完了後、一致して置換されたテキストセグメントの合計数を返します。 パラメーター

• file_path（文字列、必須）：編集対象ファイルの絶対パス
• search_term（文字列、必須）：検索して置換するテキスト部分文字列
• replacement（文字列、必須）：置換後の新しいテキスト
• line_separator（文字列、任意、デフォルト="\n"）：ファイル解析に使用する改行区切り文字

5. 画像処理ツール

fs_image_resize

元のアスペクト比を保持し、透明なキャンバスの余白で埋めて、指定されたピクセル寸法に画像をリサイズします。 パラメーター

• source_path（文字列、必須）：入力元画像の絶対パス
• dest_path（文字列、必須）：リサイズ後の出力画像の絶対パス
• width（整数、必須、>0）：目標のピクセル幅
• height（整数、必須、>0）：目標のピクセル高さ
• keep_aspect_ratio（ブール値、任意、デフォルト=true）：拡大縮小時に元画像のアスペクト比を維持します
• pad_to_target（ブール値、任意、デフォルト=true）：アスペクト比を維持した状態で、目標の幅と高さに合わせて透明な余白を追加します

fs_image_crop

元画像から長方形のピクセル領域を切り出し、独立した出力画像ファイルとして書き出します。 パラメーター

• source_path（文字列、必須）：入力元画像の絶対パス
• dest_path（文字列、必須）：切り抜いた出力画像の絶対パス
• x（整数、必須、≥0）：切り抜き領域の左端のピクセル座標
• y（整数、必須、≥0）：切り抜き領域の上端のピクセル座標
• width（整数、必須、>0）：切り抜く長方形領域のピクセル幅
• height（整数、必須、>0）：切り抜く長方形領域のピクセル高さ

fs_image_rotate

元画像を任意の小数の角度で時計回りに回転します。画像の端が切れないよう、出力キャンバスの寸法を自動的に拡張して画像全体を保持します。 パラメーター

• source_path（文字列、必須）：入力元画像の絶対パス
• dest_path（文字列、必須）：回転後の出力画像の絶対パス
• degrees（数値、必須）：時計回りの回転角度（度）

6. OCR テキスト抽出ツール

fs_ocr_extract_text

ローカルにインストールされた Tesseract OCR バイナリを使用して、ラスター画像ファイルから読み取り可能なテキストを抽出します。WASM JavaScript によるフォールバック実装はありません。tesseract_bin_path が空でも、代替のウェブベース OCR エンジンは初期化されません。 パラメーター

• image_path（文字列、必須）：テキスト認識を行う入力画像の絶対パス
• tesseract_bin_path（文字列、任意、デフォルト=""）：ローカルの Tesseract 実行可能バイナリの絶対パス。空の場合はシステムの PATH のみを検索します
• tessdata_path（文字列、任意、デフォルト=""）：Tesseract の言語学習データファイルを格納したディレクトリの絶対パス
• lang（文字列、任意、デフォルト="eng"）：利用可能な tessdata 学習ファイルに対応する言語コードの接頭辞

コアランタイムの依存関係

• io.quarkus:quarkus-bom:3.37.1：Quarkus のバージョンを統一する BOM
• io.quarkus:quarkus-arc：Quarkus の CDI 依存性注入コンテナ
• io.quarkus:quarkus-reactive-routes：リアクティブ HTTP ルーティングのコア
• io.quarkiverse.mcp:quarkus-mcp-server-http:1.13.1：ストリーミング可能な HTTP と SSE の MCP トランスポート実装
• io.quarkiverse.mcp:quarkus-mcp-server-stdio:1.13.1：Stdio MCP トランスポート実装
• net.sourceforge.tess4j:tess4j:5.18.0：Java Tesseract OCR バインディングライブラリ

プロジェクトのビルドと開発用 Gradle タスク

# Clean all compiled build artifacts and temporary directories
./gradlew clean

# Full clean + compile + package self-contained uber jar
./gradlew clean buildRunJar

ライセンス

このプロジェクトはApache License 2.0の下でオープンソースとして公開されています。法的なライセンス条件の詳細については、ルートレベルの LICENSE ファイルを参照してください。

サードパーティソフトウェアに関する通知

このソフトウェアには、複数のオープンソース依存ライブラリがバンドルされています。すべてのサードパーティコンポーネントの著作権はそれぞれの権利者に帰属し、各コンポーネントにはそれぞれのオープンソースライセンス契約が適用されます。 サードパーティライブラリ、バージョン、ライセンスの詳細な一覧は、ルートレベルの THIRD-PARTY-NOTICES ファイルと、JAR アーティファクト内の /META-INF/THIRD-PARTY-NOTICES に記載されています。

リポジトリと課題の追跡

• GitHub ソースリポジトリ：https://github.com/kurtzhi/fsext-mcp-server-java
• バグ報告と機能リクエスト：https://github.com/kurtzhi/fsext-mcp-server-java/issues