mcp-server-cloud-fs

@nogoo9/mcp-server-cloud-fs

mcp-server-filesystem 的云端替代方案——为 S3、Azure Blob 和 GCS 提供 30 种工具。
可通过 STDIO 在本地部署，也可通过 HTTP/WebSocket 远程部署，并使用 OAuth 2.1 进行身份验证。
还可作为 npm 库和交互式 TUI 使用。

📖 阅读完整文档 →

提供商： Amazon S3 · Azure Blob Storage · Google Cloud Storage · MinIO · RustFS · Cloudflare R2 · Backblaze B2 · Wasabi · LocalStack · SQLite · 内存

---

目录

• 功能介绍
• 快速开始
• 交互式 Shell
• 传输方式
• 身份验证与授权
• 生产环境功能
• CLI 参考
• 提供商配置
• MCP 客户端配置
• 工具参考
• 架构：VFS
• 缓存
• 编程式用法
• MCP Inspector
• 开发与测试
• AI Agent 技能
• 文档
• 许可证

---

功能介绍

@nogoo9/mcp-server-cloud-fs 通过云对象存储提供 mcp-server-filesystem 定义的全部 14 个工具——工具名称和参数架构均相同。将它添加到当前指向 mcp-server-filesystem 的任意 MCP 客户端配置中，你的 AI 助手便可读写 S3、Azure Blob Storage 或 Google Cloud Storage 存储桶。

它还包含 5 个扩展工具，灵感来自 claude-code 的文件系统工具集：按行范围读取、按字节范围分块读取、进程内正则搜索（单文件和多文件）、服务端复制，以及可选启用的删除功能。此外还有 6 个云原生工具（预签名 URL、对象元数据/标签、基于标签的搜索、版本历史、版本恢复）、2 个 AI 原生工具（架构提取、文件摘要），以及 1 个宏工具（用于原子差异应用的 patch_file）。

虚拟文件系统（VFS）层提供类似 FUSE 的缓存一致性，并使用 ETag 进行并发控制；shell 工具可让你针对云存储运行类 POSIX 命令（ls、grep、jq、cat | wc 等）；该软件包还可作为程序化 npm 库使用。

v0.7.0 亮点

• 动态缩减工具集：基于作用域过滤工具——客户端只能看到获准使用的工具
• DLP 内容清理：基于正则表达式的中间件会从工具响应中脱敏个人身份信息、API 密钥和凭据（--enable-dlp）
• AI 原生工具：get_file_schema 提取 CSV/JSON 结构；summarize_file 返回精简的开头/结尾预览
• ETag 并发控制：基于 SHA-256 内容寻址的 ETag，在 edit_file 和 patch_file 上通过 expected_etag 检测冲突
• patch_file 宏工具：在单次工具调用中原子地完成读取、差异计算和写入——支持统一差异和行范围替换

v0.6.0 亮点

• 云原生工具：预签名 URL、对象元数据/标签、版本历史、版本恢复
• 按字节范围读取：read_file_chunk 可获取指定字节范围，无需下载整个对象
• 结构化审计日志：带可插拔输出目标（stderr、文件）的工具调用审计记录
• 多提供商路由：MultiProvider 可在单个服务实例中提供 S3、Azure 和 GCS
• Azure 托管标识：使用 DefaultAzureCredential 进行 OIDC 和联合身份验证
• 连接健康检查：启动时验证凭据并报告诊断信息
• MCP 资源：将云存储作为原生 MCP 资源浏览（无需调用工具）
• 结构化错误：使用带类型代码的 CloudError 和特定于提供商的错误映射器

v0.5.0 亮点

• 交互式 TUI（cloud-fs）：支持 cd、Tab 补全和命令历史记录的终端 shell
• 多传输方式：STDIO（默认）、Streamable HTTP 和 WebSocket
• 双运行时：支持 Bun 原生运行时和 Node.js（HTTP 传输 + SQLite 提供商）
• OAuth 2.1：内置身份验证服务，或验证外部 IdP 令牌
• ext-auth 扩展：客户端凭据（M2M）和企业托管授权（SSO）
• 生产环境加固：速率限制、CORS、安全标头、健康检查、结构化日志记录
• AI Agent 技能：可安装的 skills/cloud-fs，适用于 Claude Code、Gemini CLI 和其他 AI 助手

---

快速开始

本地（STDIO——默认）

npx @nogoo9/mcp-server-cloud-fs s3 s3://my-bucket

远程（HTTP）

# Bun (zero Express dependency)
bunx @nogoo9/mcp-server-cloud-fs s3 s3://my-bucket --transport http --port 3000

# Node.js (requires express peer dep)
npx @nogoo9/mcp-server-cloud-fs s3 s3://my-bucket --transport http --port 3000

远程（WebSocket——仅限 Bun）

bunx @nogoo9/mcp-server-cloud-fs s3 s3://my-bucket --transport ws --port 3000

演示（无需云凭据）

bunx @nogoo9/mcp-server-cloud-fs memory mem://demo --enable-shell --seed-demo

---

交互式 Shell（cloud-fs）

进入交互式终端，浏览和管理云存储——无需 MCP 客户端：

# S3
npx -p @nogoo9/mcp-server-cloud-fs cloud-fs s3 s3://my-bucket

# In-memory demo with sample files
npx -p @nogoo9/mcp-server-cloud-fs cloud-fs memory mem://demo --seed-demo

# With a config file (cloud-fs.json in CWD)
npx -p @nogoo9/mcp-server-cloud-fs cloud-fs

功能

• cd 导航 — 使用 cd data、cd ..、cd / 导航，提示符会动态显示当前目录
• Tab 补全 — 根据上下文补全路径和命令
• 命令历史记录 — 在会话间持久保存（~/.cloud-fs_history）
• 相对路径 — 所有命令都相对于 cwd 解析，与真实 Shell 一致
• 19 个内置命令 — ls、cat、head、tail、cp、mv、rm、mkdir、touch、stat、find、grep、wc、du、echo、tee、diff、jq、cd
• 管道和重定向 — cat config.json | jq '.database'、echo hello > file.txt

本地开发

bun src/cli-tui.ts memory mem://demo --seed-demo

---

传输方式

服务支持三种 MCP 传输方式，通过 --transport 选择：

传输方式	标志	运行时	用途
STDIO	--transport stdio（默认）	Bun、Node	本地 npx、Claude Desktop、Claude Code
Streamable HTTP	--transport http	Bun ✅、Node ✅	远程部署、多用户、企业应用
WebSocket	--transport ws	仅 Bun	低延迟双向通信、实时应用

Streamable HTTP

实现了 MCP Streamable HTTP 规范，使用单个 /mcp 端点处理 POST（请求）、GET（SSE 通知）和 DELETE（终止会话）。

双运行时支持：

• Bun：直接使用 WebStandardStreamableHTTPServerTransport 和 Bun.serve()，无需依赖 Express，性能出色。
• Node.js：回退到搭配 Express 的 StreamableHTTPServerTransport。需要将 express 作为可选的对等依赖（npm install express）。

运行时会在启动时自动检测。

会话管理：

会话使用 UUID v7（RFC 9562），按时间排序且支持 K 排序，适用于日志记录、调试和数据库索引。会话通过 Mcp-Session-Id 标头进行跟踪。

可恢复性：

配置 EventStore 后，客户端可以重新连接，并通过 SSE 标头 Last-Event-ID 从中断处继续接收消息。

# Basic HTTP server
cloud-fs-mcp s3 s3://my-bucket --transport http --port 3000

# With authentication
cloud-fs-mcp s3 s3://my-bucket --transport http --port 3000 --auth builtin --auth-issuer https://my-server.example.com

# Production deployment
cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 --host 0.0.0.0 \
  --auth external --auth-jwks-uri https://login.example.com/.well-known/jwks.json \
  --cors-origin https://app.example.com \
  --rate-limit 60 --rate-limit-burst 10 \
  --security-headers \
  --request-logging

WebSocket

基于 Bun 的原生 WebSocket 传输方式，使用 Bun.serve() 处理 WebSocket 升级。对于高频工具调用，其延迟低于 HTTP。

• 通过 WebSocket 进行 JSON-RPC 消息分帧
• 升级时分配 UUID v7 会话 ID
• 使用 WS ping/pong 心跳检测连接状态

cloud-fs-mcp s3 s3://my-bucket --transport ws --port 3000

---

身份验证与授权

身份验证默认禁用，且仅适用于 HTTP/WS 传输方式。STDIO 模式始终无需身份验证。

身份验证模式

模式	标志	说明
none	--auth none（默认）	不进行身份验证。适用于本地或可信网络。
builtin	--auth builtin	可自托管的 OAuth 2.1 授权服务器。MCP 服务同时充当 AS 和 RS。
external	--auth external	根据外部 IdP（Okta、Auth0、Keycloak、Azure AD）验证持有者令牌。

内置 OAuth 服务器（--auth builtin）

服务通过 MCP SDK 的 mcpAuthRouter() 运行完整的 OAuth 2.1 授权服务器：

• 授权码 + PKCE（必需）— 交互式用户同意流程
• 动态客户端注册 — MCP 客户端首次连接时自动注册
• 刷新令牌轮换 — 一次性刷新令牌可防止重放
• 元数据发现 — /.well-known/oauth-authorization-server（RFC 8414）和 /.well-known/oauth-protected-resource（RFC 9728）

cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 \
  --auth builtin --auth-issuer https://my-server.example.com

外部 IdP（--auth external）

服务只验证持有者令牌，不签发令牌。已有身份提供方时可使用此模式。

• JWKS 验证 — 从 IdP 获取并缓存签名密钥
• JWT 验证 — 检查签名、签发者、受众和过期时间
• 令牌内省 — 为不透明令牌提供回退验证

cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 \
  --auth external \
  --auth-jwks-uri https://login.example.com/.well-known/jwks.json \
  --auth-audience https://cloud-fs.example.com

ext-auth：客户端凭据（M2M）

实现 MCP 客户端凭据扩展，无需用户交互即可进行机器间身份验证。专为 CI/CD 流水线、后台服务和自动化工作流设计。

• JWT 断言身份验证（RFC 7523 中的 private_key_jwt）——推荐
• 客户端密钥身份验证（client_secret_basic）——更简单，但安全性较低
• 无需用户交互——根据预先注册的客户端凭据授予令牌

cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 \
  --auth builtin --auth-issuer https://my-server.example.com \
  --auth-client-credentials

ext-auth：企业托管授权（SSO）

实现 MCP 企业托管授权扩展，通过组织的身份提供商实现无缝 SSO。

工作原理：

1. 用户通过企业 IdP（OpenID Connect 或 SAML）登录 MCP 客户端
2. 客户端通过令牌交换（RFC 8693）将 ID Token 换成身份断言 JWT 授权授予（ID-JAG）
3. 客户端向此服务的授权服务器（RFC 7523）出示 ID-JAG
4. 服务验证 ID-JAG 并签发访问令牌

优势：

• 无需针对每个 MCP 服务手动授权——SSO 会处理一切
• 企业管理员可以控制哪些用户/群组能够访问哪些 MCP 服务
• 通过 IdP 策略实施细粒度的范围控制

cloud-fs-mcp s3 s3://my-bucket \
  --transport http --port 3000 \
  --auth builtin --auth-issuer https://my-server.example.com \
  --auth-enterprise-idp https://acme.okta.com

OAuth 范围

启用身份验证后，工具访问由细粒度范围控制：

范围	工具
cloud-fs:read	read_file、read_text_file、read_media_file、read_multiple_files、read_file_range、read_file_chunk、get_presigned_url、get_object_metadata、list_versions、get_file_schema、summarize_file
cloud-fs:write	write_file、edit_file、create_directory、set_object_tags、restore_version、patch_file
cloud-fs:delete	delete_file
cloud-fs:search	search_files、grep_file、grep_files、list_directory、list_directory_with_sizes、directory_tree、search_by_tag
cloud-fs:shell	shell
cloud-fs:admin	所有工具 + get_file_info、list_allowed_directories

设置 grantedScopes（通过 OAuth 令牌）后，授予范围之外的工具将不会注册——它们根本不会出现在 tools/list 中，从而减少 LLM 提示词的令牌浪费，并防止工具幻觉。

范围不足的令牌会收到清晰的错误响应，指出所需的范围。

---

生产环境功能

健康检查

HTTP/WS 传输会公开符合 Kubernetes 惯例的健康检查端点：

端点	用途	成功	失败
/healthz	存活状态——进程是否正在运行？	始终为 200 OK	进程已停止
/readyz	就绪状态——能否处理流量？	VFS 初始化完成后为 200 OK	启动期间为 503

配置编排器的存活和就绪探针以使用这些端点。

速率限制

令牌桶速率限制可防止滥用。默认禁用。

• 内存——适用于单进程部署的按 IP/客户端计数器
• Redis——适用于多实例部署的分布式速率限制（使用现有的可选对等依赖 ioredis）
• 超出限制时返回带有 Retry-After 标头的 429 Too Many Requests

# 60 requests/minute with burst of 10
cloud-fs-mcp s3 s3://my-bucket --transport http \
  --rate-limit 60 --rate-limit-burst 10

CORS

为基于浏览器的 MCP 客户端提供跨域资源共享：

• 严格的来源允许列表——生产环境中不使用通配符
• 暴露 Mcp-Session-Id 和 Mcp-Protocol-Version 标头
• 使用 --host 127.0.0.1 时，localhost 会自动允许 *（方便开发）

cloud-fs-mcp s3 s3://my-bucket --transport http \
  --cors-origin https://app.example.com \
  --cors-origin https://staging.example.com

结构化请求日志

将 JSON 审计记录输出到 stderr，以满足合规和调试需求：

{"ts":"2026-05-12T12:00:00Z","sessionId":"019...","tool":"read_file","user":"[email protected]","latencyMs":42,"status":200}

使用 --request-logging 启用。

DNS 重绑定防护

绑定到 localhost 地址时会自动启用。验证 Host 标头是否与允许的主机名匹配，以防止 DNS 重绑定攻击。

安全标头

通过 nosecone 启用 HTTP 响应加固——这是一个与框架无关的安全标头库。兼容 Bun 原生传输和 Node/Express 传输。

启用后，每个 HTTP 响应都会包含标准安全标头：

• Content-Security-Policy
• Strict-Transport-Security
• X-Content-Type-Options: nosniff
• X-Frame-Options
• Cross-Origin-Opener-Policy
• Cross-Origin-Resource-Policy
• Referrer-Policy
• 等等（参见 nosecone 默认配置）

# Enable with defaults
cloud-fs-mcp s3 s3://my-bucket --transport http --security-headers

# Custom configuration via inline JSON
cloud-fs-mcp s3 s3://my-bucket --transport http \
  --security-headers-config '{"contentSecurityPolicy":false}'

# Custom configuration via file
cloud-fs-mcp s3 s3://my-bucket --transport http \
  --security-headers-config-file ./nosecone.json

注意： 需要 nosecone 同级依赖：npm install nosecone

---

CLI 参考

cloud-fs-mcp <provider> <root-uri> [root-uri...] [options]

提供方

提供方	URI 格式	说明
s3	s3://bucket[/prefix]	AWS S3，以及任何兼容 S3 的端点（MinIO、RustFS、Cloudflare R2、Backblaze B2、Wasabi、LocalStack，……）
azure	az://container[/prefix]	Azure Blob Storage
gcs	gs://bucket[/prefix]	Google Cloud Storage
memory	mem://name	内存存储（临时，用于演示）
sqlite	sqlite://name	SQLite（本地持久化）

选项

传输与网络

标志	默认值	说明
--transport <stdio|http|ws>	stdio	传输协议
--port <number>	3000	监听端口（仅限 http/ws）
--host <address>	127.0.0.1	绑定地址（仅限 http/ws）

身份验证

标志	默认值	说明
--auth <none|builtin|external>	none	身份验证模式（仅限 http/ws）
--auth-issuer <url>	—	OAuth 颁发者 URL（builtin 模式）
--auth-jwks-uri <url>	—	JWKS URI（external 模式）
--auth-audience <string>	—	预期的令牌受众（external 模式）
--auth-client-credentials	false	启用客户端凭据 ext-auth 流程
--auth-enterprise-idp <url>	—	启用企业托管授权

生产环境

标志	默认值	说明
--cors-origin <origin>	—	允许的 CORS 来源（可重复指定）
--rate-limit <req/min>	0（关闭）	每个客户端的速率限制
--rate-limit-burst <n>	10	突发请求额度
--request-logging	false	启用结构化 JSON 请求日志
--audit-log	false	启用工具调用审计日志并输出到 stderr
--audit-log-file <path>	—	将审计日志写入文件（隐含启用 --audit-log）
--security-headers	false	通过 nosecone 启用安全标头
--security-headers-config <json>	—	nosecone 的内联 JSON 配置
--security-headers-config-file <path>	—	从 JSON 文件加载 nosecone 配置

存储与缓存

标志	默认值	说明
--region <region>	—	云区域（S3、GCS）
--endpoint <url>	—	兼容 S3 的后端自定义端点
--cache-store <memory|fs|redis>	memory	缓存后端
--cache-ttl <seconds>	60	缓存 TTL（秒）
--sync-debounce <ms>	2000	写入刷新延迟（毫秒）
--cache-dir <path>	—	fs 缓存存储目录
--no-cache	—	完全绕过缓存（直通模式）
--gcs-endpoint <url>	—	GCS 自定义端点
--sqlite-db <path>	—	SQLite 数据库文件路径
--ca-file <path>	—	TLS 的 PEM CA 证书包（兼容 S3 的服务和 Redis）

工具

标志	默认值	说明
--enable-delete	false	启用 delete_file 工具
--enable-shell	false	启用 shell 工具
--enable-dlp	false	启用 DLP 内容清理（从响应中隐藏 PII/机密信息）
--grep-max-objects <n>	1000	每次调用中 grep_files 扫描的最大对象数
--seed-demo	false	使用示例文件为 VFS 填充演示数据

凭据始终来自 SDK 凭据链，绝不通过 CLI 标志传入。

---

提供方配置

AWS S3

凭据从标准 AWS 凭据链读取：AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY 环境变量、~/.aws/credentials、EC2 实例配置文件等。

cloud-fs-mcp s3 s3://my-bucket --region us-east-1

S3 兼容存储

任何兼容 S3 的后端都可以通过 --endpoint 使用。它们都使用标准 AWS 凭据链（AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY）。

提供商	--endpoint 值	说明
MinIO	http://minio:9000	可自托管；使用 --ca-file 配置由私有 CA 签发的 TLS 证书
RustFS	http://rustfs:9000	基于 Rust 的 S3 兼容存储
LocalStack	http://localhost:4566	用于本地开发和 CI 的完整 AWS 模拟器
Cloudflare R2	https://<account-id>.r2.cloudflarestorage.com	无出口流量费用；使用 R2 API 令牌作为密钥
Backblaze B2	https://s3.<region>.backblazeb2.com	使用 B2 应用密钥 ID / 密钥
Wasabi	https://s3.<region>.wasabisys.com	兼容 S3，无出口流量费用
DigitalOcean Spaces	https://<region>.digitaloceanspaces.com	使用 Spaces 访问密钥
Scaleway	https://s3.<region>.scw.cloud	使用 Scaleway 访问密钥
Ceph RGW	http://<rgw-host>:<port>	企业级可自托管服务；支持所有 S3 API
SeaweedFS	http://<master>:8333	支持 S3 API 的高吞吐量分布式文件系统
Garage	http://<node>:3900	适用于家庭实验室的轻量级分布式 S3

# MinIO
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
cloud-fs-mcp s3 s3://my-bucket --endpoint http://minio:9000

# Cloudflare R2
export AWS_ACCESS_KEY_ID=<r2-access-key-id>
export AWS_SECRET_ACCESS_KEY=<r2-secret-access-key>
cloud-fs-mcp s3 s3://my-bucket --endpoint https://<account-id>.r2.cloudflarestorage.com --region auto

# Backblaze B2
export AWS_ACCESS_KEY_ID=<b2-key-id>
export AWS_SECRET_ACCESS_KEY=<b2-application-key>
cloud-fs-mcp s3 s3://my-bucket --endpoint https://s3.us-west-004.backblazeb2.com --region us-west-004

# LocalStack
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
cloud-fs-mcp s3 s3://my-bucket --endpoint http://localhost:4566 --region us-east-1

使用私有 CA 的 TLS： 对于使用自签名证书的 MinIO、RustFS 或 Ceph，请添加 --ca-file /path/to/ca.pem。

Azure Blob Storage

使用 DefaultAzureCredential，支持 AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET 环境变量、托管身份、az login 等方式。

cloud-fs-mcp azure az://my-container

Google Cloud Storage

使用应用默认凭据（ADC）。设置 GOOGLE_APPLICATION_CREDENTIALS，或运行 gcloud auth application-default login。

cloud-fs-mcp gcs gs://my-bucket

内存存储（临时）

零配置、零依赖的提供商。所有数据都存放在 Map 中，并会在进程退出时丢失。

cloud-fs-mcp memory mem://demo --enable-shell

SQLite（本地持久化）

使用 WAL 模式的本地持久化存储。支持双运行时：在 Bun 上使用 bun:sqlite，在 Node.js 上使用 better-sqlite3（作为对等依赖安装：npm install better-sqlite3）。

cloud-fs-mcp sqlite sqlite://my-bucket --sqlite-db /tmp/cloud-fs.db --enable-shell

---

MCP 客户端配置

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "cloud-fs": {
      "command": "npx",
      "args": ["-y", "@nogoo9/mcp-server-cloud-fs", "s3", "s3://my-bucket"]
    }
  }
}

Claude Code

项目根目录中的 .mcp.json：

{
  "mcpServers": {
    "cloud-fs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@nogoo9/mcp-server-cloud-fs", "s3", "s3://my-bucket"]
    }
  }
}

远程 HTTP 客户端

{
  "mcpServers": {
    "cloud-fs": {
      "type": "streamable-http",
      "url": "https://cloud-fs.example.com/mcp"
    }
  }
}

---

工具参考

所有路径都是云 URI，例如 s3://my-bucket/path/to/file.txt。服务会在启动时根据配置的根 URI 验证每个路径；不在允许范围内的请求会被拒绝。

读取工具

工具	参数	描述
read_file	path	读取文件。二进制内容 → base64；文本内容 → UTF-8。
read_text_file	path、head?、tail?	读取文本文件，可选限制开头和结尾的行数。
read_media_file	path	将图像/媒体读取为 base64 编码的 MCP 图像内容块。
read_multiple_files	paths	并行读取多个文件。
read_file_range ✨	path、offset、limit	读取从 1 开始计数的行范围，并在头部显示总行数。
read_file_chunk ✨	path、start_byte、end_byte?、encoding?	读取字节范围，无需下载整个文件。最大 10MB。

写入工具

工具	参数	描述
write_file	path、content	写入/覆盖文件。防抖时间窗口结束后刷新。
edit_file	path、edits[]、dryRun?、expected_etag?	应用 { oldText, newText } 编辑。使用 dryRun 预览。可选启用 ETag 冲突检测。

目录工具

工具	参数	描述
create_directory	path	创建目录占位符和父级路径前缀。
list_directory	path	列出直接子项（类似 ls）。
list_directory_with_sizes	path、sortBy?、limit?	列出子项及其大小。按大小或名称排序。
directory_tree	path、excludePatterns?	递归列出目录树，支持 glob 排除模式。

移动、复制和删除工具

工具	参数	描述
move_file	source、destination	移动文件。同一存储桶内通过服务端复制和删除实现。
copy_file ✨	source、destination	复制文件。同一存储桶内通过服务端复制实现。
delete_file ✨	path	删除文件。需要 --enable-delete。

搜索工具

工具	参数	描述
search_files	path、pattern、excludePatterns?	基于 glob 搜索对象键。
grep_file ✨	path、pattern、case_insensitive?	在单个文件中进行正则搜索，并显示行号。
grep_files ✨	path、pattern、glob?、case_insensitive?、output_mode?、max_objects?	在指定路径下的所有对象中进行正则搜索。

信息工具

工具	参数	描述
get_file_info	path	文件元数据：大小、上次修改时间、内容类型。
list_allowed_directories	(none)	列出已配置的根 URI。

✨ = 扩展工具

云原生工具 ☁️

工具	参数	描述
get_presigned_url ☁️	path、operation?、expires_in?	生成临时访问 URL（默认：GET，有效期 1 小时）。
get_object_metadata ☁️	path	大小、内容类型、上次修改时间、自定义元数据和标签。
set_object_tags ☁️	path、tags	使用键值对替换对象标签。
search_by_tag ☁️	path、tags、recursive?	查找符合标签筛选条件的对象（AND 逻辑）。
list_versions ☁️	path、max_results?、page_token?	列出版本历史，包含时间戳、大小和标记。
restore_version ☁️	path、version_id	恢复对象的先前版本（覆盖当前版本）。

☁️ = 云原生工具（需要提供商支持）

AI 原生工具 🧠

工具	参数	描述
get_file_schema 🧠	path	提取结构架构：CSV 列名、类型和示例，JSON 结构，或文本行数和字节数。
summarize_file 🧠	path、max_lines?	提供精简的文件头尾预览，包含文件大小、行数和内容类型。

🧠 = AI 原生工具（减少大模型上下文令牌的浪费）

宏工具 🩹

工具	参数	描述
patch_file 🩹	path、patch、format?、expected_etag?	在一次工具调用中，以原子方式应用统一差异或行范围替换。

🩹 = 宏工具（组合读取、转换和写入）

Shell 工具 ⚡

工具	参数	描述
shell ⚡	command	执行类 POSIX 命令。支持管道和重定向。需要 --enable-shell。

内置命令： ls、cat、head、tail、cp、mv、rm、mkdir、touch、stat、find、grep、wc、du、echo、tee、diff、jq、cd

相对路径

所有 shell 命令（以及所有其他工具）都支持相对路径——无需每次都输入完整 URI。不带方案前缀（s3://、mem:// 等）的路径会相对于第一个已配置的根路径解析：

# With root s3://my-bucket/data, these are equivalent:
shell "cat config.json"
shell "cat s3://my-bucket/data/config.json"

# Subdirectories work naturally:
shell "ls logs/"
shell "cat logs/app.log | grep ERROR"

# ls with no args lists the root's contents:
shell "ls"

# find with no args searches from the root:
shell "find -name '*.json'"

标准的 . 和 .. 会被规范化；为确保安全，路径在根路径边界处会阻止通过 .. 向上遍历。

示例

# List root contents
shell "ls -l"

# JSON query with jq
shell "cat config.json | jq '.database.port'"

# Search and count
shell "grep -i error server.log | wc -l"

# Write files
shell "echo hello world > greeting.txt"

# Copy and diff
shell "cp config.json config.backup.json"
shell "diff config.json config.backup.json"

# Full URIs still work for cross-root access
shell "cat s3://other-bucket/file.txt"

⚡ 需要 --enable-shell。rm 和 mv 还需要 --enable-delete。

---

架构：虚拟文件系统（VFS）

所有工具操作都通过一个受 FUSE 启发的**虚拟文件系统（VFS）**层进行处理。

┌─────────────────────────────────────────────────────────┐
│  MCP Tool Handlers (read, write, list, stat, …)         │
├─────────────────────────────────────────────────────────┤
│  VirtualFS                                              │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐              │
│  │  Inodes   │ │ DirIndex  │ │ Tombstones│              │
│  │ (metadata)│ │ (parents) │ │ (deleted) │              │
│  └─────┬─────┘ └─────┬─────┘ └─────┬─────┘              │
│        └──────────────┴─────────────┘                   │
│         ⇣ Overlay (in-memory, persisted to CacheStore)  │
├─────────────────────────────────────────────────────────┤
│  CacheStore (Memory / Filesystem / Redis)               │
├─────────────────────────────────────────────────────────┤
│  StorageProvider (S3 / Azure Blob / GCS / Memory / SQL) │
└─────────────────────────────────────────────────────────┘

操作	解析方式
get()	缓存命中 → 返回。已标记删除 → 抛出异常。否则 → 回退到提供程序。
stat()	Inode 覆盖层 → 缓存内容大小 → 提供程序 headObject。
list()	提供程序列表 – 已标记删除项 + 覆盖层 dirIndex 条目。
put()	设置缓存 + 标记为脏 + 更新 inode + dirIndex。立即可见。
remove()	提供程序 deleteObject + 清除缓存 + 标记删除。立即不可见。

VFS 元数据会持久化到 CacheStore 的 __vfs__/* 键中。启动时，VirtualFS.hydrate() 会恢复状态；损坏的数据会被静默丢弃。

---

缓存

后端	标志	说明
内存（默认）	--cache-store memory	进程内、速度快、不共享、不持久化。
文件系统	--cache-store fs --cache-dir <path>	重启后仍然保留。
Redis	--cache-store redis	共享、持久化。需要 ioredis 对等依赖。使用 REDIS_URL 环境变量。TLS 请使用 rediss://。

写入会立即进入缓存（并标记为脏），在防抖等待时间后刷新（默认：2s）。正常关闭时会在退出前刷新所有脏条目。直通模式（--no-cache）会将每项操作直接发送给提供程序。

⚠️ Redis TLS： 当 REDIS_URL 使用未加密的 redis:// 时，服务会在启动时发出警告。生产环境中请使用 rediss:// 建立 TLS 加密连接。

自定义 CA 证书

对于使用私有 CA 的 S3 兼容端点（MinIO、RustFS）和 Redis，可使用 --ca-file <path> 提供 PEM CA 证书包：

# S3-compatible with self-signed CA
cloud-fs-mcp s3 s3://my-bucket \
  --endpoint https://minio.internal:9000 \
  --ca-file /etc/ssl/certs/my-ca.pem

# Redis with private CA
REDIS_URL=rediss://redis.internal:6380 \
cloud-fs-mcp s3 s3://my-bucket --cache-store redis \
  --ca-file /etc/ssl/certs/my-ca.pem

若要为整个运行时设置信任 CA（所有提供程序 + Redis），请改用标准的 NODE_EXTRA_CA_CERTS 环境变量：

NODE_EXTRA_CA_CERTS=/etc/ssl/certs/my-ca.pem cloud-fs-mcp s3 s3://my-bucket

---

编程式用法（npm 库）

import {
  createMcpServer, VirtualFS, MemoryStore,
  S3Provider, parseUri,
} from "@nogoo9/mcp-server-cloud-fs";

const roots    = [parseUri("s3://my-bucket")];
const provider = new S3Provider({ region: "us-east-1" });
const cache    = new MemoryStore(provider, { ttlMs: 60_000, syncDebounceMs: 2000 });
const vfs      = new VirtualFS(provider, cache);
await vfs.hydrate();

const server = createMcpServer({ vfs, roots });

导出的 API

导出项	说明
createMcpServer(ctx)	创建已配置的 MCP 服务实例
executeShell(command, ctx)	对 VFS 运行类 POSIX 命令
VirtualFS	受 FUSE 启发的写回覆盖层
MemoryStore、FilesystemStore、createRedisStore、PassThroughCache	缓存后端
S3Provider、AzureProvider、GcsProvider、MemoryProvider、SqliteProvider、MultiProvider	存储提供程序
CloudError、CloudErrorCode	结构化的云服务错误处理
checkHealth、formatHealthReport	连接健康检查工具
AuditLogger、StderrAuditSink、FileAuditSink	工具调用审计日志记录
parseUri、toCacheKey、resolveToolPath	路径工具
ShellContext、ShellCommandHandler	Shell 扩展类型

---

MCP Inspector

# Quick demo (no credentials needed)
bun run inspect:memory

# Custom configuration
bun run inspect -- s3 s3://my-bucket --region us-east-1 --enable-shell

---

MCP 应用：交互式 Shell（xterm.js）

构建应用：bun run build:app → 输出 dist/app/shell-app.html。

Catppuccin Mocha 主题、命令历史记录、自动调整大小。通过 MCP Apps 扩展在兼容的 MCP 宿主（Claude Desktop）中渲染。

---

开发与测试

完整的设置说明请参阅 CONTRIBUTING.md。

克隆后需单独安装 AI Agent 技能：bun x skills add semgrep/skills — 详情请参阅 CONTRIBUTING.md。

测试层级

层级	命令	需要基础设施？
单元测试	bun run test	否
端到端测试（HTTP）	bun run test:e2e:http	否
端到端测试（基础设施）	bun run test:e2e:infra	Docker
集成测试	bun run test:integration	Docker
全部	bun run test:all	Docker

CI 流水线

CI 工作流在每次推送/PR 时运行：

1. ci 作业：lint → 类型检查 → 单元测试（含覆盖率）→ HTTP 端到端测试 → 构建
2. e2e 作业：使用 Docker Compose 运行完整端到端测试（MinIO、Redis）

HTTP 端到端测试使用内存提供程序，无需任何基础设施，因此每次 CI 运行都快速可靠。

---

AI Agent 技能

skills/cloud-fs 目录包含一个可安装的 AI Agent 技能，可教会编码助手（Claude Code、Gemini CLI 等）如何将 cloud-fs 用作类似 POSIX 的虚拟文件系统。安装后，助手便能熟练使用云存储命令。

提供的功能

• 自动检测 MCP 模式 — 识别 mcp__cloud-fs__* 工具，并将用户意图映射到合适的工具调用
• 初始化流程 — 当 MCP 服务尚未配置时，引导用户完成首次设置
• POSIX 到 MCP 的映射 — 将 Shell 命令（ls、cat、grep、find、cp 等）转换为正确的 MCP 工具调用
• 提供商凭据参考 — AWS、Azure、GCS、MinIO/RustFS、SQLite 的设置指南
• .mcp.json 持久化 — 提议保存提供商配置，以便为后续会话预先完成配置

安装

# Claude Code
claude mcp add-skill nogoo9/mcp-server-cloud-fs

# skills.sh
npx skills add nogoo9/mcp-server-cloud-fs

# or with bun instead
bun x skills add nogoo9/mcp-server-cloud-fs

详情请参阅 CONTRIBUTING.md 中关于技能系统的说明。

---

文档

完整文档请访问 nogoo9.github.io/mcp-server-cloud-fs。

• 📖 每个版本均有对应的版本化文档（v0.4.0+）
• 🔄 为开放的拉取请求提供预览文档
• 🔍 全文搜索、深色模式、响应式设计
• 使用 VitePress 构建

在本地运行文档网站：

bun run docs:dev      # start dev server at http://localhost:5173
bun run docs:build    # build static site
bun run docs:preview  # preview production build

---

许可证

PolyForm Shield 1.0.0。可免费用于任何非竞争性用途。

---

使用 构建