# Local Image Search (Japanese) MCP Server

日本語に特化した CLIP モデル (`line-corporation/clip-japanese-base`) を利用し、日本語の自然言語（テキスト）によるローカル画像の類似度検索を提供する MCP (Model Context Protocol) サーバーです。

## 特徴
- **日本語による画像検索**: 自然な日本語クエリ（例：「赤い髪の女の子」「夜のネオン街」など）でローカル画像を検索可能。
- **効率的なインデックス更新**: 画像のスキャン結果と特徴ベクトル（Embedding）を SQLite データベースにキャッシュし、変更・追加があった画像のみを差分更新。
- **高速な検索**: インデックスされた特徴ベクトルを起動時にメモリ上に展開し、コサイン類似度計算を行うことでミリ秒単位の高速な検索を実現。
- **MCP ＆ HTTP サーバーのハイブリッド**: 
  - Claude Desktop 等から呼び出し可能な MCP サーバーとしての動作。
  - 検索 API エンドポイント (`/api/search`) および、結果画像配信用エンドポイント (`/image`) を内蔵。

---

## 構成ファイル

- `update_index.py`: 指定したフォルダ内の画像をスキャンし、特徴ベクトルを抽出してデータベースを構築・更新する CLI スクリプト。
- `server.py`: SQLite データベースを読み込み、MCP ツールおよび HTTP 検索/画像配信 API を提供するサーバープログラム。
- `requirements.txt`: 実行に必要な依存パッケージ一覧。

---

## 準備

### 1. 動作環境
- Python 3.10 以上
- GPU 環境推奨 (CUDA が利用可能な場合、自動的に GPU 上で推論が行われます)

### 2. インストール
仮想環境を作成し、必要なライブラリをインストールします。

```bash
# 仮想環境の作成 (例)
python -m venv .venv
source .venv/bin/activate  # Windows の場合は .venv\Scripts\activate

# 依存パッケージのインストール
pip install -r requirements.txt
```

---

## 使用方法

画像パスおよびデータベースパスはすべて**コマンドライン引数**のみで指定します。コード内のハードコーディングは不要です。

### 1. 画像インデックスの作成・更新 (`update_index.py`)
検索したい画像が保存されているフォルダをスキャンし、データベースを作成（または更新）します。

```bash
python update_index.py --image-dir "/path/to/images" --db-path "/path/to/image_index.db"
# 短縮形
python update_index.py -i "/path/to/images" -d "/path/to/image_index.db"
```

- `--image-dir` (`-i`): 画像が格納されているフォルダパス (サブフォルダも再帰的に検索されます)
- `--db-path` (`-d`): 出力される SQLite データベースファイルの保存先パス

### 2. 検索サーバーの起動 (`server.py`)
作成されたデータベースを指定して、MCP / HTTP サーバーを起動します。

```bash
python server.py --db-path "/path/to/image_index.db"
# 短縮形
python server.py -d "/path/to/image_index.db"
```

- `--db-path` (`-d`): `update_index.py` で作成した SQLite データベースファイルのパス

起動すると、デフォルトで `http://localhost:8000` でサーバーが待機します。

---

## Claude Desktop への連携設定

Claude Desktop で本 MCP サーバーを登録して利用するには、`claude_desktop_config.json` に以下の設定を追加します。

```json
{
  "mcpServers": {
    "local-image-search": {
      "command": "python",
      "args": [
        "C:/absolute/path/to/search-image-mcp/server.py",
        "--db-path",
        "C:/absolute/path/to/search-image-mcp/image_index.db"
      ]
    }
  }
}
```
*(※ パスはすべてご自身の環境の絶対パスに書き換えてください。Windows の場合、パスの区切り文字は `/` にすることをお勧めします)*

---

## ライセンス

[MIT License](LICENSE)