使用说明

S3 YAML MCP服务器

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

🎯 什么是MCP？

模型上下文协议（MCP）是一种开放协议，它规范了应用程序如何向大型语言模型（LLM）提供上下文。它使AI助手能够安全地访问数据源和工具。

✨ 特性

🔗 S3集成：连接到任何与S3兼容的存储服务
📁 YAML文件发现：自动列出和发现YAML/YML文件
📖 内容访问：读取YAML内容并将其提供给AI助手
🔍 高级搜索：搜索文件和特定的API终结点详细信息
🚀 VS代码本机：与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代码配置文件

方法2：去安装

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

VS代码与Docker的集成

// .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代码

设置

安装服务器 （选择上面的一种方法）
配置环境:

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

设置VS代码 （如果不是由安装程序完成）：

# 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

测试连接:

./test-vscode-integration.sh

在VS代码中打开:

code .

开始使用GitHub Copilot:
- 打开GitHub Copilot聊天(Cmd+Shift+I macOS）
- 类型： @s3YamlDocs list all YAML files in my bucket

🛠️ MCP能力

资源

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

工具

搜索yaml文件：按名称模式搜索YAML文件
list_yaml_文件：列出所有具有可选前缀过滤的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 文件基于 .env.example:

# 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身份验证

服务器支持多种身份验证方法：

AWS CLI凭据 （推荐）： aws configure
IAM角色 （适用于EC2/Lambda部署）
环境变量 （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-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

📦 发行与出版

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

🏷️ 创建发布

标记版本:

git tag v1.0.0
git push origin v1.0.0

GitHub自动操作:
- 为所有平台（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 install github.com/ander-castiblanco-stori/s3-mcp-server@latest`	Go开发者
二进制下载	下载自发布	手动安装
码头工人	`docker pull ghcr.io/ander-castiblanco-stori/s3-mcp-server:latest`	容器环境
克隆和构建	`git clone && make build`	发展

🔄 跨多个项目使用

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

在任何项目中创建VS代码配置:

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

打开VS代码并使用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代码集成问题

确保VS代码更新到最新版本
检查GitHub Copilot扩展是否处于活动状态
验证 .vscode/mcp.json 配置
检查VS代码输出→ “GitHub Copilot Chat”错误

❌ 权限不足

检查IAM策略是否与所需的S3权限匹配
检查存储桶策略是否允许访问
验证区域配置是否与存储桶区域匹配

调试模式

启用调试日志记录：

LOG_LEVEL=debug ./s3-mcp-server

📚 了解更多

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

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。