fly-mcp

fly-mcp

Fly.io インフラストラクチャを管理するオープンソースの MCP（Model Context Protocol）サーバーです。自然言語でのやり取りを通じて、AI 主導の DevOps ワークフローを実現します。

🚀 クイックスタート

前提条件

• Go 1.21 以降
• Fly.io アカウントと API トークン
• Git

ローカル開発環境のセットアップ

1. リポジトリをクローンする

   git clone https://github.com/brannn/fly-mcp.git
   cd fly-mcp
   

2. 環境変数を設定する

   export FLY_MCP_FLY_API_TOKEN="your_fly_api_token_here"
   export FLY_MCP_FLY_ORGANIZATION="your_fly_org_here"
   

3. ビルドして実行する

   make build
   make run
   

   または、ホットリロードを有効にして開発する場合：

   make dev
   

Fly.io への本番環境デプロイ

Fly.io の MCP インフラストラクチャを使用してデプロイします。

fly mcp launch \
  "github.com/brannn/fly-mcp" \
  --claude --cursor --zed \
  --server fly-infrastructure \
  --secret FLY_API_TOKEN=fo1_your_token \
  --secret FLY_ORG=your-org-name

🏗️ アーキテクチャ

プロジェクト構成

fly-mcp/
├── cmd/fly-mcp/              # Main application entry point
├── pkg/
│   ├── mcp/                  # MCP protocol implementation
│   ├── fly/                  # Fly.io API client (coming soon)
│   ├── auth/                 # Authentication (coming soon)
│   ├── tools/                # MCP tool implementations (coming soon)
│   └── config/               # Configuration management
├── internal/
│   ├── server/               # HTTP server implementation
│   ├── security/             # Security utilities (coming soon)
│   └── logger/               # Structured logging
├── config.local.yaml         # Local development configuration
├── config.production.yaml    # Production configuration
└── Makefile                  # Build automation

設定

アプリケーションでは、次の方法で柔軟に設定できます。

• YAML ファイル：開発環境では config.local.yaml、本番環境では config.production.yaml
• 環境変数：すべての設定値は、FLY_MCP_ をプレフィックスとする環境変数で上書きできます
• コマンドラインフラグ：--config および --log-level フラグ

環境変数

変数	説明	必須
FLY_MCP_FLY_API_TOKEN	Fly.io API トークン	はい
FLY_MCP_FLY_ORGANIZATION	Fly.io 組織名	はい
FLY_MCP_ENVIRONMENT	環境（local/production）	いいえ
FLY_MCP_LOGGING_LEVEL	ログレベル（debug/info/warn/error）	いいえ

🛠️ 開発

使用可能な Make ターゲット

make build          # Build the binary
make build-all      # Build for all platforms
make test           # Run tests
make test-coverage  # Run tests with coverage
make lint           # Run linters
make fmt            # Format code
make clean          # Clean build artifacts
make dev            # Run in development mode
make validate-config # Validate configuration
make docker-build   # Build Docker image
make help           # Show all available targets

テストの実行

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run benchmarks
make benchmark

コード品質

# Format code
make fmt

# Run linters
make lint

# Run all checks
make check

🔧 設定例

ローカル開発

.env ファイルを作成するか、環境変数を設定します。

export FLY_MCP_FLY_API_TOKEN="fo1_your_development_token"
export FLY_MCP_FLY_ORGANIZATION="your-dev-org"
export FLY_MCP_LOGGING_LEVEL="debug"

Fly.io の本番環境

Fly.io アプリにシークレットを設定します。

fly secrets set FLY_API_TOKEN=fo1_your_production_token
fly secrets set FLY_ORG=your-production-org

🛠️ 使用可能な MCP ツール

コアツール

ツール	説明	使用例
ping	接続とサーバー応答をテストします	{"name": "ping", "arguments": {"message": "Hello!"}}

Fly.io 管理ツール

ツール	説明	使用例
fly_list_apps	フィルタリングしてすべてのアプリケーションを一覧表示します	{"name": "fly_list_apps", "arguments": {"status_filter": "running"}}
fly_app_info	アプリケーションの詳細情報を取得します	{"name": "fly_app_info", "arguments": {"app_name": "my-app"}}
fly_status	アプリケーションとマシンのステータスをリアルタイムで表示します	{"name": "fly_status", "arguments": {"app_name": "my-app"}}
fly_restart	確認を行ってアプリケーションを再起動します	{"name": "fly_restart", "arguments": {"app_name": "my-app", "confirm": true}}
fly_scale	スケーリングのステータスと推奨事項を表示します	{"name": "fly_scale", "arguments": {"app_name": "my-app", "action": "status"}}

ツールの機能

• 🔒 セキュリティ：すべてのツールで適切な認証と権限が必要です
• 📝 監査ログ：コンプライアンスとデバッグのため、すべての操作が記録されます
• ⚡ リアルタイム：ステータスとマシンの情報をリアルタイムで取得します
• 🛡️ 安全性：破壊的な操作には明示的な確認が必要です
• 📊 豊富な出力：実行可能な推奨事項を含む、人が読みやすい応答を提供します

🧪 MCP サーバーのテスト

自動テスト

付属のテストスクリプトを使用して、すべてのツールを確認します。

# Start the server first
make dev

# In another terminal, run tests
./scripts/test-mcp-tools.sh

手動テスト

1. ヘルスチェック

   curl http://localhost:8080/health
   

2. MCP の初期化

   curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "initialize",
       "params": {
         "protocolVersion": "2024-11-05",
         "capabilities": {},
         "clientInfo": {"name": "test-client", "version": "1.0.0"}
       }
     }'
   

3. 使用可能なツールの一覧表示

   curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 2,
       "method": "tools/list"
     }'
   

4. Ping ツールのテスト

   curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 3,
       "method": "tools/call",
       "params": {
         "name": "ping",
         "arguments": {"message": "Hello from fly-mcp!"}
       }
     }'
   

5. Fly.io ツールのテスト（有効な認証情報が必要です）

   curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 4,
       "method": "tools/call",
       "params": {
         "name": "fly_list_apps",
         "arguments": {}
       }
     }'
   

🎯 現在のステータス

フェーズ 2 完了：Fly.io API 統合とコアツール

✅ 実装済みの機能

• ✅ プロジェクト構成とビルドシステム
• ✅ 構成管理（ローカル／本番環境）
• ✅ ミドルウェア（CORS、レート制限、ロギング）を備えたHTTP サーバー
• ✅ リクエストとレスポンスを完全に処理するMCP プロトコルハンドラー
• ✅ 監査証跡とセキュリティイベントに対応した構造化ロギング
• ✅ Fly.io API 統合（ハイブリッド方式：fly-go + Machines API）
• ✅ 権限と監査ログに対応した認証・認可
• ✅ コア MCP ツール：
  • ping - 接続をテストするツール
  • fly_list_apps - フィルタリング機能を備えた全アプリケーションの一覧表示
  • fly_app_info - アプリケーションの詳細情報を取得
  • fly_status - アプリケーションとマシンのリアルタイムステータス
  • fly_restart - 確認後にアプリケーションを再起動
  • fly_scale - スケーリングのステータスと推奨事項
• ✅ ヘルスチェックとメトリクスのエンドポイント
• ✅ 包括的なエラー処理と検証
• ✅ セキュリティ機能（レート制限、CORS、監査ログ）

🔄 次の予定（フェーズ 3）

• 🔄 追加ツール：ログ、シークレット、ボリューム、証明書
• 🔄 アプリケーションをデプロイするデプロイツール
• 🔄 オートスケーリングの推奨機能を備えた高度なスケーリング
• 🔄 アラートとダッシュボードに対応したモニタリング統合
• 🔄 CI/CD パイプラインと自動テスト
• 🔄 ドキュメントと使用例

📝 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

🤝 コントリビューション

コントリビューションを歓迎します！ガイドラインについては CONTRIBUTING.md をご覧ください。

📞 サポート

• GitHub Issues：バグの報告や機能のリクエスト
• ドキュメント：ドキュメント全文
• コミュニティ：ディスカッション