ai-vision-mcp 是一个 Model Context Protocol (MCP) 服务器，为兼容 MCP 的客户端提供 AI 驱动的图像和视频分析能力。它基于 Google Gemini 和 Vertex AI 模型，支持多模态内容分析，适合集成到 Claude Desktop、Claude Code、Cursor、Cline 等工具中。
用途
该服务器旨在为 AI 客户端扩展视觉理解能力，可用于 UI/UX 评估、视觉回归测试、界面理解、设计合规审计等场景。
主要能力
- 双提供商支持：可选择 Google Gemini API 或 Vertex AI。
- 多模态分析：同时支持图像和视频内容分析。
- 灵活的文件处理：可通过 URL、本地文件、base64 上传。
- 存储集成：内置 Google Cloud Storage 支持。
- 全面验证：使用 Zod 进行数据验证。
- 错误处理：具备重试逻辑和断路器机制。
- TypeScript：完整 TypeScript 支持，严格类型检查。
服务器提供四个主要 MCP 工具：
- analyze_image：分析图像并返回详细描述。支持多种模式：general（通用图像分析）、palette（提取设计令牌：颜色、间距、字体）、hierarchy（分析视觉层次和视觉流）、components（编目 UI 组件和设计系统成熟度）。可接受 imageSource、prompt、mode、options 参数。
- compare_images：比较多张图像并返回详细对比分析。imageSources 为数组，最少 2 张、最多 4 张，支持 URL、base64 或文件路径。
- detect_objects_in_image：检测图像中的物体并生成带边界框的标注图，返回检测对象坐标，可将标注图保存到指定路径或临时目录。支持自定义检测提示词，可通过环境变量调整 AI 参数。
- audit_design：审计 UI/UX 设计合规性，进行像素级分析和 AI 点评。提取主色（K-means 聚类取 5 种主要颜色）、边缘复杂度（Sobel 算子）、WCAG 对比度（W3C 相对亮度公式，AA/AAA）、亮度统计（平均亮度和标准差），自动检测对比度、复杂度、亮度问题，并给出基于 Gemini 的改进建议。
- analyze_video：分析视频并返回详细描述。支持 YouTube URL、GCS URI 或本地文件路径。注意：公共视频 URL 仅支持 YouTube URL。
使用方式
环境变量配置：可选择 Google AI Studio 提供商（推荐，简单）或 Vertex AI 提供商（生产环境）。需要设置对应的 API 密钥或凭据。建议将 MCP 客户端超时设置超过 5 分钟。
安装到不同 MCP 客户端：提供 Claude Desktop、Cursor、Cline 等配置指南。服务器使用 stdio 传输，遵循标准 MCP 协议，可通过命令运行并集成到任何兼容的 MCP 客户端。
配置优先级：运行时参数 > 功能特定变量 > 任务特定变量 > 通用变量 > 系统默认值。
开发命令：npm run build 构建 TypeScript 项目；npm run dev 启动开发服务器（watch 模式）；npm run lint 运行 ESLint；npm run format 用 Prettier 格式化；npm start 启动构建后的服务器。
适用场景
- UI/UX 评估与设计合规审计
- 视觉回归测试
- 界面理解与组件编目
- 图像内容的通用分析、比较与物体检测
- 视频内容分析
限制
- 公共视频 URL 目前仅支持 YouTube。
- 物体检测工具使用优化后的默认参数，不接受运行时 options 参数，需通过环境变量自定义。
- 使用 stdio 传输时，stdout 必须仅包含 MCP JSON-RPC 消息，日志需输出到 stderr，否则可能导致客户端断开。
- 需自行配置 Google AI Studio 或 Vertex AI 的凭据。
- 项目采用 MIT 许可证。
