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	环境（本地/生产）	否
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 集成与核心工具

✅ 已实现的功能

• ✅ 项目结构和构建系统
• ✅ 配置管理（本地/生产环境）
• ✅ HTTP 服务，包含中间件（CORS、速率限制、日志记录）
• ✅ 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 文件。

🤝 参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

📞 支持

• GitHub Issues：报告错误或申请功能
• 文档：完整文档
• 社区：讨论区