S3 YAML MCP Server

S3 YAML MCP 服务

一个可连接到 AWS S3 的模型上下文协议（MCP）服务，用于访问包含 Swagger/OpenAPI 文档的 YAML 文件。专为与 VS Code 和 GitHub Copilot 无缝集成而设计。

🎯 什么是 MCP？

模型上下文协议（MCP）是一种开放协议，用于标准化应用程序向大语言模型（LLM）提供上下文的方式。它使 AI 助手能够安全地访问数据源和工具。

✨ 功能

• 🔗 S3 集成：连接到任意兼容 S3 的存储服务
• 📁 YAML 文件发现：自动列出并发现 YAML/YML 文件
• 📖 内容访问：读取 YAML 内容并提供给 AI 助手
• 🔍 高级搜索：搜索文件和特定 API 端点的详细信息
• 🚀 VS Code 原生集成：内置与 VS Code 和 GitHub Copilot 的集成
• 🔒 安全认证：使用 AWS CLI 凭证或 IAM 角色

🚀 安装

方法 1：一键安装（推荐）

curl -fsSL https://raw.githubusercontent.com/ander-castiblanco-stori/s3-mcp-server/main/install.sh | bash

此操作将：

• 下载适用于你平台的最新二进制文件
• 将其安装到 /usr/local/bin
• 设置 VS Code 配置文件

方法 2：使用 Go 安装

go install github.com/ander-castiblanco-stori/s3-mcp-server@latest

方法 3：下载二进制文件

访问发布页面，下载适用于你平台的二进制文件。

方法 4：Docker

docker pull ghcr.io/ander-castiblanco-stori/s3-mcp-server:latest

🐳 Docker 用法

使用 Docker 快速开始

# Pull from GitHub Container Registry
docker pull ghcr.io/ander-castiblanco-stori/s3-mcp-server:latest

# Run with environment variables
docker run -it --rm \
  -e S3_BUCKET=your-bucket \
  -e S3_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID=your-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret \
  ghcr.io/ander-castiblanco-stori/s3-mcp-server:latest

使用 Docker Compose

# In your project's docker-compose.yml
version: "3.8"

services:
  s3-mcp-server:
    image: ghcr.io/ander-castiblanco-stori/s3-mcp-server:latest
    environment:
      - S3_BUCKET=your-api-docs-bucket
      - S3_REGION=us-east-1
    volumes:
      - ~/.aws:/home/mcp/.aws:ro
    stdin_open: true
    tty: true

使用 Docker 集成 VS Code

// .vscode/mcp.json
{
  "mcpServers": {
    "s3YamlDocs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "S3_BUCKET=${input:s3-bucket}",
        "-e",
        "S3_REGION=${input:aws-region}",
        "-v",
        "${env:HOME}/.aws:/home/mcp/.aws:ro",
        "ghcr.io/ander-castiblanco-stori/s3-mcp-server:latest"
      ]
    }
  }
}

在本地构建 Docker 镜像

# Using Makefile
make docker-build          # Build local image
make docker-test           # Test the image
make docker-push           # Build and push to GHCR

# Using script
./docker-build.sh          # Interactive build and push

# Manual commands
docker build --build-arg VERSION=v1.0.0 -t s3-mcp-server:v1.0.0 .
docker run --rm s3-mcp-server:v1.0.0 ./s3-mcp-server --version

🚀 快速开始

前置条件

• 已配置 AWS 凭证（通过 AWS CLI、IAM 角色或环境变量）
• 包含 YAML 文件的 S3 存储桶
• 安装了 GitHub Copilot 扩展的 VS Code

设置

1. 安装服务（从上述方法中选择一种）

2. 配置环境：

# In your project directory, create configuration
cat > .env << 'EOF'
S3_BUCKET=your-api-docs-bucket
S3_REGION=us-east-1
EOF

3. 设置 VS Code（如果安装程序尚未完成此操作）：

# Create VS Code MCP configuration
mkdir -p .vscode
cat > .vscode/mcp.json << 'EOF'
{
  "mcpServers": {
    "s3YamlDocs": {
      "command": "s3-mcp-server",
      "args": [],
      "env": {
        "S3_BUCKET": "your-bucket-name",
        "S3_REGION": "us-east-1"
      }
    }
  }
}
EOF

4. 测试连接：

./test-vscode-integration.sh

4. 在 VS Code 中打开：

code .

5. 开始使用 GitHub Copilot：
   • 打开 GitHub Copilot Chat（macOS 上按 Cmd+Shift+I）
   • 输入：@s3YamlDocs list all YAML files in my bucket

🛠️ MCP 功能

资源

• 将 S3 存储桶中的所有 YAML 文件列为 MCP 资源
• 每个文件都附带元数据（大小、修改日期）
• 可通过 S3 URI 访问文件：s3://bucket-name/path/to/file.yaml

工具

• search_yaml_files：按名称模式搜索 YAML 文件
• list_yaml_files：列出所有 YAML 文件，可选择按前缀筛选
• get_endpoint_details：获取特定 API 端点的详细信息，包括请求/响应架构

💡 使用 GitHub Copilot 的示例

生成 API 客户端代码

@s3YamlDocs I need to create a TypeScript client for the user management API.
Can you find the user API specification and generate a complete client with all methods?

查找特定端点的详细信息

@s3YamlDocs Use get_endpoint_details to find information about the /v1/cards/{card_id}/pan endpoint

验证实现

@s3YamlDocs Compare my Express.js routes in src/routes/users.js with the user API
specification to ensure I'm following the contract correctly.

生成测试用例

@s3YamlDocs Based on the payment API specification, generate comprehensive
Jest test cases that cover all endpoints and error scenarios.

搜索和分析

@s3YamlDocs Search for all authentication-related endpoints across all my APIs
@s3YamlDocs Find all endpoints that return blocked_reason in the response

⚙️ 配置

环境变量

根据 .env.example 创建 .env 文件：

# Required
S3_BUCKET=your-api-docs-bucket

# Optional (defaults shown)
S3_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key     # Optional if using IAM/AWS CLI
AWS_SECRET_ACCESS_KEY=your-secret-key # Optional if using IAM/AWS CLI
S3_ENDPOINT=                          # For S3-compatible services
LOG_LEVEL=info

AWS 身份验证

该服务支持多种身份验证方式：

1. AWS CLI 凭证（推荐）：aws configure
2. IAM 角色（用于 EC2/Lambda 部署）
3. 环境变量（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）

S3 权限

你的 AWS 凭证需要具备以下 S3 权限：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:HeadBucket",
        "s3:HeadObject"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

推荐的 S3 文件组织方式

your-s3-bucket/
├── apis/
│   ├── user-service/
│   │   ├── v1/openapi.yaml
│   │   └── v2/swagger.yaml
│   ├── payment-service/
│   │   └── api-spec.yml
│   └── notification-service/
│       └── swagger.yaml
└── legacy/
    └── old-api.yaml

🏗️ 开发

项目结构

s3-mcp-server/
├── main.go                    # Entry point
├── internal/
│   ├── config/               # Configuration management
│   ├── s3/                   # S3 client and operations
│   └── server/               # MCP server implementation
├── pkg/
│   └── mcp/                  # MCP protocol types and utilities
├── .vscode/
│   └── mcp.json              # VS Code MCP configuration
├── .env.example              # Environment configuration template
└── README.md

构建和测试

# Using Makefile (recommended)
make build          # Build binary
make test           # Run tests
make test-vscode    # Test VS Code integration
make install        # Install to /usr/local/bin

# Manual build
go build -o s3-mcp-server

# Test scripts
./test-vscode-integration.sh
./test-new-tool.sh
./test.sh

📦 分发与发布

本项目支持多种分发方式：

🏷️ 创建发布版本

1. 为版本打标签：

git tag v1.0.0
git push origin v1.0.0

2. GitHub Actions 将自动：
   • 为所有平台（Linux、macOS、Windows）构建二进制文件
   • 创建 GitHub 发布版本
   • 上传各平台对应的二进制文件

🐳 Docker 分发

# Build Docker image
make docker-build

# Run with Docker
docker run --rm -e S3_BUCKET=your-bucket s3-mcp-server:latest

📋 安装方式摘要

方式	命令	使用场景
一键安装	curl -fsSL https://raw.githubusercontent.com/ander-castiblanco-stori/s3-mcp-server/main/install.sh | bash	在多个项目中用于生产环境
Go 安装	go install github.com/ander-castiblanco-stori/s3-mcp-server@latest	Go 开发者
下载二进制文件	从 releases 下载	手动安装
Docker	docker pull ghcr.io/ander-castiblanco-stori/s3-mcp-server:latest	容器环境
克隆并构建	git clone && make build	开发

🔄 在多个项目中使用

全局安装后，即可在任何项目中使用 S3 MCP 服务：

1. 在任意项目中创建 VS Code 配置：

mkdir -p .vscode
cat > .vscode/mcp.json << 'EOF'
{
  "mcpServers": {
    "s3YamlDocs": {
      "command": "s3-mcp-server",
      "args": [],
      "env": {
        "S3_BUCKET": "your-api-docs-bucket",
        "S3_REGION": "us-east-1"
      }
    }
  }
}
EOF

2. 打开 VS Code 并使用 GitHub Copilot：

@s3YamlDocs list all YAML files
@s3YamlDocs find endpoints for user authentication

🔧 故障排除

常见问题

❌ S3 连接失败

• 验证 AWS 凭据：aws sts get-caller-identity
• 检查存储桶权限和区域
• 确保存储桶存在：aws s3 ls s3://your-bucket-name

❌ 未找到文件

• 确认 YAML 文件的扩展名为 .yaml 或 .yml
• 检查 S3 存储桶内容：aws s3 ls s3://your-bucket-name --recursive

❌ VS Code 集成问题

• 确保 VS Code 已更新到最新版本
• 检查 GitHub Copilot 扩展是否已启用
• 验证 .vscode/mcp.json 配置
• 在 VS Code「输出」→「GitHub Copilot Chat」中检查错误

❌ 权限被拒绝

• 检查 IAM 策略是否包含所需的 S3 权限
• 检查存储桶策略是否允许访问
• 确认区域配置与存储桶所在区域一致

调试模式

启用调试日志：

LOG_LEVEL=debug ./s3-mcp-server

📚 了解更多

• MCP 协议：https://modelcontextprotocol.io/
• VS Code MCP 支持：https://code.visualstudio.com/docs/copilot/copilot-mcp
• AWS S3 Go SDK：https://aws.github.io/aws-sdk-go-v2/docs/

📄 许可证

MIT 许可证，详情请参阅 LICENSE 文件。