Image Recognition MCP

🚀 圖像識別MCP服務器

本項目是一個基於模型上下文協議（MCP）的服務器，藉助與OpenAI兼容的視覺模型，提供由人工智能驅動的圖像識別和描述功能。它允許AI助手通過簡單的基於URL的接口分析和描述圖像，支持OpenAI的視覺模型以及兼容OpenAI的本地模型（如LM Studio、Ollama等），能為圖像提供詳細描述，方便將圖像分析能力集成到AI工作流程中。

🚀 快速開始

本MCP服務器使AI助手能夠通過簡單的基於URL的接口分析和描述圖像。它支持OpenAI的視覺模型以及兼容OpenAI的本地模型（如LM Studio、Ollama等），提供圖像的詳細描述，便於將圖像分析功能集成到你的AI工作流程中。

✨ 主要特性

• 圖像分析：通過URL分析圖像並獲取詳細描述。
• 靈活的模型支持：可與OpenAI的視覺模型以及兼容OpenAI的本地模型（如LM Studio、Ollama等）配合使用。
• MCP協議：完全兼容模型上下文協議標準。
• TypeScript構建：採用TypeScript構建，確保類型安全，提供更好的開發體驗。
• 簡單的API：提供易於使用的接口，用於請求圖像描述。

📦 安裝指南

前提條件

• Node.js 18+
• npm 或 yarn
• OpenAI API密鑰或本地視覺模型服務器（如LM Studio、Ollama）

MCP客戶端配置

要將此服務器與MCP客戶端配合使用，請添加以下配置：

{
  "mcpServers": {
    "image-recognition": {
      "command": "npx",
      "args": ["-y", "@akirose/image-recognition-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-actual-openai-api-key-here"
      }
    }
  }
}

若要允許從任何路徑訪問圖像文件，請將 ALLOW_ALL_PATHS 設置為 true：

{
  "mcpServers": {
    "image-recognition": {
      "command": "npx",
      "args": ["-y", "@akirose/image-recognition-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-actual-openai-api-key-here",
        "ALLOW_ALL_PATHS": "true"
      }
    }
  }
}

⚠️ 重要提示

包含API密鑰的 env 部分是必需的，這是MCP服務器正常運行的唯一方式。對於本地模型，你可以為 OPENAI_API_KEY 使用任何佔位符值，並將 OPENAI_BASE_URL 配置為指向你的本地服務器。

環境變量

服務器支持以下環境變量：

💻 使用示例

可用工具

describe-image

分析來自URL或本地文件路徑的圖像，並提供詳細描述。 參數：

• imageUrl（字符串）：要分析的圖像的URL或本地文件路徑。
• prompt（字符串，可選）：關於圖像的問題或提示（默認為 "what's in this image?"）。

使用URL的示例：

{
  "tool": "describe-image",
  "arguments": {
    "imageUrl": "https://example.com/image.jpg",
    "prompt": "what's in this image?"
  }
}

使用本地文件的示例：

{
  "tool": "describe-image",
  "arguments": {
    "imageUrl": "./images/my-image.png",
    "prompt": "Describe the objects in this image"
  }
}

響應：

{
  "content": [
    {
      "type": "text",
      "text": "The image shows a beautiful sunset over a mountain landscape with vibrant orange and pink colors in the sky..."
    }
  ]
}

與AI助手集成

此MCP服務器可以與支持MCP協議的各種AI助手集成，例如：

• Claude Desktop
• 其他兼容MCP的AI系統

🔧 技術細節

項目結構

image-recognition-mcp/
├── src/
│   ├── index.ts                # 主服務器實現
│   ├── path-validator.ts       # 路徑驗證和安全功能
│   └── image-processor.ts      # 圖像處理實用工具
├── test/
│   ├── index.test.ts           # 單元測試
│   ├── describe-image-integration.test.ts  # 集成測試
│   ├── test.png                # 測試圖像
│   └── README.md               # 測試文檔
├── dist/                       # 編譯後的JavaScript輸出
├── package.json                # 項目依賴和腳本
├── tsconfig.json               # TypeScript配置
└── README.md                   # 本文件

運行測試

項目包括單元測試和集成測試：

# 運行所有測試
npm test

# 僅運行單元測試
npm run test:unit

# 使用本地兼容OpenAI的服務器運行集成測試
npm run test:integration

集成測試要求：

• 在 http://127.0.0.1:1234/v1 運行的兼容OpenAI的API服務器。
• 服務器應支持視覺模型（如 qwen/qwen3-vl-4b）。
• 你可以使用LM Studio、Ollama或其他兼容服務器。
• 集成測試使用 OPENAI_BASE_URL 和 OPENAI_MODEL 環境變量。

集成測試將：

• 測試對視覺模型的實際API調用。
• 使用測試圖像（test/test.png）驗證圖像處理。
• 使用默認和自定義提示驗證完整的MCP工具工作流程。
• 測試錯誤處理和邊緣情況。

安全特性

服務器包含以下安全特性：

• 路徑驗證：將本地文件訪問限制在允許的目錄中。
• 擴展名驗證：僅允許特定的圖像文件擴展名（.jpg、.jpeg、.png、.gif、.webp）。
• 域名限制：可選的URL域名白名單，以增強安全性。
• 文件存在性檢查：在處理之前驗證文件是否存在。

錯誤處理

服務器包含強大的錯誤處理機制，用於處理以下情況：

• 無效的圖像URL。
• 未經授權的文件路徑或域名。
• 網絡連接問題。
• OpenAI API錯誤。
• 無效的輸入參數。
• 不支持的文件格式。

📚 詳細文檔

故障排除

常見問題

服務器無法啟動或無法正常工作：

• ✅ 檢查OpenAI API密鑰是否設置：這是問題的首要原因。

  echo $OPENAI_API_KEY  # 應顯示你的API密鑰
  

• ✅ 驗證API密鑰是否有效：直接使用OpenAI的API進行測試。
• ✅ 檢查API密鑰是否有足夠的信用額度：確保你的OpenAI賬戶有可用的信用額度。

“身份驗證失敗”錯誤：

• OpenAI API密鑰缺失或無效。
• 設置環境變量：export OPENAI_API_KEY="your-key"

貢獻代碼

1. 分叉倉庫。
2. 創建功能分支（git checkout -b feature/amazing-feature）。
3. 提交更改（git commit -m 'Add some amazing feature'）。
4. 推送到分支（git push origin feature/amazing-feature）。
5. 打開拉取請求。

📄 許可證

本項目採用MIT許可證。有關詳細信息，請參閱 LICENSE 文件。

支持

如需支持，請在GitHub倉庫中打開一個問題或聯繫維護者。