Ai Vision MCP

🚀 AI視覺MCP服務器

這是一個強大的模型上下文協議（MCP）服務器，藉助谷歌Gemini和Vertex AI模型，提供基於人工智能的圖像和視頻分析功能。

🚀 快速開始

前提條件

你可以選擇使用google 提供商或 vertex_ai 提供商。為簡便起見，建議使用 google 提供商。

以下是根據你所選提供商需要設置的環境變量。（注意：建議將MCP客戶端的超時配置設置為超過5分鐘。）

(i) 使用谷歌AI工作室提供商

export IMAGE_PROVIDER="google" # 或 vertex_ai
export VIDEO_PROVIDER="google" # 或 vertex_ai
export GEMINI_API_KEY="your-gemini-api-key"

你可以在此處獲取谷歌AI工作室的API密鑰。

(ii) 使用Vertex AI提供商

export IMAGE_PROVIDER="vertex_ai"
export VIDEO_PROVIDER="vertex_ai"
export VERTEX_CREDENTIALS="/path/to/service-account.json"
export GCS_BUCKET_NAME="your-gcs-bucket"

有關如何設置的具體指南，請參考此處。

安裝

以下是在不同MCP客戶端（如Claude Desktop、Claude Code、Cursor、Cline等）上安裝此MCP的指南。

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "google",
        "VIDEO_PROVIDER": "google",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CREDENTIALS": "/path/to/service-account.json",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

claude mcp add ai-vision-mcp \
  -e IMAGE_PROVIDER=google \
  -e VIDEO_PROVIDER=google \
  -e GEMINI_API_KEY=your-gemini-api-key \
  -- npx ai-vision-mcp

claude mcp add ai-vision-mcp \
  -e IMAGE_PROVIDER=vertex_ai \
  -e VIDEO_PROVIDER=vertex_ai \
  -e VERTEX_CREDENTIALS=/path/to/service-account.json \
  -e GCS_BUCKET_NAME=ai-vision-mcp-{VERTEX_PROJECT_ID} \
  -- npx ai-vision-mcp

{
  "env": {
    "MCP_TIMEOUT": "60000",
    "MCP_TOOL_TIMEOUT": "300000"
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "google",
        "VIDEO_PROVIDER": "google",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CREDENTIALS": "/path/to/service-account.json",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

{
  "mcpServers": {
    "timeout": 300, 
    "type": "stdio",
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "google",
        "VIDEO_PROVIDER": "google",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "timeout": 300,
      "type": "stdio",
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CREDENTIALS": "/path/to/service-account.json",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

npx ai-vision-mcp

✨ 主要特性

• 雙提供商支持：可在谷歌Gemini API和Vertex AI之間進行選擇。
• 多模態分析：支持圖像和視頻內容分析。
• 靈活的文件處理：支持通過多種方式（URL、本地文件、Base64）上傳。
• 存儲集成：內置谷歌雲存儲支持。
• 全面驗證：全程使用基於Zod的數據驗證。
• 錯誤處理：具備強大的錯誤處理機制，包含重試邏輯和熔斷機制。
• TypeScript支持：完全支持TypeScript，並進行嚴格的類型檢查。

💻 使用示例

基礎用法

服務器提供了四個主要的MCP工具，以下是這些工具的使用示例：

1) analyze_image

使用人工智能分析圖像，並返回詳細描述。 參數：

• imageSource（字符串）：圖像的URL、Base64數據或文件路徑。
• prompt（字符串）：向人工智能提出的問題或指令。
• options（對象，可選）：分析選項，包括溫度和最大令牌數。

示例：

{
  "imageSource": "https://plus.unsplash.com/premium_photo-1710965560034-778eedc929ff",
  "prompt": "這張圖片是關於什麼的？詳細描述你看到的內容。"
}

2) compare_images

使用人工智能比較多張圖像，並返回詳細的比較分析結果。 參數：

• imageSources（數組）：圖像源數組（URL、Base64數據或文件路徑），最少2張，最多4張圖像。
• prompt（字符串）：用於比較圖像的問題或指令。
• options（對象，可選）：分析選項，包括溫度和最大令牌數。

示例：

{
  "imageSources": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "prompt": "比較這兩張圖片，並告訴我它們的區別。"
}

3) detect_objects_in_image

使用人工智能視覺模型檢測圖像中的物體，並生成帶有邊界框的註釋圖像。返回帶有座標的檢測物體，並將註釋圖像保存到文件或臨時目錄。 參數：

• imageSource（字符串）：圖像的URL、Base64數據或文件路徑。
• prompt（字符串）：自定義檢測提示，描述要在圖像中檢測或識別的內容。
• outputFilePath（字符串，可選）：註釋圖像的顯式輸出路徑。

配置： 此函數使用優化的默認參數進行物體檢測，不接受運行時 options 參數。要自定義人工智能參數（溫度、topP、topK、最大令牌數），請使用環境變量：

# 推薦的物體檢測環境變量設置（這些現在是默認值）
TEMPERATURE_FOR_DETECT_OBJECTS_IN_IMAGE=0.0     # 確定性響應
TOP_P_FOR_DETECT_OBJECTS_IN_IMAGE=0.95          # 核採樣
TOP_K_FOR_DETECT_OBJECTS_IN_IMAGE=30            # 詞彙選擇
MAX_TOKENS_FOR_DETECT_OBJECTS_IN_IMAGE=8192     # 高令牌限制，用於JSON

文件處理邏輯：

1. 提供顯式輸出文件路徑 → 保存到指定的精確路徑。
2. 未提供顯式輸出文件路徑 → 自動保存到臨時目錄。

響應類型：

• 提供顯式輸出文件路徑時，返回 file 對象。
• 未提供顯式輸出文件路徑時，返回 tempFile 對象，圖像文件輸出自動保存到臨時文件夾。
• 始終包含 detections 數組，其中包含檢測到的物體和座標。
• 包含 summary，其中包含基於百分比的座標，用於瀏覽器自動化。

示例：

{
  "imageSource": "https://example.com/image.jpg",
  "prompt": "檢測這張圖片中的所有物體。"
}

4) analyze_video

使用人工智能分析視頻，並返回詳細描述。 參數：

• videoSource（字符串）：視頻的YouTube URL、GCS URI或本地文件路徑。
• prompt（字符串）：向人工智能提出的問題或指令。
• options（對象，可選）：分析選項，包括溫度和最大令牌數。

支持的視頻源：

• YouTube URL（例如：https://www.youtube.com/watch?v=...）
• 本地文件路徑（例如：C:\Users\username\Downloads\video.mp4）

示例：

{
  "videoSource": "https://www.youtube.com/watch?v=9hE5-98ZeCg",
  "prompt": "這個視頻是關於什麼的？詳細描述你看到的內容。"
}

📚 詳細文檔

環境配置

對於基本設置，你只需配置提供商選擇和所需的憑證：

谷歌AI工作室提供商（推薦）

export IMAGE_PROVIDER="google"
export VIDEO_PROVIDER="google"
export GEMINI_API_KEY="your-gemini-api-key"

Vertex AI提供商（生產環境）

export IMAGE_PROVIDER="vertex_ai"
export VIDEO_PROVIDER="vertex_ai"
export VERTEX_CREDENTIALS="/path/to/service-account.json"
export GCS_BUCKET_NAME="your-gcs-bucket"

📖 詳細配置指南

有關全面的環境變量文檔，包括：

• 完整的配置參考（60多個環境變量）
• 特定功能的優化示例
• 高級配置模式
• 故障排除指南

👉 查看環境變量指南

配置優先級概述

服務器使用分層配置系統，更具體的設置會覆蓋通用設置：

1. 大語言模型分配的值（工具調用中的運行時參數）
2. 特定功能變量（TEMPERATURE_FOR_ANALYZE_IMAGE 等）
3. 特定任務變量（TEMPERATURE_FOR_IMAGE 等）
4. 通用變量（TEMPERATURE 等）
5. 系統默認值

# 通用設置
export TEMPERATURE=0.7
export MAX_TOKENS=1500

# 特定任務優化
export TEMPERATURE_FOR_IMAGE=0.2     # 圖像更精確
export TEMPERATURE_FOR_VIDEO=0.5     # 視頻更具創造性

# 優化單個功能
export TEMPERATURE_FOR_ANALYZE_IMAGE=0.1
export TEMPERATURE_FOR_COMPARE_IMAGES=0.3
export TEMPERATURE_FOR_DETECT_OBJECTS_IN_IMAGE=0.0  # 確定性
export MAX_TOKENS_FOR_DETECT_OBJECTS_IN_IMAGE=8192   # 高令牌限制

# 為每個功能選擇模型
export ANALYZE_IMAGE_MODEL="gemini-2.5-flash-lite"
export COMPARE_IMAGES_MODEL="gemini-2.5-flash"
export ANALYZE_VIDEO_MODEL="gemini-2.5-flash-pro"

開發

前提條件

• Node.js 18+
• npm 或 yarn

設置

# 克隆倉庫
git clone https://github.com/tan-yong-sheng/ai-vision-mcp.git
cd ai-vision-mcp

# 安裝依賴
npm install

# 構建項目
npm run build

# 啟動開發服務器
npm run dev

腳本

• npm run build - 構建TypeScript項目。
• npm run dev - 以監視模式啟動開發服務器。
• npm run lint - 運行ESLint。
• npm run format - 使用Prettier格式化代碼。
• npm start - 啟動已構建的服務器。

架構

項目採用模塊化架構：

src/
├── providers/          # AI提供商實現
│   ├── gemini/        # 谷歌Gemini提供商
│   ├── vertexai      # Vertex AI提供商
│   └── factory/       # 提供商工廠
├── services/          # 核心服務
│   ├── ConfigService.ts
│   └── FileService.ts
├── storage/           # 存儲實現
├── file-upload/       # 文件上傳策略
├── types/            # TypeScript類型定義
├── utils/            # 實用函數
└── server.ts         # 主MCP服務器

錯誤處理

服務器包含全面的錯誤處理機制：

• 驗證錯誤：使用Zod模式進行輸入驗證。
• 網絡錯誤：使用指數退避進行自動重試。
• 身份驗證錯誤：針對API密鑰問題提供清晰的錯誤消息。
• 文件錯誤：處理文件大小限制和格式限制。

🔧 技術細節

配置優先級

服務器採用分層配置系統，具體優先級如下：

這種分層配置系統確保了更具體的設置能夠覆蓋通用設置，從而提供了靈活的配置選項。

錯誤處理機制

服務器具備強大的錯誤處理能力，針對不同類型的錯誤採取了相應的處理策略：

• 驗證錯誤：使用Zod模式對輸入數據進行驗證，確保數據的有效性。如果輸入數據不符合預期格式，將拋出明確的驗證錯誤信息。
• 網絡錯誤：採用指數退避算法進行自動重試，以應對臨時的網絡問題。當發生網絡錯誤時，服務器會自動重試請求，重試間隔會隨著重試次數的增加而指數級增長，直到達到最大重試次數或請求成功。
• 身份驗證錯誤：對於API密鑰問題，服務器會返回清晰的錯誤消息，幫助用戶快速定位和解決身份驗證問題。
• 文件錯誤：在處理文件上傳和存儲時，服務器會處理文件大小限制和格式限制等問題。如果文件大小超過限制或文件格式不支持，服務器會返回相應的錯誤信息。

模塊化架構設計

項目採用模塊化架構，將不同的功能模塊進行分離，提高了代碼的可維護性和可擴展性。主要模塊包括：

• providers：負責實現不同的AI提供商，如谷歌Gemini和Vertex AI。每個提供商都有獨立的實現，通過工廠模式進行管理，方便切換和擴展。
• services：包含核心服務，如配置服務和文件服務。這些服務提供了統一的接口，供其他模塊調用。
• storage：實現了存儲功能，與谷歌雲存儲集成，確保數據的安全存儲和高效訪問。
• file-upload：處理文件上傳相關的邏輯，支持多種上傳方式，如URL、本地文件和Base64編碼。
• types：定義了TypeScript類型，確保代碼的類型安全。
• utils：提供了各種實用函數，供其他模塊複用。
• server：作為主MCP服務器，負責接收和處理請求，協調各個模塊的工作。

通過這種模塊化架構，項目的各個部分可以獨立開發、測試和維護，同時也方便了新功能的添加和現有功能的優化。

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。

致謝

• 感謝谷歌提供的Gemini和Vertex AI API。
• 感謝模型上下文協議團隊提供的MCP框架。
• 感謝本項目的所有貢獻者和用戶。