Metadata-Version: 2.4
Name: sd-api-mcp
Version: 0.2.0
Summary: MCP server wrapping the Stable Diffusion WebUI API
Project-URL: Homepage, https://github.com/HizZaniya/sd-api-mcp
Project-URL: Repository, https://github.com/HizZaniya/sd-api-mcp
Project-URL: Bug Tracker, https://github.com/HizZaniya/sd-api-mcp/issues
Author: HizZaniya
License: MIT
Keywords: image-generation,mcp,stable-diffusion,webui
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.13
Requires-Dist: fastmcp>=3.3.1
Requires-Dist: httpx>=0.28.0
Requires-Dist: pillow>=11.0.0
Description-Content-Type: text/markdown

# SD API MCP

> Stable Diffusion WebUI API (AUTOMATIC1111/ForgeUI) を操作する MCP サーバ

## 前提条件

- [Stable Diffusion WebUI](https://github.com/AUTOMATIC1111/stable-diffusion-webui)（または ForgeUI）が起動していること
- [uv](https://docs.astral.sh/uv/) がインストール済みであること

## MCPクライアント設定

### Claude Code

```bash
claude mcp add sd-api-mcp uvx sd-api-mcp
```

または `.claude/settings.json` に追加:

```json
{
  "mcpServers": {
    "sd-api-mcp": {
      "command": "uvx",
      "args": ["sd-api-mcp"],
      "env": {
        "SD_WEBUI_URL": "http://localhost:7860"
      }
    }
  }
}
```

### Cursor

`.cursor/mcp.json` に追加:

```json
{
  "mcpServers": {
    "sd-api-mcp": {
      "command": "uvx",
      "args": ["sd-api-mcp"],
      "env": {
        "SD_WEBUI_URL": "http://localhost:7860"
      }
    }
  }
}
```

### VS Code (GitHub Copilot)

`.vscode/mcp.json` に追加:

```json
{
  "servers": {
    "sd-api-mcp": {
      "command": "uvx",
      "args": ["sd-api-mcp"],
      "env": {
        "SD_WEBUI_URL": "http://localhost:7860"
      }
    }
  }
}
```

## 環境変数

| 変数名 | デフォルト | 説明 |
|---|---|---|
| `SD_WEBUI_URL` | `http://host.docker.internal:7860` | SD WebUI のベース URL |
| `SD_AUTH_USER` | （なし） | Basic 認証ユーザー名（任意） |
| `SD_AUTH_PASS` | （なし） | Basic 認証パスワード（任意） |
| `SD_OUTPUT_DIR` | `./output` | 生成画像の保存先ディレクトリ |
| `REQUEST_TIMEOUT` | `300` | HTTP リクエストのタイムアウト秒数 |

## ツールリファレンス

### `txt2img`

テキストプロンプトから画像を生成し、ファイルに保存します。

| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| `prompt` | str | 必須 | 生成プロンプト |
| `negative_prompt` | str | `""` | ネガティブプロンプト |
| `steps` | int | `20` | サンプリングステップ数（1〜150） |
| `width` | int | `512` | 画像の幅 px（64〜2048） |
| `height` | int | `512` | 画像の高さ px（64〜2048） |
| `cfg_scale` | float | `7.0` | CFG スケール（1.0〜30.0） |
| `sampler_name` | str | `"Euler a"` | サンプラー名 |
| `scheduler_name` | str | `"Automatic"` | スケジューラー名 |
| `seed` | int | `-1` | シード値（-1 でランダム） |
| `batch_size` | int | `1` | 生成枚数（1〜4） |
| `restore_faces` | bool | `false` | 顔修復を有効にする |
| `tiling` | bool | `false` | タイリング画像を生成する |
| `distilled_cfg_scale` | float | `3.5` | Distilled CFG スケール（1.0〜30.0） |
| `controlnet_units` | list | `null` | ControlNet ユニットのリスト |
| `output_dir` | str | `"./output"` | 出力ディレクトリ |

**戻り値**: 生成された画像ファイルの絶対パスリスト

### `img2img`

入力画像とプロンプトから画像を生成し、ファイルに保存します。

| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| `init_image` | str | 必須 | 入力画像のファイルパス |
| `prompt` | str | 必須 | 生成プロンプト |
| `negative_prompt` | str | `""` | ネガティブプロンプト |
| `denoising_strength` | float | `0.75` | デノイズ強度（0.0〜1.0） |
| `steps` | int | `20` | サンプリングステップ数（1〜150） |
| `width` | int | `512` | 画像の幅 px（64〜2048） |
| `height` | int | `512` | 画像の高さ px（64〜2048） |
| `cfg_scale` | float | `7.0` | CFG スケール（1.0〜30.0） |
| `sampler_name` | str | `"Euler a"` | サンプラー名 |
| `scheduler_name` | str | `"Automatic"` | スケジューラー名 |
| `seed` | int | `-1` | シード値（-1 でランダム） |
| `batch_size` | int | `1` | 生成枚数（1〜4） |
| `restore_faces` | bool | `false` | 顔修復を有効にする |
| `tiling` | bool | `false` | タイリング画像を生成する |
| `controlnet_units` | list | `null` | ControlNet ユニットのリスト |
| `output_dir` | str | `"./output"` | 出力ディレクトリ |

**戻り値**: 生成された画像ファイルの絶対パスリスト

### `get_sd_models`

利用可能な Stable Diffusion モデルの一覧を返します。

パラメータなし。**戻り値**: モデル名の文字列リスト

### `set_sd_model`

アクティブな Stable Diffusion モデルを変更します。

| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| `model_name` | str | 必須 | 設定するモデル名 |

**戻り値**: 設定完了メッセージ（文字列）

### `get_sd_upscalers`

利用可能なアップスケーラーの一覧を返します。

パラメータなし。**戻り値**: アップスケーラー名の文字列リスト

### `upscale_images`

画像をアップスケールして保存します。

| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| `images` | list[str] | 必須 | アップスケールする画像ファイルパスのリスト |
| `resize_mode` | int | `0` | 0=倍率指定, 1=サイズ指定 |
| `upscaling_resize` | float | `4.0` | アップスケール倍率（`resize_mode=0` 時） |
| `upscaling_resize_w` | int | `512` | 目標幅 px（`resize_mode=1` 時） |
| `upscaling_resize_h` | int | `512` | 目標高さ px（`resize_mode=1` 時） |
| `upscaler_1` | str | `"R-ESRGAN 4x+"` | プライマリアップスケーラー |
| `upscaler_2` | str | `"None"` | セカンダリアップスケーラー |
| `output_dir` | str | `"./output"` | 出力ディレクトリ |

**戻り値**: 保存された画像ファイルの絶対パスリスト

### `get_controlnet_models`

利用可能な ControlNet モデルの一覧を返します。

パラメータなし。**戻り値**: ControlNet モデル名の文字列リスト

### `get_controlnet_modules`

利用可能な ControlNet プリプロセッサの一覧を返します。

パラメータなし。**戻り値**: ControlNet プリプロセッサ名の文字列リスト

## 開発者向け

### 環境構築

```bash
git clone https://github.com/HizZaniya/sd-api-mcp.git
cd sd-api-mcp
uv sync --group dev
pre-commit install
```

### テスト実行

```bash
uv run pytest -v
```

型チェック・Lint:

```bash
uv run ty check
uv run ruff check .
uv run ruff format --check .
```

### ファイル構成

```
src/sd_api_mcp/
├── server.py   # MCP プロトコル層 — ツール定義・リクエスト受付
└── client.py   # SD WebUI API 通信層 — httpx による HTTP クライアント
```

- `server.py`: FastMCP のツールデコレータでツールを定義し、MCP プロトコルを処理する。SD WebUI への直接アクセスは行わない。
- `client.py`: httpx を使って SD WebUI の REST API と通信する。MCP プロトコルを知らない。

### リリース手順

1. Conventional Commits 形式でコミットを積む（例: `feat: add new tool`, `fix: handle timeout`）
2. GitHub Actions の **Release** ワークフローを手動トリガーする
3. `cz bump` がコミット履歴からバージョンを自動決定し、`CHANGELOG.md` を更新してタグを作成
4. **Publish** ワークフローが自動実行され、TestPyPI で検証後 PyPI に公開される

### コントリビューション

1. `main` ブランチから feature ブランチを作成する
2. テストを先に書いてから実装する（TDD）
3. PR を作成する（テンプレートに従うこと）
4. CI（lint / format / typecheck / test）がすべてパスしたらレビューを依頼する

コミットメッセージは [Conventional Commits](https://www.conventionalcommits.org/) 形式を推奨します。

## ライセンス

MIT
