fileport

Name: fileport
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords文件与存储01 天前更新

代码仓库

关于 fileport

fileport 是为 Agent 提供本地文件沙箱访问的 MCP 服务和命令行工具。文件操作仅限明确允许的目录，并会阻止通过上级路径或符号链接越界。

主要功能

01读取和写入文本文件
02以 Base64 返回媒体内容
03应用精确匹配编辑
04列出并搜索目录内容
05将操作限制在允许的根目录

适用场景

01让 Agent 操作获准目录中的文件
02按 glob 模式搜索项目文件
03预览精确文本替换

MCP 相关

其 stdio MCP 服务提供读取、写入、编辑、列出、搜索和移动文件，以及目录和文件信息工具。所有路径都会根据配置的允许根目录进行检查。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-fileport": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/fileport"
      ]
    }
  }
}

启动命令npx -y @reneturcios/fileport

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/fileport0.1.0stdio

ocighcr.io/cloudcorprecords/fileport:0.1.0stdio

工具

收录的工具列表 · 更新于 1 天前

参数	类型	必填	说明
path	string	是	要读取的文件路径，必须位于允许的目录之一中。

详细介绍

fileport

fileport 为 Agent 提供谨慎且受沙箱限制的本地文件系统访问权限。它可以读取和写入文本、以 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