# MCP Image Tools

AIエージェント向けの画像処理MCPサーバー。スプライトシートの分割、リサイズ、クロップなどの画像操作をエージェント経由で実行できます。

## 概要

AI画像生成で作成された画像（例：1024x1024のスプライトシート）を、エージェントが直接操作できるようにするローカルツールです。ゲーム開発やピクセルアート制作時に、AIが生成した大きな画像を個別のスプライトに分割したり、任意のサイズにリサイズしたりすることができます。

### 主な機能

- **スプライトシート分割 (`tool_split_sprite_sheet`)**: 大きな画像を指定サイズのグリッドに分割
- **画像リサイズ (`tool_resize_image`)**: 任意のサイズに拡大・縮小
- **画像クロップ (`tool_crop_image`)**: 座標指定での切り取り
- **バッチリサイズ (`tool_batch_resize`)**: 複数画像の一括処理
- **画像情報取得 (`tool_get_image_info`)**: サイズや形式などのメタデータを取得

### 想定ユースケース

- AIが生成した1024x1024の画像を32x32のスプライトに分割
- アイコン画像を複数サイズ（16x16、32x32、64x64）に一括変換
- 画像の特定領域を座標指定で切り出し

## ライセンス

MIT License / MITライセンス

Copyright (c) 2026 yyyy-tt

本プロジェクトはMITライセンスの下で公開されています。英語の原文と日本語の参考訳、および著作権表示については [LICENSE](./LICENSE) ファイルを参照してください。
言語により内容に相違がある場合は、日本語の原文を正とします。

## 制約

### 技術的制約

- **対応画像形式**: PNG, JPEG, GIF, WebP
- **最大画像サイズ**: メモリ容量に依存（推奨: 8192x8192以下）
- **Python バージョン**: 3.8以上
- **動作環境**: ローカル環境のみ（リモートAPI機能なし）

### 機能的制約

- AI超解像機能は含まれません（単純な補間リサイズのみ）
- 画像の品質向上や高度なフィルタリングは行いません
- アニメーション画像（GIF）は最初のフレームのみ処理されます
- ベクター画像（SVG）には非対応

### セキュリティ上の注意

- ローカルファイルシステムへのアクセス権限が必要です
- エージェントに指定されたパスへの読み書き権限を付与します
- 信頼できるエージェントからの呼び出しのみを想定しています

## インストール方法

### 前提条件

- Python 3.8以上がインストールされていること
- pip が利用可能であること

### インストール手順

#### 開発者向け（ローカルインストール）

1. リポジトリをクローンし、ディレクトリに移動します。
2. 仮想環境を作成し、有効化します。
3. 編集モードでインストールします。

```bash
git clone https://github.com/yyyy-tt/mcp-image-tools.git
cd mcp-image-tools
python -m venv .venv
# Windowsの場合
.venv\Scripts\activate
# インストール
pip install -e .
```

#### GitHubから直接インストールする場合

```bash
pip install git+https://github.com/yyyy-tt/mcp-image-tools.git
```

## エージェントとの接続方法

### 設定方法 (`mcp_config.json`)

エージェント（Antigravity, Claude Code等）の `mcp_config.json` に以下の設定を追加します。

#### ローカル開発環境の場合（Windows推奨）

```json
{
  "mcpServers": {
    "image-tools": {
      "command": "C:\\path\\to\\mcp-image-tools\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "mcp_image_tools.server"
      ],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\mcp-image-tools"
      }
    }
  }
}
```

#### GitHub等からインストール済みの場合

```json
{
  "mcpServers": {
    "image-tools": {
      "command": "mcp-image-tools"
    }
  }
}
```

#### 3. Antigravity の再起動

設定ファイルを保存後、Antigravityを再起動してください。

#### 動作確認

Antigravityに以下のように指示して、ツールが認識されているか確認します。

```
MCPコンフィグからMCPサーバにアクセスし、使用可能なMCPツールを取得、教えて下さい。
```

以下のようなツールが表示されれば成功です：
- `tool_split_sprite_sheet`
- `tool_resize_image`
- `tool_crop_image`
- `tool_batch_resize`
- `tool_get_image_info`

### 使用例

#### スプライトシート分割 (`tool_split_sprite_sheet`)

```
./sprite_sheet.png (1024x1024) を 32x32 のスプライトに分割して ./sprites/ ディレクトリに保存してください。
```

#### 画像リサイズ (`tool_resize_image`)

```
logo.png を 512x512 にリサイズして logo_vga.png として保存してください。
```

#### 座標指定クロップ (`tool_crop_image`)

```
background.png の座標 (100, 200) から 512x512 の領域を切り取って face.png として書き出してください。
```

## トラブルシューティング

### ツールが認識されない

- 設定ファイルのパスが正しいか確認してください
- Pythonのパスが正しいか確認してください（`which python`）
- Antigravityを再起動してください

### 画像処理が失敗する

- 画像ファイルが存在し、読み取り可能か確認してください
- 対応形式（PNG, JPEG, GIF, WebP）であることを確認してください
- 出力先ディレクトリへの書き込み権限があるか確認してください

### メモリエラーが発生する

- 画像サイズが大きすぎる可能性があります（8192x8192以下を推奨）
- 使用可能なメモリ容量を確認してください

## 貢献

バグレポート、機能リクエスト、プルリクエストを歓迎します。

1. このリポジトリをフォーク
2. フィーチャーブランチを作成 (`git checkout -b feature/amazing-feature`)
3. 変更をコミット (`git commit -m 'Add some amazing feature'`)
4. ブランチにプッシュ (`git push origin feature/amazing-feature`)
5. プルリクエストを作成

## サポート

- Issues: https://github.com/yyyy-tt/mcp-image-tools/issues
- Discussions: https://github.com/yyyy-tt/mcp-image-tools/discussions

## 関連リンク

- [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)
- [Pillow Documentation](https://pillow.readthedocs.io/)
- [Antigravity Documentation](https://docs.antigravity.ai/)