# Hunyuan-mcp-webui

Apple Silicon MacでHunyuan3Dを動かし、画像またはテキストから3Dアセットを生成するためのMCPサーバーとWeb UIです。

> Independent community integration. This project is not affiliated with,
> sponsored by, or endorsed by Tencent. Tencent source code, model weights,
> trademarks, and generated outputs remain subject to their applicable terms.

## できること

- MCP（stdio）からHunyuan3D-2.1の単一画像→3D生成を呼び出す
- Codex native Image Genで単一画像を生成し、そのままHunyuan3D-2.1へ渡す
- Codex native Image Genで正面・左・背面・右の4方向画像を生成し、Hunyuan3D-2mvへ渡す
- Hunyuan3D-Paint-2.1でPBRテクスチャを生成する
- 白基調のWeb UIで入力、進捗、GLBプレビュー、ダウンロードを操作する
- Apple Silicon向けMPS/CPU設定とメモリ節約プロファイルを利用する

生成後のLOD、コライダー、リギングは
[`Hunyuan3D-blender-processor`](https://github.com/KouyamaCreate/Hunyuan3D-blender-processor)、
ゲーム組み込みは
[`Hunyuan3D-game-integration`](https://github.com/KouyamaCreate/Hunyuan3D-game-integration)
が担当します。

## 必要環境

- Apple Silicon Mac（M1以降を推奨）
- macOS
- Python 3.10
- Node.js 20以降（統合Web UIを使う場合）
- 十分な空き容量。モデルweightとキャッシュはGitに含まれません

初回のモデル取得にはHugging Faceへのネットワーク接続が必要です。処理時間と必要メモリはMac、入力、品質設定によって大きく変わります。

## セットアップ

```bash
git clone https://github.com/KouyamaCreate/Hunyuan-mcp-webui.git
cd Hunyuan-mcp-webui
./setup_macos.sh
```

従来Web UI:

```bash
./run_web_ui.sh
# http://127.0.0.1:8090
```

3役統合Web UI:

```bash
npm --prefix frontend install
./run_frontend.sh
# http://127.0.0.1:4173
```

UIだけを確認する場合:

```bash
HUNYUAN3D_BACKEND=mock ./run_frontend.sh
```

## MCPとして使う

MCPクライアントのstdio commandに次を指定します。

```text
/absolute/path/to/Hunyuan-mcp-webui/run_mcp_server.sh
```

主要tool、生成モード、Apple Silicon向けprofile、Codex app-server接続の詳細は
[`docs/spec.md`](docs/spec.md)を参照してください。

## 構成

```text
components/image_worker/    Codex native Image Gen連携
components/shape_worker/    Hunyuan3D-2.1 / Hunyuan3D-2mv shape生成
components/texture_worker/  Hunyuan3D-Paint-2.1 PBR texture生成
frontend/                   統合Web UI
schemas/                    role間のJSON contract
mcp_server.py               MCP stdio server
web_ui.py                   従来Web UI backend
```

## テスト

model weightを使わない軽量テスト:

```bash
python3 -m unittest \
  tests.test_pipeline_contracts \
  tests.test_worker_registry \
  tests.test_paint_macos_compat

npm --prefix frontend install
npm --prefix frontend test
```

`tests.test_role_pipeline`は、同じ親フォルダに`Hunyuan3D-blender-processor`がある3役構成で実行します。実モデルE2Eは大容量weightと長い実行時間を必要とするため、通常のCIには含めません。

## ドキュメント

- [`docs/spec.md`](docs/spec.md): 現在の実行仕様と操作方法
- [`docs/multi-project-roadmap.md`](docs/multi-project-roadmap.md): 3役プロジェクトの責務と統合計画
- [`docs/log.md`](docs/log.md): 実装・互換対応・実機試走の記録
- [`RIGHTS_AND_LICENSES.md`](RIGHTS_AND_LICENSES.md): ファイル群とmodelの権利境界
- [`CONTRIBUTING.md`](CONTRIBUTING.md): 開発・投稿手順
- [`SECURITY.md`](SECURITY.md): 脆弱性報告

## ライセンスと重要な注意

このrepositoryは単一ライセンスではありません。

- 独自のMCP/Web UI統合コード: [`LICENSE-MCP-WEBUI`](LICENSE-MCP-WEBUI)（MIT）
- Hunyuan3D-2.1由来コード: [`LICENSE`](LICENSE)、[`Notice.txt`](Notice.txt)ほか各ディレクトリのnotice
- Hunyuan3D-2mv互換runtime: [`LICENSE-HUNYUAN3D-2.0`](LICENSE-HUNYUAN3D-2.0)と[`NOTICE-HUNYUAN3D-2.0`](NOTICE-HUNYUAN3D-2.0)
- Python/npm依存、model weight、入力画像、生成物: それぞれの配布元・権利者の条件

Tencentのライセンスには地域、用途、配布、表示、acceptable-use等の条件があります。公開repositoryであることは、modelの利用や再配布が無条件に許諾されることを意味しません。利用・配布前に[`RIGHTS_AND_LICENSES.md`](RIGHTS_AND_LICENSES.md)と原文を確認してください。model weight、秘密情報、生成job dataはこのrepositoryに含めません。

## Upstream

本プロジェクトは[`Tencent-Hunyuan/Hunyuan3D-2.1`](https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1)を基盤とする独立したintegrationです。研究内容、model card、引用情報は公式upstreamを参照してください。