fileport

fileport

fileport を使うと、エージェントはローカルファイルシステムに慎重かつサンドボックス化された形でアクセスできます。テキストの読み書き、メディアの Base64 形式での返却、完全一致による編集、ディレクトリツリーの走査、glob による検索が可能です。ただし、許可したディレクトリ内に限られます。.. セグメントやシンボリックリンクを経由して許可されたルートの外に出るパスも含め、範囲外へのアクセスはすべて拒否されます。

インストール

npx @reneturcios/fileport list .

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/fileport

コンテナはデフォルトで MCP サーバーとして動作します。CLI として使うには、CLI 引数を渡します。

許可するディレクトリ

このツールの要であるサンドボックスは、明示的に設定します。

• fileport mcp /data/docs /data/notes — mcp の後に指定した引数が、許可するルートです。
• FILEPORT_ROOTS — 引数が指定されていない場合に使用される、パス区切り文字で区切られたパスのリストです。
• どちらも設定されていない場合は、現在の作業ディレクトリのみがルートになります。

ツールが受け取るすべてのパスは、読み書きの前に正規化（シンボリックリンクを解決し、新規ファイルは親ディレクトリを通して解決）され、ルート内にあるか確認されます。

CLI

fileport list <path>     # entries as [FILE] / [DIR] lines
fileport read <path>     # print a file's text contents
fileport mcp [dirs...]   # start the stdio MCP server
fileport --version

終了コード：成功時は 0、操作に失敗した場合（許可されたディレクトリの外にあるパスなど）は 1、使用方法に誤りがある場合は 2 です。list と read のヘルパーは、作業ディレクトリを基準にパスを解決します。

MCP サーバー

npx -y @reneturcios/fileport mcp /path/to/allowed/dir

MCP クライアントの設定：

{
  "mcpServers": {
    "fileport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/fileport", "mcp", "/path/to/allowed/dir"]
    }
  }
}

ツール

ツール	入力	返される内容
read_file	path	ファイルのテキスト全体。
read_text_file	path、任意の head または tail（行数。相互に排他的）	ファイルのテキスト、または先頭／末尾の行のみ。
read_media_file	path	拡張子に応じて選択された、画像、音声、またはバイナリデータの Base64 形式の内容。
read_multiple_files	paths	各ファイルの内容。いずれかのファイルで失敗した場合、その内容は結果内で報告され、ほかのファイルの処理は続行されます。
write_file	path、content	必要に応じて親フォルダーを作成し、テキストを書き込みます。
edit_file	path、edits（oldText／newText のペア）、任意の dryRun	完全一致する置換をそれぞれ適用します。dryRun が設定されている場合は、差分形式のプレビューを返します。oldText が見つからない場合はエラーになります。
create_directory	path	ディレクトリと、存在しない親ディレクトリを作成します。
list_directory	path	[FILE] name ／ [DIR] name の行でエントリーを返します。
list_directory_with_sizes	path、任意の sortBy（name または size）	サイズ付きのエントリーを返します。ディレクトリには再帰的な合計サイズを表示します。
directory_tree	path、任意の excludePatterns	{name, type, children?} ノードからなる入れ子の JSON ツリー。
move_file	source、destination	サンドボックス内でファイルを移動または名前変更します。
search_files	path、pattern、任意の excludePatterns	ファイル名に対する再帰的な glob 検索（**、*、?）。
get_file_info	path	サイズ、作成日時／更新日時／アクセス日時、種類、権限。
list_allowed_directories	—	現在有効なルート。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。