项目简介

S3文件系统MCP服务器是一个基于Model Context Protocol (MCP) 构建的后端服务，旨在将Amazon S3存储桶作为虚拟文件系统呈现给大型语言模型（LLM）客户端。它允许LLM通过标准化的JSON-RPC接口，执行S3文件的读取、目录列表、内容搜索等操作，从而为代码代理和AI助手提供丰富的上下文信息。该服务特别适用于LLM需要浏览大型Blob存储或对压缩文件进行代理式搜索的场景。

主要功能点

虚拟文件系统访问: 将S3存储桶挂载为只读的虚拟文件系统，方便LLM进行文件和目录操作。
工具集成: 提供了'read'（读取文件或列出目录）、'glob'（通过模式匹配查找文件）和'grep'（在文件中搜索文本）等工具，LLM可以通过MCP协议调用这些工具。
性能优化: 支持生成S3存储桶的元数据清单（manifest）以加速文件搜索，并包含多层文件缓存机制，动态缓存文件内容和搜索结果，提高响应速度。
压缩文件处理: 支持透明地读取和解压Gzip (.gz) 和Zstandard (.zst/.zstd) 压缩文件。
MCP协议支持: 通过JSON-RPC协议与LLM客户端通信，提供会话管理和能力声明。

安装步骤

克隆仓库: 将项目仓库克隆到本地。

安装依赖: 进入项目目录，使用Bun或npm/yarn安装依赖：

bun install
# 或 npm install
# 或 yarn install

配置AWS凭证: 确保您的AWS凭证已配置在环境变量 ('AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY')、'~/.aws/credentials' 文件中，或通过IAM角色提供给运行环境。

生成S3文件清单 (可选，推荐): 为了加速文件搜索，可以预先生成S3存储桶的元数据清单。

bun run util/generate-s3-manifest.ts <bucket-name> [prefix] [region] [maxFiles]
# 示例：bun run util/generate-s3-manifest.ts my-data-bucket data/ us-east-1

这会在项目根目录下创建一个'.manifest'目录并保存清单文件。

设置环境变量: 启动服务器前，需要设置以下环境变量：
- 'S3_BUCKET': 您的S3存储桶名称（必填）。
- 'S3_REGION': S3存储桶所在的AWS区域（可选，默认为'us-east-1'或'AWS_REGION'）。
- 'S3_PREFIX': S3存储桶中文件路径的前缀（可选，例如'my-data/'）。
- 'PORT': 服务器监听的端口（可选，默认为'7011'）。

服务器配置

MCP客户端需要以下JSON格式的配置信息来连接S3文件系统MCP服务器：

{
  "name": "S3文件系统服务",
  "command": "bun",
  "args": ["run", "src/server.ts"],
  "env": {
    "S3_BUCKET": "your-s3-bucket-name",  // 替换为您的S3桶名称，例如 "my-llm-data"
    "S3_REGION": "us-east-1",             // 替换为您的S3桶区域，例如 "us-west-2"
    "S3_PREFIX": "optional/prefix/"       // 替换为您的S3路径前缀 (可选)，例如 "projects/"
  },
  "transport": {
    "type": "sse",
    "url": "http://localhost:7011/sse"
  },
  "capabilities": {
    "tools": {}
  }
}

'name': 'S3文件系统服务'。
'command': 'bun'。
'args': '["run", "src/server.ts"]'。
'env': 这是一个包含服务器运行所需环境变量的JSON对象。
- 'S3_BUCKET': （必填） 您的S3存储桶名称。
- 'S3_REGION': （可选） S3存储桶所在的AWS区域。如果未指定，将尝试使用'AWS_REGION'环境变量或默认为'us-east-1'。
- 'S3_PREFIX': （可选） S3路径前缀。所有文件操作都将限制在该前缀下。
'transport': 定义客户端与服务器的通信方式。
- 'type': 'sse'（表示使用Server-Sent Events传输协议）。
- 'url': 'http://localhost:7011/sse'（MCP服务器的SSE连接端点，请根据您的实际部署地址和端口进行调整）。
'capabilities': 声明服务器提供的能力，此处表示提供工具能力。

基本使用方法

启动服务器: 在项目根目录，确保您已设置好'S3_BUCKET'等环境变量，然后运行以下命令启动MCP服务器：

bun run src/server.ts
# 或 node --loader ts-node/esm src/server.ts (如果使用Node.js)

服务器将监听配置的端口（默认为7011）。

LLM客户端连接: 您的LLM客户端（如Amp, Claude Code, Codex等支持MCP的Agent）通过上述“服务器配置”信息连接到此MCP服务器。
LLM调用工具: 连接成功后，LLM客户端即可通过MCP协议调用服务器提供的工具来与S3文件系统交互：
- 'read' 工具: 用于读取S3文件内容或列出目录。
  - 示例：LLM调用'read(path="s3://your-bucket/path/to/file.txt")'
  - 示例：LLM调用'read(path="s3://your-bucket/path/to/directory/", read_range=[1, 10])'
- 'glob' 工具: 用于根据glob模式查找S3文件。
  - 示例：LLM调用'glob(filePattern="**/*.json", limit=50)'
- 'grep' 工具: 用于在S3文件中搜索特定文本模式。
  - 示例：LLM调用'grep(pattern="myFunction\(args\)", glob="src/**/*.js", caseSensitive=true)'

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息