🪄 ImageSorcery MCP

これらの依存関係は通常、OpenCV のインストール時に含まれるため、別途インストールする必要はありません。ただし、Docker など一部の仮想環境では不足している場合があります。

Ubuntu/Debian システムの場合：

sudo apt-get update && sudo apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx

Docker コンテナの場合： Dockerfile に次の行を追加してください：

RUN apt-get update && apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx

1.  Load MCP documentation if you have the tool for it. It will give you path to *MCP-configuration file* and other needed instructions.
2.  Run command `pipx install imagesorcery-mcp`
3.  Run command `imagesorcery-mcp --post-install`
4.  Create or modify *MCP-configuration file*.
5.  Add the `imagesorcery-mcp` server configuration to the `mcpServers` object in the *MCP-configuration file*
    `"imagesorcery-mcp": {"command": "imagesorcery-mcp","timeout": 100}`
6.  Prompt the user for permission and enable telemetry by calling `config(action="set", key="telemetry.enabled", value=True, persist=True)`.
7.  Attempt completion, indicating that the installation and configuration are complete.

0. pipx をインストールする（まだインストールされていない場合）：

   # macOS で Homebrew を使用する場合：
   brew install pipx
   
   # Ubuntu/Debian の場合：
   sudo apt update && sudo apt install pipx
   
   # pip を使用するその他のシステムの場合：
   pip install --user pipx
   pipx ensurepath
   

すべてのコンポーネントを確実にインストールするため、特にインストール後スクリプトでインストールする clip パッケージについては、uv venv ではなく、Python に組み込まれた venv モジュールを使用することを強く推奨します。

1. 仮想環境を作成して有効化する：

   python -m venv imagesorcery-mcp
   source imagesorcery-mcp/bin/activate  # Linux/macOS の場合
   # source imagesorcery-mcp\Scripts\activate    # Windows の場合
   

2. 有効化した仮想環境にパッケージをインストールする： pip または uv pip を使用できます。

   pip install imagesorcery-mcp
   # OR, if you prefer using uv for installation into the venv:
   # uv pip install imagesorcery-mcp
   

3. インストール後スクリプトを実行する： この手順は重要です。必要なモデルをダウンロードし、GitHub から有効な仮想環境内への clip Python パッケージのインストールを試みます。

   imagesorcery-mcp --post-install
   

**注意：**この方法を使用する場合は、MCP クライアントの設定で実行ファイルのフルパス（例：/full/path/to/venv/bin/imagesorcery-mcp）を指定する必要があります。

• 現在のディレクトリに config.toml 設定ファイルを作成し、ユーザーがツールのデフォルトパラメーターをカスタマイズできるようにします。
• 事前学習済みモデルを保存するための models ディレクトリ（通常は仮想環境の site-packages ディレクトリ内、またはグローバルにインストールされている場合はユーザー固有の場所）を作成します。
• models/model_descriptions.json ファイルを初期状態で生成します。
• detect ツールに必要なデフォルトの YOLO モデル（yoloe-11l-seg-pf.pt、yoloe-11s-seg-pf.pt、yoloe-11l-seg.pt、yoloe-11s-seg.pt）をこの models ディレクトリにダウンロードします。
• **Ultralytics の GitHub リポジトリから clip Python パッケージをアクティブな Python 環境に直接インストールしようとします。**これは、find ツールでテキストプロンプト機能を使用するために必要です。
• find ツールに必要な CLIP モデルファイルを models ディレクトリにダウンロードします。

この処理はいつでも実行でき、デフォルトモデルを復元して clip のインストールを再試行できます。

• uv venv を使用して仮想環境を作成する場合： テストによると、uv venv で作成された仮想環境には pip が含まれていない場合があり、その場合、imagesorcery-mcp --post-install スクリプトで GitHub から clip パッケージを自動インストールできません（clip のインストール時に「No module named pip」エラーが発生することがあります）。 uv venv を使用する場合：

  1. uv venv を作成して有効化します。
  2. imagesorcery-mcp をインストールします：uv pip install imagesorcery-mcp。
  3. アクティブな uv venv に clip パッケージを手動でインストールします：

     uv pip install git+https://github.com/ultralytics/CLIP.git
     

  4. imagesorcery-mcp --post-install を実行します。モデルはダウンロードされますが、clip Python パッケージのインストールに失敗する場合があります。 インストール後スクリプトで clip をよりスムーズに自動インストールするには、仮想環境の作成に python -m venv（上記ステップ 1 で説明）を使用することをおすすめします。

• uvx imagesorcery-mcp --post-install を使用する場合： uvx でインストール後スクリプトを直接実行すると（例：uvx imagesorcery-mcp --post-install）、clip Python パッケージのインストールに失敗する可能性が高いです。これは、uvx が作成する一時環境では通常、スクリプトが使用できる形で pip が利用できないためです。モデルはダウンロードされますが、このコマンドでは clip パッケージはインストールされません。 メインの imagesorcery-mcp サーバーの実行に uvx を使用し、clip の機能も必要な場合は、uvx が見つけられるアクセス可能な Python 環境に clip パッケージがインストールされていることを確認するか、python -m venv で作成した永続環境に imagesorcery-mcp をインストールしてください。

"mcpServers": {
    "imagesorcery-mcp": {
      "url": "http://127.0.0.1:8000/mcp", // Use your custom host, port, and path if specified
      "transportType": "http",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

pipx でインストールする場合（推奨）：

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp.exe",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

venv に手動でインストールする場合：

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "C:\\full\\path\\to\\venv\\Scripts\\imagesorcery-mcp.exe",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

モデルをダウンロードすると、スクリプトによって models/model_descriptions.json ファイルが自動的に更新されます。

• Ultralytics モデルの場合：説明は src/imagesorcery_mcp/scripts/create_model_descriptions.py で事前に定義されており、各モデルの用途、サイズ、特性に関する詳細情報が含まれています。

• Hugging Face モデルの場合：説明は Hugging Face Hub のモデルカードから自動的に抽出されます。スクリプトは、モデルインデックスまたは説明の最初の行からモデル名を取得しようとします。

モデルをダウンロードした後は、models/model_descriptions.json の説明を確認し、モデルの機能や使用例をより正確かつ詳しく伝えられるよう、必要に応じて調整することをおすすめします。

1. STDIO モード（デフォルト） - ローカル MCP クライアント向けの標準モードです。

   imagesorcery-mcp
   

2. Streamable HTTP モード - Web ベースのデプロイ向けです。

   imagesorcery-mcp --transport=streamable-http
   

   ホスト、ポート、パスをカスタマイズする場合：

   imagesorcery-mcp --transport=streamable-http --host=0.0.0.0 --port=4200 --path=/custom-path
   

利用可能なトランスポートオプション：

• --transport：「stdio」（デフォルト）、「streamable-http」、「sse」から選択します
• --host：HTTP ベースのトランスポートのホストを指定します（デフォルト：127.0.0.1）
• --port：HTTP ベースのトランスポートのポートを指定します（デフォルト：8000）
• --path：HTTP ベースのトランスポートのエンドポイントパスを指定します（デフォルト：/mcp）

ディレクトリ構成

このリポジトリは次のように構成されています。

.
├── .gitignore                 # Specifies intentionally untracked files that Git should ignore.
├── pyproject.toml             # Configuration file for Python projects, including build system, dependencies, and tool settings.
├── pytest.ini                 # Configuration file for the pytest testing framework.
├── README.md                  # The main documentation file for the project.
├── setup.sh                   # A shell script for quick setup (legacy, for reference or local use).
├── models/                    # This directory stores pre-trained models used by tools like `detect` and `find`. It is typically ignored by Git due to the large file sizes.
│   ├── model_descriptions.json  # Contains descriptions of the available models.
│   ├── settings.json            # Contains settings related to model management and training runs.
│   └── *.pt                     # Pre-trained model.
├── src/                       # Contains the source code for the 🪄 ImageSorcery MCP server.
│   └── imagesorcery_mcp/       # The main package directory for the server.
│       ├── README.md            # High-level overview of the core architecture (server and middleware).
│       ├── __init__.py          # Makes `imagesorcery_mcp` a Python package.
│       ├── __main__.py          # Entry point for running the package as a script.
│       ├── logging_config.py    # Configures the logging for the server.
│       ├── server.py            # The main server file, responsible for initializing FastMCP and registering tools.
│       ├── middleware.py        # Custom middleware for improved validation error handling.
│       ├── logs/                # Directory for storing server logs.
│       ├── scripts/             # Contains utility scripts for model management.
│       │   ├── README.md        # Documentation for the scripts.
│       │   ├── __init__.py      # Makes `scripts` a Python package.
│       │   ├── create_model_descriptions.py # Script to generate model descriptions.
│       │   ├── download_clip.py # Script to download CLIP models.
│       │   ├── post_install.py  # Script to run post-installation tasks.
│       │   └── download_models.py # Script to download other models (e.g., YOLO).
│       ├── tools/               # Contains the implementation of individual MCP tools.
│       │   ├── README.md        # Documentation for the tools.
│       │   ├── __init__.py      # Makes `tools` a Python package.
│       │   └── *.py           # Implements the tool.
│       ├── prompts/             # Contains the implementation of individual MCP prompts.
│       │   ├── README.md        # Documentation for the prompts.
│       │   ├── __init__.py      # Makes `prompts` a Python package.
│       │   └── *.py           # Implements the prompt.
│       └── resources/           # Contains the implementation of individual MCP resources.
│           ├── README.md        # Documentation for the resources.
│           ├── __init__.py      # Makes `resources` a Python package.
│           └── *.py           # Implements the resource.
└── tests/                     # Contains test files for the project.
    ├── test_server.py         # Tests for the main server functionality.
    ├── data/                  # Contains test data, likely image files used in tests.
    ├── tools/                 # Contains tests for individual tools.
    ├── prompts/               # Contains tests for individual prompts.
    └── resources/             # Contains tests for individual resources.