Flutter Deprecations MCP Server

Flutter 废弃 API MCP 服务

此 MCP 服务用于跟踪 Flutter API 的废弃情况，并提供工具来检查代码中的废弃 API 和建议替代方案。

项目结构

flutter-deprecations-server/
├── cmd/
│   └── server/          # Main application entry point
│       └── main.go
├── internal/            # Private application code
│   ├── handlers/        # MCP tool handlers
│   │   ├── mcp_handlers.go
│   │   ├── mcp_handlers_test.go
│   │   └── testdata/
│   ├── models/          # Data structures
│   │   └── flutter.go
│   └── services/        # Business logic
│       ├── cache.go
│       ├── cache_test.go
│       ├── deprecations.go
│       ├── deprecations_test.go
│       ├── flutter_api.go
│       ├── flutter_api_test.go
│       ├── flutter_version.go
│       ├── interfaces.go
│       ├── version_info.go
│       ├── version_info_test.go
│       └── testdata/
├── pkg/                 # Public libraries
│   └── config/          # Configuration constants
│       └── config.go
├── bin/                 # Compiled binaries
├── Makefile            # Build automation
├── go.mod              # Go module definition
├── go.sum              # Dependency checksums
└── README.md

功能

• 基于源码的废弃项跟踪：直接扫描 Flutter 的 GitHub 源代码，查找 @Deprecated 注解
• 本地缓存：在本地存储废弃项，缓存有效期为 24 小时
• 代码分析：分析 Flutter 代码片段中的废弃 API
• 替代方案建议：为废弃 API 提供现代替代方案
• 全面扫描：扫描 Flutter 的主要目录（widgets、material、cupertino、services 等）
• 版本检查：使用 Flutter CLI 获取最新 Flutter 版本（最可靠），并在失败时回退到 GitHub API
• 多平台支持：检查 FVM 和 Docker 镜像的可用性
• 命令行缓存管理：手动更新和清除缓存，并报告进度
• 简短命令选项：同时支持长选项和短选项
• 速率限制处理：妥善处理 GitHub API 速率限制，并提供有用的错误消息
• 详细日志记录：使用 -vvv 标志记录详细日志，便于排查问题

MCP 工具

1. check_flutter_deprecations

分析提供的 Flutter 代码，查找废弃 API 并建议替代方案。

参数：

• code（字符串）：要分析的 Flutter 代码片段

示例：

Color.red.withOpacity(0.5)  // Will suggest Color.red.withValues(alpha: 0.5)

2. list_flutter_deprecations

列出缓存中的所有已知 Flutter 废弃项。

**参数：**无

**返回：**完整的废弃项列表，包含替代方案和版本信息。

3. check_flutter_version_info

获取最新的稳定版 Flutter，并检查它在不同工具和平台上的可用性。

**参数：**无

返回：

• 最新的稳定版 Flutter（如果可用则使用 Flutter CLI，否则回退到 GitHub API）
• Flutter CLI 安装状态和渠道信息
• FVM 安装状态和版本可用性
• instrumentisto/flutter 和 ghcr.io/cirruslabs/flutter 的 Docker 镜像可用性
• 使用示例和安装命令

已知废弃项

服务内置了常见废弃项的匹配模式：

• Color.withOpacity() → Color.withValues(alpha:)
• RaisedButton → ElevatedButton
• FlatButton → TextButton
• OutlineButton → OutlinedButton
• Scaffold.of(context).showSnackBar → ScaffoldMessenger.of(context).showSnackBar

安装

使用 Makefile（推荐）

# Install dependencies
make deps

# Build the server
make build

# Run the server
make run

# Build for multiple platforms
make build-all

手动构建

# Install dependencies
go mod tidy

# Build the server
go build -o bin/flutter-deprecations-server ./cmd/server

# Run the server
./bin/flutter-deprecations-server

# Update deprecations cache manually
./bin/flutter-deprecations-server --update

# Update with verbose logging  
./bin/flutter-deprecations-server --update -vvv

# Clear deprecations cache
./bin/flutter-deprecations-server --clear-cache

# Show current cache contents
./bin/flutter-deprecations-server --show-cache

# Show help information
./bin/flutter-deprecations-server --help

开发

# Format code
make fmt

# Vet code
make vet

# Run tests
make test

# Development build and run
make dev

配置 AI 助手

添加到 MCP 配置中（例如 mcp.json）：

{
  "mcpServers": {
    "flutter-deprecations": {
      "command": "/path/to/flutter-deprecations-server/bin/flutter-deprecations-server",
      "args": [],
      "env": {}
    }
  }
}

版本检测

服务采用可靠的多层方案来检测最新 Flutter 版本：

1. 主要方式：Flutter CLI（flutter --version）——最准确，与开发者环境一致
2. 官方 API：Google Storage Flutter releases API（https://storage.googleapis.com/flutter_infra_release/releases/releases_linux.json）——比 GitHub 更快、更可靠
3. 回退方式：GitHub API releases——当 Flutter CLI 和官方 API 均不可用时使用
4. 渠道检测：从官方来源识别 stable/beta/dev 渠道
5. Docker Registry 支持：同时检查 Docker Hub 和 GitHub Container Registry

缓存位置

废弃项缓存路径：~/.flutter-deprecations/flutter_deprecations.json

使用工具时，缓存每 24 小时自动更新一次。

使用示例

向你的 AI 助手提问：

• “检查这段 Flutter 代码中的废弃 API：Color.red.withOpacity(0.5)”
• “列出所有 Flutter 废弃项”
• “RaisedButton 应该用什么替代？”
• “最新的 Flutter 版本是什么？它能否通过 FVM 和 Docker 使用？”
• “检查 Flutter 版本信息”

命令行用法

服务支持多种用于缓存管理的命令行选项：

# Show help and available options
./bin/flutter-deprecations-server --help
./bin/flutter-deprecations-server -h        # Short version

# Update deprecations cache with progress reporting
./bin/flutter-deprecations-server --update
./bin/flutter-deprecations-server -u        # Short version

# Update with verbose logging for troubleshooting
./bin/flutter-deprecations-server --update -vvv
./bin/flutter-deprecations-server -u -vvv   # Short version

# Clear deprecations cache
./bin/flutter-deprecations-server --clear-cache
./bin/flutter-deprecations-server -cc       # Short version

# Show current cache contents
./bin/flutter-deprecations-server --show-cache
./bin/flutter-deprecations-server -sc       # Short version

# Start the MCP server (default behavior)
./bin/flutter-deprecations-server

可用选项

• --help, -h：显示帮助信息和用法示例
• --update, -u：更新 Flutter 弃用项缓存后退出
• --clear-cache, -cc：清除 Flutter 弃用项缓存后退出
• --show-cache, -sc：显示当前 Flutter 弃用项缓存后退出
• --vvv：启用详细日志，以便进行详细故障排查

架构

项目遵循 Go 最佳实践，采用整洁架构：

• cmd/：应用程序入口
• internal/：私有应用程序代码（其他项目无法导入）
• pkg/：可供其他项目导入的公共库
• Makefile：构建自动化和常用任务

服务层

• CacheService：处理本地文件缓存，并提供清除功能
• FlutterAPIService：管理与 GitHub API 的交互，并处理速率限制、源代码扫描和 Docker 注册表检查
• FlutterVersionService：直接通过 Flutter CLI 获取 Flutter 版本
• DeprecationService：分析和管理 Flutter 源代码中的弃用数据
• VersionInfoService：提供全面的版本和可用性信息

处理器层

• MCPHandlers：实现 MCP 工具接口并协调服务调用

测试

• 全面的测试套件：为所有服务和处理器编写单元测试
• 模拟服务：通过依赖注入搭建测试基础设施
• 测试覆盖率：运行 make test-coverage 生成覆盖率报告