S3 YAML MCP Server

S3 YAML MCP サーバー

AWS S3 に接続し、Swagger/OpenAPI ドキュメントを含む YAML ファイルへのアクセスを提供する Model Context Protocol（MCP）サーバーです。VS Code および GitHub Copilot とのシームレスな連携を目的に設計されています。

🎯 MCP とは？

Model Context Protocol（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. サーバーをインストール（上記から方法を 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

📋 インストール方法の概要

方法	コマンド	用途
1 行インストール	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 開発者
バイナリのダウンロード	リリース からダウンロード	手動インストール
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 または .yml 拡張子の YAML ファイルが存在することを確認します
• 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 Protocol：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 の詳細については、LICENSE ファイルをご覧ください。