Vulcan File Ops

## 🚀 Vulcan File Ops MCP Server

Vulcan File Ops MCP Serverは、デスクトップAIアシスタントを強力な開発パートナーに変えます。会話型AI（Claude DesktopやChatGPT Desktopなど）とローカルファイルシステムの間のギャップを埋め、CursorやClineなどのAI搭載IDEと同じファイル操作機能を提供します。コードの作成、プロジェクトのリファクタリング、ドキュメントの管理、複雑なファイル操作など、専用のAIコーディングアシスタントと同じパワーを持ちます。

## 🚀 クイックスタート
このサーバーはNode.jsが必要で、グローバル、ローカルにインストールするか、npxで直接実行できます。**ほとんどのユーザーはnpxを使用することをおすすめ**します。これにより、インストールせずに即座に実行できます。

### クイックスタート（ほとんどのユーザーにおすすめ）
インストールせずに直接実行します：
```bash
npx @n0zer0d4y/vulcan-file-ops --help

開発者がコードに貢献したり変更したい場合は、以下のローカルリポジトリの実行を参照してください。

グローバルインストール

システム全体でアクセスできるようにグローバルにインストールします：

npm install -g @n0zer0d4y/vulcan-file-ops

ローカルインストール

特定のプロジェクトにインストールします：

npm install @n0zer0d4y/vulcan-file-ops

前提条件

Node.js（バージョン14以上）がシステムにインストールされている必要があります。これにより、このパッケージを実行するために必要なnpmとnpxが提供されます。

• Node.jsをダウンロードする：https://nodejs.org/
• インストールを確認する：node --version と npm --version を実行します。

依存関係

このサーバーは外部サービスに依存せず、完全にローカルで動作します。npxを使用すると、必要なすべてのパッケージが自動的にダウンロードされます。

✨ 主な機能

Model Context Protocol

Model Context Protocol (MCP) は、AIアシスタントが外部リソースやサービスに安全にアクセスできるようにします。このサーバーは、ファイルシステム操作のためのMCPを実装しており、AIエージェントが制御されたディレクトリ境界内でファイルを読み書きおよび管理できるようにします。

主要な機能

この拡張された実装は以下を提供します：

• 動的ディレクトリアクセス：会話コマンドを通じたランタイムディレクトリ登録
• ドキュメントサポート：PDF、DOCX、PPTX、XLSX、ODTの読み書きとHTMLからドキュメントへの変換
• バッチ操作：複数のファイルを同時に読み書き、編集、コピー、移動、または名前変更
• 高度なファイル編集：柔軟なマッチングと差分プレビューを備えたパターンベースの変更
• 柔軟な読み取りモード：ファイル全体、先頭/末尾、または任意の行範囲
• 画像ビジョンサポート：AI分析と説明のための画像添付
• ディレクトリフィルタリング：不要なフォルダ（node_modules、dist、.git）をリストから除外
• 選択的ツールアクティベーション：特定のツールまたはツールカテゴリのみを有効にする
• 高パフォーマンス：スマートな再帰検出を備えた最適化された検索アルゴリズム
• セキュリティコントロール：パス検証、アクセス制限、およびシェルコマンド承認
• ローカル制御：外部依存関係のない完全なローカルインストール

ディレクトリアクセスモデル

このサーバーは、ディレクトリアクセスに複数の柔軟なアプローチをサポートしています：

1. 事前設定されたアクセス：サーバー起動時に --approved-folders を使用してディレクトリを指定し、即座にアクセスできるようにします。
2. ランタイム登録：ユーザーはAIエージェントに register_directory ツールを介して会話中にディレクトリを登録するよう指示できます。
3. MCP Rootsプロトコル：クライアントアプリケーションはワークスペースディレクトリを動的に提供できます。
4. 柔軟なパーミッション：複数のアプローチを組み合わせることができます - 承認されたフォルダから始め、ランタイムで追加することができます。
5. 安全な境界：すべての操作は、アクセス方法に関係なく、登録されたディレクトリに対して検証されます。

📦 インストール

このサーバーはNode.jsが必要で、グローバル、ローカルにインストールするか、npxで直接実行できます。ほとんどのユーザーはnpxを使用することをおすすめします。これにより、インストールせずに即座に実行できます。

クイックスタート（ほとんどのユーザーにおすすめ）

インストールせずに直接実行します：

npx @n0zer0d4y/vulcan-file-ops --help

開発者がコードに貢献したり変更したい場合は、以下のローカルリポジトリの実行を参照してください。

グローバルインストール

システム全体でアクセスできるようにグローバルにインストールします：

npm install -g @n0zer0d4y/vulcan-file-ops

ローカルインストール

特定のプロジェクトにインストールします：

npm install @n0zer0d4y/vulcan-file-ops

前提条件

Node.js（バージョン14以上）がシステムにインストールされている必要があります。これにより、このパッケージを実行するために必要なnpmとnpxが提供されます。

• Node.jsをダウンロードする：https://nodejs.org/
• インストールを確認する：node --version と npm --version を実行します。

依存関係

このサーバーは外部サービスに依存せず、完全にローカルで動作します。npxを使用すると、必要なすべてのパッケージが自動的にダウンロードされます。

💻 使用例

基本的な設定

MCPクライアントの設定（例：claude_desktop_config.json）に追加します：

オプション1：npxを使用する（推奨 - インストール不要）

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": ["@n0zer0d4y/vulcan-file-ops"]
    }
  }
}

オプション2：グローバルインストールを使用する

npm install -g @n0zer0d4y/vulcan-file-ops を実行した後：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops"
    }
  }
}

オプション3：ローカルインストールを使用する

プロジェクトで npm install @n0zer0d4y/vulcan-file-ops を実行した後：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "./node_modules/.bin/vulcan-file-ops"
    }
  }
}

オプション4：ローカルリポジトリの実行（開発者向け）

このリポジトリをクローンし、ソースから実行したい場合：

git clone https://github.com/n0zer0d4y/vulcan-file-ops.git
cd vulcan-file-ops
npm install
npm run build

その後、MCPクライアントを設定します：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops",
      "args": ["--approved-folders", "/path/to/your/allowed/directories"]
    }
  }
}

注：ビルド後、vulcan-file-ops コマンドはPATHに含まれるようになります。または、完全なパス ./dist/cli.js を使用することもできます。

高度な設定

承認されたフォルダ

サーバー起動時に特定のディレクトリを事前に設定して、即座にアクセスできるようにします：

macOS/Linux (npx)：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    }
  }
}

Windows (npx)：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "C:/Users/username/projects",
        "C:/Users/username/documents"
      ]
    }
  }
}

代替案：ローカルリポジトリの実行 クローンしたリポジトリから実行するユーザー（npm run build の後）：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops",
      "args": [
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    }
  }
}

パス形式の注：

• Windows：ドライブレター（例：C:/、D:/）を含めます。JSONではエスケープのためにバックスラッシュを避けるために正斜線を使用します。
• macOS/Linux：絶対パスの場合は / で始め、ホームディレクトリの場合は ~ を使用します。

メリット：

• 即時アクセス：サーバー起動時にディレクトリが検証され、すぐに使用できます。
• セキュリティ：指定されたディレクトリのみにアクセスできます（MCP Rootsプロトコルを使用しない限り）。
• 便利さ：会話を介してディレクトリを手動で登録する必要がありません。
• AIの可視性：承認されたディレクトリは、register_directory および list_allowed_directories ツールの説明に動的に埋め込まれ、AIアシスタントがどのディレクトリが事前承認されているかを確認でき、冗長な登録試行を避けることができます。

AIアシスタントが承認されたフォルダをどのように見るか： --approved-folders を設定すると、サーバーはこの情報を register_directory および list_allowed_directories のツール説明に動的に挿入します。これにより：

• ✅ AIアシスタントはどのディレクトリにすでにアクセスできるかを確認できます。
• ✅ AIは事前承認されたディレクトリまたはそのサブディレクトリを再登録しないことを知っています。
• ✅ AIが最初に list_allowed_directories を呼び出す必要なく、明確な可視性が得られます。
• ✅ すべてのMCPクライアント（Cursor、Claude Desktopなど）で確実に機能します。

AIがツール説明で見る例：

事前承認されたディレクトリ（すでにアクセス可能で、これらを登録しないでください）：
  - C:\Users\username\projects
  - C:\Users\username\documents

重要：これらのディレクトリとそのサブディレクトリはすべてのファイルシステムツールからすでにアクセス可能です。これらのパスに対して register_directory を使用しないでください。

注：

• パスは絶対パスである必要があります：Windowsではドライブレター（C:/path）が必要で、Unix/Macでは / または ~ で始まります。
• ディレクトリのカンマ区切りリスト（パスの一部でない限りスペースはありません）。
• ディレクトリは起動時に検証され、無効なパスがある場合はサーバーが終了します。
• ランタイムの register_directory ツールと併用して、追加のアクセスを取得できます。
• クライアントが使用する場合、MCP Rootsプロトコルは承認されたフォルダをワークスペースルートで置き換えます。

ディレクトリフィルタリング

ディレクトリリストから特定のフォルダを除外します：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--ignored-folders",
        "node_modules,dist,.git,.next"
      ]
    }
  }
}

ツール選択

特定のツールカテゴリのみを有効にします：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--enabled-tool-categories",
        "read,filesystem"
      ]
    }
  }
}

または、個々のツールを有効にします：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--enabled-tools",
        "read_file,list_directory,grep_files"
      ]
    }
  }
}

複合設定

すべての設定オプションを組み合わせることができます：

Windowsの例（npx）

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "C:/Users/username/projects",
        "C:/Users/username/documents",
        "--ignored-folders",
        "node_modules,dist,.git",
        "--approved-commands",
        "npm,node,git,ls,pwd,cat,echo",
        "--enabled-tool-categories",
        "read,filesystem,shell",
        "--enabled-tools",
        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
      ]
    }
  }
}

macOS/Linuxの例（npx）

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents",
        "--ignored-folders",
        "node_modules,dist,.git",
        "--approved-commands",
        "npm,node,git,ls,pwd,cat,echo",
        "--enabled-tool-categories",
        "read,filesystem,shell",
        "--enabled-tools",
        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
      ]
    }
  }
}

代替案：ローカルリポジトリの実行 クローンしたリポジトリから実行するユーザー（npm run build の後）：

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops",
      "args": [
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents",
        "--ignored-folders",
        "node_modules,dist,.git",
        "--approved-commands",
        "npm,node,git,ls,pwd,cat,echo",
        "--enabled-tool-categories",
        "read,filesystem,shell",
        "--enabled-tools",
        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
      ]
    }
  }
}

ディレクトリ登録

特定のディレクトリにアクセスするには、AIエージェントに指示します：

"Please register the directory C:\path\to\your\folder for access, then list its contents."

AIは register_directory ツールを使用してアクセスを取得し、そのディレクトリ内で操作を実行します。

📚 ドキュメント

カテゴリ別の利用可能なツール

読み取り操作

read_file

柔軟なモード（全量、先頭、末尾、範囲）でファイル内容を読み取ります。

注：このツールは単一ファイル操作のみに限定されています。推奨：より柔軟性の高い単一およびバッチファイル操作をサポートする read_multiple_files を代わりに使用してください。

入力：

• path (文字列)：ファイルパス
• mode (文字列、オプション)：読み取りモード
  • full - ファイル全体を読み取ります（デフォルト）
  • head - 最初のN行を読み取ります
  • tail - 最後のN行を読み取ります
  • range - 任意の行範囲を読み取ります（例：50 - 100行目）
• lines (数値、オプション)：先頭/末尾モードの行数
• startLine (数値、オプション)：範囲モードの開始行
• endLine (数値、オプション)：範囲モードの終了行

出力：テキストとしてのファイル内容。テキストファイルとドキュメント（PDF、DOCX、PPTX、XLSX、ODT、ODP、ODS）をサポートします。

attach_image

AIビジョン分析のために画像を添付します。

入力：

• path (文字列 | 文字列配列)：画像ファイルのパス、または複数の画像を一度に添付するためのパスの配列

出力：ビジョンモデル処理のためのMCP形式の画像内容。PNG、JPEG、GIF、WebP、BMP、SVGをサポートします。

read_multiple_files

複数のファイルを同時にバッチ読み取りします。

入力：

• files (配列)：パスとオプションのモード設定を持つファイルオブジェクトのリスト

出力：すべてのファイルの内容。読み取りに失敗しても操作は停止しません。

書き込み操作

write_file

ファイル内容を作成または置き換えます。

注：このツールは単一ファイル操作のみに限定されています。推奨：より柔軟性の高い単一およびバッチファイル操作をサポートする write_multiple_files を代わりに使用してください。

入力：

• path (文字列)：ファイルパス
• content (文字列)：ファイル内容（PDF/DOCX変換の場合はテキストまたはHTML）

出力：成功確認。HTMLからPDF/DOCXへの変換をサポートし、リッチな書式設定が可能です。

write_multiple_files

複数のファイルを同時に作成または置き換えます。

入力：

• files (配列)：パスと内容を持つファイルオブジェクトのリスト

出力：各ファイルのステータス。書き込みに失敗しても他のファイルの操作は停止しません。

edit_file

インテリジェントなマッチングを使用してテキストおよびコードファイルに正確な変更を適用します。単一ファイルおよび複数ファイル操作の両方をサポートします。

単一ファイル入力（モード: 'single'）：

• mode (文字列、オプション)："single" に設定します（下位互換性のために省略した場合はデフォルト）
• path (文字列)：ファイルパス
• edits (配列)：編集操作のリスト。それぞれに含まれる項目：
  • oldText (文字列)：検索するテキスト（3 - 5行のコンテキストを含めます）
  • newText (文字列)：置き換えるテキスト
  • instruction (文字列、オプション)：この編集が何をするかの説明
  • expectedOccurrences (数値、オプション)：予想される一致数（デフォルト: 1）
• matchingStrategy (文字列、オプション)：マッチング戦略
  • exact - 文字単位の一致（最速、最安全）
  • flexible - 空白を無視したマッチング、インデントを保持
  • fuzzy - トークンベースの正規表現マッチング（最も許容度が高い）
  • auto - 正確 → 柔軟 → 曖昧な順に試す（デフォルト）
• dryRun (ブール値、オプション)：書き込みせずに変更をプレビューする（デフォルト: false）
• failOnAmbiguous (ブール値、オプション)：一致が曖昧な場合に失敗する（デフォルト: true）

複数ファイル入力（モード: 'multiple'）：

• mode (文字列)："multiple" に設定します
• files (配列)：ファイル編集要求の配列（最大50）。それぞれに含まれる項目：
  • path (文字列)：ファイルパス
  • edits (配列)：このファイルの編集操作のリスト（上記と同じ構造）
  • matchingStrategy (文字列、オプション)：ファイルごとのマッチング戦略
  • dryRun (ブール値、オプション)：ファイルごとのプレビューモード
  • failOnAmbiguous (ブール値、オプション)：ファイルごとの曖昧さの処理
• failFast (ブール値、オプション)：最初の失敗でロールバックして停止する（true、デフォルト）または続行する（false）

機能：

• 複数ファイル操作のための同時処理
• 失敗時の自動ロールバックを備えたアトミック操作
• クロスプラットフォームの改行コードの保存
• 統計情報を含む詳細な差分出力

出力：統計情報を含む詳細な差分。複数ファイル操作の場合は、各ファイルの結果とアトミック操作のロールバック情報を含む要約統計が含まれます。

重要：oldText/newTextには実際の改行文字を使用し、\n などのエスケープシーケンスを使用しないでください。

ファイルシステム操作

make_directory

単一または複数のディレクトリを作成します（Unixの mkdir -p のように）。

入力：

• paths (文字列 | 配列)：単一のパスまたはパスの配列

出力：成功確認。親ディレクトリを再帰的に作成し、冪等性があります。

list_directory

複数の出力形式でディレクトリの内容をリストします。

入力：

• path (文字列)：ディレクトリパス
• format (文字列、オプション)：出力形式
  • simple - 基本的な [DIR]/[FILE] リスト（デフォルト）
  • detailed - サイズ、タイムスタンプ、および統計情報付き
  • tree - 階層的なテキストツリービュー
  • json - 完全なメタデータを含む構造化データ
• sortBy (文字列、オプション)：ソート順
  • name - アルファベット順（デフォルト）
  • size - 大きい順
• excludePatterns (配列、オプション)：除外するグロブパターン（例：['*.log', 'temp*']）

出力：指定された形式のディレクトリリストとメタデータ。

move_file

ファイルおよびディレクトリを移動または名前変更します。

注：このツールは単一ファイル操作のみに限定されています。推奨：より柔軟性の高い単一およびバッチファイルの移動、コピー、および名前変更操作をサポートする file_operations を代わりに使用してください。

入力：

• source (文字列)：ソースパス
• destination (文字列)：宛先パス

出力：成功確認。

file_operations

大量のファイル操作（移動、コピー、名前変更）を行います。

入力：

• operation (文字列)：操作タイプ
  • move - ファイルを移動する
  • copy - ファイルを複製する
  • rename - ファイルを名前変更する
• files (配列)：ソース - 宛先のペアのリスト
• onConflict (文字列、オプション)：競合解決方法
  • skip - 既存のファイルをスキップする
  • overwrite - 既存のファイルを置き換える
  • error - 競合時に失敗する（デフォルト）

出力：各操作のステータス。操作ごとの最大ファイル数は100です。

delete_files

単一または複数のファイルおよびディレクトリを削除します。

入力：

• paths (配列)：削除するパスのリスト
• recursive (ブール値、オプション)：再帰的削除を有効にする
• force (ブール値、オプション)：読み取り専用ファイルを強制削除する

出力：各削除のステータス。安全のため、デフォルトでは再帰的削除は行われません。

get_file_info

ファイルおよびディレクトリのメタデータを取得します。

入力：

• path (文字列)：ファイルまたはディレクトリのパス

出力：サイズ、タイムスタンプ、パーミッション、およびタイプ情報。

register_directory

新しいディレクトリへのランタイムアクセスを有効にします。

入力：

• path (文字列)：登録するディレクトリパス

出力：成功確認。ディレクトリが操作可能になります。

list_allowed_directories

現在アクセス可能なディレクトリパスを表示します。

入力：なし

出力：すべての許可されたディレクトリのリスト。

検索操作

glob_files

グロブパターンマッチングを使用してファイルを検索します。

入力：

• path (文字列)：検索するディレクトリ
• pattern (文字列)：グロブパターン（例：**/*.ts）
• excludePatterns (配列、オプション)：除外するパターン

出力：一致するファイルパスのリスト。

grep_files

ファイル内のテキストパターンを検索します。

入力：

• pattern (文字列)：検索する正規表現パターン
• path (文字列、オプション)：検索するディレクトリ
• -i (ブール値、オプション)：大文字小文字を区別しない
• -A/-B/-C (数値、オプション)：一致の前/後のコンテキスト行
• type (文字列、オプション)：ファイルタイプフィルター（js、py、tsなど）
• output_mode (文字列、オプション)：出力形式
  • content - 行番号付きの一致する行（デフォルト）
  • files_with_matches - ファイルパスのみ
  • count - ファイルごとの一致数
• head_limit (数値、オプション)：結果の制限

出力：コンテキスト付きの一致する行、ファイルパス、または一致数。

シェル操作

execute_shell

セキュリティコントロールを備えたシェルコマンドを実行します。

入力：

• command (文字列)：実行するシェルコマンド
• description (文字列、オプション)：コマンドの目的
• workdir (文字列、オプション)：作業ディレクトリ（許可されたディレクトリ内である必要があります）。指定されない場合は、process.cwd() が使用され、検証されます。
• timeout (数値、オプション)：タイムアウト（ミリ秒）（デフォルト: 30000）

出力：終了コード、標準出力、標準エラー出力、および実行メタデータ。

セキュリティ：

• シェルコマンドを実行する前に、少なくとも1つの承認されたディレクトリを構成する必要があります。
• 作業ディレクトリ（明示的に指定された場合またはデフォルトのprocess.cwd()）は、常に許可されたディレクトリに対して検証されます。
• コマンド引数内のすべてのファイル/ディレクトリパスは自動的に抽出され、許可されたディレクトリに対して検証されます。
• 承認されたディレクトリ外のパスを参照するコマンドはブロックされ、ディレクトリ制限のバイパスを防止します。

複数ファイル編集の例

複数ファイルにまたがるバッチリファクタリング

{
  files: [
    {
      path: "src/utils.ts",
      edits: [{
        instruction: "Update deprecated function call",
        oldText: "oldApi.getData()",
        newText: "newApi.fetchData()"
      }]
    },
    {
      path: "src/components/Button.tsx",
      edits: [{
        instruction: "Update component prop",
        oldText: "onClick={oldHandler}",
        newText: "onClick={newHandler}"
      }]
    },
    {
      path: "src/hooks/useData.ts",
      edits: [{
        instruction: "Update hook implementation",
        oldText: "const data = oldApi.getData()",
        newText: "const data = newApi.fetchData()"
      }]
    }
  ],
  failFast: true  // Atomic operation - rollback all if any fails
}

ファイルごとの設定

{
  files: [
    {
      path: "config.json",
      edits: [{
        oldText: '"version": "1.0.0"',
        newText: '"version": "1.1.0"'
      }],
      matchingStrategy: "exact"  // JSON needs exact matches
    },
    {
      path: "src/app.py",
      edits: [{
        oldText: "def old_function():",
        newText: "def new_function():"
      }],
      matchingStrategy: "flexible"  // Python indentation may vary
    },
    {
      path: "README.md",
      edits: [{
        oldText: "## Old Section",
        newText: "## New Section"
      }],
      matchingStrategy: "auto"  // Let AI decide best strategy
    }
  ],
  failFast: false  // Continue even if some files fail
}

詳細な使用例については、ツール使用ガイド を参照してください。

🔧 技術詳細

セキュリティ

このMCPサーバーは、一般的なファイルシステムの脆弱性から保護するためのエンタープライズグレードのセキュリティコントロールを実装しています。すべてのセキュリティ対策は業界のベストプラクティスに基づいており、既知のCVEパターンに対応しています。

保護対象

パストラバーサルとディレクトリバイパス (CWE-22)

• 保護パターン：CVE-2025-54794 / CVE-2025-53110
• 緩和策：パス区切り文字の要件を持つ正規パス検証により、接頭辞の衝突攻撃を防止します。
• 実装：isPathWithinAllowedDirectories() を使用し、実際のサブディレクトリパスが必要です（単なる接頭辞の一致ではありません）。
• 例：/path/to/allowed が承認されている場合、/path/to/allowed_evil へのアクセスをブロックします。

コマンドインジェクション (CWE-78)

• 保護パターン：CVE-2025-54795
• 緩和策：コマンド置換検出、ルートコマンド抽出、および危険なパターンマッチングを含む多層検証。
• 実装：$()、` `, >(), <() パターンをブロックし、チェーン内のすべてのコマンドを検証し、危険な操作には承認が必要です。
• 例：echo "; malicious_cmd; echo" のインジェクション試行を防止します。

シェルコマンドのディレクトリバイパス (CWE-22)

• 保護パターン：シェルコマンド内の絶対パスを介したパス制限のバイパス
• 緩和策：コマンド引数内に埋め込まれたすべてのファイル/ディレクトリパスを抽出し、検証します。
• 実装：コマンド文字列からパスを抽出し（Windows/Unixパス、引用符、相対パス、環境変数を処理）、実行前に各パスを許可されたディレクトリに対して検証します。
• 例：これらのパスが承認されたディレクトリ外の場合、type C:\Windows\System32\drivers\etc\hosts および cat /etc/passwd をブロックします。
• 適用範囲：execute_shell ツールを介して実行されるすべてのシェルコマンドに適用されます - 引数内のパスはファイルシステム操作と同じように検証されます。

シンボリックリンク攻撃 (CWE-59 / CWE-61)

• 保護パターン：CVE-2025-53109
• 緩和策：検証前に realpath() を介してすべてのパスを解決し、シンボリックリンクを実際のターゲットにたどります。
• 実装：シンボリックリンクのターゲットは許可されたディレクトリ内にある必要があります。新しいファイルの親ディレクトリを検証します。
• 例：シンボリックリンクが許可されたディレクトリ内にあっても、/etc/passwd を指すシンボリックリンクへのアクセスをブロックします。

ディレクトリトラバーサル

• 緩和策：承認されたディレクトリのみに対する厳格なパス正規化と検証。
• 実装：../ のトラバーサル試行を拒否し、ファイル作成前に親ディレクトリを検証します。
• 例：トラバーサル試行に関係なく、/unauthorized/path へのアクセスをブロックします。

セキュリティコントロール

パス検証

• 正規パス解決：すべてのパスは検証前に正規化および解決されます。
• 区切り文字要件：サブディレクトリはパス区切り文字を含む必要があります（接頭辞の衝突を防止します）。
• 実際のパス解決：シンボリックリンクはアクセスチェック前に実際のターゲットに解決されます。
• 親ディレクトリ検証：新しいファイルの作成時に、親ディレクトリが許可された範囲内にあることを検証します。

コマンド実行

• コマンドホワイトリスト：事前承認されたコマンドのみが確認なしに実行されます。
• パターン検出：危険なパターン（破壊的、特権昇格、ネットワーク実行）をブロックします。
• コマンド置換ブロッキング：$()、バッククォート、プロセス置換を防止します。
• ルートコマンド抽出：チェーン操作内のすべてのコマンドを分析して承認を得ます。
• パス引数検証：コマンド引数内のすべてのファイル/ディレクトリパスを抽出し、許可されたディレクトリに対して検証します（コマンド内の絶対パスを介したバイパスを防止します）。

アクセス制御

• ディレクトリホワイトリスト：操作は明示的に承認されたディレクトリに制限されます。
• ランタイム登録：追加のディレクトリは register_directory ツールを介して明示的に登録する必要があります。
• アトミック検証：ファイル操作が開始される前にパスが検証されます。
• クロスプラットフォームの安全性：Windows/Unixのパスの違いとUNCパスを適切に処理します。

セキュリティのベストプラクティス

1. 承認されたディレクトリを最小限に抑える：AIアクセスが必要なディレクトリのみを承認します。
2. ディレクトリフィルタリングを使用する：機密フォルダ（例：.git、node_modules）をリストから除外します。
3. ツールアクセスを制限する：--enabled-tools または --enabled-tool-categories を介して必要なツールのみを有効にします。
4. コマンド承認：--approved-commands を介して安全なコマンドを事前承認し、他のコマンドには承認を要求します。
5. 操作を監視する：MCPクライアントのログを確認して、予期しないアクセス試行を監視します。
6. 定期的な更新：セキュリティパッチを受け取るためにサーバーを最新の状態に保ちます。

セキュリティ監査

このサーバーは、既知の脆弱性と静的解析の結果に対して包括的に監査されています：

CVE保護状況：

• ✅ CVE-2025-54794 (パス制限バイパス) - 修正済み
• ✅ CVE-2025-54795 (コマンドインジェクション) - 保護済み
• ✅ CVE-2025-53109 (シンボリックリンク攻撃) - 保護済み
• ✅ CVE-2025-53110 (ディレクトリ包含バイパス) - 保護済み
• ✅ シェル実行ディレクトリバイパス - 修正済み (2024年11月)

最新のセキュリティ監査：

• 📋 Snyk脆弱性監査レポート - 2025年11月
  • ステータス：Snykの6つの調査結果のうち5つが誤検出として検証され、1つの調査結果が修正されました。
  • リスクレベル：LOW - 包括的なパストラバーサル保護が検証されました。
  • 静的解析：カスタム検証が認識されないため、Snykの誤検出率は83%でした。
  • テストカバレッジ：2000行以上のセキュリティテストにより、すべての保護対策が検証されました。
• 📋 CVE手動監査 - 2025年11月
  • ステータス：重大な make_directory の脆弱性が特定され、修正されました。
  • 焦点：CVE-2025-54794/54795のパターン分析と緩和策。
  • 日付：2025年11月4日 (手動CVE調査)
• 📋 シェルコマンドディレクトリバイパス監査 - 2025年11月
  • ステータス：✅ 2024年11月に修正されました (遡及的なドキュメント)
  • 問題：以前はシェルコマンドが絶対パスを介して承認されたディレクトリ外のファイルにアクセスできました。
  • 深刻度：HIGH (CVSS ~7.5) - コマンド引数を介したパストラバーサル
  • 修正ステータス：✅ 修正済み - パス抽出と検証が実装されました。
  • テストカバレッジ：419行の包括的なテストがすべて合格しました。
• 📋 セキュリティテストカバレッジの要約
  • テストスイート：src/tests/ に2000行以上のセキュリティに焦点を当てたテストが含まれています。
  • CVEテスト：CVE-2025-54794、CVE-2025-54795、CVE-2025-53109の明示的なテスト。
  • カバレッジ：パストラバーサル、シンボリックリンク (129以上のケース)、コマンドインジェクション、シェルバイパス。

セキュリティアーキテクチャ

• 多層パス検証（正規解決、境界チェック、シンボリックリンク保護）
• アトミック操作と競合状態防止を備えた防御的な設計
• 接頭辞の衝突保護を備えたディレクトリホワイトリスト
• 静的解析ツールのための包括的なセキュリティ注釈

サポートされるファイルタイプ

テキストファイル操作

読み取りツール (read_file, read_multiple_files)：

• テキストファイル：すべてのファイルをUTF-8エンコードのテキストとして読み取ります（ソースコード、設定ファイル、マークダウン、JSON、XML、CSV、ログ）。
• ドキュメントファイル：自動的に検出して解析します：
  • PDF (.pdf) - pdf-parse を介した平文抽出
  • Word (.docx) - mammoth を介した書式付きマークダウン（見出し、太字、リスト、テーブル）
  • PowerPoint (.pptx) - officeparser を介した平文抽出
  • Excel (.xlsx) - officeparser を介した平文抽出
  • OpenDocument Text (.odt) - officeparser を介した平文抽出
  • OpenDocument Presentation (.odp) - officeparser を介した平文抽出
  • OpenDocument Spreadsheet (.ods) - officeparser を介した平文抽出
• read_file はテキストファイルに対して4つのモードをサポートします：
  • full：ファイル全体を読み取ります。
  • head：最初のN行を読み取ります。
  • tail：最後のN行を読み取ります。
  • range：任意の行範囲を読み取ります（例：50 - 100行目、包括的、1インデックス）。
• read_multiple_files はファイルごとのモード指定を許可し、単一の操作で各ファイルが異なるモードを使用できます。
• ドキュメントファイルはモードパラメータを無視し、常に全内容を返します。
• サポートされていないバイナリファイル（画像、実行可能ファイル、圧縮ファイル）に対しては文字化けした出力が生成されます。

書き込みツール (write_file, write_multiple_files, edit_file)：

• UTF-8エンコードのテキスト内容を書き込みます。
• HTMLからPDF/DOCXへの変換をサポートし、リッチな書式設定（見出し、太字、斜体、テーブル、リスト、色）が可能です。
• ソースコード、設定ファイル、マークダウン、JSON、XML、CSV、テキストドキュメント、HTMLからの書式付きPDF/DOCXを作成できます。
• HTMLが検出されない場合、PDF/DOCXには平文が使用されます。
• バイナリファイルを書き込むことはできません（base64からバイナリへの変換は利用できません）。

画像ファイル操作

画像添付ツール (attach_image)：

• AIビジョン分析のために画像を添付します（ビジョン対応のMCPクライアントが必要）。
• サポートされる形式：PNG、JPEG、GIF、WebP、BMP、SVG
• バッチサポート：1回の呼び出しで単一の画像または複数の画像を添付できます。
• 画像はユーザーが直接アップロードしたかのようにAIに提示されます。
• 視覚分析を可能にします：画像内のテキストの読み取り、図の分析、シーンの説明。
• 使用例：
  • デバッグのためのスクリーンショットの分析