Image Recognition MCP

🚀 画像認識MCPサーバー

OpenAI互換のビジョンモデルを使用して、AIによる画像認識と説明機能を提供するModel Context Protocol (MCP) サーバーです。

🚀 クイックスタート

このMCPサーバーを使用すると、AIアシスタントはシンプルなURLベースのインターフェースを通じて画像を分析し、説明することができます。OpenAIのビジョンモデルや、OpenAI互換のローカルモデル（LM Studio、Ollamaなど）をサポートしており、画像の詳細な説明を提供し、AIワークフローに画像分析機能を簡単に統合できます。

✨ 主な機能

• 画像分析：URLから画像を分析し、詳細な説明を取得します。
• 柔軟なモデルサポート：OpenAIのビジョンモデルとOpenAI互換のローカルモデル（LM Studio、Ollamaなど）で動作します。
• MCPプロトコル：Model Context Protocol標準と完全に互換性があります。
• 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アカウントに利用可能なクレジットがあることを確認します。

"Authentication failed" エラーが発生する場合:

• 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リポジトリでイシューを作成するか、メンテナに連絡してください。