fileport

fileport

fileport gives an agent careful, sandboxed access to the local filesystem. It can read and write text, return media as base64, apply exact-match edits, walk directory trees, and search by glob — but only inside the directories you allow. Anything outside those roots is refused, including paths that escape through .. segments or symlinks.

Install

npx @reneturcios/fileport list .

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/fileport

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead.

Allowed directories

The sandbox is the whole point of this tool, so it is configured explicitly:

• fileport mcp /data/docs /data/notes — the arguments after mcp are the allowed roots.
• FILEPORT_ROOTS — a path-delimiter-separated list used when no arguments are given.
• With neither set, the current working directory is the only root.

Every path a tool receives is canonicalised (symlinks resolved; new files resolved through their parent) and checked against the roots before any read or write happens.

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

Exit codes: 0 on success, 1 when an operation fails (for example a path outside the allowed directories), 2 for usage errors. The list and read helpers resolve paths against the working directory.

MCP server

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

MCP client configuration:

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

Tools

Tool	Input	What it returns
read_file	path	The file's full text contents.
read_text_file	path, optional head or tail (line counts, mutually exclusive)	The file text, or just its first/last lines.
read_media_file	path	Base64 image, audio, or blob content chosen by extension.
read_multiple_files	paths	Each file's contents; a failure for one file is reported in-band and does not stop the others.
write_file	path, content	Writes the text, creating parent folders as needed.
edit_file	path, edits (oldText/newText pairs), optional dryRun	Applies each exact-match replacement, or returns a diff-like preview when dryRun is set. Errors if an oldText is not found.
create_directory	path	Creates the directory and any missing parents.
list_directory	path	Entries as [FILE] name / [DIR] name lines.
list_directory_with_sizes	path, optional sortBy (name or size)	Entries with sizes; directories report their recursive total.
directory_tree	path, optional excludePatterns	A nested JSON tree of {name, type, children?} nodes.
move_file	source, destination	Moves or renames within the sandbox.
search_files	path, pattern, optional excludePatterns	Recursive glob search over file names (**, *, ?).
get_file_info	path	Size, created/modified/accessed times, type, and permissions.
list_allowed_directories	—	The roots currently in force.

Development

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

License

MIT — see LICENSE.